EPG für OTT-Middleware

Der Sendeplan aus der EPG-Datenbank wird externen Systemen — Set-Top-Boxen, Anwendungen und OTT-Middleware — auf zwei Wegen bereitgestellt: als vollständiges XMLTV-Dokument über den dedizierten EPG-Server und als Tagesprogramm eines Kanals im JSON-Format über die HTTP API des Knotens.

XMLTV-Auslieferung

XMLTV wird von einem separaten integrierten EPG-Server ausgeliefert. Er wird im Bildschirm „EPG-Server“ (EPG-Server) aktiviert: „EPG-Server aktivieren“, HTTP-Port (Standardwert 43973), bei Bedarf HTTPS mit Zertifikat (Standardport 43983) und „Hostname“. Aktivieren und Deaktivieren wirken sofort, ohne Neustart des Dienstes; ein deaktivierter Server öffnet weder den HTTP- noch den HTTPS-Port.

Der Zugriff erfolgt über Benutzerkonten (Registerkarte „Benutzerkonten“ des Bildschirms „EPG-Einstellungen“, EPG-Einstellungen): Login und Passwort, „Kanalsatz“, „Ablaufdatum“ der Gültigkeit, „Zugelassene IP“ sowie das Kennzeichen „Angehalten“. Der Umfang der Auslieferung wird durch den Kanalsatz bestimmt:

  • Sätze werden auf der Registerkarte „Kanalsätze“ angelegt;

  • Kanäle werden in der EPG-Datenbank (EPG-Datenbank) in Sätze aufgenommen; ein Kanal kann mehreren Sätzen angehören;

  • einem Benutzerkonto wird genau ein Satz zugewiesen — ohne ihn bleibt die Auslieferung leer;

  • ein Satz, der einem Benutzerkonto zugewiesen ist, lässt sich nicht löschen; beim Löschen eines Satzes wird auch sein Inhalt gelöscht.

Das Dokument ist unter dem Pfad /xmltv verfügbar (sowie /xmltv.gz — die komprimierte Datei); die Autorisierung erfolgt per HTTP Digest oder über Anfrageparameter. Die Sendezeiten werden mit der Zeitzone des Kanals ausgegeben; in das Dokument gelangen nur laufende und künftige Ereignisse. Wurde derselbe Kanalbezeichner aus verschiedenen Quellen empfangen, wird der Kanal nur einmal ausgegeben; über die Auslassung informiert das Protokoll. Seit Version 2.0.2.418 werden zusammen mit dem Kanal auch seine Sendungen ausgelassen; bisher gelangten sie unter dem Bezeichner des ausgegebenen Kanals neben dessen eigenen Sendungen in das Dokument, und eine Sendung konnte sich wiederholen.

Vollständiger Export mit Zuordnungsdaten

Seit Version 2.0.2.418 liefert der EPG-Server außerdem einen vollständigen XMLTV-Export für die Zuordnung der ausgestrahlten Kanäle zum Sendeplan: den Pfad /xmltv-src (sowie /xmltv-src.gz — die komprimierte Datei). Anders als in /xmltv sind darin die Kanäle aller Quellen (oder der ausgewählten) enthalten, mit den Daten, über die ein Kanal mit seiner Quelle verknüpft wird:

  • der Kanalbezeichner im Export lautet <Quelle>:<Kanal>; er ist eindeutig, auch wenn derselbe Kanal in mehreren Quellen vorkommt;

  • jeder Kanal trägt Nummer und Namen der Quelle (src-id, src-name), den eigenen Bezeichner des Kanals im Feed (channel-id, der Zuordnungsschlüssel), den zusätzlichen Bezeichner (channel-id2), falls gesetzt, die Zeitzone (time-zone) und das Ende der letzten Sendung (last-stop);

  • alle Namen und Logos des Kanals; ein Kanal wird auch ohne Sendungen ausgegeben, und ein Kanal ohne Namen erhält als Namen seinen Bezeichner;

  • die Sendezeiten sind in UTC (+0000): Die Zeitzone des Kanals wird nicht angewendet, sondern als Attribut übergeben; zu jeder Sendung werden alle Titel, Beschreibungen, Genres und Altersfreigaben ausgegeben. Seit Version 2.0.2.419 wird der Untertitel einer Sendung (zum Beispiel der Folgentitel) als eigenes Element <sub-title> ausgegeben, und <title> kommt ohne ihn; welcher Untertitel abgetrennt wird, ist unten in Tagesprogramm im JSON-Format beschrieben.

Anfrageparameter:

  • src — all (Standard) oder durch Kommas getrennte Quellennummern; 0 ist die integrierte Quelle „Stream-Import“. Deaktivierte Quellen und unbekannte Nummern werden übersprungen;

  • programmes — 1 (Standard) liefert Kanäle und Sendungen, 0 nur den Kanalkatalog;

  • days-back — 0 (Standard) liefert laufende und künftige Sendungen, wie /xmltv; N beginnt um Mitternacht UTC vor N Tagen, jedoch nicht weiter zurück als die Aufbewahrungsdauer des Verlaufs („Verlauf aufbewahren, Tage“, Konfiguration der Quellen).

Ein ungültiger Parameterwert wird mit dem Code 400 abgelehnt. Der Zugriff erfolgt über Benutzerkonten des EPG-Servers, wie bei /xmltv: Ein Benutzerkonto mit dem Kennzeichen all-channels (in der Einstellungsdatei oder über die API; seit Version 2.0.2.419 der Schalter „Alle Kanäle in /xmltv-src“, EPG-Einstellungen) erhält alle Kanäle der ausgewählten Quellen, die übrigen nur die Kanäle ihres Kanalsatzes. Eine Anfrage vom Knoten selbst (von einer lokalen Adresse) erhält alle Kanäle ohne Benutzerkonto — nur auf diesem Pfad.

Der Export wird auf dem Server erstellt und zwischengespeichert, bis sich die Daten seiner Quellen oder die Einstellungen ändern, jedoch höchstens 5 Minuten. Eine wiederholte Anfrage nach demselben Inhalt mit dem Header If-None-Match erhält die Antwort 304. Ein großer Export mit vergangenen Tagen braucht Minuten; gleichzeitig wird nur ein Export mit Sendungen erstellt, die übrigen warten. Lässt sich der Export gerade nicht erstellen (der Dienst wird beendet, eine Quelle wird gelöscht, die Warteschlange ist belegt), antwortet der Server mit 503 und dem Header Retry-After: 30. Das Format von /xmltv ändert sich nicht.

Tagesprogramm im JSON-Format

Für Middleware-Schnittstellen liefert der Knoten das Tagesprogramm eines Kanals mit einer einzigen Anfrage an die HTTP API im JSON-Format (Autorisierung wie bei den übrigen API-Anfragen):

GET /data/epg/channel?src=<Quelle>&ch=<Kanal>&lang=<Sprache>&t=<Zeit>

Zurückgegeben wird die Liste der Ereignisse des Tages (nach UTC), in den der Zeitpunkt t fällt: Anfang, Ende, Titel und Beschreibung jeder Sendung in der angeforderten Sprache; fehlt eine Übersetzung, wird die Standardsprache verwendet, anschließend eine beliebige verfügbare. Seit Version 2.0.2.418 enthält eine Sendung mit Altersfreigabe auch diese — als Objekt rating: age (das Alter in Jahren, 16 für die Freigabe 16+, 0 für 0+) und system (das Bewertungssystem aus dem XMLTV-Feed oder der DVB-Ländercode, falls bekannt). Die Freigabe stammt aus dem Element <rating> des XMLTV-Feeds oder aus der Altersfreigabe (Parental Rating) von DVB EIT; hat eine Sendung mehrere, wird das höchste Alter ausgegeben. Eine Sendung ohne Freigabe hat dieses Objekt nicht.

Seit Version 2.0.2.419 wird der Untertitel einer Sendung (das Element <sub-title> des XMLTV-Feeds, zum Beispiel der Folgentitel) als eigenes Feld sub in der Sprache des Titels ausgegeben, und title enthält den Untertitel nicht mehr. Bis einschließlich Version 2.0.2.418 wurde der Untertitel an den Titel angehängt: Nachrichten. Folge 1. Eine Sendung ohne Untertitel hat kein Feld sub.

Separat ausgegeben wird nur ein Untertitel in der Sprache des Titels oder ohne Sprachangabe. Ein Untertitel in einer anderen Sprache (zum Beispiel ein englischer unter einem russischen Titel) wird weiterhin an den Titel angehängt und hat kein eigenes Feld. Hat eine Sendung zwei Untertitel — einen in der Sprache des Titels und danach einen fremdsprachigen —, enthält das eigene Feld beide, durch einen Punkt verbunden: A. B.

Die normale Auslieferung /xmltv, das ausgehende EIT und die Weboberfläche zeigen den Titel weiterhin zusammen mit dem Untertitel. Nach dem Update des Knotens wird die EPG-Datenbank an Ort und Stelle ergänzt, ohne Datenverlust; die Untertitel erscheinen nach der nächsten Aktualisierung jeder Quelle.

Ein leerer Tag ist eine gültige leere Liste. Die Antworten werden vom Server zwischengespeichert und beim Eintreffen neuer EPG-Daten automatisch aktualisiert.

Der integrierte Cache ist auf etwa tausend gleichzeitige Clients ausgelegt; bei größeren Installationen wird empfohlen, sowohl die XMLTV- als auch die JSON-Auslieferung hinter einem zwischenspeichernden Reverse-Proxy oder einem CDN zu betreiben.

Die Wiedergabe des DVR-Archivs anhand eines Sendeplan-Ereignisses (Parameter epg in der Wiedergabe-URL) ist in Archivwiedergabe (VOD) beschrieben.