Upload
others
View
4
Download
0
Embed Size (px)
Citation preview
Seite 2 ORF.at Media Library v2.0
INHALT
Einleitung ....................................................................................................................................................... 3
Konzept ..................................................................................................................................................... 3
Kompatibilität ........................................................................................................................................... 3
Videoplayer ................................................................................................................................................... 4
Einbindung ................................................................................................................................................ 4
Verwendung des Videoplayers ................................................................................................................. 4
Player-Optionen ........................................................................................................................................ 5
Video-Optionen ......................................................................................................................................... 5
Definition der Video-URL .......................................................................................................................... 6
Vorbereiten der Video-URL ....................................................................................................................... 6
Video liegt auf APA Streaming Plattform ............................................................................................. 6
Video liegt auf APA Streaming Plattform, Abfrage über Loadbalancer ................................................ 7
Beispiele .................................................................................................................................................... 7
Farboptionen ............................................................................................................................................. 8
Events ...................................................................................................................................................... 11
Audioplayer ................................................................................................................................................. 13
Einbindung .............................................................................................................................................. 13
Verwendung des Audioplayers ............................................................................................................... 13
Player-Optionen ...................................................................................................................................... 13
Audio-Optionen....................................................................................................................................... 14
Beispiele .................................................................................................................................................. 14
Farboptionen ........................................................................................................................................... 14
jQuery Plugins .............................................................................................................................................. 17
jquery.video Plugin ................................................................................................................................. 17
jquery.audio Plugin ................................................................................................................................. 18
Versionshistorie ........................................................................................................................................... 19
Seite 3 ORF.at Media Library v2.0
EINLEITUNG
Die ORF.at Media Library ist eine rein browserseitige Lösung zum Einbinden von Videos und Audios in
HTML-Seiten. Er besteht aus einer Javascript-Bibliothek, die unabhängig von anderen Libraries (jQuery,
Mootools, YUI o.ä.) verwendet werden kann. Die eigentliche Einbindung von Videos bzw. Audios erfolgt
durch wenige Zeilen Javascript-Code. Der Library ist ausgerichtet auf die APA Streamingplattform, kann
aber "progressive download"-Videos von jedem beliebigen Server abspielen.
KONZEPT
Aufgrund der mangelhaften nativen Unterstützung von "streaming HTML5-Video/Audio" der meisten
Browser sowie der limitierten Möglichkeiten, das Design von nativen HTML5 Playern zu beeinflussen,
verwendet die ORF.at Media Library sowohl für Video als auch Audio grundsätzlich einen Adobe Flash-
basierten Player.
Nur in Browsern, die kein Flash-Plugin installiert haben bzw. auf Betriebssystemen, die Flash nicht
unterstützen (z.B. Apple IOS-basierte Geräte wie iPhone oder iPad), wird der native HTML5 Video-
/Audioplayer verwendet. Ob die Videos bzw. Audios auf solchen Systemen tatsächlich abgespielt werden
können, hängt aber vom verwendeten Format und von den Fähigkeiten des Browsers bzw. des
Betriebssystems ab, und kann von der ORF.at Media Library nicht beeinflusst werden. Im Falle von
"streamed Videos" ist das gegenwärtig nur auf IOS-Geräten der Fall, bei "progressive download"-Videos
ist die Unterstützung abhängig vom Format des Videos (Mozilla Firefox und Opera z.B. unterstützen das
Dekodieren von MPEG4 Videos nicht). Im Audiobereich ist die Unertstützung von streaming content zwar
ein wenig besser, allerdings unterstützen auch hier Firefox und Opera die Dekodierung von MP3 Audios
nicht.
KOMPATIBILITÄT
Der ORF.at Videoplayer funktioniert mit allen gängigen Browsern:
Firefox >= 2
Opera >= 9.26
Internet Explorer >= 7
Safari >= 3.1
Da derzeit mit Ausnahme von Chrome und Safari (unter OS X) kein Browser das Abspielen von streamed
MPEG4 Videos in HTML5-Playern unterstützt, ist die sinnvolle Verwendung der HTML5-Version des
Players derzeit beschränkt auf Apple IOS-Systeme. "Progressive download"-Videos können hingegen in
allen aktuellen Browsern dargestellt werden.
Seite 4 ORF.at Media Library v2.0
VIDEOPLAYER
EINBINDUNG
Um den ORF.at Videoplayer verwenden zu können muss folgender SCRIPT-Tag in den HEAD-Bereich der
HTML-Seite eingefügt werden:
<script type="text/javascript" src="http://orf.at/oon/media/2.0/oon.media-
min.js"></script>
Der URL der Javascript-Datei definiert, welche Version der Player-Library verwendet wird:
http://orf.at/oon/media/current/oon.media-min.js
ist die aktuelle Version. Statt "current" kann auch eine Versionsnummer angegeben werden, z.B.
http://orf.at/oon/media/2.0/oon.media-min.js
Die verfügbaren Versionen können unter http://orf.at/oon/media/ eingesehen werden.
VERWENDUNG DES VIDEOPLAYERS
Für jeden Videoplayer muss folgender HTML/Javascript-Code in die jeweilige Seite eingebaut werden:
<div id="video1234"></div> 1 <script type="text/javascript"> 2 3 (function() { 4 var settings = <JSON:Object>; 5 var container = document.getElementById("video1234"); 6 var player = oon.video.createPlayer(container); 7 player.render(settings); 8 })(); 9 10 </script> 11
In Zeile 1 wird ein "Container"-Element definiert, in das der Videoplayer eingefügt wird. Wichtig: das
"id"-Attribut innerhalb einer HTML-Seite muss eindeutig sein.
In Zeile 5 werden die Settings des Videoplayers definiert. <JSON:Object> muss ersetzt werden durch ein
JSON Objektliteral mit den Player- und Video-Optionen (siehe auch Beispiele im Anhang).
Seite 5 ORF.at Media Library v2.0
In Zeile 6 wird eine Variable mit dem Container-Element für den Player definiert. Zeile 7 erzeugt den
Videoplayer (je nachdem ob der Browser das Flash-Plugin installiert hat oder nicht wird entweder ein
Flash- oder HTML5-Videoplayer erzeugt), und in Zeile 8 wird der Player mit den Optionen in das
Container-Element gerendert.
PLAYER-OPTIONEN
"isLiveStream": <Boolean>
→ Mit true wird der Flash-Player in den Livestream-Modus geschaltet (u.a. wird dabei die Anzeige
der Position innerhalb des Videos deaktiviert).
"autoplay": <Boolean>
→ Mit true beginnt der Player sofort nach dem vollständigen Laden der Seite zu spielen.
Standardmäßig steht diese Option auf false.
"adUrl": <String>
→ Diese Option definiert die URL der Parameter-Datei im Adserver für Pre-/Postroll Werbevideos
(nur Flash Videoplayer). Der URL muss vollständig (d.h. inklusive einer ev. notwendigen Ad-
Kategoriebezeichnung) sein, da der URL vom Player 1:1 verwendet wird. Wichtig ist, dass der URL
mit einem Slash (/) endet!
"flashVars": <String>
→ Diese Option ermöglicht es, die Farbgebung des Flashplayers zu beeinflussen.
"wmode": <String>
→Optionale wmode Definition für Flash Videoplayer
"loadbalancer": <String>
→Optionaler URL des APA Loadbalancers. Wenn gesetzt wird vor dem Rendern des Players der
Loadbalancer via JSONP kontaktiert, und die dem Client-Browser entsprechende URL aus der
Antwort des Loadbalancers für das Rendern des Players verwendet.
VIDEO-OPTIONEN
Seite 6 ORF.at Media Library v2.0
Pro Video-Qualität müssen zumindest Angaben zur URL des Videos sowie der Breite und Höhe gemacht
werden. Die URL des Videos kann auf zwei verschiedene Arten definiert werden:
"width": <Number>
→ Die Breite des Videos (in Pixel)
"height": <Number>
→ Die Höhe des Videos (in Pixel)
Optional können pro Video-Qualität noch folgende Eigenschaften definiert werden:
"preview": <String>
→ Die URL, unter der das Vorschaubild dieser Video-Qualität erreichbar ist.
DEFINITION DER VIDEO-URL
Die vom Player verwendete URL kann entweder direkt angegeben werden:
"url": <String>
→ Die URL, unter der das Video erreichbar ist. Diese Definition wird sowohl für den Flash- als auch
den HTML5-Videoplayer verwendet, d.h. es wird keine Unterscheidung zwischen
unterschiedlichen Streaming-Protokollen gemacht. Generell sollte diese URL-Definition nur bei
"progressive download"-Videos via http Protokoll verwendet werden.
Wenn der Player je nach Browser die Flash- oder HTML5-Version rendern soll, muss entweder der
Server, Pfad und Dateiname des Videos bekannt sein, oder aus einer existierenden URL extrahiert
werden.
VORBEREITEN DER VIDEO-URL
Die OON Media Library bietet dafür eine Reihe von Hilfsmethoden, die das Konstruieren bzw. Eruieren
des für den Player zu verwendenden Video-URLs erleichtern:
VIDEO LIEGT AUF APA STREAMING PLATTFORM
Seite 7 ORF.at Media Library v2.0
var settings = {...};
var server = "apasfftp.apa.at";
var path = "filehandler";
var name = "video-filename.mp4";
settings.url = oon.streaming.composeUrl(clientParams.protocol, server, path,
name);
player.render(settings);
oon.streaming.composeUrl() setzt aus den Argumenten die URL des Videos zusammen, inklusive
ev. notwendiger Prefixes (z.B. "mp4:" für rtmp-Videos). Als letztes Argument kann optional ein
spezifischer Port definiert werden. Der zurückgelieferte URL kann dann dann dem Player als Teil der
Settings übergeben werden.
VIDEO LIEGT AUF APA STREAMING PLATTFORM, ABFRAGE ÜBER LOADBALANCER
Im Regelfall sollte vor dem Rendern des Players der APA Streaming Loadbalancer kontaktiert werden, um
den finalen Video-URL zu erhalten:
var settings = {...};
var path = "filehandler";
var name = "name-of-the-video.mp4";
var clientParams = oon.streaming.getClientParams();
var loadBalancerURL = ["http://apasfiis.apa.at/jsonp", path, name].join("/");
oon.streaming.queryLoadbalancer(loadBalancerURL, function(response) {
settings.url = response.redirect[clientParams.type];
player.render(settings);
});
oon.streaming.getClientParams() liefert u.a. das für den Player passende Streaming-Protokoll
(rtmp für Flashplayer, http für HTML5 Videoplayer) zurück, sowie den Streaming-Typ. Danach wird in
obigem Beispiel der Loadbalancer-URL erstellt. oon.streaming.queryLoadbalancer() requested
diese Streaming Loadbalancer URL via JSONP und verwendet aus der Liste an URLs, die es von ihm
erhalten hat, den für den Client passenden zum Rendern des Players.
BEISPIELE
"Progressive Download"-Video in einer Qualität mit Vorschaubild:
Seite 8 ORF.at Media Library v2.0
var container = document.getElementById("video");
var player = oon.video.createPlayer(container);
var settings = {
"url": "http://server.orf.at/path/to/videos/video.mp4",
"preview": "http://server.orf.at/path/to/previews/preview.jpg",
"width": 640,
"height": 360
};
player.render(settings);
Streaming Video in einer Qualität:
var container = document.getElementById("video");
var player = oon.video.createPlayer(container);
var settings = {
"width": 640,
"height": 360,
"preview": "http://server.orf.at/path/to/previews/preview.jpg"
};
var server = "apasf.apa.at";
var path = "publishingpoint";
var name = "video-filename.mp4";
var clientParams = oon.streaming.getClientParams();
settings.url = oon.streaming.composeUrl(clientParams.protocol,
server, path, name);
player.render(settings);
FARBOPTIONEN
Um die Farben der einzelnen Kontrollelemente des Flash-Videoplayers zu verändern, kann beim Aufruf
der "render"-Methode ein zweites Argument übergeben werden:
player.render(settings, colors);
Dieses "colors"-Argument muss ein Objekt-Literal sein, in dem die Farben aller oder auch einzelner
Kontrollelemente definiert ist.
Diese Farbdefinitionen haben nur Gültigkeit für die Flash-Variante des Videoplayers, auf die
Gestaltung des HTML5-Players haben sie keine Auswirkung.
Eine einfache Farbdefinition könnte so aussehen:
Seite 9 ORF.at Media Library v2.0
{
// diese definition gilt für alle kontrollelemente
"controls": {
// Vordergrundfarbe:
"symbol": "#8999bc",
// Hintergrundfarbe:
"background": "#edeef0",
// Farbe für leere Elemente (z.B. in der Fortschrittsanzeige)
"empty": "#ffffff",
// Farbdefinitionen für "hover"-Effekte (d.h. Maus über Element)
"hover": {
// Vordergrundfarbe:
"symbol": "#466199",
// Hintergrundfarbe:
"background": "#e0e4ec"
}
},
// die Schriftfarbe der Zeitanzeige
"timer": "#8999bc"
}
Farbdefinitionen müssen immer in HEX-Notation angegeben werden, benannte Farben (z.B. "red") oder
RGBa-Definitionen sind nicht erlaubt.
Darüberhinaus lassen sich die Farben der Player-Elemente auch einzeln definieren, wobei diese
spezifischeren Definitionen allgemeinere (wie z.B. obige) überschreiben. Die verfügbaren Farb-Optionen
mit ihren Standardwerten auf einen Blick:
Seite 10 ORF.at Media Library v2.0
{
"controls": {
"symbol": "#8999bc",
"background": "#edeef0",
"empty": "#ffffff",
"hover": {
"symbol": "#466199",
"background": "#e0e4ec"
}
},
// Das "Playbutton"-Overlay im Video-Bereich
"overlay": {
"symbol": "#ffffff",
"background": "#000000",
"opacity": 0.75,
"hover": {
"symbol": "#ffffff",
"background": "#000000"
}
},
// Das "Play/Pause"-Kontrollelement
"play": {
"symbol": "#8999bc",
"background": "#edeef0",
"hover": {
"background": "#e0e4ec",
"symbol": "#466199"
}
},
// Lautstärke-Kontrollelement
"volume": {
"symbol": "#8999bc",
"background": "#edeef0",
"empty": "#ffffff",
"hover": {
"symbol": "#466199",
"background": "#e0e4ec"
}
},
// Fortsetzung auf der nächsten Seite
Seite 11 ORF.at Media Library v2.0
// Vollbild-Kontrollelement
"fullscreen": {
"symbol": "#8999bc",
"background": "#edeef0",
"hover": {
"symbol": "#466199",
"background": "#e0e4ec"
}
},
// Fortschrittsanzeige
"progressbar": {
"background": "#edeef0",
"loaded": "#8999bc",
"played": "#466199",
"empty": "#ffffff"
},
// Lautstärke-Regler
"volumebar": {
"background": "#e0e4ec",
"slider": "#466199",
"empty": "#ffffff"
},
// Schriftfarbe der Zeitanzeige
"timer": "#8999bc"
}
EVENTS
Der ORF.at Videoplayer feuert folgende Events:
1. "init": wird gefeuert wenn der VideoPlayer gerendert wurde
2. "play": feuert wenn der User den Abspielvorgang startet oder fortsetzt
3. "pause": feuert wenn der User den Pause-Button betätigt
4. "ended": feuert wenn das Ende des Videos erreicht wurde
Die Library stellt einen Event-Bus namens "oon.pubsub" zur Verfügung, über den Callbacks für Events
registriert werden können, z.B.
Seite 12 ORF.at Media Library v2.0
var player = oon.video.createPlayer(document.getElementById("video123"));
// bind to "play"-Event of the above player
oon.pubsub.subscribe("play." + player.id, function(event) {
...
});
Jede Instanz des Videoplayers besitzt eine eindeutige ID (z.B. "videoPlayer2004721593"). Diese ID dient
als Namespace für alle Events. Um nur auf Events eines bestimmten Players zu lauschen, muss die ID des
Players beim Subskribieren des Events angegeben werden (wie oben). Prinzipiell ist es aber auch
möglich, auf bestimmte Events aller Player in einer HTML-Seite zu lauschen.
Die Callback-Funktionen werden alle mit dem Event-Namen (String, z.B. "init.videoPlayer81341922433")
als erstes Argument aufgerufen. Nur bei "init"-Events wird die Instanz des Players als zweites Argument
an die Callback-Funktion übergeben.
Seite 13 ORF.at Media Library v2.0
AUDIOPLAYER
EINBINDUNG
siehe Einbindung des Videoplayers
VERWENDUNG DES AUDIOPLAYERS
Für jeden Audioplayer muss folgender HTML/Javascript-Code in die jeweilige Seite eingebaut werden:
<div id="audio1234"></div> 1 <script type="text/javascript"> 2 3 (function() { 4 var settings = <JSON:Object>; 5 var container = document.getElementById("audio1234"); 6 var player = oon.audio.createPlayer(container); 7 player.render(settings); 8 })(); 9 10 </script> 11
In Zeile 1 wird ein "Container"-Element definiert, in das der Audioplayer eingefügt wird. Wichtig: das
"id"-Attribut innerhalb einer HTML-Seite muss eindeutig sein.
In Zeile 5 werden die Settings des Audioplayers definiert. <JSON:Object> muss ersetzt werden durch ein
JSON Objektliteral mit den Player- und Audio-Optionen (siehe auch Beispiele im Anhang).
PLAYER-OPTIONEN
"autoplay": <Boolean>
→ Mit true beginnt der Player sofort nach dem vollständigen Laden der Seite zu spielen.
Standardmäßig steht diese Option auf false.
"flashVars": <String>
→ Diese Option ermöglicht es, die Farbgebung des Flashplayers zu beeinflussen.
Seite 14 ORF.at Media Library v2.0
"width": <Number>
→Die Breite des Audioplayers in Pixel (optional)
"height": <Number>
→Die Höhe des Audioplayers in Pixel (optional)
"duration": <Number>
→Die Länge des Audios (optional)
"wmode": <String>
→Optionale wmode Definition für Flash Audioplayer
AUDIO-OPTIONEN
"url": <String>
→ Die URL, unter der das Audio erreichbar ist. Diese Definition wird sowohl für den Flash- als auch
den HTML5-Audioplayer verwendet. Generell sollte diese URL-Definition nur bei "progressive
download"-Audios via http Protokoll verwendet werden.
BEISPIELE
"Progressive Download"-Audio:
var container = document.getElementById("audio");
var player = oon.audio.createPlayer();
var settings = {
"url": http://server.orf.at/path/to/audios/audio.mp3,
"width": 300,
"height": 40
};
player.render(settings);
FARBOPTIONEN
Seite 15 ORF.at Media Library v2.0
Um die Farben der einzelnen Kontrollelemente des Flash-Audioplayers zu verändern, kann beim Aufruf
der "render"-Methode ein zweites Argument übergeben werden:
player.render(settings, colors);
Dieses "colors"-Argument muss ein Objekt-Literal sein, in dem die Farben aller oder auch einzelner
Kontrollelemente definiert ist.
Diese Farbdefinitionen haben nur Gültigkeit für die Flash-Variante des Audioplayers, auf die
Gestaltung des HTML5-Players haben sie keine Auswirkung.
Farbdefinitionen müssen immer in HEX-Notation angegeben werden, benannte Farben (z.B. "red") oder
RGBa-Definitionen sind nicht erlaubt.
Darüberhinaus lassen sich die Farben der Player-Elemente auch einzeln definieren, wobei diese
spezifischeren Definitionen allgemeinere (wie z.B. obige) überschreiben. Die verfügbaren Farb-Optionen
mit ihren Standardwerten auf einen Blick:
Seite 16 ORF.at Media Library v2.0
{
"controls": {
"symbol": "#8999bc",
"background": "#edeef0",
"empty": "#ffffff",
"hover": {
"symbol": "#466199",
"background": "#e0e4ec"
}
},
"play": {
"symbol": "#8999bc",
"background": "#edeef0",
"hover": {
"background": "#e0e4ec",
"symbol": "#466199"
}
},
"volume": {
"symbol": "#8999bc",
"background": "#edeef0",
"empty": "#ffffff",
"hover": {
"symbol": "#466199",
"background": "#e0e4ec"
}
},
"progressbar": {
"background": "#edeef0",
"loaded": "#8999bc",
"played": "#466199",
"empty": "#ffffff"
},
"volumebar": {
"background": "#e0e4ec",
"slider": "#466199",
"empty": "#ffffff"
},
"timer": "#8999bc"
}
Seite 17 ORF.at Media Library v2.0
JQUERY PLUGINS
Um das Einbinden von Videos und Audios zu erleichtern, bietet die OON Media Library zwei jQuery
Plugins an.
JQUERY.VIDEO PLUGIN
Um das jQuery Video Plugin verwenden zu können, muss neben der OON Media Library auch das Plugin
im HEAD Bereich der Seite eingebunden werden:
<script type="text/javascript" src="http://orf.at/oon/media/2.0/oon.media-
min.js"></script>
<script type="text/javascript" src="http://orf.at/oon/media/2.0/jquery.video-
min.js"></script>
Alle notwendigen Informationen zum Rendern eines Videos können mit data Properties im HTML-
Element, das den Player enthalten soll, definiert werden:
<div id="video" class="remote video"
data-url=http://files2.orf.at/vietnam2/files/oon.media.test.mp4
data-preview=http://files2.orf.at/vietnam2/files/oon.media.test.jpg
data-width="480"
data-height="268"
data-loadingmessage="Video wird geladen…"
data-errormessage="Video kann nicht geladen werden"
data-adcategory="skialpin">
</div>
Das eigentliche Rendern des bzw. der Player erfolgt dann über einen einfachen Aufruf des jQuery
Plugins:
$(document).ready({
$("#video").video();
});
Alle Parameter (mit Ausnahme der Video-spezifischen wie die Video-URL oder die URL des
Vorschaubilds, bzw. adBaseURL) können auf zwei Arten definiert werden: entweder direkt im HTML-Tag
als data Attribut oder zentral als options Objekt, das dem Plugin beim Aufruf übergeben wird:
Seite 18 ORF.at Media Library v2.0
{
"loadbalancer": <String>,
"autoplay": [true|false],
"wmode": <String>,
"flashVars": <String>,
"isLiveStream": [true|false],
"adBaseUrl": <String>,
"adCategory": <String>,
"width": <Number>,
"height": <Number>,
"loadingmessage": <String>,
"errormessage": <String>
}
adBaseUrl kann nur als Teil des options Objekts übergeben werden, und dient zusammen mit der
adCategory der Konstruktion des Adserver-URLs für Preroll-Videos (nur im Flash Player). data-
Attribute überschreiben jene des options-Objekts.
JQUERY.AUDIO PLUGIN
Analog zum Video Plugin kann das Einbinden von Audios auch über das jquery.audio Plugin erfolgen.
Hierfür muss neben der OON Media Library auch das jQuery Audio Plugin im HEAD-Bereich der Seite
eingebaut werden:
<script type="text/javascript" src="http://orf.at/oon/media/2.0/oon.media-
min.js"></script>
<script type="text/javascript" src="http://orf.at/oon/media/2.0/jquery.audio-
min.js"></script>
Alle notwendigen Informationen zum Rendern des Audio-Players können mit data Properties im HTML-
Element, das den Player enthalten soll, definiert werden:
<div id="audio" class="remote audio"
data-url=http://files2.orf.at/vietnam2/files/oon.media.test.mp4
data-width="300"
data-height="30"
data-loadingmessage="Audio wird geladen…"
data-errormessage="Audio kann nicht geladen werden">
</div>
Das eigentliche Rendern des bzw. der Player erfolgt dann über einen einfachen Aufruf des jQuery
Plugins:
Seite 19 ORF.at Media Library v2.0
$(document).ready({
$("#audio").audio();
});
Alle Parameter (mit Ausnahme der Audio-spezifischen wie die URL) können auf zwei Arten definiert
werden: entweder direkt im HTML-Tag als data Attribut oder zentral als options Objekt, das dem
Plugin beim Aufruf übergeben wird:
{
"autoplay": [true|false],
"wmode": <String>,
"flashVars": <String>,
"width": <Number>,
"height": <Number>,
"loadingmessage": <String>,
"errormessage": <String>
}
data-Attribute überschreiben jene des options-Objekts.
VERSIONSHISTORIE
Version Datum Bemerkungen
1.0beta1 23.04.2012
1.0beta2 05.07.2012
1.0 23.08.2012
2.0 10.09.2013