Files

T

CI / pruefen (pull_request) Canceled after 0s

Details

Unbekannte Jellyfin-Titel zur Auswahl stellen und nachladen

Der Abgleich ordnete nur gegen Titel zu, die Flimmer schon kannte. Auf einer
frisch aufgesetzten Instanz meldet Jellyfin damit tausend Eintraege und
Flimmer ordnet keinen einzigen zu — der Bericht konnte nur aufzaehlen, was er
nicht einsortieren konnte.

Aus dem Bericht wird eine Auswahlliste: anhaken, was uebernommen werden soll,
und nur das aus TMDB nachladen. Ein pauschales Haekchen waere bei tausend
Eintraegen keine Wahl gewesen — in einer Mediathek liegen Konzertmitschnitte
neben dem, was man wirklich verfolgt.

Der Bericht ist dafuer umgebaut:

- Zusammengefasst je TMDB-Kennung. Jellyfin fuehrt oft mehrere Dateien zum
  selben Film; in der Liste steht er einmal, mit der Zahl der Dateien.
- Die Grenze stand bei 50 und war bei ueber tausend gelesenen Eintraegen ein
  Blick durchs Schluesselloch. Jetzt 1000, und was darueber hinausgeht, wird
  gezaehlt statt stillschweigend abgeschnitten.
- Der Typ kommt aus dem Item statt aus dem Umkehrschluss "keine Episode, also
  Film". Eine Probe zeigte sonst eine Serie als Film.

Nachgeladen wird nur auf Klick, hoechstens hundert je Lauf, und ein einzelner
Fehlschlag beendet den Lauf nicht. Aus der Liste verschwindet nur, was
tatsaechlich ankam: ein Fehlschlag laesst den Eintrag stehen, damit man es
erneut versuchen kann, ohne den ganzen Abgleich zu wiederholen. Mein erster
Entwurf strich auch Gescheiterte — der Test hielt das falsche Verhalten fest
und wurde mitkorrigiert.

Eintraege ohne TMDB-Kennung bleiben sichtbar, aber nicht auswaehlbar: dort
fehlt die Kennung in Jellyfin selbst, da kann Flimmer nichts holen.

Fuenf Tests dazu. Der Importschritt selbst laesst sich lokal nur ueber die
Domaenenschicht pruefen — der Entwicklungs-Stub speist sich aus dem Katalog
und kann per Definition nichts liefern, was dort fehlt. Der Klickweg belegt
Liste, Entdopplung, Suche, Auswahl, die gesperrten Zeilen und die ehrliche
Fehlermeldung.

Refs #16

2026-09-02 13:12:19 +02:00

20 KiB

Raw Blame History

Flimmer — Anleitung

Diese Anleitung führt einmal durch die ganze Anwendung: vom ersten Konto über das tägliche Abhaken bis zu Universen, Statistik und Schnittstelle.

Die Bilder stammen aus einer Instanz mit Beispieldaten (npm run db:seed). Die Poster darin sind erfunden — mit hinterlegtem TMDB-Schlüssel stehen dort die echten.

Inhalt

Erster Start
Die Übersicht
Titel finden und aufnehmen
Eine Serie verfolgen
Hab ich — die eigene Sammlung
Die Bibliothek
Universen
Kalender
Statistik
Einstellungen
Benachrichtigungen
Import und Export
API-Schlüssel
Papierkorb
Verwaltung
Öffentliches Profil
Auf dem Handy
Helles Farbschema

Erster Start

Nach der Installation ruf die Adresse deiner Instanz auf. Solange es noch kein einziges Konto gibt, ist die Registrierung offen — der erste Zugang wird automatisch Administrator. Lege ihn also gleich für dich an.

Danach kannst du die Registrierung in der Verwaltung schließen, damit sich niemand sonst anmeldet.

Ist SSO eingerichtet (OIDC_* in der .env), erscheint hier zusätzlich ein Knopf für die Anmeldung über den eigenen Anbieter.

Die Übersicht

Die Startseite beantwortet drei Fragen:

Weiterschauen — welche Serien laufen gerade, und welche Episode ist als Nächstes dran. Der Knopf +1 Episode hakt genau diese Folge ab; du musst die Serie dafür nicht öffnen.
Demnächst — welche Episoden deiner Serien in den nächsten vier Wochen ausgestrahlt werden.
Neu verfügbar — welche Titel von deiner Watchlist zuletzt auf einem Streamingdienst in deiner Region aufgetaucht sind.

Ist die Bibliothek noch leer, steht hier stattdessen der Weg zur Suche.

Titel finden und aufnehmen

Über Suchen durchsuchst du TMDB. Die Treffer lassen sich auf Alles, Serien oder Filme eingrenzen; die Suchanfrage steht in der Adresszeile und ist damit teilbar.

Ein Klick auf einen Treffer holt die vollständigen Daten — bei Serien alle Staffeln und Episoden — und öffnet die Detailseite. Von dort nimmst du den Titel auf, wahlweise als Ich schaue das gerade oder Auf die Watchlist.

Nichts dabei? Unter Titel selbst anlegen trägst du etwas ein, das TMDB nicht kennt — Heimvideos, Vorträge, regionale Produktionen. Solche Titel werden vom automatischen Abgleich nie angefasst.

Eine Serie verfolgen

Die Detailseite ist der Ort, an dem du eine Serie führst:

Fortschrittsbalken mit gesehenen Episoden und verbleibender Laufzeit, berechnet aus der echten Episodenanzahl.
Als Nächstes dran nennt Staffel, Episode, Titel und Ausstrahlungsdatum. Der Knopf +1 Episode hakt sie ab.
Der Status (Schaue gerade, Watchlist, Pausiert, Abgeschlossen, Abgebrochen) ergibt sich beim Abhaken von selbst: die erste Episode startet die Serie, die letzte schließt sie ab. Pausiert und Abgebrochen bleiben stehen — wer bewusst pausiert hat, will das nicht durch ein Häkchen aufgehoben bekommen.
In der Staffelliste hakst du einzelne Episoden ab, ganze Staffeln auf einmal, oder über Bis hierhin gesehen alles Vorherige. Beim Abhaken glimmt die Zeile kurz warm auf.
Rechts stehen Bewertung (1 bis 10), wo du das schaust (mit Vorschlag aus der Streaming-Verfügbarkeit), Tags und ein Notizfeld.

Jede Sichtung meldet sich unten kurz zurück und lässt sich mit Rückgängig zurücknehmen.

Ist eine Serie durch, erscheint Noch einmal schauen — der Fortschritt beginnt von vorn, die alten Sichtungen bleiben für die Statistik erhalten. Die Karte zeigt dann „2. Durchlauf".

Hab ich — die eigene Sammlung

„Wo läuft das?" beantwortet nur die halbe Frage. Manche Filme laufen nirgends mehr — die hat man gekauft und liegen bei sich zu Hause, in Jellyfin, Plex, Emby, auf dem NAS oder als Scheibe im Regal.

Dafür gibt es das Häkchen Hab ich auf der Detailseite, rechts über dem Feld „wo schaue ich das". Daneben trägst du ein, wo der Titel liegt; das Feld schlägt die gängigen Möglichkeiten vor, nimmt aber auch alles andere an.

Was das bewirkt:

Auf der Detailseite steht die Sammlung vor der Streaming-Verfügbarkeit — was du hast, ist die verlässlichere Antwort.
Poster in der Bibliothek bekommen ein Abzeichen, und statt des Streamingdienstes steht dort deine Quelle.
In der Filterleiste gibt es einen eigenen Knopf Hab ich samt Zähler.
Export und Import führen die Angabe mit (Spalten HabIch und Sammlung), ebenso die REST-API.

Bewusst getrennt vom Feld „wo schaue ich das": Das eine sagt, wo ein Titel gerade läuft — das ändert sich ständig. Das andere sagt, was dir gehört, und das bleibt.

Die Bibliothek

Alles, was du verfolgst, als Posterraster. Jede Kachel zeigt Status, Bewertung und — bei Serien — den Fortschritt.

Filtern kannst du nach:

Filter	Wirkung
Volltextsuche	Titel und Originaltitel
Status	Schaue gerade, Watchlist, Pausiert, Abgeschlossen, Abgebrochen
Typ	nur Serien oder nur Filme
Genre	alle Genres, die in deiner Bibliothek vorkommen
Dienst	Streamingdienste deiner Titel
Tag	deine eigenen Schlagworte

Sortieren geht nach zuletzt aktualisiert, zuletzt hinzugefügt, Titel, Bewertung oder Erscheinungsjahr. Die gesamte Auswahl steht in der Adresszeile — ein Lesezeichen auf „alle pausierten Krimis" ist damit möglich.

Universen

Ein Universum bündelt Titel, die zusammengehören — MCU, Star Wars, Wizarding World — und zwar Filme und Serien gemeinsam.

Auf der Detailseite steht oben der Gesamtfortschritt: wie viel abgeschlossen ist, wie viel Zeit schon drinsteckt und wie lange es bis zum Ende noch dauert. Der erste noch offene Eintrag ist als Als Nächstes dran hervorgehoben.

Mehrere Reihenfolgen sind der Kern der Sache:

Die Erscheinungsreihenfolge ist immer da und wird aus den Erscheinungsdaten berechnet — sie stimmt damit auch, wenn später etwas dazukommt.
Über + Reihenfolge legst du weitere an, etwa Chronologisch oder Für Einsteiger. Sortiert wird per Ziehen oder über die Pfeile neben jedem Eintrag; gespeichert wird sofort.

Titel nimmst du rechts aus deiner Bibliothek auf. Gehört ein Film zu einer TMDB-Reihe (etwa „Spider-Man Collection"), lässt sich die ganze Reihe mit einem Klick übernehmen.

Teilen geht mit anderen Konten derselben Instanz, wahlweise nur zum Ansehen oder zum gemeinsamen Pflegen. Der Fortschritt bleibt dabei persönlich: jede Person sieht ihren eigenen Stand.

Kalender

Das Monatsraster zeigt, wann Episoden deiner Serien laufen. Tage mit Terminen sind hinterlegt, der heutige Tag trägt den Signaturverlauf. Unter dem Raster stehen dieselben Termine noch einmal als Liste mit vollem Datum.

Mit den Pfeilen blätterst du durch die Monate, Heute springt zurück.

Abgebrochene Serien tauchen hier nicht auf. Abgeschlossene schon — wer bei einer laufenden Serie auf dem Stand ist, will die nächste Folge erst recht sehen.

Statistik

Oben die Gesamtschauzeit in Stunden und umgerechnet in Tage am Stück, daneben Episoden, Filme und abgeschlossene Titel.

Die letzten zwölf Monate — abgehakte Episoden und Filme je Monat. Beim Überfahren einer Säule erscheinen die genauen Zahlen samt Schauzeit.
Nach Streamingdienst — wo du tatsächlich geschaut hast. Grundlage ist das Feld wo schaue ich das, nicht die bloße Verfügbarkeit.
Nach Genre — Titel mit mehreren Genres zählen in jedem mit.
Jahr in Zahlen — Schauzeit, Episoden, Filme, neu Angefangenes, Abgeschlossenes, der stärkste Monat und der Titel mit der meisten Zeit. Über die Jahreszahlen wechselst du das Jahr.
Darunter wo die meiste Zeit hinging und deine besten Bewertungen.

Alles ist aus den Sichtungen gerechnet; Rewatches zählen mit.

Einstellungen

Hier stellst du Anzeigename und Region ein — Letztere bestimmt, welche Streamingdienste angezeigt werden (Standard: DE).

Darunter legst du fest, wovon Flimmer dir berichten soll: neue Episoden, neue Releases, neu verfügbare Watchlist-Titel.

Wenn der Betreiber öffentliche Profile erlaubt, kannst du deins freischalten und eine Adresse wählen. Die Profilseite zeigt Zahlen und zuletzt Gesehenes — keine Notizen, keine Watchlist, keine E-Mail-Adresse.

Das Passwort änderst du im Abschnitt darunter; danach wirst du auf allen Geräten abgemeldet.

Anmelden per Passkey

Statt Passwort geht auch ein Passkey — Windows Hello, Face ID, Touch ID oder ein Sicherheitsschlüssel am Schlüsselbund. Auf dem Handy ist das der Unterschied zwischen einem Blick in die Kamera und dem Abtippen eines langen Passworts.

Unter Einstellungen → Passkeys gibst du dem Gerät einen Namen und klickst Passkey anlegen; den Rest übernimmt dein Browser. Danach steht auf der Anmeldeseite „Mit Passkey anmelden" — ohne dass du vorher deine E-Mail-Adresse eintippen musst.

Das Passwort bleibt daneben bestehen. Den letzten verbleibenden Anmeldeweg lässt Flimmer nicht entfernen: wer weder Passwort noch SSO hat, behält seinen letzten Passkey.

Passkeys brauchen HTTPS Der Browser gibt sie nur über eine verschlüsselte Verbindung frei; einzige Ausnahme ist localhost. Läuft deine Instanz über einfaches HTTP, verschwindet die Verwaltung mit einem Hinweis, statt einen kryptischen Browserfehler zu zeigen.

Und: Ein Passkey ist fest an den Hostnamen gebunden. Ziehst du von flimmer.fritz.box auf flimmer.example.com um, musst du alle Passkeys neu anlegen. Halte vorher einen zweiten Anmeldeweg bereit.

Ein Passkey, der nur auf einem Gerät liegt und nicht mit deinem Konto synchronisiert wird, ist mit dem Gerät verloren. Die Übersicht sagt dir zu jedem Eintrag, was Sache ist.

Benachrichtigungen

Wovon berichtet wird, steht im Profil — wohin, hier. Vier Wege stehen zur Wahl:

Kanal	Nötige Angaben
E-Mail	nichts (oder eine abweichende Adresse); der SMTP-Zugang kommt vom Betreiber
ntfy	Server (Standard `https://ntfy.sh`) und Topic, optional ein Token
Gotify	Serveradresse und Anwendungs-Token
Webhook	die Zieladresse — funktioniert mit Discord, Slack und Mattermost

Jeder Kanal lässt sich einzeln stummschalten und mit Testen ausprobieren. Unten steht, was zuletzt verschickt wurde — auch fehlgeschlagene Versuche mit Grund.

Dieselbe Meldung kommt nie zweimal: Flimmer merkt sich, was schon draußen ist.

Import und Export

Import aus zwei Quellen:

CSV, wie es Tabellenprogramme und viele Tracker ausgeben. Die Kopfzeile braucht mindestens eine Titelspalte (Titel, title, name oder show); erkannt werden außerdem Typ, Status, Bewertung, TMDB-ID, Jahr und Notiz. Komma und Semikolon als Trennzeichen funktionieren beide.
Trakt.tv — ein JSON-Export aus Watchlist, History, Ratings oder Collection. Flimmer sucht sich die Einträge selbst heraus.

Der Import überschreibt nichts. Titel, die schon in deiner Bibliothek liegen, bleiben unangetastet; es kommt nur dazu, was fehlt.

Export als JSON (mit allen Sichtungen und Universen) oder als CSV für Tabellenkalkulationen.

Jellyfin anbinden

Wer seine Mediathek selbst hostet, pflegt Bestand und Gesehen-Status meist schon in Jellyfin. Flimmer kann beides übernehmen, damit du es nicht doppelt führst.

Unter Einstellungen → Medienserver trägst du die Adresse deines Servers ein, dazu Benutzername und Passwort. Nach dem Verbinden sagt Flimmer, wie viele Einträge es gefunden hat — und ob der Gesehen-Status mitkommt.

Warum Benutzername und Passwort, nicht ein API-Schlüssel? Mit einem API-Schlüssel liefert Jellyfin zwar den Bestand, aber keinen Gesehen-Status — und zwar ohne Fehlermeldung. Der Abgleich liefe dann stumm ins Leere. Flimmer meldet sich deshalb wie ein normaler Nutzer an und prüft beim Verbinden ausdrücklich nach. Das Zugangstoken wird verschlüsselt abgelegt, dein Passwort gar nicht gespeichert.

Zugeordnet wird über die TMDB-Kennung, die Jellyfin zu jedem Film und jeder Serie mitliefert. Das ist dieselbe Kennung, auf der Flimmers Katalog aufbaut — es gibt also kein Raten über Titel und Jahreszahlen. Was Jellyfin ohne Kennung führt (eigene Aufnahmen etwa), landet im Bericht statt falsch zugeordnet zu werden.

Beim Abgleich passiert dreierlei:

Titel, die auf dem Server liegen, bekommen „hab ich" mit der Quelle Jellyfin.
Was du dort gesehen hast, wird zur Sichtung mit dem Termin aus Jellyfin.
Fehlende Titel werden nur aufgenommen, wenn du das Häkchen setzt. Eine Mediathek mit achthundert Filmen soll nicht ungefragt deine Bibliothek werden.

Danach läuft der Abgleich im täglichen Hintergrundlauf mit — dort allerdings ohne automatisches Aufnehmen.

Titel, die Flimmer noch nicht kennt

Beim ersten Abgleich einer gewachsenen Mediathek passiert oft etwas Ernüchterndes: Jellyfin meldet tausend Einträge, und Flimmer ordnet keinen einzigen zu. Das ist richtig so — Flimmer kennt nur, was du selbst aufgenommen oder über die Suche importiert hast.

Deshalb steht unter dem Bericht eine Auswahlliste: alles, was auf dem Server liegt und Flimmer unbekannt ist. Hake an, was übernommen werden soll, und klicke auf Übernehmen — die Daten holt Flimmer dann von TMDB, bei Serien samt Staffeln und Episoden.

Zwei Dinge, die dabei helfen:

Zusammengefasst. Führt Jellyfin drei Dateien zum selben Film (Extended Edition, zweite Fassung), steht er trotzdem nur einmal in der Liste — mit dem Vermerk, wie viele Dateien darauf zeigen.
Es werden hundert auf einmal geholt. Wer mehr auswählt, bekommt den Rest beim nächsten Klick. Jeder Titel bedeutet einen Abruf bei TMDB, bei Serien einen je Staffel.

Manche Einträge lassen sich nicht anhaken: dort fehlt die TMDB-Kennung in Jellyfin selbst. Das trifft oft Extended Editions, Konzertmitschnitte oder Dateien mit eigenwilliger Benennung. Meist hilft es, in Jellyfin die Erkennung für diesen Titel nachzuziehen — danach taucht er beim nächsten Abgleich mit Kennung auf.

Der Unterschied zwischen den beiden Häkchen „Bekannte Titel dabei in die Bibliothek aufnehmen" beim Abgleich nimmt auf, was Flimmer kennt, aber noch nicht in deiner Bibliothek steht. Die Auswahlliste holt, was Flimmer nicht kennt.

Der Abgleich ist eine Einbahnstraße. Er ergänzt, was auf dem Server steht, und löscht nie etwas, das in Flimmer steht. Markierst du einen Film in Flimmer als gesehen und löschst ihn in Jellyfin, bleibt deine Sichtung erhalten.

Eine Grenze, die von Jellyfin kommt Jellyfin merkt sich, wie oft du etwas gesehen hast und wann zuletzt — aber keine Liste der einzelnen Male. Ein Film, den du dreimal gesehen hast, kommt deshalb mit einem Termin in Flimmers Statistik an, nicht mit drei. Rewatch-Durchläufe, die du in Flimmer selbst anlegst, sind davon nicht betroffen. Das lässt sich nicht beheben — die Information gibt es an der Quelle nicht.

API-Schlüssel

Für Skripte und eigene Anwendungen. Ein Schlüssel ist einmalig sichtbar — danach liegt in der Datenbank nur ein Hash. Er hat dieselben Rechte wie dein Konto; zieh ihn zurück, sobald du ihn nicht mehr brauchst.

curl -H "Authorization: Bearer flm_…" \
  https://flimmer.example.com/api/v1/bibliothek?status=WATCHING

Alle Endpunkte stehen in API.md; die maschinenlesbare Fassung liegt unter /api/v1/openapi.json.

Papierkorb

Entfernte Titel landen für 30 Tage im Papierkorb und behalten dabei ihren Fortschritt. Von dort lassen sie sich wiederherstellen oder sofort endgültig löschen. Nimmst du denselben Titel erneut auf, lebt der alte Eintrag samt Sichtungen wieder auf.

Nach Ablauf der Frist räumt der tägliche Hintergrundlauf auf.

Verwaltung

Nur für Administratoren. Hier lässt sich

der Name der Instanz ändern,
die Registrierung öffnen oder schließen,
öffentliche Profile instanzweit erlauben oder abschalten,
der Abgleich von Hand anstoßen,
und der Zustand der Instanz ablesen: Anzahl Konten, Umfang des Katalogs und ob TMDB, SMTP, Zeitplan und OIDC eingerichtet sind.

In der Kontenliste vergibst du Verwaltungsrechte und sperrst Konten. Ein gesperrtes Konto wird sofort von allen Geräten abgemeldet. Die letzte Administration lässt sich nicht entmachten, und sich selbst kann niemand sperren.

Öffentliches Profil

Wer mag, kann eine schlichte Seite unter /u/<adresse> freischalten — mit Schauzeit, Zahlen, zuletzt Gesehenem und den Listen „Die meiste Zeit" und „Bestbewertet".

Was dort nicht steht: Notizen, Watchlist, E-Mail-Adresse, Tags. Die Seite braucht zwei Freigaben — deine in den Einstellungen und die des Betreibers in der Verwaltung. Fehlt eine davon, ist die Adresse schlicht nicht erreichbar.

Auf dem Handy

Die Oberfläche ist für schmale Geräte ausgelegt: die Navigation rutscht in eine eigene, wischbare Zeile, Karten stapeln sich untereinander, und der Knopf +1 Episode bleibt groß genug für den Daumen.

Flimmer ist als PWA installierbar — im Browsermenü Zum Startbildschirm hinzufügen. Danach startet die App im eigenen Fenster ohne Adresszeile. Bereits geladene Seiten und Poster bleiben auch ohne Verbindung sichtbar; statt einer Fehlerseite erscheint dann ein Hinweis.

Helles Farbschema

Über den Knopf im Kopfbereich wechselst du zwischen Dunkel, Hell und System. Die Wahl bleibt auf dem Gerät gespeichert und greift, bevor die Seite gezeichnet wird — es blitzt nichts auf.

Und wenn etwas fehlt?

Die Suche findet nichts → Es fehlt der TMDB-Schlüssel. Trag TMDB_API_KEY in die .env ein und starte die Instanz neu.
Keine Streamingdienste → Prüfe die Region in den Einstellungen. TMDB hat nicht für jedes Land Daten zu jedem Titel.
Keine Benachrichtigungen → Erst im Profil auswählen, wovon berichtet werden soll, dann einen Kanal anlegen und mit Testen prüfen.
Neue Episoden fehlen → Der Abgleich läuft einmal täglich. In der Verwaltung lässt er sich sofort anstoßen.

Alles Weitere zur Installation, zum Aktualisieren und zum Backup steht in der README.

20 KiB Raw Blame History