Library Doctor für Jellyfin — Anleitung

Installation

Du brauchst Jellyfin Server 12.2 oder neuer und ein MediaLab-Works-Konto mit einer Lizenz, die das Plugin abdeckt (ein aktives Abonnement, eine Lifetime-Lizenz innerhalb ihres Update-Zeitraums, das Jellyfin-Paket oder den kostenlosen 30-tägigen Testzeitraum).

Über dein Plugin-Repository (empfohlen). Jellyfin installiert und aktualisiert das Plugin dann von selbst.

1. Öffne in deinem MediaLab-Works-Konto Lizenzen → Jellyfin-Plugin-Repository und klicke auf Adresse erstellen. Kopiere sie: Sie ist privat (sie enthält einen Token), teile sie also nicht; du kannst sie jederzeit neu erzeugen oder widerrufen.
2. Öffne in Jellyfin Dashboard → Erweiterungen → Repositories, klicke auf +, gib einen Namen ein (zum Beispiel MediaLab Works), füge die Adresse ein und speichere.
3. Finde im Dashboard → Erweiterungen → Katalog den Eintrag Library Doctor by MediaLab, klicke auf Installieren und starte Jellyfin neu.

Das Repository listet nur die Plugins, die deine Lizenzen abdecken, und nur die Versionen, die sie erlauben. Seine Download-Links sind signiert und laufen nach ein paar Stunden ab, deshalb liest Jellyfin immer eine frische Liste.

Über den öffentlichen Katalog. https://medialab.works/jellyfin/manifest.json listet jedes veröffentlichte MediaLab-Works-Plugin mit seinem öffentlichen Build; medialab Server fügt ihn von selbst hinzu. Du kannst ihn auf dieselbe Weise hinzufügen, um ein Plugin zu installieren, bevor du einen Schlüssel hast: Das Plugin fragt dann auf seiner Lizenzseite nach der Lizenz oder startet den Testzeitraum. Bei einer Lifetime-Lizenz, deren Update-Zeitraum endete, bleib bei deinem privaten Repository, das nur die Versionen anbietet, die deine Lizenz erlaubt.

Manuell aus einer Zip-Datei.

1. Lade in Konto → Lizenzen jf-librarydoctor_x.y.z.zip herunter (die SHA-256 der Datei steht neben dem Button).
2. Entpacke sie in einen neuen Ordner Library Doctor by MediaLab_x.y.z.0 im Jellyfin-Plugin-Ordner:
   • Linux (Paket): /var/lib/jellyfin/plugins/
   • Docker (offizielles Image): /config/plugins/ im Konfigurations-Volume
   • Windows: %ProgramData%\Jellyfin\Server\plugins\
3. Starte Jellyfin neu.

Lizenzaktivierung

1. Öffne die Plugin-Seite unter Dashboard → Erweiterungen → Library Doctor by MediaLab und klicke auf License.
2. Füge deinen Lizenzschlüssel ein und klicke auf Activate with key. Das Plugin kontaktiert den Lizenzserver, bindet den Schlüssel an diesen Jellyfin-Server und zeigt die Lizenz als Active an.
3. Noch kein Schlüssel? Gib auf derselben Seite deine E-Mail-Adresse ein und starte den kostenlosen 30-tägigen Testzeitraum (Karte erforderlich, heute nichts zu zahlen) oder kaufe eine Lizenz; das Plugin aktiviert sich, sobald die Zahlung erledigt ist.

Die Lizenz wird einmal am Tag und bei jedem Start von Jellyfin geprüft. Ohne Internet funktioniert das Plugin noch 7 Tage nach der letzten erfolgreichen Prüfung weiter. Ohne gültige Lizenz stoppt das Plugin seine Arbeit, und nur seine License-Seite funktioniert weiter (Testzeitraum, Schlüssel, Verlängerung); es wird nichts gelöscht, und alles läuft weiter, sobald die Lizenz wieder gültig ist. Move license (release this server) auf derselben Seite gibt den Schlüssel für einen anderen Server frei.

Updates und Rollback

• Aus dem Repository: Jellyfin zeigt neue Versionen unter Dashboard → Erweiterungen an und kann das Plugin automatisch aktualisieren; starte Jellyfin neu, um die neue Version zu laden.
• Über die Lizenzseite des Plugins: Mit gültiger Lizenz installiert Install update die neueste Version, die deine Lizenz erlaubt, und Roll back to x.y.z geht zur vorherigen Version zurück (zum Beispiel, wenn nach einem Update etwas nicht mehr funktioniert). Starte Jellyfin nach beidem neu. Beide Pakete werden gegen die Prüfsumme geprüft, die der Lizenzserver veröffentlicht.
• Eine Lifetime-Lizenz erhält die Versionen, die während ihres Update-Zeitraums erschienen sind; danach läuft das Plugin mit der letzten Version weiter, die es nutzen darf.
• Nach Roll back to x.y.z ist die automatische Aktualisierung von Jellyfin für dieses Plugin ausgeschaltet, bis zum nächsten Install update auf der Lizenzseite, damit die geplante Aufgabe Update Plugins (beim Start und täglich) die neuere Version nicht zurückholt.
• Lifetime-Lizenz und automatische Updates. Der öffentliche Jellyfin-Katalog (https://medialab.works/jellyfin/manifest.json) bietet immer die neueste Version an. Wenn der Update-Zeitraum einer Lifetime-Lizenz endete, sind später erschienene Versionen nicht lizenziert: Wenn Jellyfins automatische Plugin-Updates so eine Version installieren, stoppt das Plugin mit „version not licensed", bis du auf seiner Lizenzseite mit Roll back to x.y.z zurückgehst oder einen Update-Pass kaufst. Um das zu vermeiden, lass Jellyfin dieses Plugin nicht automatisch aktualisieren: Füge dein privates Plugin-Repository hinzu, das nur die Versionen anbietet, die deine Lizenz erlaubt, anstelle des öffentlichen Katalogs, oder entferne die Auslöser der geplanten Aufgabe Update Plugins unter Dashboard → Geplante Aufgaben (das stoppt automatische Updates für jedes Plugin).

Quellcode

Der GPL-3.0-Quellcode jeder Version liegt in Konto → Lizenzen (Quellcode) neben dem Download als .tar.gz-Archiv, erzeugt aus dem exakten Commit dieser Version.

Konfiguration

Öffne Library Doctor im Dashboard-Menü von Jellyfin (nur Administratoren). Es gibt nichts einzurichten: Die Seite liest deine Film- und Episoden-Mediatheken bei jedem Öffnen neu ein.

Bevor du die Quarantäne nutzt, gib Jellyfin Schreibzugriff auf die Mediathek-Ordner. Die Quarantäne legt einen Ordner .medialab-de-sters (rumänisch für „zu löschen") im Stamm jedes Mediathek-Ordners an und verschiebt Dateien aus ihren Ordnern, daher braucht der Benutzer, als der Jellyfin läuft (unter Linux meist jellyfin), Schreibrechte auf den Mediathek-Ordnern und den Ordnern darin. Unter Docker binde die Media-Volumes mit Lese- und Schreibrecht ein (ohne :ro). Alles andere im Plugin liest nur.

Tägliche Nutzung

1. Die Zahlen oben: Videodateien, Duplikatgruppen, der durch Duplikate freizugebende Platz, nicht zugeordnete Filme und die Gesamtgröße.

2. Duplikate: Jede Gruppe zeigt die Versionen, die beste zuerst, markiert als best (zuerst höhere Auflösung, dann HDR, dann ein effizienterer Codec — AV1, HEVC, VP9 —, dann Bitrate).

   • Filme werden über ihre TMDb- oder IMDb-ID verglichen, Episoden über Serie, Staffel und Episodennummer.
   • Filme ohne TMDb- oder IMDb-ID werden über Titel und Jahr verglichen. Ihre Gruppen sind markiert als by title and year (no metadata id) — check: Öffne beide und vergewissere dich, dass es wirklich derselbe Film ist, bevor du sie gruppierst oder einen in Quarantäne schiebst (ein Remake kann denselben Titel und manchmal dasselbe Jahr haben).
   • Group as versions behält alle Dateien und macht sie zu einem Titel mit Versionswahl bei der Wiedergabe (Jellyfins eigene Versionsgruppierung). Es wird keine Datei verschoben.
   • Quarantine fragt bei einer schwächeren Version nach Bestätigung und verschiebt diese Datei und ihre Begleiter in die Quarantäne (siehe unten).

3. Nicht zugeordnete Filme: Filme ohne Metadaten-ID. Klicke auf Open und nutze dann Identify in Jellyfin, um den richtigen Film auszuwählen; beim nächsten Öffnen der Seite ist er aus der Liste verschwunden.

4. Fehlende, defekte oder abgeschnittene Dateien: Klicke auf Check the files. Die Prüfung läuft im Hintergrund, Datei für Datei, und zeigt ihren Fortschritt; bei einer großen Mediathek dauert sie eine Weile, und du kannst die Seite verlassen. Für jede Datei prüft sie, dass die Datei existiert, liest sie mit ffprobe (maximal 30 Sekunden) und decodiert dann die letzten 3 Sekunden des Videos mit ffmpeg (maximal 60 Sekunden). Jedes Problem wird mit seiner Ursache gelistet:

   • fehlt auf der Festplatte;
   • nicht lesbar, mit der Fehlermeldung;
   • keine Videospur: das einzige „Video" ist ein Bild (Cover zählt nicht als Video), wie in einer Datei aus Zufallsbytes;
   • keine Dauer (defekter Header);
   • Dauer null;
   • das Ende fehlt (unvollständiger Download/Kopie): die letzten Sekunden lassen sich nicht decodieren. Eine Datei, die sehr nah am Ende abgeschnitten ist (zum Beispiel bei etwa 98 %), kann trotzdem bestehen, weil ihre letzten Sekunden noch decodierbare Bilder enthalten können.

   Das Ergebnis bleibt erhalten, bis Jellyfin neu startet.

5. Platz: der Platz nach Mediathek, nach Auflösung und nach Codec sowie die 20 größten Dateien, die kein Benutzer gesehen hat.

Die Quarantäne

• Was verschoben wird: die Videodatei und die Dateien im selben Ordner, deren Name mit demselben Namen gefolgt von . oder - beginnt — zum Beispiel Movie (2010).mkv mit Movie (2010).en.srt, Movie (2010).nfo und Movie (2010)-poster.jpg. Andere Dateien im Ordner bleiben, wo sie sind.
• Wohin: in .medialab-de-sters im Stamm des Mediathek-Ordners, der die Datei enthält, mit denselben Unterordnern (/media/movies/Movie (2010)/Movie (2010).mkv wird zu /media/movies/.medialab-de-sters/Movie (2010)/Movie (2010).mkv). Wenn sich im Quarantäne-Ordner bereits eine Datei desselben Namens befindet, kommt die neue in einen Unterordner mit eindeutigem Namen, damit nichts überschrieben wird.
• Wenn eine Verschiebung halb scheitert (zum Beispiel lässt sich eine Begleitdatei nicht verschieben): Die bereits verschobenen Dateien werden zurückgelegt, und eine durch eine unterbrochene Verschiebung zwischen Festplatten zurückgelassene Kopie in .medialab-de-sters wird entfernt, sodass du nie dieselbe Datei an zwei Orten hast. Lassen sich die Dateien auch nicht zurücklegen, bleibt der Eintrag in der Quarantine-Liste, und Restore holt das Verschobene zurück. Die Seite zeigt den Fehler.
• Nach der Verschiebung scannt Jellyfin die Mediathek neu, und die in Quarantäne geschobene Version verschwindet daraus; Jellyfin importiert den Ordner .medialab-de-sters nicht.
• Restore: Die Quarantine-Liste zeigt jeden Titel mit seinen ursprünglichen Pfaden und seiner Größe. Restore verschiebt die Dateien genau dorthin zurück, wo sie waren, und scannt die Mediathek neu. Wenn eine Datei sowohl in Quarantäne als auch an ihrem ursprünglichen Pfad liegt (weil du den Film zum Beispiel erneut hinzugefügt hast), wird die Wiederherstellung verweigert und nichts angefasst.
• Das endgültige Löschen überlässt es dir: Das Plugin löscht nie. Wenn du sicher bist, löschst du den Ordner .medialab-de-sters (oder die Dateien darin) von der Festplatte; erst dann wird der Platz frei.
• Die Liste der Quarantäne-Dateien liegt im Datenordner des Plugins und überlebt so einen Jellyfin-Neustart. Benenne den Ordner .medialab-de-sters nicht um und verschiebe ihn nicht, solange sich darin noch etwas befinden kann, das wiederhergestellt werden muss.

Fehlerbehebung

• Quarantine, Restore oder Group as versions zeigt „It could not be done": Die Meldung danach nennt den Grund.
• Quarantine schlägt fehl: Meist hat Jellyfin keinen Schreibzugriff auf den Mediathek-Ordner; siehe Konfiguration. Dateien außerhalb der Ordner deiner Jellyfin-Mediatheken und Dateien, die bereits in .medialab-de-sters liegen, werden ebenfalls abgelehnt.
• Restore schlägt fehl: Eine Datei liegt bereits am ursprünglichen Pfad (weil du den Film zum Beispiel erneut hinzugefügt hast). Verschiebe oder lösche diese Datei und stelle sie dann wieder her.
• Jede Datei wird als „nicht lesbar" gemeldet: ffprobe wurde nicht gefunden; installiere jellyfin-ffmpeg und prüfe seinen Pfad unter Dashboard → Wiedergabe → Transcodierung.
• Eine Gruppe, die als „by title and year — check" markiert ist, enthält zwei verschiedene Filme: Gruppiere oder quarantäniere nichts; identifiziere beide Filme in Jellyfin, und sobald sie ihre TMDb- oder IMDb-IDs haben, werden sie nicht mehr gruppiert.
• Ein Film ist zweimal in der Mediathek, taucht aber nicht unter Duplikaten auf: Die beiden Einträge haben verschiedene IDs, oder einer hat eine ID und der andere keine (identifiziere ihn dann).
• Eine Datei, die nicht abspielt, wird nicht gemeldet: Der Schaden kann in der Mitte der Datei liegen, was nicht geprüft wird, oder die Datei wurde sehr nah am Ende abgeschnitten.