kurmann-familienfilm-manager 1.2.1

CLI-Tool und Python-Bibliothek zur Veröffentlichung von Familienfilmen: Medienset-Erstellung, Infuse-Deployment, Webserver-Deployment und Archivierung.

familienfilm-manager

CLI-Tool und Python-Bibliothek zur Veröffentlichung von selbst geschnittenen Familienfilmen. Orchestriert den gesamten Workflow: Metadaten extrahieren, Medienset erstellen (via mediaset-creator), Infuse-/Webserver-Deployment und Archivierung.

Inhalt

Erste Schritte

• Voraussetzungen · Installation · Verwendung (CLI)

Workflows

• Verzeichnis-Publikation (Batch) — publish-dir
• Verzeichnis-Überwachung — watch-dir
• rclone-Quellen — Cloud/NAS direkt als Quelle

Konzepte

• Web-Speicher-Budget — Storage-Limit + Aufbewahrungsdauer
• KI-Vorschaubild-Wahl & Persistierung — Claude-Frame-Auswahl + Sidecar-Cache
• Poison-Video-Detection — Auto-Skip kaputter Videos
• Metadaten-Extraktion — Dateiname / QuickTime-Tags
• Settings-Sidecar-Datei — .settings.toml neben jedem Video
• Verzeichnis-Settings — familienfilm.toml für Defaults

Konfiguration

• API-Keys (KI) · Konfiguration · Python API

---

Quickstart

Drei Schritte vom Null zur ersten Publikation:

# 1. Installieren
uv tool install kurmann-familienfilm-manager

# 2. Konfigurieren (rclone-Remotes für Targets sind Pflicht)
familienfilm-manager config set targets.infuse  "nas:/Familienfilme/Final"
familienfilm-manager config set targets.archive "nas:/Archiv/2026/Videoschnitt"
familienfilm-manager config set targets.web     "hostpoint:"
familienfilm-manager config set paths.work_dir  "$HOME/Movies/Familienfilm-Manager"

# 3. Erstes Video publizieren
familienfilm-manager publish "/pfad/zu/2026-04-30 Mein Familienvideo.mov"

Für Cloud-Quellen + Watch-Modus + KI-Auto-Vorschaubild siehe die jeweiligen Sektionen unten.

---

Voraussetzungen

• Python 3.11+
• ffmpeg und ffprobe im $PATH
• rclone im $PATH (für Deployments und Archivierung)
• hdiutil (macOS, für ISO-Erstellung)
• kurmann-mediaset-creator (wird als Dependency installiert)

---

Installation

uv pip install kurmann-familienfilm-manager

Im Entwicklungsmodus:

uv sync

---

Verwendung (CLI)

Gesamtworkflow

familienfilm-manager publish /pfad/zu/video.m4v \
  --title "Wanderung auf den Napf" \
  --category "Familie Kurmann-Glück" \
  --date "2025-03-24" \
  -v

Das Tool:

1. Extrahiert Metadaten (QuickTime-Tags oder Dateiname)
2. Erstellt ein Medienset via mediaset-creator mit separaten Profilen (Infuse/Web)
3. Deployt zu Infuse sofort bei Fertigstellung (direkt via rclone, kein ZIP-Entpacken)
4. Deployt zum Webserver nach Fertigstellung der Web-Komprimierung (rclone)
5. Archiviert die Originaldatei direkt (rclone copyto) + .settings.toml + neue .archive.toml mit konservierten Metadaten (Originalname, Export-mtime, Titel, Beschreibung) — kein TAR mehr seit v0.9.0, direkter Zugriff am NAS

Einzeloperationen

# Nur Infuse-Deployment eines Verzeichnisses mit Infuse-Dateien
familienfilm-manager deploy-infuse /pfad/zum/infuse-verzeichnis/

# Nur Web-Deployment eines Web-ID-Verzeichnisses
familienfilm-manager deploy-web /pfad/zum/01JNXYZ.../

# Nur Archivierung
familienfilm-manager archive /pfad/zu/video.m4v --date 2025-03-24

Optionen (publish)

Option	Beschreibung
--title TEXT	Video-Titel (überschreibt extrahierte Metadaten)
--description TEXT	Beschreibung des Videos
--category TEXT	Kategorie (z.B. «Familie Kurmann-Glück»)
--date TEXT	Aufnahmedatum im ISO-Format (YYYY-MM-DD)
--output-dir PATH	Basisverzeichnis für die Web-Medienset-Ausgabe
--poster-frame INT	Frame-Nummer für Vorschaubild (überspringt KI-Auswahl)
--poster-at FLOAT	Zeitpunkt in Sekunden für Vorschaubild (z.B. 90 oder 1.5)
--poster-crop TEXT	Bildausschnitt (left/center-left/center/center-right/right)
--web-id TEXT	Web-ID für Web-Medienset (12 Zeichen, a-z 0-9; überschreibt Sidecar-Wert)
--max-luminance INT	Peak-Leuchtdichte in nits für HDR-Metadaten (Default: 1000)
--no-sidecar	Sidecar-Datei nicht lesen/schreiben
--no-infuse	Infuse-Deployment überspringen
--no-web	Web-Deployment überspringen
--no-archive	Archivierung überspringen
--force	Neuerstellung erzwingen
--delete-source	Originaldatei (+ .settings.toml) nach verifiziertem Publish löschen. Nur wenn Archiv aktiv und Size-verifiziert ist. Default: aus
--web-budget	Override Web-Speicherbudget für diesen Lauf (z.B. '500GB', '1TB'). Überschreibt web.storage_budget aus Config
--web-max-age	Override max. Alter eines Web-Mediasets in Tagen (z.B. 365). Überschreibt web.max_age_days aus Config
--web-cleanup-dry-run	Zeigt welche Web-Mediasets bei Budget-Überschuss oder Alter gelöscht würden, löscht aber nichts
--verbose, -v	Zusätzliche Ablaufinformationen auf stderr

Ausgabe

stdout enthält den Pfad zum erstellten Verzeichnis (Web-ID-Verzeichnis oder Infuse-Verzeichnis):

/pfad/zum/output/01JNXYZ.../

---

Verzeichnis-Publikation (Batch)

Mit publish-dir werden alle qualifizierten Videos in einem Verzeichnis sequenziell publiziert (älteste zuerst). Ideal für Watch-Folder-Workflows.

# Trockenlauf: zeige welche Videos publiziert würden
familienfilm-manager publish-dir /Movies/LumaFusion-Export/ --dry-run

# Alle qualifizierten Videos publizieren
familienfilm-manager publish-dir /Movies/LumaFusion-Export/

# Auch bereits publizierte Videos neu publizieren
familienfilm-manager publish-dir /Movies/LumaFusion-Export/ --force

Filter-Kriterien

Nur Dateien werden publiziert, die alle Bedingungen erfüllen:

• Bekannte Video-Endung: .mov, .mp4, .m4v, .mkv
• Dateiname matcht das Muster <YYYY-MM-DD> <titel>.<ext> (mindestens Datum-Präfix)
• Kein Hidden-File (kein . am Anfang)
• Keine Verzeichnisse

Alles andere wird stillschweigend ignoriert.

Idempotenz

Nach erfolgreicher Publikation wird ins Sidecar (<video>.settings.toml) geschrieben:

• Pro aktivem Deploy-Kanal ein published_at-Zeitstempel: [web].published_at, [local].published_at, [archive].published_at
• source.size_bytes – Dateigrösse der Quelle zu diesem Zeitpunkt
• source.head_sha1 – SHA1 der ersten 1 MB der Quelldatei (Fingerprint)

Beim nächsten publish-dir-Lauf wird ein Video übersprungen, wenn alle aktiven Kanäle einen published_at-Zeitstempel haben UND der Fingerprint der Quelldatei mit dem gespeicherten übereinstimmt (gleiche Grösse UND gleicher Hash der ersten 1 MB).

„Aktiv" heisst: ohne --no-web/--no-infuse/--no-archive-Flag. Wenn ein Kanal deaktiviert ist, wird sein published_at für den Skip-Check nicht verlangt.

Warum Fingerprint statt Timestamps?

Die frühere Logik verglich published_at mit der mtime von Video und Sidecar. Auf SMB-/NAS-Mounts (typisch für LumaFusion-Export auf ein NAS) ist das nicht zuverlässig:

• mtime-Auflösung schwankt je nach Backend (teilweise 2-Sekunden-Raster, SMB-Metadaten-Caching)
• Clock-Drift zwischen lokaler Uhr (datetime.now()) und NAS-Filesystem
• Drittsoftware verändert Timestamps (Spotlight-Indexierung, Time Machine, Finder-Copy, Backup-Tools)

Resultat: Videos wurden zuverlässig neu publiziert, obwohl sie klar publiziert waren. Der Fingerprint (Grösse + Kopf-Hash) ist unabhängig von Timestamps und funktioniert identisch auf lokalem APFS und SMB.

Der Hash deckt nur die ersten 1 MB ab — ein pragmatischer Kompromiss aus Scan-Geschwindigkeit (~100 ms auf SMB pro Video) und Kollisionssicherheit. Ein Neu-Export ändert in aller Regel sofort Header-Bytes (Metadaten, Container-Stream) und wird erkannt.

Republish-Trigger

• Andere Dateigrösse → Video wurde neu exportiert
• Gleiche Grösse, anderer Kopf-Hash → Header/Metadaten verändert
• Altes Sidecar ohne Fingerprint (aus Version ≤ 0.5.0) → einmaliger Republish erfasst den Fingerprint; ab dann idempotent

Mit --force werden alle Videos unabhängig vom Status neu publiziert.

Hinweis: Beim Einzeldatei-publish greift der Skip-Check nicht — der explizite Aufruf publiziert immer.

Optionen (publish-dir)

Option	Beschreibung
--category TEXT	Kategorie für alle Videos im Verzeichnis (überschreibt defaults.category aus Config)
--no-infuse	Infuse-Deployment für alle Videos überspringen
--no-web	Web-Deployment für alle Videos überspringen
--no-archive	Archivierung für alle Videos überspringen
--force	Auch bereits publizierte Videos neu publizieren
--dry-run	Nur anzeigen welche Videos publiziert würden, ohne zu publizieren
--recursive, -r	Unterverzeichnisse mit einbeziehen (siehe Verzeichnis-Settings)
--work-dir PATH	Arbeitsverzeichnis für temporäre Dateien (überschreibt paths.work_dir Config)
--web-budget	Override Web-Speicherbudget für diesen Batch (siehe Web-Speicher-Budget)
--web-max-age	Override max. Alter in Tagen (siehe Web-Speicher-Budget)
--web-cleanup-dry-run	Cleanup-Plan zeigen (Budget + Alter), nichts löschen
--verbose, -v	Zusätzliche Ablaufinformationen pro Video auf stderr

Verhalten bei Fehlern

Ein Fehler bei einem Video stoppt den Batch-Lauf nicht — die Verarbeitung läuft mit dem nächsten Video weiter. Am Schluss wird eine Zusammenfassung mit Erfolgen, übersprungenen und fehlgeschlagenen Videos ausgegeben. Exit-Code 1 wenn mindestens ein Video fehlschlug.

Robustes Deployment

Die drei rclone-basierten Deployment-Schritte (Infuse, Web, Archive) sind gegen typische SMB/NAS-Flakeyness abgesichert:

• Automatischer Retry mit exponentiellem Backoff (1 s → 3 s → 9 s, 3 Versuche nach dem ersten). Deckt flüchtige Netzwerk-Hiccups und Filesystem-Sync-Delays ab, ohne den gesamten Publish-Workflow (oft 20+ min ffmpeg-Arbeit) wiederholen zu müssen. Jeder Retry wird im Terminal gelb angezeigt.
• Post-Deploy Health-Check: Nach erfolgreichem rclone-Lauf wird via rclone lsf geprüft, ob die erwarteten Dateien/Verzeichnisse wirklich im Ziel angekommen sind. Bei Mismatch: rot markierter Fehler statt silencieren.
• Infuse-Medienset bleibt bei Deploy-Fehler erhalten (Temp-Verzeichnis wird nicht aufgeräumt). Nachholen ohne Neuerstellung:

  familienfilm-manager deploy-infuse /pfad/zum/temp-verzeichnis/
  

  Der genaue Pfad wird im roten Fehler-Hinweis mitgeliefert.
• Bei Archive-Deploy-Fehler bleibt die Originalquelle unangetastet (v0.9.0 nutzt rclone copyto statt move, und --delete-source löst erst nach Size-verifiziertem Upload aus). Einfach erneut ausführen.

---

Verzeichnis-Überwachung (watch-dir)

Überwacht ein oder mehrere Verzeichnisse und publiziert neue Videos automatisch. Ein Tick ist verhaltensidentisch zu einem publish-dir-Lauf — gleiche Idempotenz, gleiche Filter-Regeln, gleiche Fehler-Isolation.

# Ein einziges Verzeichnis, Default-Intervall (24h):
familienfilm-manager watch-dir -d /Volumes/Videoschnitt/LumaFusion-Export

# Mehrere Verzeichnisse, alle 90 Minuten:
familienfilm-manager watch-dir -d /pfad/a -d /pfad/b --interval 90m

# Konfiguration in der Config hinterlegt, einfach starten:
familienfilm-manager config set watch.directories "/pfad/a,/pfad/b"
familienfilm-manager config set watch.interval_seconds "21600"   # 6h
familienfilm-manager watch-dir

# Einmaliger Durchlauf für launchd/cron:
familienfilm-manager watch-dir --once

Verhaltens-Defaults persistent setzen (v1.2.0+)

Wer regelmässig dieselben Optionen mitgibt, kann sie einmalig persistieren:

familienfilm-manager config set watch.recursive true
familienfilm-manager config set watch.delete_source true

Damit reicht später ein blosses familienfilm-manager watch-dir (oder watch-dir --once). Pro Lauf ist das Verhalten via Bool-Pair-Flags umkehrbar — --no-recursive, --no-delete-source, --infuse, --archive.

Vor jedem Lauf erscheint kurz auf stderr ein Konfigurations-Block, der zeigt, welche Werte effektiv gelten und woher sie kommen (CLI / Config / Default) — beim Debugging entfallen Vermutungen.

Modi

Modus	Beschreibung	Typischer Einsatz
Daemon (Default)	Endlosschleife: Tick → sleep(interval) → Tick → … Der erste Tick läuft sofort beim Start.	Manuell im Terminal, oder launchd mit KeepAlive=true.
Single-shot (--once)	Genau ein Tick, dann Exit 0.	launchd mit StartInterval / StartCalendarInterval, oder cron.

Beide Modi führen einen Tick identisch aus — --once beendet danach nur die Schleife. Umstieg vom Daemon auf launchd+--once ändert das Verhalten eines einzelnen Laufs nicht.

Intervall-Notation

--interval akzeptiert nackte Sekunden oder Suffixe s / m / h / d:

--interval 600      # 600 Sekunden = 10 Minuten
--interval 90m      # 90 Minuten
--interval 24h      # 24 Stunden (Default)
--interval 2d       # 2 Tage

Default ist 24 Stunden — Familienfilme müssen nicht sofort publiziert werden, ein täglicher Durchlauf schont das NAS (der Scan liest pro Video 1 MB zum Fingerprint-Abgleich).

Im --once-Modus wird --interval ignoriert (mit Hinweis) — das Timing gehört dem externen Scheduler.

Stabilitätscheck für wachsende Dateien

LumaFusion-Exporte direkt auf SMB schreiben die Datei inkrementell. Würde der Watch-Tick genau dann zuschlagen, wenn der Export noch läuft, würde eine unvollständige Datei publiziert.

Mechanismus: Zu Beginn der Publish-Phase wird die Grösse aller Kandidaten gemessen, anschliessend --stability-window Sekunden gewartet und erneut gemessen. Dateien, deren Grösse sich geändert hat, werden als „wächst noch" markiert und beim nächsten Tick erneut geprüft. Die Wartezeit gilt einmalig für alle Kandidaten gemeinsam — bei 5 neuen Videos kostet das 60 s total, nicht 5×60 s.

Default: 60s. Mit --stability-window 0 abschaltbar (oder via Config watch.stability_window_seconds).

Wie beim Fingerprint-Check wird absichtlich die Dateigrösse geprüft, nicht die mtime — aus denselben Gründen (SMB-Unzuverlässigkeit).

Markdown-Benachrichtigung mit Live-Status

Ist notification.file konfiguriert, wird bei Publikationsbeginn ein „In Bearbeitung"-Eintrag in eine Markdown-Datei geschrieben und beim Abschluss durch den finalen Zustand ersetzt:

• In Bearbeitung — während der Publikation
• Veröffentlicht — mit Web-URL und/oder lokalem Zielpfad
• Fehlgeschlagen — {Fehlermeldung}
• Abgebrochen (wird beim Watch-Start gesetzt, falls vom letzten Lauf noch pending-Einträge liegenblieben, z.B. nach einem Crash)
• Aus Web-Speicher entfernt am {Datum} ({Grund}) (nach Cleanup)

Jeder Eintrag hat eine stabile video-id (aus dem absoluten Pfad abgeleitet) — ein Republish überschreibt denselben Eintrag statt Duplikate anzuhängen. Die Datei begrenzt sich automatisch auf die 50 jüngsten Einträge (älteste fallen raus); damit bleibt sie auf dem Telefon kurz und scrollbar.

Format der Datei:

# Familienfilme

> _Diese Datei wird automatisch vom Familienfilm-Manager geschrieben._
> _Bitte nicht manuell editieren — Änderungen werden beim nächsten
> Publish überschrieben._

_Aktualisiert: 01.05.2026, 14:58_

## 01.05.2026 — Langnau im Emmental
> id: d969107420757722 · status: published · aktualisiert: 2026-05-01T12:57:45Z

- **Status:** Veröffentlicht
- **Aufnahmedatum:** 04.02.2024
- **Kategorie:** Familie
- **Web:** <https://mediathek.kurmann.swiss/mteyn0n1pm9d/>
- **Lokal:** `lyssach-nas:/Familienfilme/Final/2024`

Der Hinweis-Block-Quote oben warnt vor manueller Bearbeitung; die Metadaten-Block-Quote pro Eintrag (id, status, aktualisiert) dient FFM intern als State für Read-Modify-Write und Multi-Machine- Merge — sie ist im Renderer als kleiner grauer Kasten sichtbar, was ehrlich vermittelt, dass die Datei gemanagt ist.

Cloud-Sync via rclone

notification.file kann ein lokaler Pfad ODER ein rclone-URI sein:

# Lokal (default):
familienfilm-manager config set notification.file "/Users/me/Movies/Familienfilme.md"

# Cloud (z.B. mega.nz, hostpoint, Google Drive — alles was rclone kann):
familienfilm-manager config set notification.file "mega.nz:Familienfilme/Familienfilme.md"

Bei rclone-URIs hält FFM einen lokalen Cache unter ~/.cache/familienfilm-manager/ und synchronisiert nach Real-Time-relevanten Updates (pending / published / failed / cleaned-up). Auf mega.nz und anderen Cloud-Plattformen wird die MD-Datei nativ gerendert — Links sind direkt klickbar, ohne dass die Datei runter- geladen werden muss.

Konflikt-Strategie: FFM gewinnt immer. Wer die Remote-MD manuell editiert, während FFM läuft, wird beim nächsten Sync überschrieben.

Multi-Machine-Setups

Mehrere Rechner können dieselbe notification.file auf einem gemeinsamen rclone-Target nutzen (z.B. zwei Macs mit eigenen Watch- Quellordnern, aber einem geteilten mega.nz:Familienfilme.md für die Status-Übersicht auf dem Telefon). Vor jedem Push wird der aktuelle Remote-Stand gepullt und mit dem lokalen Inhalt vereinigt (Union per video-id; bei Konflikt gewinnt der jüngere updated-Timestamp). Damit überschreiben sich die Rechner nicht gegenseitig.

Empfohlenes Setup: pro Rechner eigene Quellverzeichnisse, gemeinsames Notification-Target. Geteilte Quellverzeichnisse (gleicher Watch- Ordner auf zwei Rechnern) werden NICHT explizit unterstützt — dort besteht das Risiko von Doppel-Publikationen.

Sync-Fail-Toleranz: bei Push-Fehler (Network, Auth) bleibt der Cache aktuell — der nächste erfolgreiche Sync räumt auf. Eine Warnung erscheint auf stderr, der Publish läuft weiter.

Interne Hygiene-Updates (z.B. die aborted-Markierung beim Watch-Start) syncen nicht sofort — sie gehen beim nächsten echten Status-Update mit raus. Hält die rclone-Aufrufe pro Watch-Tick gering.

Fehler-Isolation

Fehler in einem Verzeichnis (fehlend, nicht lesbar, Exception) stoppen den Watch-Lauf nicht. Andere Verzeichnisse werden weiter verarbeitet, beim nächsten Tick wird erneut versucht. Fehler auf Video-Ebene (einzelne Publikation schlägt fehl) werden wie bei publish-dir pro Video geloggt und der Tick macht mit dem nächsten Video weiter.

Beenden

SIGTERM und SIGINT (Ctrl+C) beenden den Daemon sauber nach dem laufenden Tick — nicht mittendrin. Kompatibel mit launchctl stop und Docker-ähnlichen Graceful-Shutdown-Mechanismen.

launchd-Beispiel (macOS)

Variante A — Daemon mit KeepAlive:

<plist>
  <dict>
    <key>Label</key><string>ch.kurmann.familienfilm-manager</string>
    <key>Program</key><string>/usr/local/bin/familienfilm-manager</string>
    <key>ProgramArguments</key>
    <array>
      <string>familienfilm-manager</string>
      <string>watch-dir</string>
    </array>
    <key>KeepAlive</key><true/>
    <key>StandardErrorPath</key><string>/tmp/familienfilm-manager.err</string>
  </dict>
</plist>

Variante B — --once mit Kalender-Trigger (täglich 03:00 Uhr):

<key>ProgramArguments</key>
<array>
  <string>familienfilm-manager</string>
  <string>watch-dir</string>
  <string>--once</string>
</array>
<key>StartCalendarInterval</key>
<dict><key>Hour</key><integer>3</integer></dict>

Optionen (watch-dir)

Option	Beschreibung
-d / --directory PATH	Zu überwachendes Verzeichnis (mehrfach angebbar). Überschreibt watch.directories.
--interval TEXT	Intervall zwischen Ticks (24h, 90m, 600). Default: Config (24h). Im --once-Modus ignoriert.
--once	Genau ein Tick, dann Exit 0.
--stability-window TEXT	Wartezeit zur Erkennung wachsender Dateien. Default: Config (60s). 0 deaktiviert.
--category TEXT	Kategorie für alle Videos in allen überwachten Verzeichnissen (überschreibt defaults.category aus Config).
--recursive, -r	Unterverzeichnisse mit einbeziehen (siehe Verzeichnis-Settings)
--no-infuse / --no-web / --no-archive	Profile überspringen (wie bei publish-dir).
--force	Auch bereits publizierte Videos neu publizieren.
--delete-source	Pro Video: Originaldatei (+ .settings.toml) im überwachten Verzeichnis löschen, sobald alle aktiven Kanäle erfolgreich und das Archiv Size-verifiziert ist. Ideal für unattended Watch auf Export-Verzeichnissen (Platz wird automatisch frei).
--web-budget	Override Web-Speicherbudget für diesen Watch-Lauf (siehe Web-Speicher-Budget)
--web-cleanup-dry-run	Cleanup-Plan zeigen, nichts löschen
--work-dir PATH	Arbeitsverzeichnis (überschreibt paths.work_dir).
--verbose, -v	Zusätzliche Ablaufinformationen auf stderr.

---

Web-Speicher-Budget

Das Web-Target (typisch Hostpoint) hat in der Regel ein hartes Speicherlimit (z.B. 500 GB). Damit unattended watch-dir-Läufe nicht in den Vollläufer laufen, kann ab v0.10.0 ein Speicherbudget und/oder eine maximale Aufbewahrungsdauer pro Mediaset konfiguriert werden. Vor jedem Web-Upload laufen zwei Cleanup-Pässe in dieser Reihenfolge:

1. Age-Pass (web.max_age_days): alles löschen, was älter als die Schwelle ist — unabhängig vom Budget.
2. Budget-Pass (web.storage_budget): falls noch immer zu wenig Platz, ältester Rest weg, bis (used + new + 5 %-Marge) ins Budget passt.

Beide Constraints sind unabhängig: nur Budget, nur Age, beides oder keines.

Konfiguration

# Speicherbudget (optional)
familienfilm-manager config set web.storage_budget 500GB

# Maximales Alter eines Web-Mediasets in Tagen (optional)
familienfilm-manager config set web.max_age_days 365

storage_budget-Suffixe: B, K/KB, M/MB, G/GB, T/TB (case-insensitiv, SI-Basis = 10⁹). Leerer Wert → kein Cleanup.

max_age_days ist ein einfacher Integer in Tagen. Leerer Wert oder 0 → keine Altersbegrenzung.

Trigger-Verhalten (lazy)

Beide Cleanup-Pässe laufen nur vor einem Web-Upload. Es gibt keinen separaten Hintergrund-Job. Wenn lange nichts publiziert wird, können Mediasets im Web durchaus älter als die Schwelle bleiben — pragmatisch und ohne Überraschungen.

Wie der Budget-Pass rechnet

benötigt = aktuell_belegt + neues_mediaset
maximum = budget × 95 %    # 5 % Sicherheitsmarge

Wenn benötigt > maximum, wird das älteste Mediaset (gemessen an der mtime der index.html im Mediaset-Verzeichnis) per rclone purge gelöscht. Iteriert solange, bis Platz reicht.

Konsole loggt explizit

Web-Alter-Check: max 365 Tage, 2 von 17 Mediaset(s) zu alt
Web-Cleanup (Alter): lösche q26qobjxl4c3 (220 MB, 412 Tage alt — älter als max 365)
Web-Budget: belegt 421.2 GB / 500 GB (Marge 5% = 25 GB), neuer Upload 220 MB

Effekt auf Familienfilme.md

Bereinigte Einträge bekommen den Status cleaned-up und eine sprechende Status-Zeile:

- **Status:** Aus Web-Speicher entfernt am 27.04.2026 (älter als 365 Tage)
- **Lokal:** `nas:/Familienfilme/Final/2024`

Mögliche Gründe in Klammern: „älter als 365 Tage" oder „Speicherplatz". Der Lokal-Pfad bleibt sichtbar — der Film bleibt auf dem NAS, nur die Web-Kopie ist weg. Die Web-Zeile bleibt ebenfalls als historische Spur erhalten; der Status-Text macht klar, dass die URL nicht mehr live ist.

Pro-Lauf-Overrides

Flag	Wirkung
--web-budget '1TB'	Übersteuert web.storage_budget für diesen Lauf
--web-max-age 90	Übersteuert web.max_age_days für diesen Lauf (Tage)
--web-cleanup-dry-run	Zeigt den Lösch-Plan beider Pässe, löscht aber nichts (Upload erfolgt trotzdem)

Hinweis zu Infuse + Archive

Beide Kanäle bleiben unbeschränkt — sie laufen gegen NAS-Storage, das aus Sicht des Managers als grenzenlos gilt. Es gibt dort weder Budget- noch Age-Cleanup.

Status-Übersicht

familienfilm-manager web-storage status

Zeigt Read-only ohne Änderung:

Web-Target: hostpoint:
Budget: 500.00 GB (Marge 5% = 25.00 GB)
Max-Age: 365 Tage

Mediasets: 36
Belegt: 98.54 GB
  → 19.7% des Budgets
  → effektiv frei (mit Marge): 376.46 GB

Ältestes:  q26qobjxl4c3 (220.00 MB, 102 Tage alt)
Neuestes:  k2x7sifsp7ja (1.45 GB, 0 Tage alt)

→ Erstes Mediaset wird in 263 Tag(en) alters-rotiert (bei nächstem Web-Upload).

Override für „was-wäre-wenn"-Szenarien: --web-budget 1TB, --web-max-age 90.

---

KI-Vorschaubild-Wahl & Persistierung

Wenn du beim Publish kein explizites Vorschaubild angibst (kein --poster-frame/--poster-at, kein poster-Xs-Filename-Suffix, kein Sidecar-Wert), wählt der Vorschaubild-Manager via Claude Frame + Crop. Seit v0.11.0 wird die Wahl ins .settings.toml zurückgeschrieben:

[poster]
frame_number = 142
crop_position = "center"
selected_by = "ai"
ai_reasoning = """
Frame zeigt schönes Lächeln und gute Belichtung.
Crop center wegen zentraler Bildkomposition.
"""

Beim nächsten Republish liest der Familienfilm-Manager diese Werte aus dem Sidecar und übergibt sie als „manuelle" Vorgabe an den Mediaset-Creator — kein erneuter KI-Aufruf, kein Token-Verbrauch, gleicher Frame, gleicher Crop. Stabilität + Kosten-Effizienz.

Hierarchie der Poster-Wahl

Bei jedem Publish wird in dieser Reihenfolge der erste gefundene Wert genommen:

1. CLI-Argumente (--poster-frame, --poster-at, --poster-crop)
2. Filename-Suffix (Video poster-2m14s700.mov)
3. Sidecar [poster] (egal ob selected_by="manual" oder "ai")
4. Nichts da → KI im Vorschaubild-Manager wählt + Wahl wird persistiert

Ein explizites User-Argument überschreibt auch eine bestehende KI-Wahl im Sidecar — wenn du also unzufrieden mit der KI-Wahl bist, einfach --poster-at 47.5 setzen und die alte Wahl wird beim Re-Publish ersetzt.

selected_by-Werte

Wert	Bedeutung
"cli"	User hat per CLI-Argument explizit gewählt (--poster-frame/--poster-at/--poster-crop)
"filename"	Aus dem Datei­namen-Suffix poster-Xs abgeleitet
"sidecar"	Aus bestehender Sidecar gelesen (Ursprung in dieser Sidecar-Datei nicht weiter dokumentiert — z.B. pre-v0.11.0 oder per Hand editiert)
"ai"	Claude im Vorschaubild-Manager hat gewählt; ai_reasoning enthält die Begründung
"sidecar-image"	Neben dem Video lag ein Sidecar-Bild (z.B. .jpg), das direkt als Vorlage genommen wurde — kein Frame-Index

KI-Origin-Schutz: Wenn ein Sidecar-Eintrag ursprünglich von der KI stammt (selected_by = "ai") und beim nächsten Republish nichts Neues vom User kommt, wird selected_by = "ai" beibehalten — du verlierst die Information „KI-Wahl" nicht, nur weil sie zwischenzeitlich ins Sidecar gewandert ist.

---

Poison-Video-Detection

Im watch-dir-Modus läuft der Publisher unattended. Wenn ein Video wiederholt scheitert (z.B. wegen falschem poster-Xs-Suffix oder defektem Codec), wäre es früher bei jedem Tick erneut versucht worden — endlos, alle 5 Minuten.

Seit v0.11.0:

• Bei jedem Fehlversuch zählt das Sidecar [publish].failure_count hoch.
• Ab 3 aufeinander folgenden Fehlversuchen UND unveränderter Source-Datei wird das Video als POISONED geskippt — mit klarer Meldung in der Konsole:

  Poison-Skip: Video.mov (3 Fehlversuche, Source unverändert).
  Mit --force erzwingen.
  

• Sobald die Source-Datei geändert wird (anderer Fingerprint), startet der Counter wieder bei 0 — neue Datei verdient frischen Versuch.
• Ein erfolgreicher Publish löscht den Counter ebenfalls.
• --force umgeht die Poison-Sperre (für gezieltes Re-Try ohne Source-Änderung).

Damit terminieren watch-dir-Loops auf bekannt kaputten Videos zuverlässig.

---

rclone-Quellen

Statt SMB/NAS-Mounts kannst du seit v0.7.0 rclone-Pfade direkt als Quelle angeben (remote:path). Alle drei Befehle (publish, publish-dir, watch-dir) akzeptieren rclone-URIs. Lokale Pfade und rclone-URIs können in watch.directories frei gemischt werden (komma-separiert).

familienfilm-manager config set paths.work_dir "/Users/du/Movies/Familienfilme"
familienfilm-manager config set watch.directories "lyssach-nas:/Familienfilme/Quelle"
familienfilm-manager watch-dir --once -v

Warum rclone statt SMB-Mount?

⚠️ Wichtig — Bekannte Inkompatibilität: Auf macOS kann ein SMB-Mount zum NAS nicht gleichzeitig mit rclone-SFTP-Verbindungen zum selben NAS genutzt werden. Der aktive SMB-Mount belegt die Netzwerkroute exklusiv; parallele SFTP-Versuche scheitern mit no route to host (ARP-/Routing- Konflikt). Diagnostiziert in v0.6.0 nach langem Debugging.

Konsequenz: Wenn dein NAS gleichzeitig als Quelle und als Deploy-Ziel dient (Infuse/Archive), darfst du es nicht als SMB-Share einbinden. Nutze stattdessen einen rclone-Remote für beide Richtungen.

Wenn Quelle und Ziel auf unterschiedlichen NAS liegen, kann der SMB-Mount der Quelle funktionieren — aber rclone-Quellen sind trotzdem empfohlen (Staging-Verzeichnis + Light-Peek profitieren).

Mit rclone in beide Richtungen — lesen vom NAS, schreiben zum NAS (Infuse, Archive) — gibt es keinen SMB-Mount mehr, das Problem ist vermieden. Ein eventuell noch vorhandener SMB-Mount zum selben NAS sollte in Finder → Gehe zu → Mit Server verbinden getrennt werden (oder via diskutil unmount /Volumes/<ShareName>).

Wie läuft ein Publish mit rclone-Quelle ab?

1. Staging — Video plus alle stem-identischen Sidecars (.settings.toml, .fcpxml, .lfpackage, Fanart etc.) werden via rclone copyto ins paths.work_dir/stage-<uuid>/ kopiert. Das Staging- Verzeichnis ist pro Publish isoliert.
2. Lokaler Publish — ab hier läuft der Publisher unverändert: ffprobe, mediaset-Erstellung, Infuse- und Web-Deploy, Archivierung. Alles passiert auf der lokalen Kopie — kein Netzwerk-Stress.
3. Sidecar-Rücksync — nach erfolgreichem Publish wird die aktualisierte .settings.toml via rclone copyto zurück an die Original-Position auf dem Remote geschrieben. Idempotenz (per-Kanal published_at + Fingerprint) bleibt voll erhalten.
4. Cleanup — das Staging-Verzeichnis wird entfernt.

Light-Peek Skip-Check

Bei publish-dir / watch-dir gegen eine rclone-Quelle wird für die Idempotenz-Prüfung nur das kleine Sidecar vom Remote geladen, nicht das Video. Wenn alle aktiven Kanäle ein published_at haben und die im Sidecar gespeicherte source.size_bytes mit der aktuellen Remote-Size übereinstimmt, wird das Video übersprungen — ohne einen einzigen Byte Video-Traffic. Beim Daemon-Lauf mit 100 Videos und 3 neuen fallen damit nur die 3 neuen ins Gewicht.

Limitation: Head-SHA1-Fingerprint entfällt bei rclone-Quellen (würde volles Staging erfordern). Size-Match allein ist die Fingerprint-Basis. Bei Neu-Export ändert sich die Size in aller Regel ebenfalls — zuverlässig genug für den praktischen Fall.

Voraussetzungen

• rclone muss konfiguriert sein für das Remote — genauso wie für die Deploy-Ziele. Der mediaset-creator braucht kein Extra-Setup.
• paths.work_dir muss gesetzt sein für rclone-Quellen (Staging-Ziel). Ohne diese Config gibt es einen deutlichen Fehler vor dem Staging:

  rclone-Quelle nas:/Quelle braucht ein work_dir zum Stagen.
  Setze paths.work_dir in der Config.
  

• familienfilm.toml kann auch auf dem Remote liegen. Die Settings-Kette läuft via rclone cat nach oben bis Remote-Root (remote:).

Nicht in v0.7.0

• Stabilitätscheck (gegen wachsende Dateien während eines LumaFusion- Exports) ist bei rclone-Quellen aktuell inaktiv. Lokale Quellen nutzen ihn weiter.
• Mixed-Kontext: lokale Video-Quelle mit familienfilm.toml auf Remote (oder umgekehrt) wird nicht unterstützt — die Settings-Suche folgt strikt dem Quelltyp der Video-URI.

---

Metadaten-Extraktion

Metadaten werden in folgender Priorität ermittelt:

Aufnahmedatum

1. CLI-Parameter (--date) – überschreibt alles
2. QuickTime-Tag (com.apple.quicktime.creationdate) – bewusst in Final Cut Pro gesetztes Datum
3. Dateiname – ISO-Datum am Anfang des Dateinamens (z.B. 2019-12-22 Twannbachschlucht.mov)
4. Generische Tags (creation_time, date) – oft das Datei-Änderungsdatum, nicht das Aufnahmedatum

Der Dateiname hat bewusst höhere Priorität als generische Tags (creation_time), weil der Videoschnitt selten am gleichen Tag wie die Aufnahme stattfindet. So kann das korrekte Aufnahmedatum über den Dateinamen bestimmt werden.

Titel

1. CLI-Parameter (--title) – überschreibt alles
2. QuickTime-Tags (via ffprobe) – aus Final Cut Pro exportierte Metadaten
3. Dateiname – Titel nach dem Datumspräfix:
   • 2025-03-24 Wanderung auf den Napf.m4v → «Wanderung auf den Napf»
   • 2025-03-24 - Wanderung auf den Napf.m4v → «Wanderung auf den Napf»

Poster-Zeitpunkt aus dem Dateinamen

Der Zeitpunkt für das Vorschaubild kann direkt im Dateinamen mitgegeben werden – ideal für Videoschnitt-Programme wie LumaFusion, die keine Sidecar-Dateien beim Export erstellen.

Format: poster-<zeit> am Ende des Dateinamens (Leerzeichen davor). Minuten-Marker: min (vollständig) oder m (Kurzform, ffmpeg-Stil).

Suffix	Bedeutung
poster-2min / poster-2m	2 Minuten = 120 Sek.
poster-3min12 / poster-3m12	3 Min 12 Sek = 192 Sek.
poster-3min11s / poster-3m11s	3 Min 11 Sek (mit trailing s als Sekunden-Marker)
poster-1min30s500 / poster-1m30s500	1 Min 30.5 Sek (Sub-Sekunden)
poster-30s	30 Sek.
poster-30s500	30.5 Sek.

Beispiel:

2026-04-16 HDR-Test poster-1min30.mov

→ Datum: 2026-04-16, Titel: «HDR-Test», Poster-Zeitpunkt: 90 Sek.

Der Suffix wird beim Parsen vom Titel entfernt (landet nicht im Output-Dateinamen) und automatisch in die Sidecar-Datei (.settings.toml) geschrieben. Bei einem späteren publish ohne Suffix im Dateinamen wird der Wert aus der Sidecar-Datei gelesen.

Priorität: CLI (--poster-at) > Filename-Suffix > Sidecar.

Wichtig: Ein Aufnahmedatum ist zwingend erforderlich. Ohne Datum wird die Verarbeitung abgebrochen.

---

Settings-Sidecar-Datei

Wenn Poster-Einstellungen via CLI angegeben werden (--poster-frame, --poster-at, --poster-crop), speichert der Familienfilm Manager diese automatisch in einer .settings.toml-Datei neben dem Video:

2025-03-24 Wanderung auf den Napf.m4v
2025-03-24 Wanderung auf den Napf.settings.toml   ← automatisch erstellt

Inhalt:

[poster]
timestamp_seconds = 42.5
crop_position = "center-right"

[web]
web_id = "a3xk9mn2pqrw"
published_at = "2026-04-18T10:23:45"

[local]
published_at = "2026-04-18T10:24:12"

[archive]
published_at = "2026-04-18T10:26:58"

[source]
size_bytes = 4521830394
head_sha1 = "a3f4c9b2..."

[metadata]
category = "Familie Kurmann-Glück"

• [poster] — Poster-Einstellungen (bei erneutem Publish wiederverwendet)
• [web] — Web-ID, Luminance, Publish-Zeitpunkt der Web-Publikation (Hostpoint o.ä.)
• [local] — Publish-Zeitpunkt der Infuse-/LAN-Medienserver-Publikation. Heißt [local] (nicht [infuse]), weil der Kanal einen lokalen Medienserver beliefert — Infuse ist nur eine mögliche Consumer-App
• [archive] — Publish-Zeitpunkt der Archivierung (direkte Kopie des Originals im Langzeit-Archiv, seit v0.9.0 kein TAR mehr)
• [source] — Fingerprint für die publish-dir-Idempotenz (siehe Idempotenz)
• [metadata] — Effektive Metadaten zum Publish-Zeitpunkt. Macht das Archiv selbsttragend: wenn ein Video später aus dem Archiv extrahiert und mit publish neu veröffentlicht wird, kennt es seine ursprüngliche Kategorie — unabhängig von Config-Defaults auf dem aktuellen System.

Archiv-Layout

Im Archiv-Ziel liegen pro Video drei Dateien nebeneinander:

nas:/Archiv/2026/Videoschnitt/
  2026-04-15-Mika-Socken-waschen.mov           ← Originalvideo (direkt, kein TAR)
  2026-04-15-Mika-Socken-waschen.settings.toml ← Management-Metadaten
  2026-04-15-Mika-Socken-waschen.archive.toml  ← konservierte Originalmetadaten

Vorteil: direkter Zugriff auf archivierte Videos am NAS — kein Entpacken mehr nötig. Bestehende TAR-Archive aus früheren Versionen bleiben erhalten.

.archive.toml hält fragile Werte fest, die bei Moves zwischen Archiv- Locations oder bei der ASCII-Slug-Benennung verloren gehen würden:

schema_version = 1
original_filename = "2026-04-15 Mika Socken waschen.mov"
original_mtime = 2026-04-15T18:22:31+02:00   # Export-/Schnittdatum (wichtig!)
archived_at = 2026-04-24T09:00:00+02:00
recording_date = 2026-04-15
title = "Mika Socken waschen"
description = """
Mehrzeilige Beschreibung möglich.
Umlaute, Quotes und Backslashes werden TOML-sicher escaped.
"""

Der .settings.toml-Sidecar bleibt das Publish-Management (Fingerprints für Idempotenz, Poster-Einstellungen, per-Kanal-Timestamps) — .archive.toml ist die Originalmetadaten-Konservierung. Andere Halbwertszeit, andere Datei.

Per-Kanal published_at und Partial-Failure-Schutz

Die drei published_at-Felder werden unabhängig voneinander gesetzt — ein Feld erscheint erst, wenn der zugehörige rclone-Deploy erfolgreich war. Beispiel einer typischen „Web ok, NAS war im Sleep"-Situation:

[web]
web_id = "a3xk9mn2pqrw"
published_at = "2026-04-18T10:23:45"   # Hostpoint erfolgreich

# [local] und [archive] fehlen komplett — NAS war offline

Beim nächsten publish-dir-Lauf erkennt der Skip-Check, dass Local und Archive noch nicht publiziert sind, und baut das Video komplett neu auf (inkl. erneuter Web-Publikation — --force auf Kanal-Ebene folgt in einer späteren Version). Vorher wurde nur ein einziges published_at geschrieben, und der Skip-Check interpretierte das als „fertig" → Infuse und Archive wurden nie nachgeholt.

Category-Auflösung

Die Kategorie wird beim Publish in folgender Reihenfolge aufgelöst (erste Quelle mit Wert gewinnt):

1. CLI --category — expliziter Wille, überschreibt alles
2. Video-Sidecar [metadata].category — für aus dem Archiv extrahierte Videos
3. familienfilm.toml — Verzeichnis-Settings, nächstgelegenes Verzeichnis gewinnt (siehe unten)
4. Config defaults.category — globaler Fallback
5. ffprobe-Metadata — QuickTime-Tag (LumaFusion-Exports liefern das typischerweise nicht)

Sidecar hat bewusst Vorrang vor Config und Directory-Settings: Ein Video soll seine ursprüngliche Kategorie behalten, auch wenn der aktuelle Config-Default inzwischen auf etwas anderes zeigt, oder der Export-Ordner zwischendurch eine andere familienfilm.toml bekommen hat.

---

Verzeichnis-Settings (familienfilm.toml)

Eine Datei namens familienfilm.toml in einem Quellverzeichnis liefert Default-Werte für alle Videos darunter.

Gelesene Felder:

• category (string) — Kategorie für Videos im Verzeichnis.
• web_enabled (bool, seit v0.8.0) — Opt-in für die Web-Veröffentlichung. Seit v0.8.0 ist die Web-Publikation per Default aus. Nur Verzeichnisse mit explizitem web_enabled = true (oder Sidecar-Override, oder CLI --web) publizieren ins Web. Damit kann keine Datei mehr versehentlich veröffentlicht werden — insbesondere nicht beim Re-Publish aus dem Archiv. Der aufgelöste Wert wird beim Publish zusätzlich ins .settings.toml-Sidecar ([web].enabled = true) persistiert, damit die Entscheidung auch ohne Zugriff auf die Quell-familienfilm.toml erhalten bleibt.

Format

# /Volumes/Videoschnitt/Luma Fusion-Export/Familie Kurmann-Glück/familienfilm.toml
category = "Familie Kurmann-Glück"
web_enabled = true   # Web-Kanal aktiv (Default ist aus)

# /Volumes/Videoschnitt/Luma Fusion-Export/Kurmann-Glück privat/familienfilm.toml
category = "Kurmann-Glück privat"
# kein web_enabled → Web bleibt aus (Safety-Default)

Keine hidden-Datei (kein führender Punkt) — absichtlich, damit sie beim Navigieren sichtbar bleibt.

Vererbung

Beim Publish jedes Videos wird die Verzeichniskette von der Quelldatei nach oben gelaufen. Pro Feld gewinnt das nächstgelegene Vorkommen — verschiedene Felder dürfen in verschiedenen Ebenen stehen (z.B. category oben, skip_web weiter unten). Unterverzeichnisse überschreiben also Parents, pro Feld.

Beispiel:

/Movies/
  familienfilm.toml              ← category = "Familie Kurmann-Glück"
  2026-Frühjahr/
    2026-04-14 Ostern.mov        ← erbt "Familie Kurmann-Glück"
  Arbeit-Präsentationen/
    familienfilm.toml            ← category = "Firma XY"
    2026-04-15 Quartalsreport.mov ← "Firma XY" (Child-Override)

Grenze der Suche

• Bei publish-dir und watch-dir ist der Scan-Root des Befehls die obere Grenze. Eine familienfilm.toml direkt im Scan-Root-Argument greift; darüber wird nicht gesucht.
• Beim Einzel-publish läuft die Suche bis zum Filesystem-Root — praktisch heisst das: bis zu der Datei, die du tatsächlich irgendwo im Baum hinterlegt hast.

Rekursiver Scan (--recursive / -r)

publish-dir und watch-dir sind standardmässig flach (nur direkte Dateien des Verzeichnisses). Mit --recursive werden auch Unterverzeichnisse durchsucht:

# Ganzer Jahresbaum in einem Zug:
familienfilm-manager publish-dir /Movies/LumaFusion-Export --recursive

# Watch über verschachtelte Verzeichnisse:
familienfilm-manager watch-dir -d /Movies/LumaFusion-Export --recursive

Hidden-Verzeichnisse (.Trashes, .Spotlight-V100 etc.) werden übersprungen. Sortierung läuft über Verzeichnisgrenzen hinweg (älteste Videos zuerst, egal in welchem Unterverzeichnis).

Kombiniert mit familienfilm.toml: Du kannst einen Kategorien-Baum anlegen, jede Ebene ihre eigene Kategorie — und trotzdem mit einem einzigen publish-dir -r-Aufruf alles konsistent publizieren.

Bei einem erneuten publish werden die Werte automatisch aus der Sidecar-Datei gelesen – CLI-Parameter überschreiben gespeicherte Werte. Die Web-ID wird nach erfolgreicher Erstellung automatisch gespeichert, damit bei erneutem Publish die gleiche ID wiederverwendet wird (gleiche URL bleibt stabil).

Die Sidecar-Datei wird bei der Archivierung automatisch mit ins ISO aufgenommen.

Deaktivieren: --no-sidecar (pro Aufruf) oder familienfilm-manager config set sidecar.enabled false (global).

---

API-Keys (KI-Funktionen)

Der Familienfilm-Manager selbst spricht nicht mit Claude. Wenn aber kein Vorschaubild manuell gewählt wurde (kein --poster-frame/--poster-at, kein Filename-Suffix, kein Sidecar-Wert), übergibt er die Auswahl an den mediaset-creator, der seinerseits den vorschaubild-manager nutzt — und letzterer ruft Claude auf, um aus einem 20-Frame-Mosaik das beste Frame plus Bildausschnitt zu wählen.

Empfohlenes Setup: ANTHROPIC_API_KEY als Umgebungsvariable

# In ~/.zshenv eintragen (gilt für interaktive UND non-interaktive Shells,
# also auch für launchd / cron / Tool-Subprozesse via uv tool):
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshenv

# Für laufende launchd-Jobs zusätzlich (einmalig, persistiert über Reboots):
launchctl setenv ANTHROPIC_API_KEY "sk-ant-..."

ANTHROPIC_API_KEY ist der offizielle Variablenname des Anthropic-SDK und wird von allen meinen Tools bevorzugt gelesen. Der historische Name CLAUDE_API_KEY bleibt als Fallback unterstützt.

Wer liest den Key wann?

Tool	Liest Key?	Wann
Familienfilm-Manager	❌ nein	reicht nichts weiter, KI greift implizit auf das Prozess-ENV zu
Mediaset-Creator	❌ nein	dito (Pass-Through)
Vorschaubild-Manager	✅ ja	beim Mosaic-Auto-Frame und beim Crop-Auto-Wahl

Alternative: lokale Config-Datei

Falls du die Variable nicht ins ENV setzen willst:

vorschaubild-manager config set claude.api_key "sk-ant-..."
# → schreibt nach ~/.config/vorschaubild-manager/config.toml

Funktioniert auch, wenn der vorschaubild-manager nur als Library (via Familienfilm-Manager-Dependency) installiert ist — der Pfad ist unabhängig von der CLI-Nutzung.

Ohne API-Key

Wenn weder ENV noch Config gesetzt sind und kein manuelles Vorschaubild spezifiziert wurde, schlägt der Publish mit einer eindeutigen Fehlermeldung aus dem Vorschaubild-Manager fehl. Lösung: entweder Key setzen oder Vorschaubild explizit angeben (--poster-at 47.5 o.ä.).

---

Konfiguration

Einstellungen werden in ~/.config/familienfilm-manager/config.toml gespeichert.

Befehle

# Wert speichern
familienfilm-manager config set <schlüssel> "<wert>"

# Einzelnen Wert lesen
familienfilm-manager config get <schlüssel>

# Alle gespeicherten Werte anzeigen
familienfilm-manager config list

Erlaubte Schlüssel

Schlüssel	Beschreibung	Standard
targets.infuse	rclone-Ziel für Infuse (z.B. nas:/media/videos/)	(leer)
targets.web	rclone-Ziel für Webserver (z.B. azure:container/shares/)	(leer)
targets.archive	rclone-Ziel für Archiv (z.B. nas:/archive/familienfilme/)	(leer)
infuse.group_by	Gruppierung: year oder month	year
defaults.category	Standard-Kategorie für Videos	(leer)
sidecar.enabled	Sidecar-Dateien automatisch lesen/schreiben	true
cleanup.web_workdir	Temporäres Web-Arbeitsverzeichnis nach erfolgreichem Deployment löschen	true
paths.work_dir	Standard-Arbeitsverzeichnis für temporäre Dateien (lokaler SSD bei SMB-Quellen empfohlen)	(leer)
watch.directories	Zu überwachende Verzeichnisse (komma-separiert) — siehe watch-dir	(leer)
watch.interval_seconds	Intervall zwischen Watch-Ticks in Sekunden	86400 (24h)
watch.stability_window_seconds	Wartezeit zur Erkennung wachsender Dateien (0 = aus)	60
mediaset.branding_base_url	Stamm-URL für Web-Mediasets und OG-Tags	(leer)
mediaset.branding_site_name	Site-Name (sichtbar im Header + OG-Meta)	(leer)
tools.ffmpeg	Pfad zur ffmpeg-Binärdatei	ffmpeg
tools.ffprobe	Pfad zur ffprobe-Binärdatei	ffprobe
tools.rclone	Pfad zur rclone-Binärdatei	rclone

Beispiel

familienfilm-manager config set targets.infuse "nas:/media/familienfilme/"
familienfilm-manager config set targets.web "azure:kurmann-glueck/shares/"
familienfilm-manager config set targets.archive "nas:/archive/familienfilme/"
familienfilm-manager config set defaults.category "Familie Kurmann-Glück"
familienfilm-manager config set mediaset.branding_base_url "https://kurmannmedia.blob.core.windows.net/kurmann-glueck/"

Arbeitsverzeichnis bei SMB-Quellen

Wenn die Quellvideos auf einem SMB-/NAS-Laufwerk liegen, sollte ein lokales Arbeitsverzeichnis konfiguriert werden, damit Komprimierung und temporäre Dateien nicht über das Netzwerk laufen:

familienfilm-manager config set paths.work_dir "~/Movies/.familienfilm-tmp"

Dann werden bei jeder Publikation:

• Quellvideo gelesen vom SMB
• Sidecar .settings.toml geschrieben auf SMB (klein)
• Komprimierung, Thumbnails, Web-Output: lokal im Work-Dir
• Web-Deployment: rclone push vom lokalen Work-Dir zum Webserver

Resolution: CLI --work-dir > Config paths.work_dir > Quellverzeichnis.

---

Verwendung (Python API)

from pathlib import Path
from familienfilm_manager.api import (
    PublishRequest,
    RuntimeOptions,
    publish,
)

request = PublishRequest(
    source_path=Path("/pfad/zu/video.m4v"),
    title="Wanderung auf den Napf",
    category="Familie Kurmann-Glück",
    recording_date="2025-03-24",
)

runtime = RuntimeOptions(
    infuse_target="nas:/media/familienfilme/",
    web_target="azure:kurmann-glueck/shares/",
    archive_target="nas:/archive/familienfilme/",
    branding_base_url="https://example.com/shares/",
)

result = publish(request, runtime)

if result.success:
    print(f"Infuse: {result.infuse_dir} (deployed: {result.infuse_deployed})")
    print(f"Web: {result.web_dir} (deployed: {result.web_deployed})")
    print(f"Archiv: {result.archived}")
else:
    print(f"Fehler: {result.error_message}")

Öffentliche API-Exporte

from familienfilm_manager.api import (
    publish,                 # Gesamtworkflow
    publish_directory,       # Batch über ein Verzeichnis
    watch_directories,       # Endlosschleife / Single-Shot über mehrere Verzeichnisse
    deploy_infuse,           # Nur Infuse-Deployment
    deploy_web,              # Nur Web-Deployment
    archive,                 # Nur Archivierung
    PublishRequest,          # Fachlicher Request
    PublishResult,           # Ergebnis
    DirectoryPublishResult,  # Batch-Ergebnis
    VideoStatus,             # Status eines Videos im Batch
    VideoStatusKind,         # PUBLISHED/SKIPPED/FAILED/PENDING/UNSTABLE
    WatchRequest,            # Watch-Request
    WatchResult,             # Watch-Gesamtergebnis
    WatchTickResult,         # Ergebnis eines einzelnen Ticks
    DeployRequest,           # Deploy-Request
    DeployResult,            # Deploy-Ergebnis
    ArchiveRequest,          # Archiv-Request
    ArchiveResult,           # Archiv-Ergebnis
    RuntimeOptions,          # Technische Optionen
    FamilienfilmEvent,       # Fortschritts-Event
    FamilienfilmStage,       # Stage-IDs
)

---

Lizenz

MIT