TV-Daten Tutorial
Inhaltsverzeichnis
Voraussetzungen
Bevor man mit diesem Tutorial anfangen kann, sollte man zuerst noch sicherstellen, das man folgende Tools installiert hat:
- Apache Ant
- JDK 5 oder höher (also die Entwickler-Version von Java), zu finden unter http://java.sun.com
- Das TV-Daten Starterkit muss runtergeladen und entpackt werden.
Einleitung
Achtung: Bevor man TV-Daten anbietet, müssen die Rechteinhaber der Daten vorher natürlich die Veröffentlichung in dieser Form genehmigt haben!
Danke, dass du dir dieses Tutorial durchliest. Das zeigt, dass du Interesse hast am Anbieten von TV-Daten. Das ganze ist auch nicht wirklich schwer. Man muss nur die Daten in XML wandeln können (oder ein kleines Java-Programm schreiben) und drei Tools laufen lassen.
Diese drei Tools sind:
- PDSRunner, ein Tool zum konvertieren der Daten in das TVBrowser-Format und legt diese in dem "raw"-Verzeichnis ab.
- PrimaryDataManager, dieses Tool erzeugt Diff-Dateien und legt diese im "prepared"-Verzeichnis ab. Die TV-Browser wissen, welche Version einer Datei lokal vorliegt und laden dann die Diff-Dateien mit den Unterschieden zur aktuellen Version. Dies verhindert, das komplette Tagesprogramme mehrfach runtergeladen werden müssen und sparen so eine große Zahl an zu übertragenen MBs.
- MirrorUpdater, ein Tool das die Dateien auf die eigentlichen Server hochlädt
In diesem Beispiel werden wir eine XML-Datei konvertieren die in dem Verzeichnis input liegt. In dieser Datei sind einige Beispiel-Einträge vorhanden, die aufzeigen sollen, wie die Datei auszusehen hat.
PDSRunner
Um die XML-Datei in das TV-Browser-Format zu konvertieren, muss folgendes in der Kommadozeile eingegeben werden:
ant pdsrunner -Dpdsclasses=XmlTvPDS
Jetzt wird die Klasse XmlTvPDS kompiliert und danach die Xml-Datei konvertiert. Nach diesem Schritt sollte im Verzeichnis raw eine neue Datei 2008-09-10_de_test24_raw_full.prog.gz vorhanden sein.
Man kann hier auch meherere PDS mit Komma getrennt angeben.
Sollten wider Erwarten Fehler auftreten, befindet sich nach Ende des Programmes in dem Verzeichnis pdslog eine Datei mit einer Fehlermeldung.
Um zu überprüfen, ob der Inhalt der Datei korrekt ist, gibt es ein Tool namens "DayProgramFileTranslator". Um es zu starten, einfach
ant dayprogramfiletranslator
ausführen. Jetzt ist ein neues Verzeichnis vorhanden namens raw/txt. Dort sind Text-Dateien mit dem Inhalt der .prog.gz-Dateien und .bin-Dateien mit Jpegs der Bilder, sollten Bilder vorhanden sein.
PrimaryDataManager
Gruppen
Damit der TV-Browser die vielen Sender von unterschiedlichen Anbietern unterscheiden kann, gibt es ein Gruppen-System. Jeder Anbieter kann mehrere Gruppen mit Sendern anbieten. Dabei ist der Name der Gruppe eindeutig. Der Name der Gruppe kann Buchstaben von A-Z und a-z und Zahlen enthalten.
Folgende Gruppen-Namen sind also gültig:
- BodosLokaleSender3
- SenderDesOstens
Folgende Gruppen-Namen sind ungültig:
- Bodo's Lokale Sender 3 (Keine Leerzeichen und ' erlaubt)
- Ausländische_Sender (Keine Umlaute und _ erlaubt)
In jeder Gruppe können beliebig viele Sender vorhanden sein. Jeder Sender hat dabei ebenfalls eine ID, die den selben Regeln folgt. Diese ID wird auch in der XML-Datei benutzt als Attribut "channel". Channel darf also keine Leerzeichen oder Umlaute enthalten. Aber keine Angst, die Umlaute und Leerzeichen werden auf andere Wege angegeben.
<programme channel="test24" [...]
Ein Sender ist immer eindeutig durch die Kombination von Gruppe+Sender-ID, das bedeutet es kann mehrere Sender mit der ID fox geben in unterschiedlichen Gruppen. Den Gruppen-Namen und die Sender-ID sollte man allerdings sehr sorgfältig wählen, diese können nicht mehr geändert werden, sobald Nutzer diese Sender abonniert haben. Sollte der Sender seinen Namen ändern, sollte die Sender-ID bestehen bleiben, damit die Nutzer den Sender nicht neu einstellen müssen.
Konfiguration
Damit eine Gruppe funktioniert, gibt es drei Dateien, die gefüllt werden müssen. Das TV-Daten Starterkit liefert eine Test-Gruppe namens myfirstgroup mit. Für diese gibt es im config-Verzeichnis schon Beispiel-Dateien.
Diese Dateien haben alle das Windows-Encoding ISO-8859-15, wenn du nicht unter Windows arbeitest, berücksichtige dies bitte in deinem Text-Editor.
Der Name der Dateien beginnt immer mit dem Gruppen-Namen, in unserem Fall beginnen also alle Dateien mit myfirstgroup.
myfirstgroup.txt
In dieser Datei wird der Name und die Beschreibung der Gruppe angegeben. Da der TV-Browser in Zukunft auch International an Bedeutung gewinnt, muss dies in Deutsch und in Englisch geschehen. Damit die Gruppe einer Person zugewiesen werden kann, und nicht "anonym" ist, kann der eigene Name in der Provider-Zeile angegeben werden.
myfirstgroup_mirrorlist.txt
In dieser Datei muss angegeben werden, auf welchen Servern diese Sendergruppe zu finden ist, damit der TV-Browser diese auch laden kann. Hierbei kann man pro Zeile einen Server angeben. Neben der URL des Verzeichnisses, in dem die Dateien liegen, muss noch mit einem ";" getrennt die Priorität des Servers eingestellt werden. Sollten alle Server gleich stark genutzt werden, sollte man hier "50" angeben.
Der TV-Browser addiert alle Zahlen einer Sendergruppe zusammen und errechnet daraus eine Wahrscheinlichkeit und nutzt diese bei dem "Auswürfeln" des zu nehmenden Servers. Sollte ein Server nicht erreichbar sein, wird ein weiterer aus der Liste genommen. Findet der TV-Browser keinen Server aus dieser Liste, bekommt der Nutzer eine Fehlermeldung, das für diese Sendergruppe kein Server bereit steht.
myfirstgroup_channellist.txt
Diese Datei ist die wichtigste Datei im Config-Verzeichnis. Hier wird eingestellt, welche Sender in dieser Gruppe vorhanden sein sollen und wie diese heißen und aussehen sollen. Jede Zeile hat dabei folgende Felder:
land;zeitzone;senderID;sendername;copyright;sender-url;icon-url;senderkategorie;Name in HTML;länder;zweiter-sender
Nur die ersten fünf Felder sind zwingend, der Rest ist optional.
- land: Zweistelliger Landescode ISO 3166
- zeitzone: Zeitzone des Senders, z.B. CET oder GMT+01 (bei GMT+/-X wird Sommerzeitumstellung nicht berücksichtigt!)
- senderID: ID des Senders, die auch in der XML-Datei definiert ist
- sendername: So wie der Name im TV-Browser angezeigt werden soll.
- copyright: Dieser Text wird unter dem Sender angezeigt, z.B: (c) ZDF
Ab hier optional (um aber z.B. das dritte optionale Feld angeben zu können, müssen die vorherigen 2 angegeben seien):
- sender-url: Webseite des Senders, z.B. http://www.zdf.de
- icon-url: URL des Senderlogos, z.B. http://www.meinesender.de/logos/zdf.png
- senderkategorie: Dies ist eine Nummer, hinter der sich die Kategorie des Senders verbirgt. Diese Nummer kann man hier berechnen lassen. Z.B. 81 für einen digitalen Sport-TV-Sender
- Name in HTML: Da diese Konfigurations-Datei in ISO-8849-15 ist, mussten wir auf HTML ausweichen, um Russische Zeichen in Sendernamen darstellen zu können. Um abwärts kompatibel zu bleiben ist dies nur optional, alte TV-Browser (<2.7) zeigen den ersten Sendernamen an
- NEU (ab V.3.2.2) länder: Für Sender die mehreren Ländern zugeordnet werden können (z.B. 3sat), können diese hier noch mit "$" getrennt angegeben werden (z.B. at$de$ch)
- NEU (ab V.3.2.2) zweiter-sender: Wenn zwei Sender fest zusammengehören, also immer auf selben Kanal abwechselnd senden (z.B. Nick und Comedy Central, kann hier die id des 2. Senders angegeben werden, damit sie im TVB zusammengefasst werden können.
Z.B.:
de;CET;ard;ARD;(c) by DasErste/TV-Browser;http://www.ard.de;http://www.tvbrowser.org/icons/ard01.gif;3 de;CET;rtl;RTL;;;;4 de;CET;superrtl;SuperRTL de;MET;zdf;ZDF;(c) by ZDF/TV-Browser de;MET;vox;Vox;(c) by Vox;http://www.vox.de
Start
Um die Update-Dateien zu erzeugen, muss folgender Befehl ausgeführt werden:
ant primarydatamanager -Dgroups=myfirstgroup
dies erzeugt für die Sendergruppe "myfirstgroup" die Dateien. Dafür müssen die oben beschriebenen Dateien zwingend vorhanden sein. Man kann auch mit Komma getrennt mehrere Sendergruppen zeitgleich erzeugen lassen.
Nach dem Aufruf sind im prepared-Verzeichnis .prog.gz-Dateien. Sollte ein Tag aktualisiert worden sein, finden sich dort auch _update-Dateien. Dieses Verzeichnis darf nicht verloren gehen und ist sehr wichtig für die Funktion des Mirrors.
Wenn ein Tag zu stark geändert worden ist, wird dieses im prepared-Verzeichnis in ein quarantine-Verzeichnis geschoben und am Ende des Erzeugens wird eine entsprechende Warnung angezeigt. Danach kann man diese Datei dann mit Hilfe des dayprogramfiletranslators nach Text konvertieren und kontrollieren. Sollte die Datei in Ordnung sein, kann man diese aus dem quarantine-Ordner in den prepared-Ordner verschieben.
MirrorUpdater
Als letztes müssen die Dateien noch auf den Server kopiert werden, dies macht der MirrorUpdater. Dieser kann auf zwei Weisen benutzt werden. Entweder lädt er die Dateien direkt per FTP auf einen Server oder in ein Verzeichnis das man selber auf die Server kopiert (z.B. per Sitecopy).
Der MirrorUpdater wird über die Datei MirrorUpdater.ini im config-Verzeichnis konfiguriert. Die Datei ist relativ selbst erklärend.
Hier eine Beispiel-Konfiguration für FTP:
dataSource.type=file dataSource.dir=prepared dataTarget.type=ftp dataTarget.url=members.meinprovider.de dataTarget.path=myhome/tvdata dataTarget.user=myusername dataTarget.password=vollgeheim groups = myfirstgroup
oder um die Daten in ein Verzeichnis namens mirror zu speichern mit mehreren Gruppen:
dataSource.type = file dataSource.dir = prepared dataTarget.type = file dataTarget.dir = mirror groups = myfirstgroup:mysecondgroup:mythirdgroup # The weight of your mirror (100 = normal, 0 = the mirror won't be used) mirror.weight = 100
Den MirrorUpdater startet man mit
ant mirrorupdater -Dgroups=myfirstgroup
Der TV-Browser kontrolliert allerdings, ob der Server noch aktuell ist, dafür kontrolliert er das Datum in der Datei gruppe_lastupdate. Ist das Datum älter als 5 Tage, wird dieser Server nicht mehr berücksichtigt und ein neuer Server gesucht. Sollte kein aktueller Server vorhanden sein, wird dem Nutzer eine Warnung angezeigt.
Daten in den TV-Browser laden
Um die Daten im TV-Browser zu sehen, kann man in den Einstellungen der TVDaten-Services die eigene Gruppe hinzufügen. Die URL, die anzugeben ist, baut sich aus der Adresse des Webservers + des Gruppennamens zusammen. Z.B.: http://members.meinprovider.de/myfirstgroup
Sollten die Daten korrekt sein und eine Erlaubnis des Senders vorliegen, diese Daten zu veröffentlichen, kann man diese auf der Webseite im Entwickler-Bereich anmelden. Nach einer Freigabe durch das TV-Browser-Team ist die Sendergruppe dann für alle Nutzer automatisch verfügbar. Der TV-Browser schaut regelmäßig nach neuen Sendergruppen und Sendern und informiert die Nutzer entsprechend.
Nach der Anmeldung der Sendergruppe wird 2x täglich die Erreichbarkeit der Sendergruppe geprüft und eine EMail verschickt, sollte der Server nicht erreichbar oder veraltet sein. Sollte der Server zu lange nicht erreichbar sein, wird die Sendergruppe gesperrt. Dann solltest du dich mit uns in Verbindung setzen zum Entsperren der Gruppe.
Eigene PDS schreiben
Um mehr Flexibiltät zu besitzen, kann man auch einen eigenen PDS schreiben, der eine Webseite oder Text-Dateien ausliest. Ein Beispiel hierfür ist dem Datenkit schon beigelegt in der Form des SimplePDS. Dies sollte erste Anhaltspunkte liefern für die Implementierung dieser Klasse.
