kurmann-mediathek-manager 0.2.0

Generiert statische HTML-Bibliotheken aus Videodateien – archivierungsfähig, ohne Server, ohne Datenbank.

Mediathek Manager

Generiert statische HTML-Bibliotheken aus Videodateien — archivierungsfähig, ohne Server, ohne Datenbank.

Das Tool scannt Verzeichnisse mit Videodateien (M4V, MP4, MKV, MOV), extrahiert eingebettete Metadaten (Titel, Tags, Genre, Kapitel, Beschreibungen) und generiert eine navigierbare HTML-Bibliothek direkt neben den Videos. Eine einzige Bibliothek pro Aufruf — rekursiv über alle Unterverzeichnisse mit hierarchie-gespiegelter Struktur, Breadcrumb-Navigation, Tag- und Genre-Filtern sowie Detailseiten inkl. klickbaren Kapiteln.

Scope — was der Mediathek Manager nicht tut

Der Mediathek Manager erzeugt keine Vorschaubilder. Poster-Extraktion ist eine eigenständige Kompetenz und gehört in spezialisierte Tools (z. B. den kurmann-vorschaubild-manager, aufgerufen aus dem kurmann-mediaset-creator). Der Mediathek Manager konsumiert nur existierende Sidecars nach folgender Konvention:

• Existiert neben einem Video eine Datei {stem}-poster.jpg (z. B. Urlaub-poster.jpg neben Urlaub.m4v), wird sie als Poster referenziert.
• Fehlt das Sidecar, rendert der Generator eine Platzhalter-Card mit zentriertem Titel. Sie ist weiterhin voll klickbar und führt zur Detailseite.

Dadurch bleibt der Mediathek Manager fokussiert auf Scannen, Metadaten, HTML und nimmt keine ffmpeg-Abhängigkeit für Bildverarbeitung auf.

Voraussetzungen

• Python >= 3.11
• ffprobe (für Metadaten-Extraktion aus eingebetteten Tags und Kapiteln)
• rclone (optional, für den Zugriff auf Remote-Speicher wie Synology via SFTP)

Hinweis zu rclone + ffprobe: Da ffprobe in einer Pipe nicht seeken kann, muss bei MP4-/M4V-Dateien mit moov-Atom am Ende die gesamte Datei gestreamt werden. Bei großen Videos auf langsamen Verbindungen läuft das in den Timeout. Für verlässliche Workflows empfiehlt sich stattdessen ein lokal gemountetes Volume (SMB oder rclone mount) und die lokale Pfadangabe.

Installation

# Via PyPI
pip install kurmann-mediathek-manager

# Lokale Entwicklung
uv sync

Verwendung

# Bibliothek lokal generieren
mediathek-manager generate /pfad/zum/videoverzeichnis

# Mit eigenem Titel (sonst wird der Ordnername verwendet)
mediathek-manager generate /pfad/zum/Familienfilme --title "Familienfilme"

# Über rclone-Remote (z. B. Synology via SFTP)
mediathek-manager generate lyssach-nas:/Familienfilme --title "Familienfilme"

# Ohne Rekursion: nur Videos im Root-Verzeichnis
mediathek-manager generate /pfad/zum/videoverzeichnis --no-recursive

# Mit ausführlicher Ausgabe
mediathek-manager generate /pfad/zum/videoverzeichnis --verbose

# Nur scannen (zeigt gefundene Videos und Metadaten)
mediathek-manager scan /pfad/zum/videoverzeichnis

# Konfiguration
mediathek-manager config list
mediathek-manager config set tools.ffprobe_path /usr/local/bin/ffprobe

Erzeugte Struktur

videoverzeichnis/                  ← CLI-Input (Root der Bibliothek)
├── index.html                     ← Einstiegspunkt (einzige HTML im Root)
├── Film1.m4v
├── Film1-poster.jpg               ← optionales Sidecar (nicht vom Tool erzeugt)
├── Ferien/
│   ├── Urlaub.m4v
│   └── Urlaub-poster.jpg
└── mediathek/                     ← alle weiteren Artefakte
    ├── style.css
    ├── browse/                    ← Unterverzeichnis-Indexe (Hierarchie gespiegelt)
    │   └── Ferien/
    │       └── index.html
    ├── detail/                    ← Detailseiten (Hierarchie gespiegelt)
    │   ├── Film1.html
    │   └── Ferien/
    │       └── Urlaub.html
    ├── tag/                       ← Tag-Filterseiten (über gesamte Bibliothek)
    │   └── weltraum.html
    └── genre/                     ← Genre-Filterseiten
        └── dokumentation.html

Poster werden nicht unter mediathek/poster/ abgelegt, sondern direkt vom Sidecar neben dem Video referenziert. Existiert kein Sidecar, zeigt die Card einen Platzhalter mit zentriertem Titel.

Safari-optimiert: Die Detailseiten nutzen native <video>-Tags, die in Safari via AVFoundation rendern — dieselbe Pipeline wie QuickTime. HDR10 / Dolby Vision / Rec.2020 PQ wird korrekt tone-mapped. Safari ist daher der empfohlene Browser.

Suche: Die Bibliothek nutzt keine JavaScript-Suche — die Browser-interne Textsuche (⌘+F bzw. Strg+F) funktioniert bestens auf der langen Videoliste.

Konfiguration

Persistente Konfiguration unter ~/.config/mediathek-manager/config.toml:

[tools]
ffprobe_path = "ffprobe"
rclone_path = "rclone"

Upgrade von 0.1.x auf 0.2.0

Version 0.2.0 ändert die Ausgabestruktur grundlegend. Alte .mediathek/-Ordner sind nicht kompatibel und sollten vor der erneuten Generierung gelöscht werden:

rm -rf /pfad/zum/videoverzeichnis/.mediathek
mediathek-manager generate /pfad/zum/videoverzeichnis --title "Deine Bibliothek"

Änderungsverlauf

Siehe CHANGELOG.md.

Lizenz

MIT — siehe LICENSE.