ORF.AT MEDIA LIBRARY · Seite 4 ORF.at Media Library v1.0 Der ORF.at Videoplayer funktioniert mit allen gängigen Browsern: Firefox >= 2 Opera >= 9.26 Internet Explorer >= 7

Seite 1 ORF.at Media Library v1.0

ORF.AT MEDIA LIBRARY VERSION 1.0


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 ...................................................................................................................................................... 12

Audioplayer ................................................................................................................................................. 14

Einbindung .............................................................................................................................................. 14

Verwendung des Audioplayers ............................................................................................................... 14

Player-Optionen ...................................................................................................................................... 14

Audio-Optionen....................................................................................................................................... 15

Beispiele .................................................................................................................................................. 16

Farboptionen ........................................................................................................................................... 16

Versionshistorie ........................................................................................................................................... 19


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.

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


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.


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/1.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/1.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:

http://orf.at/oon/media/current/oon.media-min.js

http://orf.at/oon/media/1.0/oon.media-min.js

http://orf.at/oon/media/


<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).

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)


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>


}

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/")


"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

"http://apasfw.apa.at/filehandler/mp4:testvideo.mp4/playlist.m3u8".

"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": "http://server.orf.at/path/to/previews/preview.jpg",

"url": "http://server.orf.at/path/to/videos/video.mp4",

"videoWidth": 640,

"videoHeight": 360

}

}

}

Streaming Video in einer Qualität:


var settings = {

"qualities": 1,

"sources": {

"default": {

"server": "apasfw.apa.at",

"path": "/filehandler/",

"name": "entscheidung_176799.mp4",

"preview": "http://static.orf.at/blockstars/entscheidung_176800.jpg",

"videoWidth": 640,

"videoHeight": 360

}

}

}

Streamed Video in zwei Qualitäten:

var settings = {

"duration": 26680,

"qualities": 2,

"sources": {

"q4a": {



"name": "video.mp4",

"preview": "http://static2.orf.at/preview_q4a_184478.jpg",

"videoWidth": 480,

"videoHeight": 268

},

"q1a": {



"name": "video.3gp",

"preview": "http://static2.orf.at/preview_q1a_184479.jpg",

"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:

http://static2.orf.at/preview_q4a_184478.jpg

http://static2.orf.at/preview_q1a_184479.jpg


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:

"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:


{

"controls": {



"empty": "#ffffff",

"hover": {

"symbol": "#466199",


}

},

// Das "Playbutton"-Overlay im Video-Bereich

"overlay": {

"symbol": "#ffffff",

"background": "#000000",

"opacity": 0.75,

"hover": {

"symbol": "#ffffff",

"background": "#000000"

}

},

// Das "Play/Pause"-Kontrollelement

"play": {



"hover": {

"background": "#e0e4ec",

"symbol": "#466199"

}

},

// Lautstärke-Kontrollelement

"volume": {



"empty": "#ffffff",

"hover": {

"symbol": "#466199",


}

},

// Fortsetzung auf der nächsten Seite


// Vollbild-Kontrollelement

"fullscreen": {



"hover": {

"symbol": "#466199",


}

},

// Fortschrittsanzeige

"progressbar": {


"loaded": "#8999bc",

"played": "#466199",

"empty": "#ffffff"

},

// Lautstärke-Regler

"volumebar": {


"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.


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.


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.


"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": {



}

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/")


"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

"http://apasfw.apa.at/filehandler/mp3:testaudio.mp3/playlist.m3u8".

BEISPIELE

"Progressive Download"-Audio in einer Qualität mit Vorschaubild:

var settings = {

"sources": {

"default": {

"url": http://server.orf.at/path/to/audios/audio.mp3

}

}

}

Streaming Audio in einer Qualität:

var settings = {

"sources": {

"default": {



"name": "tv_life_ball_song_1021378849182.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.


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:


{

"controls": {



"empty": "#ffffff",

"hover": {

"symbol": "#466199",


}

},

"play": {



"hover": {


"symbol": "#466199"

}

},

"volume": {



"empty": "#ffffff",

"hover": {

"symbol": "#466199",


}

},

"progressbar": {


"loaded": "#8999bc",

"played": "#466199",

"empty": "#ffffff"

},

"volumebar": {


"slider": "#466199",

"empty": "#ffffff"

},

"timer": "#8999bc"

}


VERSIONSHISTORIE

Version Datum Bemerkungen

1.0beta1 23.04.2012

1.0beta2 05.07.2012

1.0 23.08.2012

Documents

ORF.AT MEDIA LIBRARY · Seite 4 ORF.at Media Library v1.0 Der ORF.at Videoplayer funktioniert mit allen gängigen Browsern: Firefox >= 2 Opera >= 9.26 Internet Explorer >= 7