ORF.AT MEDIA LIBRARY

Seite 1 ORF.at Media Library v2.0

ORF.AT MEDIA LIBRARY VERSION 2.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


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.


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

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

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

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


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


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


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];


});

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:

http://apasfiis.apa.at/jsonp/


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

};


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


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:


{

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


"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

};


FARBOPTIONEN

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


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"

}


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:


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:

http://files2.orf.at/vietnam2/files/oon.media.test.mp4

http://files2.orf.at/vietnam2/files/oon.media.test.jpg


{

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


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:

http://files2.orf.at/vietnam2/files/oon.media.test.mp4


$(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

Documents

ORF.AT MEDIA LIBRARY