# 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 1. [Erster Start](#erster-start) 2. [Die Übersicht](#die-übersicht) 3. [Titel finden und aufnehmen](#titel-finden-und-aufnehmen) 4. [Eine Serie verfolgen](#eine-serie-verfolgen) 5. [Hab ich — die eigene Sammlung](#hab-ich--die-eigene-sammlung) 6. [Die Bibliothek](#die-bibliothek) 7. [Universen](#universen) 8. [Kalender](#kalender) 9. [Statistik](#statistik) 10. [Einstellungen](#einstellungen) 11. [Benachrichtigungen](#benachrichtigungen) 12. [Import und Export](#import-und-export) 13. [API-Schlüssel](#api-schlüssel) 14. [Papierkorb](#papierkorb) 15. [Verwaltung](#verwaltung) 16. [Öffentliches Profil](#öffentliches-profil) 17. [Auf dem Handy](#auf-dem-handy) 18. [Helles Farbschema](#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](#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. --- ## Errungenschaften  Unten auf der Statistikseite sammeln sich **Abzeichen**. Sie tauchen auf, wenn etwas erreicht ist — mehr passiert nicht. Keine Serien, die reißen, wenn du eine Woche nichts schaust, keine Balken, die dich antreiben. Ein paar davon: - **Abgehakt** — die erste Serie vollständig durchgeschaut - **Der lange Atem** — eine Serie mit mindestens hundert Episoden komplett - **Treu geblieben** — über ein Jahr an demselben Titel drangeblieben - **Durchgemacht** — zwischen drei und fünf Uhr morgens etwas abgehakt - **Zeitreisender** — Titel aus sieben Jahrzehnten gesehen - **Strenges Urteil** — einmal die Note 1 vergeben Dazu kommen Abzeichen für **ganze Filmreihen**: Wer alle Spider-Man-Filme gesehen hat, bekommt sie als solche angerechnet. Flimmer erkennt das an der TMDB-Kennung, die zu jedem Film mitgeliefert wird — es braucht keine gepflegte Liste. Für bekannte Reihen gibt es einen eigenen Namen, sonst heißt es schlicht „Reihe komplett — …". Genauso zählen **eigene Universen**, sobald alle Titel darin abgeschlossen sind. > **Einmal erreicht, bleibt erreicht.** > Nimmst du eine Sichtung zurück oder entfernst einen Titel, verlierst du kein > Abzeichen. Es wieder einzukassieren wäre kleinlich — und ein Fehlklick soll > nichts kaputt machen. Beim ersten Öffnen der Seite schaut Flimmer einmal deine ganze Historie durch. Wenn du Flimmer schon länger nutzt, sind deshalb sofort mehrere Abzeichen da — ohne dass du dafür eine Flut von Meldungen bekommst. Erst danach wird gemeldet, was neu dazukommt. Wenn du ein öffentliches Profil hast, kannst du die Abzeichen dort zeigen oder ausblenden — der Schalter steht in den Einstellungen direkt bei der Profiladresse. --- ## 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. **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. ```bash curl -H "Authorization: Bearer flm_…" \ https://flimmer.example.com/api/v1/bibliothek?status=WATCHING ``` Alle Endpunkte stehen in [`API.md`](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/` 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](../README.md).