# 🎬 Internetfilm Manager

**"Entschleunigung durch Archivierung"**

Dieses Tool dient nicht dem massenhaften Ansammeln von Videos, sondern dem bewussten Kuratieren, Veredeln und Archivieren wertvoller Inhalte aus dem Internet. Es transformiert flüchtige Streams in beständige, private Medienbibliotheken.

## Letzte Änderungen

**2.5.0**

- **Migration zu `kurmann-vorschaubild-manager` 2.0.0**: Abhängigkeit auf das veröffentlichte Paket [`kurmann-vorschaubild-manager`](https://github.com/kurmann/vorschaubild-manager) aktualisiert
  - `module_mosaic.py` und `module_poster_rebuild.py` nutzen jetzt ausschliesslich die öffentliche Python-API aus `vorschaubild_manager`
  - Die bisherige Session-basierte Integration wurde durch Public-API-Aufrufe wie `extract`, `create_mosaic`, `extract_frame`, `suggest_crop`, `render_poster` und `read_poster_metadata` ersetzt
  - Minor-Release 2.5.0 zur Veröffentlichung der neuen Manager-Integration

**2.3.3**

- **Interne Architekturbereinigung**: Klare Schichtentrennung zwischen CLI, App-Orchestrierung und Feature-Logik
  - `version.py`: Version- und Runtime-Hilfsfunktionen aus `cli.py` extrahiert (inkl. Bugfix für `_get_pyproject_path`)
  - `app.py`: Job-Listing (`list_jobs`) aus `cli.py` in dediziertes App-Modul verschoben
  - `cli.py`: Schlanker gehalten – delegiert an `version.py` und `app.py`
- **Externe Abhängigkeit vollständig**: `[tool.uv.sources]`-Pfadüberschreibung für `video-thumbnail-creator` entfernt; das Paket wird ausschliesslich als externe PyPI-Abhängigkeit referenziert

**2.3.2**

- **Repositorystruktur korrigiert**: `video-thumbnail-creator` wurde wieder aus diesem Repository entfernt. Es verbleibt als eigenständiges Repository [`kurmann/video-thumbnail-creator`](https://github.com/kurmann/video-thumbnail-creator), da es auch von anderen Repositories (z. B. `kurmann/videoschnitt`) genutzt wird. `internetfilm-manager` referenziert es wieder als externe Abhängigkeit.

**2.3.1**

- **Verbesserung Szenenerkennung**: Die Prompts für die K.I.-Bildauswahl wurde verbessert: Bessere Berücksichtigung von Gesichtsausdrücken und Posen des Hauptsubjekts

**2.3.0**

- **Claude-Auto-Kuratierung robuster**: Titel, Beschreibungen und Transkript-Auszüge mit eingebetteten Anführungszeichen werden im Prompt sauber escaped, und fehlerhaftes JSON von Claude wird in typischen Quote-Fällen toleranter geparst
- **video-thumbnail-creator 1.6.1**: Upgrade auf die aktuelle PyPI-Version mit verfeinertem Internet-Poster-Layout
  - Neues `ThumbnailSession`-API für schrittweise Thumbnail-Erstellung
  - `create_thumbnail()` Convenience-Funktion für vollautomatische Thumbnail-Generierung
  - Drei Integrationsstufen: High-Level (`create_thumbnail`), Mid-Level (`ThumbnailSession`), Low-Level (Einzelfunktionen)
   - Lange Titel bleiben im Internet-Stil besser innerhalb des Titelbereichs und drängen Datum oder Notiz unten nicht mehr zusammen
   - Overlay-Notiz und Datum erhalten einen reservierten Bereich im unteren Poster-Teil, was Lesbarkeit und visuelle Balance verbessert
   - Der Kategorie-Header oben ist größer und ausgewogener proportioniert, skaliert aber weiterhin automatisch für längere Labels
   - Header-Band oben und Textfläche unten wurden neu austariert und sorgen für ruhigere Abstände im Gesamtbild
- **Phase 2 Poster-Format**: Wechsel von 16:9 Landscape auf 2:3 Poster-Format mit Overlays (Titel, Kanal, Upload-Datum)
- **Refactoring module_mosaic.py**: Komplette Überarbeitung der Poster-Erstellung – von ~460 Zeilen eigenem Code auf ~80 Zeilen via `ThumbnailSession`

**2.1.0**
- HandBrake mit ffmpeg ersetzt für das Video-Encoding, vereinfachter Build-Workflow

**2.0.0**
- Veröffentlichung auf PyPI

## 🎯 Sinn & Zweck

Der **Internetfilm Manager** ist eine intelligente, KI-gestützte Pipeline für macOS, die einen klaren Fokus hat:

**Archivierung mit Qualität:** Statt Videos einfach herunterzuladen und zu sammeln, veredelt dieses Tool jeden Inhalt professionell. Es erstellt hochwertige, dauerhaft archivierte Medien mit vollständigen Metadaten, die sowohl auf Media-Servern (Emby/Plex) perfekt funktionieren als auch als langfristige Cold-Storage-Archive (DMG) gesichert werden.

**Weniger Ablenkungen, mehr Fokus:** Das Tool hilft dabei, bewusst mit digitalen Inhalten umzugehen. Anstatt in der unendlichen Flut von Online-Videos verloren zu gehen, kuratierst du gezielt wertvolle Inhalte für deine private Mediathek. Einmal archiviert, sind die Videos jederzeit verfügbar – ohne Algorithmen, ohne Ablenkungen, ohne die Versuchung endlos weiterzuscrollen.

**Digitale Souveränität:** Du behältst die Kontrolle über deine Inhalte. Keine Abhängigkeit von Plattformen, die Videos löschen oder ändern können. Deine Mediathek gehört dir.

## ✨ Features

### 📥 Download & Queue-Management
* **Smart Fetch:** Einzelne Videos oder ganze Playlists in eine Warteschlange packen
* **Auto-Download Playlists (NEU):** Vordefinierte Playlists automatisch zur Queue hinzufügen – keine manuelle URL-Eingabe mehr nötig ([Details](docs/AUTO_DOWNLOAD_PLAYLISTS.md))
  * Konfigurierbar über Einstellungsmenü
  * Jede Playlist mit eigener Kategorie (Patrick, Eltern, Kathrin, Kinder)
  * Automatische Prüfung gegen Archiv – nur neue Videos werden heruntergeladen
* **Automatische Pausen:** Intelligente Rate-Limiting für YouTube (60 Sekunden zwischen Downloads)
* **Multi-Target-Support:** Sortierung nach Zielgruppen (Patrick, Kinder, Eltern, Kathrin, Musikvideos)
* **Höchste Qualität:** Lädt Videos, Audio, Untertitel und Metadaten in bestmöglicher Qualität via `yt-dlp`
* **Auto-Pipeline (NEU):** Download + Auto-Kuratierung + Auto-Deployment in einem Durchgang
  * `[d]` Nur Download (Standard)
  * `[c]` Download + Auto-Kuratierung
  * `[cd]` Download + Auto-Kuratierung + Auto-Deployment (Vollautomatisch bis zur Server-Bereitstellung)

### 🧠 Anthropic Claude AI Integration (Kernstück)
Die KI-Integration ist der Herzschlag des Tools und macht jedes Video zu einem professionellen Medienprodukt:

* **Intelligente Metadaten-Bereinigung:**
  * Entfernt Clickbait, Emojis (🚀), Hashtags (#) und "Schreihals"-Elemente
  * Korrigiert Groß-/Kleinschreibung automatisch (keine ALL CAPS mehr)
  * Entfernt störende Zusätze wie "Official Video", "4K", "HD"
  * Ersetzt Pipe-Zeichen ( | ) durch sinnvolle Trennzeichen
  * Unterstützt mehrsprachige Titel mit korrekter Grammatik (Englisch: Title Case, Deutsch: Normale Rechtschreibung)

* **Kontrolliertes Vokabular für Keywords (NEU):**
  * **Archivarische Verschlagwortung:** Konsistente und homogene Keywords für langfristiges Archiv
  * **Masterlist:** ~600 standardisierte Keywords aus `Masterlist_keywords.txt`
  * **Trichter-Prinzip:** Genre → Thematische Keywords aus Vokabular → Neue Keywords nur bei Bedarf
  * **Blacklist-Filterung:** Automatische Entfernung von Kanalnamen, Qualitätsangaben (4K, HD), technischen Begriffen
  * **Deduplizierung:** Case-insensitive Entfernung von Dubletten
  * **Beispiele:** "Tata Signa 4018" → "LKW", "Nicole" (Kanalname) → "Finanzen" (Thema)
  * **Substantiv-Singular-Regel:** Übergeordnete Kategorien statt spezifischer Markennamen

* **Mehrstufige Beschreibungsgenerierung:**
  * **Kurzbeschreibung:** Kompakte, sachliche Zusammenfassung (max. 150 Zeichen) für Übersichtslisten
  * **Langbeschreibung:** Ausführliche Inhaltsangabe basierend auf Video-Beschreibung UND vollständigem Transkript
  * Analyse der tatsächlichen Sprache des Videos (nicht nur der Metadaten)

* **Strikte Genre-Klassifizierung (Single-Choice):**
  * 12 vordefinierte Standard-Genres für konsistente Kategorisierung
  * Automatische Validierung der AI-Antworten gegen Genre-Liste
  * Trennung von Genre (Thema) und Format (z.B. Tutorial, Vlog → Keywords)
  * Fallback zu "Unkategorisiert" bei ungültigen Genres
  * Siehe [Genre-Klassifizierung](docs/GENRE_CLASSIFICATION.md) für Details

* **Automatische Kapitelgenerierung:**
  * Analysiert das VTT-Transkript (gesprochenes Wort) mit Zeitstempeln
  * Erstellt 5-15 logische Kapitelmarken (keine 1:1-Kopie des Transkripts)
  * Kapitel werden direkt in die M4V-Datei eingebettet (FFMETADATA)
  * Respektiert die Originalsprache für Kapiteltitel

* **Spracherkennung:**
  * Automatische Erkennung der tatsächlichen Video-Sprache durch Transkript-Analyse
  * Korrigiert fehlerhafte Metadaten von YouTube
  * Mehrsprachige Untertitel-Verwaltung (Hauptsprache + Englisch als Fallback)

### 🎨 Professionelle Poster-Erstellung
* **16:9 Format:** Perfekt für moderne Media-Server (Emby/Plex)
* **4x5 Mosaik:** 20 Vorschaubilder aus dem Video
* **Blurred-Background-Technik:** Verhindert schwarze Balken bei nicht-16:9-Videos
* **Interaktive Auswahl:** Wähle manuell das beste Bild aus 19 Optionen oder verwende das Original
* **KI-gestützte Auswahl:** Claude AI analysiert alle Bilder und wählt automatisch das beste Poster (niemals das Original-Thumbnail)
* **Automatische Beschriftung:** Nummerierte Kacheln mit Tastenkürzel-Info

### 🤖 Auto-Kuratierung
* **Vollautomatischer Modus:** K.I. trifft alle Entscheidungen ohne Nutzer-Interaktion
* **Intelligente Auswahl:** Automatische Wahl von Titeln, Beschreibungen, Kapiteln und Poster
* **Transparenz:** Zeigt alle getroffenen Entscheidungen in der Konsole an
* **Fallback:** Bei Fehlern wird Abbruch empfohlen und manuelle Kuratierung vorgeschlagen
* **Nachbearbeitung möglich:** Auch nach Auto-Kuratierung kann der Job manuell nachbearbeitet werden

### 🎵 Spezieller Musikvideo-Modus
* **ID3-Tags:** Korrekte Artist-, Album-, Track-, Disk-Metadaten
* **Compilation-Support:** Sampler/Alben mit mehreren Künstlern
* **Automatische Sortierung:** Nach Album organisiert statt nach Kanal

### 📦 Import
* **Restore-Funktion:** Suche im Master-Archiv nach ID **oder Titel** und hole alte Videos zurück
* **DMG→MP3 Extraktion:** Audio aus Archiv-DMGs per ID **oder Titel** extrahieren und in Apple Music importieren
* **Direkte Kuratierung:** Nach Import sofort zur Bearbeitung springen

### 🔨 Professionelle Verarbeitung

#### Audio
* **Loudnorm-Filter:** Gleichmäßige Lautstärke nach TV-Standard (I=-16, TP=-1.5, LRA=11)
* **AAC-Encoding:** 256 kbit/s, 48 kHz, Stereo
* **Resampling:** Asynchrone Audio-Synchronisation für problemfreie Wiedergabe

#### Video
* **H.265 10-bit Encoding:** Höchste Qualität bei minimaler Dateigröße
* **VideoToolbox Acceleration:** Hardware-beschleunigte Encodierung auf macOS (vt_h265_10bit)
* **Adaptives Encoding:** Automatische Qualitätsanpassung bei zu hoher Bitrate (Zielqualität → Bitratenprüfung → ggf. erneutes Encoding mit reduzierter Qualität)
* **Konstante Framerate:** CFR für optimale Kompatibilität
* **Intelligente Keyframes:** Alle 30 Frames für präzises Seeking

#### Container & Tagging
* **M4V-Container:** Vollständig kompatibel mit Apple-Ökosystem, Emby und Plex
* **mutagen:** Professionelles MP4-Atom-Tagging für alle Metadaten (pure Python)
* **Eingebettete Untertitel:** Mehrsprachige VTT-Untertitel direkt im Container
* **Kapitelmarken:** FFMETADATA-Format mit Millisekunden-Präzision
* **Komplette Metadaten:** Titel, Künstler, Album, Jahr, Genre, Beschreibungen (kurz & lang), Sprache, Artwork

### 🚀 Automatisches Deployment

#### Media-Deployment (Hot Storage)
* **Ziel:** Media-Server (Emby/Plex) via Rclone
* **Struktur:** `/Zielgruppe/Kanal/Video.m4v`
* **Beispiel:** `/Patrick/SpaceX/2025-05-15_Starship_Launch.m4v`
* **Musikvideos:** `/Musikvideos/Album-Name/001 - Artist - Title.m4v`

#### Master-Archivierung (Cold Storage)
* **DMG-Format:** Read-only Disk Images für macOS
* **Vollständiger Inhalt:**
  * Original-Video (MKV/WebM/MP4)
  * Alle Original-Metadaten (JSON)
  * Original-Thumbnail
  * Kuratiertes Poster
  * VTT-Untertitel (alle Sprachen)
  * Chat-Logs der KI-Interaktion
* **Struktur:** `/Jahr/YYYY-MM-DD_platform_id.dmg`
* **Beispiel:** `/2025/2025-05-15_youtube_xYz123Ab.dmg`
* **Vorteil:** Perfekt für Cold Storage auf NAS – kompakt, schreibgeschützt, macOS-nativ mountbar

#### Robuster Transfer
* **Rclone:** Zuverlässiger Upload mit Fortschrittsanzeige
* **Checksum-Skip:** Umgeht SFTP-Probleme mit Synology NAS
* **Cleanup:** Automatische Löschung des Arbeitsverzeichnisses nach erfolgreichem Upload

## 🛠️ Installation

### Voraussetzungen
Das Tool ist für **macOS** optimiert und nutzt native macOS-Features wie `hdiutil` für DMG-Erstellung.

**System-Anforderungen:**
* macOS 10.14 oder neuer
* Python 3.9 oder höher
* Mindestens 20 GB freier Speicherplatz (SSD empfohlen für `work_dir`)
* Internetverbindung für Downloads und KI-Anfragen

### 1. System-Tools installieren

Alle erforderlichen Tools via Homebrew installieren:

```bash
brew install ffmpeg yt-dlp rclone
```

**Was wird wofür genutzt?**
* `ffmpeg` / `ffprobe`: Audio/Video-Analyse, -Verarbeitung und H.265 10-bit Video-Encoding (VideoToolbox HW)
* `yt-dlp`: Video-Download von YouTube und anderen Plattformen
* `rclone`: Remote-Dateitransfer zum NAS/Cloud

### 2. Rclone konfigurieren

Richte ein Rclone-Remote für dein NAS/Cloud-Ziel ein:

```bash
rclone config
```

**Beispiel-Konfiguration:**
* Name: `lys-nas`
* Type: `sftp` (oder `webdav`, `ftp`, etc.)
* Host: `192.168.1.100:22`
* User: `dein-username`
* Password: `dein-password` (oder SSH-Key)

Teste die Verbindung:
```bash
rclone lsd lys-nas:/
```

### 3. Repository klonen & Installation

#### Option A: Installation mit uv (empfohlen)

[uv](https://github.com/astral-sh/uv) ist ein schneller Python-Paketmanager, der die Installation vereinfacht:

```bash
# uv installieren (falls noch nicht vorhanden)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Repository klonen
git clone https://github.com/kurmann/internetfilm_manager.git
cd internetfilm_manager

# Abhängigkeiten mit uv installieren
uv pip install -e .

# Anwendung starten
internetfilm-manager
```

Mit `uv` wird automatisch eine virtuelle Umgebung erstellt und das Tool ist sofort über den Befehl `internetfilm-manager` verfügbar.

#### Option B: Klassische Installation mit pip

```bash
# Repository klonen
git clone https://github.com/kurmann/internetfilm_manager.git
cd internetfilm_manager

# Python Virtual Environment erstellen
python3 -m venv .venv
source .venv/bin/activate

# Abhängigkeiten installieren (aus pyproject.toml)
pip install -e .

# Anwendung starten
internetfilm-manager
```

#### CLI-Befehl global verfügbar machen (macOS)

Um `internetfilm-manager` von überall im Terminal aufrufen zu können, kannst du einen symbolischen Link (Symlink) in deinem lokalen Bin-Verzeichnis erstellen. Dies ist der empfohlene Weg auf macOS:

```bash
# 1. Sicherstellen, dass run.sh ausführbar ist
chmod +x run.sh

# 2. Symlink in /usr/local/bin erstellen (erfordert Admin-Passwort)
sudo ln -s "$(pwd)/run.sh" /usr/local/bin/internetfilm-manager
```

Nun kannst du die Anwendung einfach durch Eingabe von `internetfilm-manager` in jedem beliebigen Terminal-Fenster starten.

**Hinweis:** Bei Installation mit `uv` oder `pip install -e .` ist der Befehl `internetfilm-manager` automatisch verfügbar, sodass der Symlink nicht mehr nötig ist.

### 4. Anthropic Claude API Key holen

Das Tool nutzt Anthropic Claude für KI-Funktionen. Hier erfährst du, wie du einen API Key erhältst:

1. Gehe zu [Anthropic Console](https://console.anthropic.com/)
2. Erstelle einen neuen API Key
3. Kopiere den Key

**Wichtig:** Der API Key wird beim ersten Start abgefragt und in `config.json` gespeichert.

**Konfigurationsspeicherort:**
* macOS/Linux: `~/.config/internetfilm_manager/config.json`
* Windows: `%APPDATA%\internetfilm_manager\config.json`

Bei Upgrade von einer älteren Version wird eine vorhandene `config.json` im Projektverzeichnis automatisch in das neue Verzeichnis migriert.

### 5. Erste Schritte

```bash
# Anwendung starten (interaktives Menü)
internetfilm-manager

# Oder direkt via Skript
./run.sh
```

Beim ersten Start wird automatisch eine `config.json` erstellt. Du wirst nach folgenden Pfaden gefragt:
* **Work Directory:** Lokales Arbeitsverzeichnis (sollte auf SSD liegen, z.B. `~/Movies/Internetfilme/Work`)
* **Rclone Media Root:** Ziel für Media-Server (z.B. `lys-nas:/Emby/media/Internetfilme`)
* **Rclone Master Root:** Ziel für DMG-Archive (z.B. `lys-nas:/Archive`)
* **Claude API Key:** Dein Anthropic API Key

## 🚀 Workflow & Nutzung

Das Tool führt einen "Job" durch 5 aufeinanderfolgende Phasen. Jeder heruntergeladene Video-Link wird zu einem Job im `work_dir`.

### 📋 Hauptmenü

Beim Start siehst du das interaktive Cockpit:

```text
========================================
🎬 INTERNETFILM MANAGER - COCKPIT
========================================
1. ⬇️  Neues Video herunterladen (Queue)
2. 📦 Importieren (Archiv/Lokal)
3. 🎨 Vorhandene Jobs kuratieren
4. 🚀 Jobs deployen
5. 📊 Analyse und Bestandspflege
6. ⚙️  Einstellungen
q. Beenden
```

### Phase 0: 📊 Analyse und Bestandspflege

**Menü-Navigation:** `5`

Dieses Menü bietet Tools zur Analyse und zur aktiven Bestandspflege (z.B. Suchen, Verschieben, Löschen von Videos uvm.):

1. **Video analysieren**: Analysiere einzelne M4V/MP4-Dateien auf technische Details (Codec, Bittiefe, Faststart, Metadaten)
2. **Metadata-Indexierung**: Erstelle eine vollständige CSV-Übersicht aller Videos auf dem Server ([Details](docs/METADATA_INDEXING.md))
3. **Video-Suche**: Suche nach Videos anhand von Metadaten (Titel, Schlüsselwörter, Beschreibung, Album) ([Details](docs/VIDEO_SEARCH.md))
4. **Klassifikationsregeln lernen**: Analysiere die Metadaten und lerne Regeln für automatische Kategoriezuweisung ([Details](docs/CLASSIFICATION_RULES.md))
5. **Kategorie ändern**: Verschiebe Videos zwischen Kategorien (z.B. von "Patrick" nach "Kinder") ([Details](docs/CATEGORY_CHANGE.md))
6. **Video löschen**: Lösche Videos sicher vom Media-Server und Archiv ([Details](docs/VIDEO_DELETION.md))

#### Metadata-Indexierung

Die Metadata-Indexierung scannt alle Videos auf dem Server und extrahiert deren Metadaten in eine CSV-Datei:

```text
--- METADATA-INDEXIERUNG ---
Erstellt eine CSV-Datei mit allen Metadaten der Videos auf dem Server.

Indexierung starten? [Y/n]: y

🔍 Suche nach Videos auf lyssach-nas:/Internetfilme...
✅ 342 Videos gefunden

📝 Erstelle CSV-Datei: video_metadata_index.csv
📊 Analysiere 342 Videos...
[1/342] Patrick/SpaceX/2024-11-23_Starship_IFT6.m4v... ✅
...
✅ CSV-Datei erstellt
```

Die CSV enthält alle Metadaten: Titel, Künstler, Genre, Beschreibung, Auflösung, Codec, Dauer, Dateigröße, etc. 

**Nutzen:**
- Vollständiger Katalog aller Videos
- Basis für Suche und Filterung
- Statistiken und Berichte
- Backup der Metadaten

Siehe [Metadata-Indexierung](docs/METADATA_INDEXING.md) für Details.

#### Video-Suche (Metadaten)

Mit der Video-Suche kannst du schnell Videos in deiner Mediathek finden:

```text
--- VIDEO-SUCHE ---

Suchoptionen:
1. 📝 Volltextsuche (Titel) - Default
2. 🏷️  Schlüsselwörter (Keywords/Tags)
3. 📄 Beschreibung (kurz + lang)
4. 💿 Album
5. 🔍 Erweiterte Suche (mehrere Felder)

Auswahl: 1
Suchbegriff: Starship

🔍 Suche nach 'Starship' in Titeln...

================================================================================
🔍 SUCHERGEBNISSE: 1 Video(s) gefunden
================================================================================

[1] SpaceX Starship IFT-6: Full Launch and Landing
    Pfad:        lyssach-nas:/Internetfilme/Patrick/SpaceX/2024-11-23_Starship_IFT6.m4v
    Künstler:    SpaceX Official
    Genre:       Dokumentation
    Jahr:        2024
    Dauer:       20:45 min
    Keywords:    SpaceX / Raketen / Raumfahrt / Starship / IFT-6
```

**Suchfunktionen:**
- **Volltextsuche (Titel)**: Durchsucht nur die Videotitel (Standard/Default)
- **Schlüsselwörter**: Durchsucht das Grouping-Feld mit Keywords (getrennt durch "/")
- **Beschreibung**: Durchsucht sowohl Kurz- als auch Langbeschreibung
- **Album**: Sucht nach Album-/Kanal-Namen
- **Erweiterte Suche**: Durchsucht alle Felder gleichzeitig

**Voraussetzung**: Die CSV-Datei muss zuerst über die Metadata-Indexierung erstellt werden. Falls diese nicht existiert, wird automatisch gefragt, ob eine Indexierung durchgeführt werden soll.

#### Kategorie ändern

Die Kategorie-Änderungsfunktion ermöglicht es, bereits deployed Videos zwischen verschiedenen Kategorien zu verschieben:

```text
--- 📂 KATEGORIE ÄNDERN ---

Suche nach Titel oder ID, um die Kategorie zu ändern.

Suchbegriff (Titel oder ID) oder 'z' für Zurück: Starship

🔍 Suche nach 'Starship'...

📹 Video gefunden:
   Titel:    SpaceX Starship IFT-6: Full Launch and Landing
   Aktuelle Kategorie: Patrick

📂 Verfügbare Kategorien:
   1. Kinder
   2. Eltern
   3. Kathrin
   z. Zurück

Kategorie wählen (1-3): 2

📦 Verschiebe Video von 'Patrick' nach 'Eltern'...
   ✅ Datei erfolgreich verschoben
   ✅ CSV-Index aktualisiert
```

**Wichtig**: Die Kategorie-Änderung:
- Verschiebt die Datei im Zielverzeichnis (`rclone_root`) in das neue Unterverzeichnis
- Aktualisiert die `video_metadata_index.csv` mit dem neuen Pfad
- Lässt das DMG-Archiv unverändert (da die Kategorie dort nicht abgebildet ist)

Siehe [Kategorie-Änderung](docs/CATEGORY_CHANGE.md) für Details.

### Phase 1: ⬇️ Fetch (Download)

**Menü-Navigation:** `1` → URLs eingeben → Zielgruppe wählen → ENTER

```text
--- ⬇️  DOWNLOAD QUEUE ---

URL eingeben (oder [ENTER] zum Starten): https://youtube.com/watch?v=xyz123
   Ziel wählen:
   1. Patrick
   2. Kinder
   3. Eltern
   4. Kathrin
   5. Musikvideos
   Auswahl (1-5) [Default: Patrick]: 1
   ✅ Zur Queue hinzugefügt. (Aktuell: 1 Videos)
   [ENTER] startet Download, oder nächste URL eingeben...

URL eingeben (oder [ENTER] zum Starten): https://youtube.com/watch?v=abc456
   Ziel wählen:
   1. Patrick
   ...
   Auswahl (1-5) [Default: Patrick]: 2
   ✅ Zur Queue hinzugefügt. (Aktuell: 2 Videos)

URL eingeben (oder [ENTER] zum Starten): [ENTER]

🚀 Starte Download von 2 Videos...
[1/2] https://youtube.com/watch?v=xyz123 -> Patrick
   📥 Lade Video, Audio, Subs, Metadaten...
   ⏳ Warte 60 Sekunden (YouTube Rate-Limit)...
[2/2] https://youtube.com/watch?v=abc456 -> Kinder
   📥 Lade Video, Audio, Subs, Metadaten...

✅ Alle Downloads abgeschlossen. [ENTER]...
```

**Was passiert:**
* `yt-dlp` lädt höchste verfügbare Qualität (Video + Audio getrennt)
* Automatischer Download aller verfügbaren Untertitel (VTT)
* Metadaten (JSON) mit allen Infos (Titel, Beschreibung, Upload-Datum, Kanal, etc.)
* Original-Thumbnail
* Automatische Pause zwischen Downloads (60 Sek. gegen Rate-Limiting)
* Job wird im `work_dir` angelegt: `job_YYYY-MM-DD_HH-MM-SS_platform_id/`

### Phase 2: 📦 Import

**Menü-Navigation:** `2` → Restore oder MP3-Extraktion wählen

```text
--- 📦 IMPORT ---
1. 🔙 Restore aus bestehendem Archiv (DMG)
2. 🎵 MP3 aus DMG extrahieren
z. Zurück
```

#### Option 1: Restore
Suche ein bereits archiviertes Video anhand der ID und erstelle eine neue Arbeitskopie:

```text
--- RESTORE (Kopie erstellen) ---
Gezielte Suche im Archiv (z.B. nach ID '5fk8XXCw').
Suchbegriff (Pflicht): 5fk8XXCw

🔍 Suche nach '5fk8XXCw' in lys-nas:/Archive...
✅ Gefunden: 2024-03-15_youtube_5fk8XXCw.dmg
📥 Lade DMG und entpacke...
✨ Import erfolgreich: job_2024-03-15_youtube_5fk8XXCw

   👉 Direkt kuratieren (Titel, Musik-Tags, etc.)? [Y/n]: y
```


### Phase 3: 🎨 Kuratieren (Der Herzschlag)

**Menü-Navigation:** `3` → Modus wählen → Job auswählen

Dies ist die wichtigste Phase – hier passiert die kreative Arbeit und KI-Magie:

```text
Offene Jobs:
1. ⭕️ SpaceX Starship IFT-7 Full Launch and Landing
2. ✅ Die Geschichte der Künstlichen Intelligenz
3. ⭕️ Nyan Cat [original]

   Kuratierungs-Modus:
   [m] Manuell (mit Bestätigungen)
   [a] Automatisch (K.I. trifft Entscheidungen)
   [z] Zurück

   Modus wählen: m

Job wählen: 1
```

#### Manueller Modus (Standard)
Im manuellen Modus wirst du bei jedem Schritt um Bestätigung gebeten und kannst Anpassungen vornehmen.

#### Automatischer Modus (Auto-Kuratierung)
Im automatischen Modus trifft die K.I. alle Entscheidungen selbstständig:
- Wählt automatisch den besten Titel aus den Vorschlägen
- Akzeptiert alle AI-generierten Beschreibungen
- Wählt automatisch das beste Poster-Bild per K.I.-Analyse
- Zeigt alle Entscheidungen in der Konsole an
- Bei Fehlern wird abgebrochen und manuelle Kuratierung empfohlen

#### Beispiel: Manueller Modus für Internet-Videos (Vlogs, Dokus, Tutorials):

```text
--- 🎨 Kuratierung: SpaceX Starship IFT-7 Full Launch... ---

📋 Original-Infos:
   Titel: SPACEX STARSHIP IFT-7 | FULL LAUNCH AND LANDING 🚀
   Kanal: SpaceX Official
   Sprache (Metadata): en

   🤖 [1/3] Analysiere Video-Sprache (Transkript)...
   ✅ Erkannte Sprache: English (87% Konfidenz)

   🤖 [2/3] Generiere Titel-Variationen (English)...
   🤖 [3/3] Generiere Beschreibungen (English → German)...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 TITEL-VORSCHLÄGE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. SpaceX Starship IFT-7: Full Launch and Landing
2. Starship IFT-7 Complete Mission Coverage
3. SpaceX IFT-7 - Integrated Flight Test Full Video

Auswahl (1-3) oder eigener Titel: 1
✅ Titel: SpaceX Starship IFT-7: Full Launch and Landing

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 BESCHREIBUNGEN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
KURZ: Vollständige Aufzeichnung des siebten Integrated Flight Test...
LANG: Der siebte Testflug des SpaceX Starship Systems zeigt...

Beschreibungen ändern? [y/N]: n

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🏷️  GENRE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Vorschlag: Dokumentation
Genre ändern? [y/N]: n

   🤖 Generiere Kapitel (Originalsprache)...
   ✅ 8 Kapitel erstellt.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📑 KAPITEL (Optional bearbeiten)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
00:00:00 - Introduction and Countdown
00:02:30 - Liftoff and Ascent
00:05:45 - Stage Separation
...

Kapitel bearbeiten? [y/N]: n

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🖼️  POSTER AUSWAHL (16:9)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Erstelle 4x4 Mosaik mit Blurred Background...
   
   [Zeigt ASCII-Art des Mosaiks oder Info über Bildauswahl]
   
   Bild wählen (1-15, ENTER für Original): 7
   ✅ Poster ausgewählt: Bild 7

✅ Kuratierung abgeschlossen!
   Status: ✅ Bereit für Deployment
```

#### Für Musikvideos:

```text
--- 🎨 Kuratierung: Nyan Cat [original] ---

🎵 MUSIK-MODUS erkannt (Ziel: Musikvideos)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎤 KÜNSTLER
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Aktuell: daniwell (aus Metadaten)
Künstler: Nyan Cat

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎵 TITEL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Aktuell: Nyan Cat [original]
Titel: Nyan Cat

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💿 ALBUM / COMPILATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Album-Name: Internet Classics

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔢 TRACK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Track-Nummer [1]: 5

   [Poster-Auswahl wie bei Internet-Videos]

✅ Musikvideo kuratiert!
   Dateiname: 005 - Nyan Cat - Nyan Cat.m4v
```

### Phase 4: 🔨 Build (Verarbeitung)

**Passiert automatisch beim Deployment.** Diese Phase wird nicht manuell aufgerufen.

```text
📀 --- PHASE 1: MASTER ARCHIVIERUNG (DMG) ---
   📦 Erstelle DMG-Inhalt...
   ✅ Quelle: original.mkv
   ✅ Metadaten: original.info.json
   ✅ Poster: poster_curated.jpg
   ✅ Untertitel: original.en.vtt, original.de.vtt
   
   🔨 Erstelle schreibgeschütztes DMG...
   ✅ DMG erstellt: 2025-05-15_youtube_xYz123.dmg

🎬 Ziel-Datei: 2025-05-15_Starship_IFT7.m4v

🔊 --- PHASE 2: AUDIO NORMALISIERUNG ---
   🎚️  Extrahiere Audio-Spur...
   🎚️  Wende Loudnorm-Filter an (I=-16, TP=-1.5, LRA=11)...
   ✅ Audio: 256 kbit/s AAC, 48 kHz Stereo

🎞️ --- PHASE 3: VIDEO ENCODING (Adaptiv) ---
   ⚙️  Ziel-Qualität: 70
   ⚙️  Bitrate-Limite: 100 Mbit/s (Video+Audio)
   🎬 Encoding mit Qualität 70...
   ⏳ Encoding... [██████████████░░░░] 75% ETA 2:30
   📊 Gesamtbitrate (Video+Audio): 85.3 Mbit/s (Limite: 100 Mbit/s)
   ✅ Bitrate OK – unter 100 Mbit/s

📦 --- PHASE 4: MUXING ---
   🔍 Suche Untertitel...
   ✅ Hauptsprache: English (eng)
   ✅ Zusätzlich: Deutsch (ger)
   
   📑 Füge Kapitelmarken ein (FFMETADATA)...
   🖼️  Füge Poster als Cover-Art ein...
   
   🏷️  Schreibe Metadaten mit mutagen:
      • Titel: SpaceX Starship IFT-7: Full Launch and Landing
      • Künstler: SpaceX Official
      • Album: SpaceX Official
      • Jahr: 2025
      • Genre: Dokumentation
      • Beschreibung (kurz): Vollständige Aufzeichnung...
      • Beschreibung (lang): Der siebte Testflug...
      • Sprache: eng
   
   ✅ M4V erstellt: 2025-05-15_Starship_IFT7.m4v (2.3 GB)
```

### Phase 5: 🚀 Deploy (Upload & Cleanup)

**Menü-Navigation:** `4` → Job wählen oder ENTER für alle kuratierten Jobs

```text
Jobs bereit zum Deployen:
1. ✅ SpaceX Starship IFT-7: Full Launch and Landing
2. ⚠️  Noch nicht kuratiert
3. ✅ Nyan Cat

[ENTER] für ALLE deployen (nur kuratierte!).
Oder Nummer wählen: [ENTER]

🚀 Starte Deployment für 2 kuratierte Jobs...

⚙️  [1/2] Verarbeite: SpaceX Starship IFT-7: Full Launch and Landing
   [Build-Phase läuft wie oben...]

🚀 Upload Video nach: lys-nas:/Emby/media/Internetfilme/Patrick/SpaceX Official
   ⬆️  Übertrage 2025-05-15_Starship_IFT7.m4v... [████████] 100%
   ✅ Video hochgeladen

   Archiviere Master nach: lys-nas:/Archive/2025
   ⬆️  Übertrage 2025-05-15_youtube_xYz123.dmg... [████████] 100%
   ✅ Master archiviert

   Räume Arbeitsverzeichnis auf...
   ✅ Job abgeschlossen & gelöscht.

⚙️  [2/2] Verarbeite: Nyan Cat
   [...]

✅ Fertig. [ENTER]...
```

### ⚙️ Einstellungen

**Menü-Navigation:** `5`

```text
--- ⚙️  EINSTELLUNGEN ---
1. 🔑 Claude API Key:     sk-ant-api...******
2. 🤖 Claude Modell:      claude-sonnet-4-20250514
3. 📂 Work Directory:     /Users/patrick/Movies/Internetfilme/Work
4. 📡 Rclone Media-Pfad:  lys-nas:/Emby/media/Internetfilme
5. 📦 Rclone Master-Pfad: lys-nas:/Archive
z. Zurück

Auswahl: 1

Aktuell: sk-ant-api...
Neuer API Key: [neue Eingabe]
✅ Konfiguration gespeichert.
```

## 🖥️ CLI-Befehle

`internetfilm-manager` lässt sich auf zwei Arten nutzen: über das **interaktive Cockpit-Menü** (Standard, kein Argument) oder direkt über **Direktbefehle** für Skripting und Automatisierung.

📄 **Vollständige CLI-Referenz:** [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)

### Kurzübersicht aller Befehle

| Befehl | Beschreibung |
|--------|-------------|
| *(kein Argument)* | Startet das interaktive Cockpit-Menü |
| `--help`, `-h` | Alle Befehle und Optionen anzeigen |
| `--version`, `-V` | Installierte Version und Abhängigkeiten anzeigen |
| `fetch <URL> <Ziel>` | Video herunterladen und Job anlegen |
| `curate <job_pfad> [--auto]` | Job kuratieren (manuell oder via KI) |
| `build_master <job_pfad>` | DMG-Archiv (Cold Storage) erstellen |
| `build_dist <job_pfad>` | Finale M4V-Datei bauen (H.265, Metadaten) |
| `deploy <job_pfad>` | Build + Upload + Cleanup in einem Schritt |
| `rebuild-poster <pfad> [--batch] [--recursive] [--new-frame] [--fanart]` | Poster-Bild neu erstellen |

```bash
# Überblick über alle Befehle
internetfilm-manager --help

# Installierte Version und Abhängigkeiten anzeigen
internetfilm-manager --version
```

### `fetch` – Video herunterladen

Lädt ein einzelnes Video von YouTube (oder einer anderen von yt-dlp unterstützten Plattform) herunter und legt einen Job im Work-Verzeichnis an.

```bash
internetfilm-manager fetch <URL> <Ziel>
```

| Argument | Beschreibung |
|----------|-------------|
| `<URL>` | URL des Videos (z.B. YouTube-Link) |
| `<Ziel>` | Zielgruppe/Kategorie (z.B. `Patrick`, `Kinder`) |

**Beispiel:**
```bash
internetfilm-manager fetch "https://www.youtube.com/watch?v=xYz123" Patrick
```

---

### `curate` – Job kuratieren

Startet den Kuratierungsprozess für einen bestehenden Job. Ohne `--auto` läuft der manuelle Modus mit Rückfragen; mit `--auto` übernimmt die K.I. alle Entscheidungen.

```bash
internetfilm-manager curate <job_pfad> [--auto]
```

| Option | Beschreibung |
|--------|-------------|
| `--auto` | Automatischer Modus: K.I. trifft alle Entscheidungen (Titel, Poster, Beschreibung) ohne Rückfragen |

**Beispiele:**
```bash
# Manuell kuratieren (mit Bestätigungsdialogen)
internetfilm-manager curate ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123

# Vollautomatisch via K.I. kuratieren
internetfilm-manager curate ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123 --auto
```

---

### `build_master` – Master-Archiv erstellen

Erstellt ein schreibgeschütztes DMG-Archiv (Cold Storage) aus einem kuratierten Job, ohne es hochzuladen.

```bash
internetfilm-manager build_master <job_pfad>
```

**Beispiel:**
```bash
internetfilm-manager build_master ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123
```

---

### `build_dist` – Dist-M4V bauen

Erzeugt die finale M4V-Datei (mit Audio-Normalisierung, H.265-Encoding, Metadaten und Untertiteln) aus einem kuratierten Job.

```bash
internetfilm-manager build_dist <job_pfad>
```

**Beispiel:**
```bash
internetfilm-manager build_dist ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123
```

---

### `deploy` – Job deployen

Führt Build (Master + Dist) und anschliessenden Upload zum Media-Server und Archiv in einem Schritt aus. Räumt das Arbeitsverzeichnis nach erfolgreichem Upload automatisch auf.

```bash
internetfilm-manager deploy <job_pfad>
```

**Beispiel:**
```bash
internetfilm-manager deploy ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123
```

---

### `rebuild-poster` – Poster neu erstellen

Erstellt das Poster-Bild für ein einzelnes Video oder alle Videos in einem Verzeichnis neu. Nützlich, wenn das Poster nach einer Aktualisierung des Poster-Layouts oder nach manuellen Änderungen regeneriert werden soll.

```bash
internetfilm-manager rebuild-poster <pfad> [OPTIONEN]
```

| Option | Beschreibung |
|--------|-------------|
| `--batch` | Verarbeitet alle Videos im angegebenen Verzeichnis (statt nur einer Datei) |
| `--recursive` | Durchsucht Unterverzeichnisse rekursiv (nur sinnvoll zusammen mit `--batch`) |
| `--new-frame` | K.I. analysiert alle Mosaik-Bilder und wählt automatisch das beste Poster-Bild (niemals das Original-Thumbnail) |
| `--fanart` | Erzwingt die Verwendung von Fanart als Poster-Basis |

**Beispiele:**
```bash
# Poster für ein einzelnes Video neu erstellen
internetfilm-manager rebuild-poster ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123

# Poster für alle Videos in einem Verzeichnis neu erstellen
internetfilm-manager rebuild-poster ~/Movies/Internetfilme/Work --batch

# Poster rekursiv für alle Videos inkl. Unterverzeichnisse neu erstellen
internetfilm-manager rebuild-poster ~/Movies/Internetfilme/Work --batch --recursive

# K.I. wählt automatisch das beste Bild als neues Poster
internetfilm-manager rebuild-poster ~/Movies/Internetfilme/Work/job_2025-05-15_youtube_xYz123 --new-frame

# Kombiniert: Stapel mit K.I.-Bildauswahl und Fanart-Aktivierung
internetfilm-manager rebuild-poster ~/Movies/Internetfilme/Work --batch --new-frame --fanart
```

## 📂 Archiv-Struktur

### Media Server (Hot Storage)

Videos für die aktive Mediathek (Emby/Plex):

```text
/Internetfilme
    /Patrick
        /SpaceX Official
            2025-05-15_Starship_IFT7.m4v
            2025-04-10_Starship_IFT6.m4v
        /Kurzgesagt – In a Nutshell
            2025-03-20_Was_ist_Bewusstsein.m4v
        /Veritasium
            2025-02-14_Warum_Gold_wertvoll_ist.m4v
    /Kinder
        /Peppa Wutz
            2024-01-01_Matschpfuetzen.m4v
            2024-01-08_Dinosaurier.m4v
        /Die Sendung mit der Maus
            2024-12-25_Weihnachtsspecial.m4v
    /Musikvideos
        /Internet Classics
            001 - Nyan Cat - Nyan Cat.m4v
            002 - Rick Astley - Never Gonna Give You Up.m4v
            003 - PSY - Gangnam Style.m4v
        /80s Hits
            001 - A-ha - Take On Me.m4v
            002 - Queen - Bohemian Rhapsody.m4v
```

**Struktur-Logik:**
* **Internet-Videos:** `/Zielgruppe/Kanal-Name/YYYY-MM-DD_Titel.m4v`
* **Musikvideos:** `/Musikvideos/Album-Name/TTT - Artist - Title.m4v`
  * TTT = Track-Nummer (dreistellig)

### Master Archiv (Cold Storage)

Vollständige Originale für Langzeitarchivierung:

```text
/Archive
    /2025
        2025-05-15_youtube_xYz123Ab.dmg
        2025-04-10_youtube_aBc456Xy.dmg
        2025-03-20_youtube_dEf789Gh.dmg
    /2024
        2024-12-25_youtube_jKl012Mn.dmg
        2024-01-08_youtube_pQr345St.dmg
        2024-01-01_youtube_uVw678Xy.dmg
```

**DMG-Inhalt (Beispiel):**
```text
youtube_xYz123Ab.dmg (mounted) enthält:
├── original.mkv                    # Original-Video in höchster Qualität
├── original.info.json              # Vollständige Metadaten von yt-dlp
├── original.jpg                    # Original-Thumbnail von Plattform
├── original.en.vtt                 # Englische Untertitel
├── original.de.vtt                 # Deutsche Untertitel (falls vorhanden)
├── poster_curated.jpg              # Handverlesenes Poster (16:9)
└── curate_chat_log.json            # Log der KI-Interaktion (optional)
```

**Struktur-Logik:**
* Sortiert nach Upload-Jahr (`YYYY`)
* Dateiname: `YYYY-MM-DD_plattform_id.dmg`
* Read-only Format (schreibgeschützt)
* Perfekt für NAS Cold-Storage oder externe Archiv-Festplatten
* Kann jederzeit mit "Restore"-Funktion zurückgeholt werden

### Temporäre Arbeitsdateien

Während der Verarbeitung im `work_dir`:

```text
~/Movies/Internetfilme/Work
    /job_2025-05-15_12-30-45_youtube_xYz123Ab
        original.mkv                       # Original-Download
        original.info.json                 # Metadaten
        original.jpg / .webp / .png        # Original-Thumbnail
        original.en.vtt                    # Untertitel (Englisch)
        original.de.vtt                    # Untertitel (Deutsch)
        audio_norm.m4a                     # Normalisiertes Audio (Build-Phase)
        video_enc.mp4                      # Encodiertes Video (Build-Phase)
        chapters.txt                       # Kapitel-Liste (KI-generiert)
        poster.jpg                         # Ausgewähltes Poster
        job_state.json                     # Kuratierungs-Status
        dmg_content/                       # Temp für DMG-Erstellung
        temp_mosaic_frames/                # Temp für Poster-Mosaik
        2025-05-15_Starship_IFT7.m4v      # Finales Video (vor Upload)
        2025-05-15_youtube_xYz123Ab.dmg   # Master-DMG (vor Upload)
```

**Nach erfolgreichem Deployment wird der komplette Job-Ordner gelöscht.**

## 🔧 Technische Details

### Video-Encoding-Pipeline

```text
INPUT (original.mkv/webm/mp4)
    ↓
[Phase 2: Audio]
    • Extraktion: ffmpeg -i input -vn
    • Resampling: aresample=async=1
    • Normalisierung: loudnorm=I=-16:TP=-1.5:LRA=11
    • Codec: AAC 256 kbit/s, 48 kHz, Stereo
    ↓
[Phase 3: Video – Adaptives Encoding]
    • Encoder: ffmpeg hevc_videotoolbox (VideoToolbox HW)
    • Codec: H.265 (HEVC) 10-bit
    • Ziel-Qualität: 70 (konfigurierbar, Skala 0-100, höher = besser)
    • Framerate: CFR (Constant Frame Rate)
    • Keyframes: Alle 30 Frames
    • Bitratenprüfung: Video+Audio Gesamtbitrate
    • Adaptive Anpassung: Falls Bitrate > Limite (Standard 100 Mbit/s),
      wird Qualitätswert um 2 erhöht und erneut encodiert
      (höherer RF-Wert = stärkere Kompression)
    ↓
[Phase 4: Muxing]
    • Container: M4V (MP4 kompatibel)
    • Video: Copy (kein Re-Encoding)
    • Audio: Copy (kein Re-Encoding)
    • Untertitel: VTT → MOV_TEXT (mehrsprachig)
    • Kapitel: FFMETADATA → MP4 Atoms
    • Cover-Art: JPEG Poster → MP4 Atom
    ↓
[Phase 5: Tagging]
    • Tool: mutagen (Python)
    • Metadaten: Titel, Künstler, Album, Jahr, Genre,
                  Beschreibung (kurz + lang), Sprache,
                  Track/Disk (bei Musik), Cover-Art
    ↓
OUTPUT (final.m4v)
    • Perfekte Kompatibilität: macOS, iOS, Emby, Plex, Infuse
    • Dateigröße: ~30-50% kleiner als Original (H.265 10-bit)
    • Qualität: Visuell verlustfrei
    • Metadaten: Vollständig und sauber
```

### KI-Prompt-Strategie

Die Claude-Integration verwendet mehrere spezialisierte Prompts:

1. **Spracherkennung** (Transkript-Analyse):
   - Analysiert ersten Teil des VTT-Transkripts
   - Erkennt tatsächliche Sprache (nicht nur Metadaten)
   - Gibt ISO 639-2 Code + Konfidenz zurück

2. **Titel-Bereinigung** (Metadaten-Cleanup):
   - Entfernt Clickbait-Elemente
   - Korrigiert ALL CAPS → Title Case / normale Rechtschreibung
   - Entfernt | → : oder - oder ()
   - Mehrere Vorschläge zur Auswahl

3. **Beschreibungs-Generierung** (Transkript + Metadata):
   - Kurz: Max. 250 Zeichen, sachlich, für Listen
   - Lang: Ausführlich und detailliert, basierend auf vollem Transkript
   - Deutschsprachig (auch bei englischen Videos)

4. **Genre-Klassifikation**:
   - Automatische Einordnung basierend auf Inhalt
   - Kategorien: Dokumentation, Tutorial, Vlog, Interview, 
     Comedy, Musikvideo, Gaming, Review, usw.

5. **Kapitel-Generierung** (Transkript mit Timestamps):
   - 5-15 logische Abschnitte
   - Keine 1:1-Kopie des Transkripts
   - Titel in Originalsprache
   - Korrekte Groß-/Kleinschreibung (sprachabhängig)

### Besonderheiten

**Blurred Background für Poster:**
Wenn Videos nicht 16:9 sind (z.B. 4:3, Vertical), verwendet das Tool einen speziellen FFmpeg-Filter:
```bash
# Hintergrund: Skaliert Video auf 16:9 (mit Crop) → Weichzeichnen (Blur)
[0:v]scale=640:360:force_original_aspect_ratio=increase,crop=640:360,boxblur=20[bg];
# Vordergrund: Skaliert Video passend ein (ohne Crop)
[0:v]scale=640:360:force_original_aspect_ratio=decrease[fg];
# Overlay: Legt scharfes Bild mittig auf unscharfen Hintergrund
[bg][fg]overlay=(W-w)/2:(H-h)/2
```
Ergebnis: Perfektes 16:9 Bild ohne schwarze Balken, ohne Verzerrung.

**Mehrsprachige Untertitel:**
Das Tool bevorzugt die Video-Hauptsprache + Englisch (wenn nicht bereits Englisch). Automatische Auswahl der besten VTT-Dateien basierend auf Dateinamen-Patterns.

**Rclone Konfiguration:**
Für Synology NAS-Systeme sollte `--ignore-checksum` in der rclone-Konfiguration gesetzt werden, da SFTP oft keine Checksummen liefert. Dies ist eine Umweltbedingung und wird nicht mehr im Code verwendet.

**DMG vs. TAR/ZIP:**
DMGs haben gegenüber TAR/ZIP mehrere Vorteile:
- Native macOS-Integration (Doppelklick zum Mounten)
- Read-only (schreibgeschützt gegen versehentliche Änderungen)
- Kompression auf Dateisystem-Ebene
- Schnelleres Mounten als Entpacken

## 💡 Tipps & Best Practices

### Qualität vs. Speicherplatz

* **H.265 10-bit** spart ~30-50% Speicher gegenüber H.264 bei gleicher Qualität
* **Qualität 70** ist der Standard-Qualitätswert (konfigurierbar über `video_quality`, Skala 0-100, höher = besser)
* **Adaptives Encoding:** Falls die Gesamtbitrate (Video+Audio) den Schwellenwert überschreitet (Standard: 100 Mbit/s), wird das Video automatisch mit reduzierter Qualität neu encodiert (Qualitätswert -2 pro Versuch). Dies betrifft vor allem hochauflösende 4K-Videos.
* Konfiguration in `config.json`:
  ```json
  {
    "video_quality": 70,
    "bitrate_threshold_mbps": 100,
    "adaptive_quality_step": 2
  }
  ```
  - `video_quality`: Ziel-Qualitätswert (Standard: 70, Skala 0-100, höher = bessere Qualität)
  - `bitrate_threshold_mbps`: Maximale Gesamtbitrate in Mbit/s (Standard: 100)
  - `adaptive_quality_step`: Qualitätsreduktion pro Versuch (Standard: 2)
* Typische Dateigrößen:
  - 10-Min-Video (1080p): ~200-400 MB
  - 30-Min-Video (1080p): ~600-1200 MB
  - 60-Min-Video (4K): ~2-4 GB

### Workflow-Optimierung

1. **Queue nutzen:** Lade mehrere Videos auf einmal herunter (nachts)
2. **Batch-Kuratierung:** Kuratiere mehrere Jobs hintereinander
3. **Batch-Deployment:** ENTER im Deploy-Menü verarbeitet alle kuratierten Jobs automatisch
4. **SSD für work_dir:** Encoding ist 3-5x schneller auf SSD vs. HDD

### KI-Nutzung

Die Anwendung nutzt Anthropic Claude für K.I. Aufgaben (Spracherkennung, Titel-Bereinigung, Beschreibungen, Kapitel, Musik-Analyse, Titelbild-Auswahl).

**Modell-Konfiguration:**
Das Modell kann in der `config.json` oder über die Einstellungen konfiguriert werden:
```json
{
  "claude_model": "claude-sonnet-4-20250514"
}
```

**API-Limits:**
* Token-Kosten: Pro Video ca. 50.000-100.000 Tokens (abhängig von Transkript-Länge)
* **Tipp:** Bei vielen Videos über den Tag verteilen, um Limits nicht zu überschreiten

**Kontrolliertes Vokabular anpassen:**
Die Keyword-Extraktion nutzt ein kontrolliertes Vokabular aus `Masterlist_keywords.txt`.
Du kannst diese Datei erweitern oder anpassen:

1. Öffne `Masterlist_keywords.txt` im Repository-Root
2. Füge neue Keywords hinzu (ein Keyword pro Zeile)
3. Beachte die Regeln:
   - Substantive, Singular
   - Keine Eigennamen
   - Keine technischen Begriffe (4K, HD, etc.)
   - Thematisch gruppiert (mit `# === KATEGORIE ===` Überschriften)
4. Speichern - wird beim nächsten Start automatisch geladen

**Beispiel für eigene Keywords:**
```
# === MEINE SPEZIALTHEMEN ===
Drohnenfotografie
Zeitraffer
Makrofotografie
```

Die AI wird diese Keywords bei der Verschlagwortung bevorzugen.

### Archivierungs-Strategie

**3-2-1-Regel:**
1. **3 Kopien:** Original (DMG), Media (M4V), Backup
2. **2 Medientypen:** NAS (Hot) + externe HDD (Cold)
3. **1 Offsite:** Cloud oder externe HDD an anderem Ort

**Empfehlung:**
* Media (M4V): Emby/Plex auf NAS (schneller Zugriff)
* Master (DMG): NAS + jährliches Backup auf externe HDD
* Zusätzlich: Wichtige Videos auch in Cloud (rclone → Google Drive / OneDrive)

### Netzwerk-Performance

Bei langsamer Verbindung zum NAS:
```bash
# In config.json oder rclone config anpassen:
rclone ... --transfers=1 --checkers=1  # Weniger parallele Verbindungen
```

Bei schneller Verbindung (Gigabit+):
```bash
rclone ... --transfers=4 --checkers=8  # Mehr Parallelität
```

### Fehlerbehandlung

**Video lässt sich nicht herunterladen:**
- Prüfe, ob `yt-dlp` aktuell ist: `brew upgrade yt-dlp`
- Manche Videos sind geo-blocked oder privat
- VPN kann helfen (aber Rate-Limit beachten)

**Encoding schlägt fehl:**
- Prüfe, ob genug Speicherplatz vorhanden ist (mindestens 3x Originalgröße)
- VideoToolbox-Fehler → Neustart von macOS
- ffmpeg-Update: `brew upgrade ffmpeg`

**KI-Fehler (Claude):**
- API Key gültig? Prüfe in [Anthropic Console](https://console.anthropic.com/)
- Rate-Limit erreicht? Warte einige Minuten
- Transkript zu lang (>100k Tokens)? → Wird automatisch gekürzt

**Rclone-Upload hängt:**
- SFTP-Timeout → `--timeout 30s` in config hinzufügen
- Netzwerk unterbrochen → Rclone resumed automatisch
- Checksummen-Fehler → `--ignore-checksum` in der rclone-Konfiguration für betroffene Remotes setzen

## 🔐 Sicherheit & Datenschutz

### API Keys
* **Claude Key:** Wird lokal in `config.json` gespeichert (nicht in Git!)
* **Rclone Credentials:** Gespeichert in `~/.config/rclone/rclone.conf` (verschlüsselt mit Passwort möglich)

### Datenfluss
1. **Download:** YouTube → Lokal (via yt-dlp)
2. **KI-Analyse:** Transkript & Metadaten → Anthropic Claude API (nur Text und Bilder, kein Video)
3. **Verarbeitung:** Komplett lokal (FFmpeg)
4. **Upload:** Lokal → eigenes NAS (via Rclone)

**Wichtig:** Das Video selbst wird NICHT an Anthropic gesendet, nur Text (Titel, Beschreibung, Transkript) und Mosaik-Bilder für die Titelbild-Auswahl.

### Berechtigungen
* **Netzwerk:** Für Downloads (yt-dlp) und Uploads (rclone)
* **Dateisystem:** Lese-/Schreibzugriff auf `work_dir` und temporäre Ordner
* **Keine Root-Rechte nötig**

## 📚 Weiterführende Dokumentation

Detaillierte Anleitungen befinden sich im [`docs/`](docs/) Verzeichnis:

| Dokument | Beschreibung |
|----------|-------------|
| [CLI-Referenz](docs/CLI_REFERENCE.md) | Vollständige Übersicht aller Kommandos, Subkommandos, Flags und Optionen |
| [Genre-Klassifizierung](docs/GENRE_CLASSIFICATION.md) | Die 12 Standard-Genres und das Klassifizierungssystem |
| [Klassifikationsregeln](docs/CLASSIFICATION_RULES.md) | Automatische Kategoriezuweisung basierend auf gelernten Regeln |
| [Metadata-Indexierung](docs/METADATA_INDEXING.md) | CSV-Export aller Video-Metadaten vom Server |
| [Video-Suche](docs/VIDEO_SEARCH.md) | Suche nach Videos anhand verschiedener Metadaten |
| [Kategorie-Änderung](docs/CATEGORY_CHANGE.md) | Videos zwischen Kategorien verschieben |
| [Video-Löschung](docs/VIDEO_DELETION.md) | Videos sicher vom Server und Archiv entfernen |
| [Auto-Download Playlists](docs/AUTO_DOWNLOAD_PLAYLISTS.md) | Vordefinierte Playlists automatisch herunterladen |

## 🤝 Credits

Entwickelt als privates Tool für digitale Souveränität und bewussten Medienkonsum.

**Powered by:**
* [yt-dlp](https://github.com/yt-dlp/yt-dlp) – Flexibler Video-Downloader
* [FFmpeg](https://ffmpeg.org/) – Audio/Video-Verarbeitung & H.265 Hardware-Encoding
* [Anthropic Claude](https://www.anthropic.com/) – KI-Metadaten & Analyse
* [mutagen](https://github.com/quodlibet/mutagen) – MP4-Tagging (pure Python)
* [Rclone](https://rclone.org/) – Cloud/NAS-Transfer
* [Python](https://www.python.org/) – Orchestrierung & CLI
* [Pillow](https://python-pillow.org/) – Bildverarbeitung

**Entwicklung:**
Diese Anwendung wurde in Handarbeit und in enger Zusammenarbeit mit KI-Unterstützung entwickelt. Die KI half bei der Architektur, Code-Implementierung und Dokumentation.

## 📄 Lizenz

Dieses Projekt ist für den persönlichen Gebrauch entwickelt. Beim Verwenden dieses Tools musst du die Nutzungsbedingungen der jeweiligen Plattformen (YouTube, etc.) und lokale Urheberrechtsgesetze beachten.

**Hinweis:** Das Tool dient der **privaten Archivierung** von Inhalten, die du berechtigt bist herunterzuladen. Verwende es nicht für illegale Zwecke oder zur Massenverteilung urheberrechtlich geschützter Inhalte.

---

**Made with ❤️ for conscious digital archiving and less distraction.**
