radioplayer

Technische Dokumentation: Die Konsole anpassen

Einführung

Diese Dokumentation richtet sich an Webentwickler und Techniker, die den JavaScript-Code der Konsole verändern wollen um sie anzupassen und neue Funktionen und Inhalte hinzuzufügen. Falls das nicht auf Sie zutrifft, sollten Sie mit der Anleitung „Erste Schritte“ fortfahren.

Theme

Das Logo des Senders und das Hintergrundbild bzw. die -farbe können im style/theme.css verändert werden.

Wenn Sie einen dunklen Hintergrund wählen, müssen Sie die Bedienungslemente auf die helle Variante umstellen. Um dies zu tun, öffnen Sie index.html und scrollen Sie zu der Zeile, die mit <div class=“radioplayer. Hier sehen Sie das dunkle Theme als voreingestellt und können dies auf das helle Theme ändern.

Außerdem müssen Sie das Sender logo aktualisieren um zu Ihrer Website zu verlinken und den Text, welcher Ihren Sendernamen beinhaltet. Um diese Anpassungen vorzunehmen gehen zur Ziele <a class=“stn-logo“ und aktualisieren Sie den ‚href‘ parameter mit der URL zu Ihrer Website. Zudem ersetzten Sie die zwei Instanzen von ‚Your Station Name‘ mit Ihrem Sendernnamen.

Einstellungen

Diese finden Sie relativ weit oben in der index.html.

currentStationID und currentStationName müssen Ihre radioplayer ID und Ihr Sendername sein. Kontaktieren Sie uns, wenn Sie Ihre radioplayer ID nicht wissen.

nowPlayingSource können Sie default lassen. Diese Einstellung verändert das Verhalten im ‚now playing‘ Balken.

Die Konsole wird den Balken mit folgenden Inhalten, sofern nicht anders eingestellt, in dieser Reihenfolge befüllen:

  • Der aktuell gespielte Titel, bereitgestellt als PE für radioplayer.
  • Das aktuelle Programm on air, bereitgestellt als PI für radioplayer.
  • Die Metadaten, die vom live audio stream kommen.
  • Die Beschreibung des Senders, bereitgestellt in SI für radioplayer.
  • Der Name des Senders, bereitgestellt in SI für radioplayer

Wenn Sie wünschen, können die Inhalte des Balkens an eine bestimmte Quelle gebunden werden. Andere Optionen für nowPlayingSource beinhaltet:

  • ‚default-no-stream‘ – dies verwendet die default-Einstellungen, welche oben gelistet sind, ausgenommen dem Stream mit den Metadaten
  • ‚stream‘ – dies verwendet ausschließlich die Metadaten des Streams
  • ‚SI‘ -dies verwendet entweder die Beschreibung des Senders (wenn bereitgestellt) oder den Namen, der von Ihrer SI für radioplayer zur Verfügung gestellt wird
  • ‚PI‘ – dies verwendet den Namen des Programms, der via PI für radioplayer zur Verfügung gestellt wird

xDomainProxyUrl muss auf die volle URL in der xdomainproxy.html-Datei gesetzt sein. Per default können Sie diese im preroll-framework directory finden. Diese Datei wird genützt, wenn eine preroll-Überlagerung aktiviert ist.

initOption beinhaltet 3 Optionen, welche, wenn sie aktiviert sind, zugehörige Einstellungen im radioplayer Zentralsystem überschreiben. Alle Details bezüglich dieser Optionen finden Sie in der Commercial Settings section unterhalb.

Stream

Die Einstellungen für den Stream oder On-Demand Audio finden Sie oben im index.html.

audioLive soll für Live Streams true und für On-Demand Audio false sein.

audioFlash beinhaltet die Optionen für den Stream.

  • audioType kann ‚playlist‘, ‚http‘, ‚httpmp4m4a‘, ‚rtmp‘ sein.
  • audioURL soll für die Playlist, http und httpmp4m4a gesetzt sein.
  • audioServer und audioEndpoint sollen für rtmp gesetzt sein.

bufferTime kann, wenn nötig, angepasst werden.

Für audioType ‚playlist‘ werden folgende Playlist-Formate unterstützt: SMIL, ASX, XSPF, PLS, M3U. Links zu ‚playlist within playlists‘ werden ebenfalls untersützt.

RTMP Streams mit ‚server-endpoint‘ Konfigurationen sind in Playlists nur dann konfigurierbar, wenn sie das XSPF und SMIL Format verwenden.

Wenn Sie einen Stream haben der von Browsern, welche Audio ohne Verwendung des Adobe Flash Players abspielen können, unterstützt wird, können Sie die Parameter für audioHTML spezifizieren. Das RTMP Format wird bei diesem Szenario nicht unterstützt. Der audioHTML Stream wird von einem Browser verwendet werden, der keinen Flash benützt, oder auf einem Gerät auf welchem die Installation von Flash nicht möglich ist (z.B.: iPad).

Einige Streams/Playlisten werden nicht abgespielt, wenn Security Errors aufgrund Ihres Streaminganbieters bzgl. nicht implementierter Adobe crossdomain policy permissions auftreten.

Erhalten Sie den Security Error können Sie diese Beispieldatei für eine Adobe cossdomain policy Ihrem Streaminganbieter senden. Sie finden diese ebenfalls in der kompletten radioplayer.zip.

 

<?xml version="1.0" ?> 
<!DOCTYPE cross-domain-policy (View Source for full doctype...)> 
<cross-domain-policy> 
<site-control permitted-cross-domain-policies="all" /> 
<allow-access-from domain="*.example.com" secure="false" /> 
<allow-http-request-headers-from domain="*.example.com" headers="*" secure="false" /> 
</cross-domain-policy> 

Mehr Informationen dazu finden Sie hier:
http://www.adobe.com/devnet/adobe-media-server/articles/cross-domain-xml-for-streaming.html

Plugin Space

Der Platz für das Plugin kann vollkommen individualisiert werden. Sie finden dies nahezu am Ende der index.html Datei. Der Bereich ist durch Anfangs- und Endkommentare klar ersichtlich.

Audio Clips abspielen

Ein Audio Clip kann in der Konsole durch das einfache Hinzufügen der Konsolen URL ?rpAodUrl= followed abgespielt werden. Die Konsole wird versuchen, sich die ‚now playing‘ Informationen vom Zentralsystem oder beim Durchsuchen auf sämtliche ID3 Metadaten in den Audiodateien, zu beschaffen.

Kommerzielle Einstellungen

Das initOptions Objekt, welches Sie im head-Bereich des index.html finden, erlaubt Ihnen 3 kommerzielle Einstellungen für Ihre Konsole auszuwählen. Diese Optionen können ebenfalls im Zentralsystem von radioplayer aktiviert werden.

Interstitial

Ändern Sie enabled auf true um ein Interstitial zu aktivieren und vervollständigen Sie die URL mit der URL Ihrer Interstitial-Seite. Das Interstitial wird erscheinen sobald die Konsole gelaunched ist, aber nicht wenn von einem zum anderen radioplayer navigiert wird.

Sie können das Template, welches im preroll-framework/index.html bereitgestellt wird verwenden. Fügen Sie einen Skip Button hinzu und bearbeiten Sie das redirecting zurück zu Ihrer Konsole ohne dass das Interstitial erneut angezeigt wird.

Song Action

Ein Song Action ist ein kleiner Button der, während ein Song gespielt wird, auf der rechten Seite des ‚now playing‘ Streifens zu finden ist.  Der Button  kann zu einer URL Ihrer Wahl verlinken, und den Artist  und/oder Titel in dem Query String mitliefern.

Ändern Sie enabled zu true um eine Song Action zu aktivieren. type soll den Text des Buttons beinhalten. baseurl soll die URL, welche in dem neuen Browserfenster bei Klick auf den Button geöffnet wird, beinhalten.

Wenn Sie arist oder title des gespielten Songs zur URL hinzufügen wollen, können Sie diese in den Platzhaltern [artist] und [title] hinzufügen. Zum Beispiel:

http://www.song-retailer.com/buy.php?artist=[artist]&title=[title]

Wenn Sie artist und title in ‚URL within a URL‘ einfügen, benötigen Sie eine doppelte Zeichencodierung. In diesem Fall können Sie dies so verwenden: [[artist]] und [[title]]

 

API Dokumentation

Generieren Sie eine Konsole mit dem Konsolen-Generator im station control panel. Im Quellcode sind die Javascript-Sourcen alle unverschlüsselt und unkomprimiert enthalten. In den Kommentaren sind die einzelnen Funktionen genauer beschrieben.

Hilfreich ist es, wenn Sie sich die vorhandenen Javascript Objekte einfach im Browser anschauen: Sie beginnen alle mit radioplayer…

Die wichtigsten sind:

radioplayer.emp = Flash/HTML5 Player-Komponente
radioplayer.controls = GUI-Elemente wie Start/Stop-Buttons oder Lautstärkeregler
radioplayer.playing = Statuszeile/Ticker

In den radioplyer.emp.*.js-Dateien finden Sie zudem diverse Events, die der Player erzeugt.

Ein Hinweis: Genutzt wird in der Konsole das minimized Script.

Einige Beispiele:

Stream für eigene Audios/Audiowerbespots unterbrechen:

Möchten Sie mittels Javascript die Wiedergabe des aktuellen Streams unterprechen, so bieten sich die folgenden beiden Funktionen an:

radioplayer.emp.stop();
radioplayer.emp.start();

Möchten Sie unmittelbar nach dem Aufruf der Konsole den Autostart des radioplayers für einen Prestream-Spot unterdrücken, empfehlen wir den Player nur auf stumm zu schalten. Dies hat den Vorteil, dass die Zeit der Wiedergabe des Prestream-Spots dafür genutzt werden kann, den eigentlichen Audiostream schon zu laden:

radioplayer.controls.mute();

Hinweis: Bei der Funktion mute() handelt es sich um einen Toggle. Den aktuellen Status können Sie mit Hilfe der Variablen radioplayer.controls.currentVolume sowie radioplayer.controls.muted auslesen.

Mittels Setzen der Variable radioplayer.controls.volumeLocked auf den Wert true können Sie zudem den Lautstärkebutton für Benutzereingaben sperren. So können Sie sicherstellen, dass ein Nutzer Ihren Prestream-Spot nicht überspringen kann und den Audiostream bereits vor Ablauf des Spots laut schaltet.

Bitte beachten Sie: Von der Verwendung der Funktion radioplayer.emp.setVolume() wird abgeraten! Hintergrund: Die radioplayer-Konsolen hinterlegen die zuletzt gewählte Lautstärkeeinstellung eines Benutzers in einem Cookie, sodass dieser Wert über alle Sender-Konsolen hinweg erhalten bleibt. Überschreiben Sie mittels der oben genannten Funktion nun diesen Wert, sinkt die Usability der Konsolen erheblich.

Eigene Titelanzeige implementieren:

Übermitteln Sie bereits mittels Programm-Events (PE) Metadaten an die radioplayer-Plattform, wird der aktuelle Song automatisch in der Statusleiste der Konsole angezeigt. Dazu sendet die Konsole alle 20 Sekunden ein AJAX-Request an die radioplayer-Plattform, um die Daten zu aktualisieren.

Möchten Sie darüber hinaus eigene (zusätzliche) Titelinformationen, wie Cover oder Hooks, in Ihrem Plugin-Space darstellen, empfehlen wir, diese beiden Anzeigen zu synchronisieren:

var lastArtist = “;
var lastTitle = “;
function checkStationSonginfos() {
if(radioplayer.playing.showingPlayingType == ‚PE‘) {
if(radioplayer.playing.artist && radioplayer.playing.artist != lastArtist &&
radioplayer.playing.title && radioplayer.playing.title != lastTitle) {
lastArtist = radioplayer.playing.artist;
lastTitle = radioplayer.playing.title;
updateEigeneSonginfos();
}
}
}
checkStationSonginfos();
window.setInterval(‚checkStationSonginfos();‘, 1000);

So wird die Statusleiste des radioplayers jede Sekunde auf eine mögliche Änderung hin überprüft. Sofern sich die Daten ändern, werden dann über die von Ihnen zu implementierende Funktion updateEigeneSonginfos() Ihre weiterführenden Titelinformationen abgefragt. So sparen Sie zudem Traffic-Kosten und vermeiden unnötige AJAX-Requests auf Ihre Server.

jQuery

radioplayer bindet die Javascript-Bibliothek jQuery auf bekannte Art uns Weise ein. Der „noconflict“-Modus wird nicht genutzt.

Zögern Sie nicht unser Support-Team zu kontaktieren. So können wir Ihnen gezielt Programmier-Beispiele für Ihr Problem liefern.

 

Seitliche Navigation

Wenn Sie einen Link in Ihrem Plugin Space zum Navigieren von einer Konsole  zu einer anderen haben, gibt es ein Attribut data-newstationid, welches Sie zu Ihrem Link-Tag hinzufügen können. Dieses kann dadurch für Analytics getracked werden. Hier sehen Sie einen Beispiellink, bei dem XXXX durch die destination player’s radioplayer ID ersetzt werden soll:

<a href=“http://player.example.com/“ data-newstationid=“XXXX“>My other station</a>

Stay up to date!