ORF.AT MEDIA LIBRARY VERSION 1.0. Seite 1 ORF.at Media Library v1.0

Transkript

1 ORF.AT MEDIA LIBRARY VERSION 1.0 Seite 1 ORF.at Media Library v1.0

2 INHALT Einleitung... 3 Konzept... 3 Auswahl der Videoqualität... 3 Kompatibilität... 3 Videoplayer... 5 Einbindung... 5 Verwendung des Videoplayers... 5 Player-Optionen... 6 Video-Optionen... 7 Beispiele... 8 Farboptionen... 9 Events Audioplayer Einbindung Verwendung des Audioplayers Player-Optionen Audio-Optionen Beispiele Farboptionen Versionshistorie Seite 2 ORF.at Media Library v1.0

3 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 Flashbasierten 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. AUSWAHL DER VIDEOQUALITÄT Bei Verwendung von zwei Videoqualitäten (q1a bzw. q4a, siehe Abschnitt Video-Optionen) entscheidet das Betriebssystem des Client-Browsers über die Verwendung der hohen bzw. niedrigen Videoqualität: Niedrige Videoqualität (q1a): iphone, ipod und alle Android-Systeme Hohe Videoqualität (q4a): Alle anderen Browser/Betriebssysteme KOMPATIBILITÄT Seite 3 ORF.at Media Library v1.0

4 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 v1.0

5 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=" Der URL der Javascript-Datei definiert, welche Version der Player-Library verwendet wird: ist die aktuelle Version. Statt "current" kann auch eine Versionsnummer angegeben werden, z.b. Die verfügbaren Versionen können unter eingesehen werden. VERWENDUNG DES VIDEOPLAYERS Für jeden Videoplayer muss folgender HTML/Javascript-Code in die jeweilige Seite eingebaut werden: Seite 5 ORF.at Media Library v1.0

6 <div id="video1234"></div> <script type="text/javascript"> (function() { var settings = <JSON:Object>; var container = document.getelementbyid("video1234"); var player = oon.video.createplayer(container); player.render(settings); )(); </script> 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). 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. "flashvars": <String> Diese Option ermöglicht es, die Farbgebung des Flashplayers zu beeinflussen. "duration": <Number> Die Länge des Videos (optional) Seite 6 ORF.at Media Library v1.0

7 VIDEO-OPTIONEN "qualities": <Number> Der Wert dieser Option muss der Anzahl an verfügbaren Video-Qualitäten entsprechen. Wenn nur eine Video-Qualität existiert, kann diese Option weggelassen werden. "sources": <JSON:Object> Die Metadaten der verfügbaren Video-Qualitäten werden in einem JSON Literal definiert. Wenn nur eine verfügbare Qualität vorliegt, müssen die Metadaten wie folgt definiert werden: "sources": { "default": <JSON:Object> Wenn das Video in zwei Qualitäten vorliegt, müssen die Qualitäten wie folgt definiert werden: "sources": { "q1a": <JSON:Object> "q4a": <JSON:Object> 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: "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. Bei Videos, deren URL sich je nach Browser/Betriebssystem unterscheidet (eg. Flash-Streaming via "rtmp" Protokoll bzw. Apple HTTP Live Streaming), müssen anstatt obiger "url"-definition der Server, Pfad und Video-Dateiname angegeben werden: "server": <String> Der vollständige DNS-Name des Streamingservers (i.e. "apasfw.apa.at") "path": <String> Der Pfad des Publishing-Points, der das Video streamt (i.e. "/filehandler/") Seite 7 ORF.at Media Library v1.0

8 "name": <String> Der Name des Videos (i.e. "testvideo.mp4") Abhänging von Browser/Betriebssystem bzw. der Existenz des Flash-Plugins im Browser konstruiert die Video-Library den passenden URL. Mit den obigen Beispielwerten wird für die Flash-Variante des Players der URL "rtmp://apasfw.apa.at/filehandler/mp4:testvideo.mp4" verwendet, bei IOS-Endgeräten " "videowidth": <Number> Die Breite des Videos (in Pixel) "videoheight": <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. "mimetype": <String> Optionaler Mime-Type des Videos (der Standardwert lautet "video/mp4") BEISPIELE "Progressive Download"-Video in einer Qualität mit Vorschaubild: var settings = { "qualities": 1, "sources": { "default": { "preview": " "url": " "videowidth": 640, "videoheight": 360 Streaming Video in einer Qualität: Seite 8 ORF.at Media Library v1.0

9 var settings = { "qualities": 1, "sources": { "default": { "server": "apasfw.apa.at", "path": "/filehandler/", "name": "entscheidung_ mp4", "preview": " "videowidth": 640, "videoheight": 360 Streamed Video in zwei Qualitäten: var settings = { "duration": 26680, "qualities": 2, "sources": { "q4a": { "server": "apasfw.apa.at", "path": "/filehandler/", "name": "video.mp4", "preview": " "videowidth": 480, "videoheight": 268, "q1a": { "server": "apasfw.apa.at", "path": "/filehandler/", "name": "video.3gp", "preview": " "videowidth": 320, "videoheight": 180 FARBOPTIONEN Um die Farben der einzelnen Kontrollelemente des Flash-Videoplayers zu verändern, kann beim Aufruf der "render"-methode ein zweites Argument übergeben werden: Seite 9 ORF.at Media Library v1.0

10 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: { // diese definition gilt für alle kontrollelemente "controls": { // Vordergrundfarbe: "symbol": "#8999bc", // Hintergrundfarbe: // 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 v1.0

11 { "controls": { "symbol": "#8999bc", "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", "hover": { "background": "#e0e4ec", "symbol": "#466199", // Lautstärke-Kontrollelement "volume": { "symbol": "#8999bc", "empty": "#ffffff", "hover": { "symbol": "#466199", "background": "#e0e4ec", // Fortsetzung auf der nächsten Seite Seite 11 ORF.at Media Library v1.0

12 // Vollbild-Kontrollelement "fullscreen": { "symbol": "#8999bc", "hover": { "symbol": "#466199", "background": "#e0e4ec", // Fortschrittsanzeige "progressbar": { "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 v1.0

13 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. "videoplayer "). 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.videoplayer ") 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 v1.0

14 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> <script type="text/javascript"> (function() { var settings = <JSON:Object>; var container = document.getelementbyid("audio1234"); var player = oon.audio.createplayer(container); player.render(settings); )(); </script> 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 v1.0

15 "duration": <Number> Die Länge des Audios (optional) AUDIO-OPTIONEN "qualities": <Number> Der Wert dieser Option muss der Anzahl an verfügbaren Audio-Qualitäten entsprechen. Wenn nur eine Audio-Qualität existiert, kann diese Option weggelassen werden. "sources": <JSON:Object> Die Metadaten der verfügbaren Audio-Qualitäten werden in einem JSON Literal definiert. Wenn nur eine verfügbare Qualität vorliegt, müssen die Metadaten wie folgt definiert werden: "sources": { "default": <JSON:Object> Wenn das Audio in zwei Qualitäten vorliegt, müssen die Qualitäten wie folgt definiert werden: "sources": { "q1a": <JSON:Object> "q4a": <JSON:Object> Pro Audio-Qualität muss die URL des Audio angegeben werden. Entweder: "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. Bei Audios, deren URL sich je nach Browser/Betriebssystem unterscheidet (eg. Flash-Streaming via "rtmp" Protokoll bzw. Apple HTTP Live Streaming), müssen anstatt obiger "url"-definition der Server, Pfad und Audio-Dateiname angegeben werden: "server": <String> Der vollständige DNS-Name des Streamingservers (i.e. "apasfw.apa.at") "path": <String> Der Pfad des Publishing-Points, der das Audio streamt (i.e. "/filehandler/") Seite 15 ORF.at Media Library v1.0

16 "name": <String> Der Name des Audios (i.e. "testaudio.mp3") Abhänging von Browser/Betriebssystem bzw. der Existenz des Flash-Plugins im Browser konstruiert die Library den passenden URL. Mit den obigen Beispielwerten wird für die Flash-Variante des Players der URL "rtmp://apasfw.apa.at/filehandler/mp3:testaudio.mp3" verwendet, bei IOS-Endgeräten " BEISPIELE "Progressive Download"-Audio in einer Qualität mit Vorschaubild: var settings = { "sources": { "default": { "url": Streaming Audio in einer Qualität: var settings = { "sources": { "default": { "server": "apasfw.apa.at", "path": "/filehandler/", "name": "tv_life_ball_song_ mp3" FARBOPTIONEN 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. Seite 16 ORF.at Media Library v1.0

17 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 17 ORF.at Media Library v1.0

18 { "controls": { "symbol": "#8999bc", "empty": "#ffffff", "hover": { "symbol": "#466199", "background": "#e0e4ec", "play": { "symbol": "#8999bc", "hover": { "background": "#e0e4ec", "symbol": "#466199", "volume": { "symbol": "#8999bc", "empty": "#ffffff", "hover": { "symbol": "#466199", "background": "#e0e4ec", "progressbar": { "loaded": "#8999bc", "played": "#466199", "empty": "#ffffff", "volumebar": { "background": "#e0e4ec", "slider": "#466199", "empty": "#ffffff", "timer": "#8999bc" Seite 18 ORF.at Media Library v1.0

19 VERSIONSHISTORIE Version Datum Bemerkungen 1.0beta beta Seite 19 ORF.at Media Library v1.0