CSV-Datei-Filterkomponente

Allgemeines

Dieses Plugin ermöglicht die Erstellung einer Filterkomponente, deren Filterinformationen aus einer CSV-Datei gelesen werden. Die resultierende Filterkomponente stellt somit eine offnen Schnittstelle für beliebige Fremdsysteme dar.

Diese Filterkomponente basiert auf den Überlegungen, die im Artikel BeanShell-Filter unter dem Punkt Dynamischer BeanShell-Filter als CSV-File-Interface ausgeführt werden. Die hier vorgestellte Filterkomponente stellt eine erweiterte und hinsichtlich der Performance optimierte Variante des dort vorgestellten BeanShell-Skriptes in Form eines Plugins dar.

Funktionsweise

Die CSV-Datei-Filterkomponente ließt Informationen aus dem Datensatz einer CSV-Datei aus und vergleicht diese mit den entsprechnden Informationen einer Sendung im Datenbestand des TV-Browsers.

Installation

Für die Installation des Plugins folgt man den diesbezüglichen Anweisungen im Artikel Plugin.

Erstellung einer CSV-Datei-Filterkomponente

Die Erstellung einer CSV-Datei-Filterkomponente erfolgt gemäß der Beschreibung zur Erstellung von Filterregeln. Hierzu muss aus der entsprechenden Liste der Typ CSV-Datei ausgewählt und anschließend der Pfad zur jeweiligen CSV-Datei angegeben werden. Das folgende Schaubild verdeutlicht diese Konfiguration an einem Beispiel.

Nach einen Doppelklick mit der linken Maustaste auf das Eingabefeld öffnet sich ein Fenster für die Auswahl einer CSV-Datei. Die Bestätigung der Auswahl erfolgt über den Schalter Öffnen.

Relativer Pfad zur CSV-Datei

Die Pfade zu den jeweiligen CSV-Dateien werden als relative Pfade bezüglich des TV-Browser-Hauptverzeichnisses angelegt.

Konventionen

Bei der Bereitstellung einer CSV-Datei, die von der CSV-Filter-Komponente eingelesen werden soll, sind bestimmte Konventionen zu beachten.

Kodierung der CSV-Datei

Bei der Erstellung der CSV-Datei muß die Kodierung UTF-8 verwendet werden.

Aufbau der CSV-Datei

Die CSV-Datei-Filterkomponente erwartet eine CSV-Datei mit einem definierten Aufbau.

Einfachen Format

Das einfache Format bietet neben dem Schlüsselfeld SENDUNGSTITEL nur das Feld INFO für die Hinterlegung in der CSV-Datei an.

Hinweis:

Dieses Format wird nach der Einführung des erweiterten Formates zunächst weiterhin von der CSV-Datei-Filterkomponente unterstützt. Dies soll allen Usern genug Zeit einräumen, auf das erweiterte Format zu wechseln. Langfristig ist geplant, dieses Format vollständig durch das erweiterte Format zu ersetzen. Daher wird allen Usern empfohlen, sich rechtzeitig mit dem erweiterten Format vertraut zu machen.

Separator:

In der CSV-Datei werden die Datenfelder durch ein Semikolon ";" getrennt. Zeilen ohne den Trenner Semikolon werden ignoriert.

Datenfelder:

Die CSV-Datei enthält folgende Datenfelder

Feld	Beschreibung
SENDUNGSTITEL	Titel der Sendung
INFO	Info zur Sendung

Datensätze:

Ein Datensatz in der CSV-Datei wird von der CSV-Datei-Filterkomponente in folgender Form erwartet.

SENDUNGSTITEL;INFO

Erweitertes Format

Im erweiterten Format werden die einzelnen Kenngrößen in separate Felder geschrieben.

Hinweis:

Das einfache Format wird nach der Einführung des erweiterten Formates zunächst weiterhin von der CSV-Datei-Filterkomponente unterstützt. Dies soll allen Usern genug Zeit einräumen, auf das erweiterte Format zu wechseln. Langfristig ist geplant, dieses Format vollständig durch das erweiterte Format zu ersetzen. Daher wird allen Usern empfohlen, sich rechtzeitig mit dem erweiterten Format vertraut zu machen.

Separator:

In der CSV-Datei werden die Datenfelder durch ein Semikolon ";" getrennt. Zeilen ohne den Trenner Semikolon werden ignoriert.

Datenfelder:

Die CSV-Datei enthält folgende Datenfelder

Feld	Beschreibung
SENDUNGSTITEL	Titel der Sendung
EPISODENTITEL	Titel der Episode
STAFFELNUMMER	Nummer der Staffel
EPISODENNUMMER	Nummer der Episode
SPRACHE	Spreche der Sendung
PRODUKTIONSJAHR	Produktionsjahr der Sendung
INFO	Info zur Sendung

Datensätze:

Ein Datensatz in der CSV-Datei wird von der CSV-Datei-Filterkomponente in folgender Form erwartet.

SENDUNGSTITEL;EPISODENTITEL;STAFFELNUMMER;EPISODENNUMMER;SPRACHE;PRODUKTIONSJAHR;INFO

Anleitung zur Umstellung vom einfachen zum erweiterten Format:

Um die vollständige Kompatibilität der Formate zu gewährleisten, werden alle Daten des Feldes INFO des einfachen Formates in das Feld INFO des erweiterten Formates übertragen. Die Behandlung des Feldes INFO erfolgt exakt wie die des ursprünglichen Feldes INFO.

Die Umstellung kann folgendermaßen durchgeführt werden:

• Anlegen einer Kopie der CSV-Datei (empfohlen)
• Ersetzen das Zeichen ";" durch ";;;;;;" in der gesamten CSV-Datei in einem Texteditor. Dies führt zu einem Umstellungsformat.
• Übertragung der Daten vom Feld INFO in die entsprechenden neuen Felder (ab Version 1.1.6.0)

Bitte hinterlaßt eine kurze Nachrciht !!!

Mit der Version 1.1.5.0 wird ein erweitertes Format für die CSV-Datei eingeführt. Das einfache Format wird zwar weiterhin unterstützt, aber langfristig ist geplant, das einfache Format vollständig durch das erweiterte zu ersetzen. Um den geeigneten Zeitpunkt für die Einstellung der Unterstützung des einfachen Formates zu finden, wäre es hilfreich, zu wissen, wieviele Nutzer bereits auf das neue Format umgestellt haben. Im Forum können alle, die das Format bereits umgestellt haben, eine kurze Nachricht hinterlassen. Die Anzahl dieser Nachrichten kann dann leicht mit der aktuellen Anzahl der Downloads abgeglichen werden. Natürlich wird die Einstellung des einfachen Formates rechtzeitig kommuniziert.

Informationen in einem Datensatz

Die CSV-Datei-Filterkomponente behandelt alle Sendungen wie eine Episode einer Serie. Gehört eine Sendung zu einer Serie, so enthält sie standardmäßig die Informationen Sendungstitel1 und Episodentitel1. Auf diesbezügliche Ausnahmen wird im folgenden Abschnitt eingegangen. Eine solche Sendung wird standardmäßig in Abhängigkeit vom verwendeten Format in der CSV-Datei wie folgt hinterlegt.

Einfaches Format:

Sendungstitel1;Episodentitel1

Erweitertes Format mit Hinterlegung im Feld INFO (Umstellungsformat):

Sendungstitel1;;;;;;Episodentitel1

Erweitertes Format:

Sendungstitel1;Episodentitel1;;;;;

Gehört eine Sendung nicht zu einer Serie (z. B. Spielfilm, Dokumentation etc.), so enthält sie nur die Informationen Sendungstitel2. Eine solche Sendung wird von der CSV-Filter-Komponente als Serie mit nur einer Episode interpretiert. Somit entspricht im Standardfall der Episodentitel dem Sendungstitel. Auf diesbezügliche Ausnahmen wird im folgenden Abschnitt eingegangen. Die Hinterlegung einer solchen Sendung erfolgt in der CSV-Datei in Abhängigkeit vom verwendeten Format standardmäßig auf folgende Weise.

Einfaches Format:

Sendungstitel2;Sendungstitel2

Erweitertes Format mit Hinterlegung im Feld INFO (Umstellungsformat):

Sendungstitel2;;;;;;Sendungstitel2

Erweitertes Format:

Sendungstitel2;Sendungstitel2;;;;;

Hinweis:

Die CSV-Datei-Filterkomponnete berücksichtigt auch den Ausnahmefall, in dem eine Serie im TV-Browser nicht explizit als Serie gekennzeichnet ist

Gleicher Sendungstitel für Serie und Film

In Ausnahmefällen kann ein Sendungstitel sowohl eine Serie als auch einen Film repräsentieren. Die CSV-Datei-Filterkomponente erkennt eine solche Situation und unterscheidet automatisch zwischen der Serie und dem Film. In diesem Fall können die entsprechenden Sendungen in der CSV-Datei in Abhängigkeit vom verwendeten Format folgendermaßen hinterlegt werden:

Einfaches Format:

Sendungstitel3;Episodentitel3
Sendungstitel3;Episodentitel4 
Sendungstitel3;Sendungstitel3

Erweitertes Format mit Hinterlegung im Feld INFO (Umstellungsformat):

Sendungstitel3;;;;;;Episodentitel3
Sendungstitel3;;;;;;Episodentitel4
Sendungstitel3;;;;;;Sendungstitel3

Erweitertes Format:

Sendungstitel3;Episodentitel3;;;;;
Sendungstitel3;Episodentitel4;;;;; 
Sendungstitel3;Sendungstitel3;;;;;

Informationen in den Datenfeldern

Die Datenfelder in der CSV-Datei werden von der CSV-Datei-Filterkomponnete in Abhängigleit vom verwendeten Format mit den entsprechnden Feldern im TV-Browser abgeglichen. Dies ist bei der Erstellung der CSV-Datei zu beachten.

Informationen in den Datenfeldern des einfachen Formates

Erläuterungen zu den Informationen in den Datenfeldern des einfachen Formates findet man hier.

Informationen in den Datenfeldern des erweiterten Formates

Erläuterungen zu den Informationen in den Datenfeldern des erweiterten Formates findet man hier

Übersicht der Hinterlegungen

In den vorhergehenden Abschnitten wurden die möglichen Hinterlegungen für die Datenfelder in der CSV-Datei in Abhängigkeit von der Hinterlegung der Sendung im TV-Browser ausführlich behandelt. Die folgende Aufstellung fasst diese Hinterlegungen zur besseren Übersicht zusammen. Dies soll zur Erleichterung der korrekten Hinterlegung in der CSV-Datei beitragen. Hierbei entspricht die Reihenfolge der Fälle der des in der CSV-Datei-Filterkomponente verwendeten Matching-Modells mit den entsprechnden Matching-Modi.

Übersicht der Hinterlegungen im einfachen Format

Ein Übersicht der Hinterlegungen im einfachen Format findet man hier.

Übersicht der Hinterlegungen im Feld INFO im erweiterten Format

Eine Übersicht der Hinterlegungen im Feld INFO im erweiterten Format findet man hier.

Übersicht der Hinterlegungen im erweiterten Format (In Bearbeitung, ab Version 1.1.6.0)

Eine Übersicht der Hinterlegungen im erweiterten Format findet man hier.

Beispiel einer CSV-Datei

Eine gemäß den obigen Konventionen bereitgestellte CSV-Datei sieht in Abhängigkeit vom verwendeten Format wie folgt aus.

Einfaches Format:

Sendungstitel1;Episodentitel1   <-- Die Sendung gehört zu einer Serie
Sendungstitel1;Episodentitel2
Sendungstitel2;Sendungstitel2   <-- Die Sendung gehört nicht zu einer Serie (z. B. Spielfilm, Dokumentation etc.)
Sendungstitel3;Episodentitel3   <--|
Sendungstitel3;Episodentitel4   <--|--- Der Sendungstitel gehört sowohl zu einer Serie als auch zu einem Film
Sendungstitel3;Sendungstitel3   <--|
Sendungstitel4;Episodentitel5
Sendungstitel4;Episodentitel6  
Sendungstitel4;Episodentitel7  

Erweitertes Format mit Hinterlegung im Feld INFO (Umstellungsformat):

Sendungstitel1;;;;;;Episodentitel1   <-- Die Sendung gehört zu einer Serie
Sendungstitel1;;;;;;Episodentitel2
Sendungstitel2;;;;;;Sendungstitel2   <-- Die Sendung gehört nicht zu einer Serie (z. B. Spielfilm, Dokumentation etc.)
Sendungstitel3;;;;;;Episodentitel3   <--|
Sendungstitel3;;;;;;Episodentitel4   <--|--- Der Sendungstitel gehört sowohl zu einer Serie als auch zu einem Film
Sendungstitel3;;;;;;Sendungstitel3   <--|
Sendungstitel4;;;;;;Episodentitel5
Sendungstitel4;;;;;;Episodentitel6  
Sendungstitel4;;;;;;Episodentitel7  

Erweitertes Format:

Sendungstitel1;Episodentitel1;;;;;   <-- Die Sendung gehört zu einer Serie
Sendungstitel1;Episodentitel2;;;;;
Sendungstitel2;Sendungstitel2;;;;;   <-- Die Sendung gehört nicht zu einer Serie (z. B. Spielfilm, Dokumentation etc.)
Sendungstitel3;Episodentitel3;;;;;   <--|
Sendungstitel3;Episodentitel4;;;;;   <--|--- Der Sendungstitel gehört sowohl zu einer Serie als auch zu einem Film
Sendungstitel3;Sendungstitel3;;;;;   <--|
Sendungstitel4;Episodentitel5;;;;;
Sendungstitel4;Episodentitel6;;;;;  
Sendungstitel4;Episodentitel7;;;;;  

Anwendung

In diesem Abschnitt werden einige Möglichkeiten zur Anwendung der CSV-Datei-Filterkomponenrte aufgezeigt.

Hinweis:

Bei der Verwendung einer CSV-Datei-Filterkomponente in einem Filter ist, nach einer Modifikation der zu Grunde liegenden CSV-Datei, für die Aktualisierung der Darstellung der Filterinfomationen im TV-Browser eventuell ein Neustart des TV-Browsers erforderlch.

Offene bidirektionale Schnittstelle

Die vorgestellte CSV-Datei-Filterkomponente kann in Kombination mit den Plugins Filter-Info-Icons und SwitchPlugin zur Konfiguration einer offenen bidirektionalen Schnittstelle verwendet werden.

Informationen zu Sendungen bereitstellen

Im Beispiel zur Konfiguration einer offenen bidirektionalen Schnittstelle, wird aus einer CSV-Datei die Information bereitgestellt, ob eine Sendung in einer Mediathek enthalten ist oder nicht. Über die CSV-Datei-Filterkomponente können aber auch andere Informationsmerkmale zu Sendungen bereitgestellt werden. Hierzu muß eine CSV-Datei mit den Sendungen gefüllt werden, die das Merrkmal tragen. Anschließend folgt man der im Artikel Konfiguration einer offenen bidirektionalen Schnittstelle vorgestellten Vorgehensweise. Das folgende Beispiel soll helfen, dies zu verdeutlichen.

Erstausstrahlungen und Wiederholungen

Um anzuzeigen, ob eine Sendung eine Erstausstrahlung ist, wird Im TV-Browser die zusätzliche Informtaion Neu verwendet. Die Information, ob eine Sendung eine Wiederholung ist, wird über den ProgramFieldType im Feld REPETITION_OF_TYPE angezeigt. Leider sind diese Informationen nicht immer für alle Sendungen verfügbar. Daher läßt sich im TV-Browser nicht immer eindeutig bestimmen, ob eine Sendung eine Erstausstrahlung bzw. Wiederholung ist oder nicht.

Dieses Problem kann mittels der CSV-Datei-Filterkomponente gelößt werden. Hierzu muß eine CSV-Datei mit den Sendungen gefüllt werden, deren Erstausstrahlungsdatum in der Zukunft liegt. Die Sendungen, die nicht in dieser Datei aufgeführt werden, sind folglich Wiederholungen. Das Datum der Erstausstrahlung einer Sendung kann hierzu aus einer externen Datenquelle wie z. B. der freien Datenbank TheTVDB ausgelesen werden. Zur Anzeige im TV-Browser folgt man wieder der übliche Vorgehensweise.

Anbindung an externe Datenquellen

Die CSV-Datei-Filterkomponente kann zur Anbindung des TV-Browsers an externe Datenquellen genutzt werden. Hierbei sind inbesondere freie Datenbanken wie z. B. TheTVDB, AniDB oder TVRage von Interesse, da diese umfangreiche TV-Daten verwalten. Für die Kommunkation mit diesen Datenbanken kann z. B. das FileBot CLI verwendet werden.

Performance

Dieses Plugin wurde hinsichtlich der Performance optimiert. Diese Optimierung wurde aus technischer Sicht hauptsächlich durch die Minimierung der Lesezugriffe auf die CSV-Datei und das Laden der Daten aus der CSV-Datei in den Arbeitspeicher erreicht. Somit kommt es bei der Arbeit mit CSV-Dateien, die eine große Anzahl von Datensätzen enthalten, zu einer erhöhten Auslastung des Arbeitsspeichers. Daher ist die Performance vom vefügbaren Arbeitsspeicher abhängig. Für Details sei auf den Quellcode im Plugin-Paket verwiesen.

Diesbezügliche Tests wurden mit Dateien durchgeführt, die bis zu 100.000 Datensätzen enthielten. Diese Tests führten bei einem Arbeitsspeicher von 3 GB zu guten Ergebnissen.

Versionen

Eine Übersicht der Versionen des Plugin findet man hier.