pvd/README.md

# Amazon PVD Mezzanine Encoder

Automatisches Windows-Tool zur Erstellung von Amazon-PVD-Mezzanine-Dateien aus ProRes-, Blu-ray-, DVD- und anderen Videodateien.

Das Tool erzeugt:

- ein PVD-MP4 mit deutschem Stereo-Ton
- eine separate MOV-Datei mit allen deutschen Tonspuren als uncompressed PCM
- falls vorhanden, eine separate MOV-Datei mit allen originalsprachigen bzw. nicht-deutschen Tonspuren als uncompressed PCM

## Aktueller Workflow

1. Quelle auswaehlen oder als Parameter uebergeben.
2. FFprobe analysiert Video, Audio, Framerate, Aufloesung, Interlacing und Farbraum-Metadaten.
3. Audio-Sprache und Layout werden bevorzugt aus dem Dateinamen gelesen, z.B. `DEU51_ENG20`.
4. Das PVD-MP4 wird erzeugt.
5. Danach werden die Audio-MOVs erzeugt.

## Schnellstart fuer Kollegen

Am einfachsten:

1. Datei korrekt benennen, z.B. `Film_DEU51_ENG20.mov`.
2. `create_mezzanine.bat` doppelklicken.
3. Im Dateidialog die Videodatei auswaehlen.
4. Warten, bis im Fenster `ERFOLGREICH abgeschlossen.` steht.
5. Ergebnis im Zielordner pruefen, standardmaessig bevorzugt `F:\VOD`, sonst `H:\VOD`.

Noch einfacher mit Drag & Drop:

1. Videodatei auf `create_mezzanine.bat` ziehen.
2. Warten, bis das Encoding fertig ist.

Wichtig: Das Fenster waehrend des Encodings offen lassen. Am Ende bleibt es stehen, damit Fehlermeldungen gelesen werden koennen.

## Voraussetzungen

- Windows
- Python 3.10+
- FFmpeg und FFprobe
- Schreibzugriff auf das Zielverzeichnis

Hinweis: Auf manchen Windows-Rechnern gibt es den Befehl `py` nicht. Das ist normal. `create_mezzanine.bat` sucht deshalb automatisch nach mehreren Python-Varianten:

1. lokale Python-Installationen wie `Python314`, `Python313`, `Python312`, `Python311`, `Python310`
2. `py`
3. `python`
4. `python3`

Wenn nichts davon gefunden wird, zeigt die Batch-Datei eine Installationsmeldung.

### Python und `py` installieren

`py` ist ein kleiner Python-Starter fuer Windows. Er hilft, die passende Python-Version zu finden. Fuer dieses Tool ist `py` praktisch, aber nicht zwingend notwendig, weil `create_mezzanine.bat` auch nach `python` und lokalen Python-Installationen sucht.

Python 3.14 ist fuer dieses Tool in Ordnung. Einfachster Weg fuer einen neuen Rechner:

1. Python fuer Windows von [python.org](https://www.python.org/downloads/windows/) installieren.
2. Im Installer diese Optionen aktivieren:
   - `Add python.exe to PATH`
   - `py launcher` bzw. `Python Launcher for Windows`, falls angeboten
   - `tcl/tk and IDLE`, damit die grafische Oberflaeche funktioniert
3. Nach der Installation ein neues PowerShell-Fenster oeffnen.
4. Pruefen:
   ```powershell
   python --version
   py --version
   ```

Wenn `python --version` funktioniert, aber `py --version` nicht, ist das fuer dieses Tool nicht schlimm. Dann startet die Batch-Datei Python ueber `python`.

Wenn weder `python` noch `py` funktioniert, Python erneut installieren und darauf achten, dass `Add python.exe to PATH` aktiviert ist.

Bei neueren Python-Versionen kann auch der Python Install Manager verwendet werden. Danach sollten normalerweise `python` und `py` verfuegbar sein.

FFmpeg und FFprobe werden automatisch gesucht:

1. explizite Pfade aus `config.ini`
2. `PATH`
3. `C:\Tools\FFMPEG`
4. `C:\Software`

## Starten

Interaktiv per Doppelklick oder Konsole:

```powershell
.\create_mezzanine.bat
```

Mit direktem Dateiparameter:

```powershell
.\create_mezzanine.bat "D:\Trailers\Film_DEU51_ENG20.mov"
```

Direkt per Python:

```powershell
python .\pvd_mezzanine.py "D:\Trailers\Film_DEU51_ENG20.mov"
```

Kompatibler CLI-Modus:

```powershell
python .\pvd_mezzanine.py --cli "D:\Trailers\Film_DEU51_ENG20.mov"
```

Falls `python` nicht gefunden wird, aber der Python-Launcher vorhanden ist:

```powershell
py -3 .\pvd_mezzanine.py "D:\Trailers\Film_DEU51_ENG20.mov"
```

Wenn Tkinter in der verwendeten Python-Installation verfuegbar ist, startet eine UI mit Analyse, Audio-Uebersicht und Encoding-Log.

Wenn Tkinter nicht verfuegbar ist, oeffnet das Tool einen nativen Windows-Dateidialog fuer die Quelle und laeuft danach im Konsolenmodus weiter. Wird eine Datei als Parameter uebergeben, wird kein Dialog geoeffnet.

## Bedienoberflaeche und Tkinter

Tkinter ist ein Bestandteil vieler Python-Installationen. Es ist die einfache grafische Oberflaeche, die Python fuer kleine Windows-Programme mitbringt.

Fuer dieses Tool bedeutet das:

- Mit Tkinter erscheint eine kleine Programmoberflaeche.
- Dort kann man Quelle und Ausgabeordner auswaehlen.
- Nach `Analysieren` sieht man Video-Infos, erkannte Tonspuren und geplante Ausgaben.
- Mit `Encoding starten` beginnt die Verarbeitung.
- Das Log zeigt, was FFmpeg gerade macht.

Nicht jede Python-Installation enthaelt Tkinter. Das ist kein Problem. Wenn Tkinter fehlt, erscheint keine grosse Programmoberflaeche. Das Tool funktioniert trotzdem:

1. Es oeffnet einen normalen Windows-Dateidialog fuer die Videodatei.
2. Danach laeuft die Verarbeitung im schwarzen Konsolenfenster.
3. Alle wichtigen Informationen und Fehler stehen dort als Text.

Fuer Kollegen ohne Python-Wissen ist deshalb die Empfehlung:

```text
create_mezzanine.bat doppelklicken oder Videodatei darauf ziehen.
```

Wenn eine grafische Oberflaeche erscheint: normal benutzen. Wenn nur ein Dateidialog und danach ein Konsolenfenster erscheint: ebenfalls normal, einfach laufen lassen.

### Tkinter installieren

Tkinter wird unter Windows normalerweise zusammen mit Python installiert. Es ist kein normales Python-Paket, das man verlaesslich mit `pip install tkinter` nachinstalliert.

Empfohlener Weg:

1. Windows-Einstellungen oeffnen.
2. `Apps` suchen.
3. Die installierte Python-Version suchen, z.B. `Python 3.11`.
4. `Aendern` oder `Modify` waehlen.
5. Im Python-Installer `Modify` auswaehlen.
6. Sicherstellen, dass `tcl/tk and IDLE` aktiviert ist.
7. Installation abschliessen.
8. Neues PowerShell-Fenster oeffnen und Tool erneut starten.

Wenn Python nicht in der App-Liste auftaucht oder die Option fehlt, Python von [python.org](https://www.python.org/downloads/windows/) installieren. Im Installer sollte `tcl/tk and IDLE` aktiviert bleiben.

Pruefen, ob Tkinter verfuegbar ist:

```powershell
python -m tkinter
```

Wenn `python` nicht gefunden wird, alternativ versuchen:

```powershell
py -3 -m tkinter
```

Wenn ein kleines Testfenster erscheint, ist Tkinter installiert. Wenn eine Fehlermeldung erscheint, fehlt Tkinter in dieser Python-Installation oder Python ist nicht im `PATH`.

Wenn weder `python` noch `py` gefunden wird, Python neu von [python.org](https://www.python.org/downloads/windows/) installieren. Im Installer diese Optionen aktivieren:

- `Add python.exe to PATH`
- `py launcher` bzw. `Python Launcher for Windows`, falls angeboten
- `tcl/tk and IDLE`

## Ausgabe

Das Zielverzeichnis wird ueber `config.ini` bestimmt:

1. `output.base_dir`, wenn gesetzt
2. erstes vorhandenes Verzeichnis aus `output.preferred_dirs`
3. falls keines existiert, der erste Eintrag aus `output.preferred_dirs`

Default:

```ini
preferred_dirs = F:\VOD, H:\VOD
```

Damit wird `F:\VOD` bevorzugt, wenn vorhanden. Sonst wird `H:\VOD` verwendet, wenn vorhanden.

Dateinamen (Beispiel fuer Quelldatei `EinCoolerFilm_FTR_1080p2398_DEU20_ENG51_ENG20.mov`):

```text
EinCoolerFilm_FTR_1080p2398_DEU20_ENG51_ENG20_PVD.mp4
EinCoolerFilm_FTR_DEU20_AUDIO.mov
EinCoolerFilm_FTR_ENG51_ENG20_AUDIO.mov
```

- Das MP4 erhaelt einfach `_PVD` als Suffix – der Quelldateiname bleibt unveraendert.
- Die Audio-MOVs verwenden den Stem ohne Aufloesung/FPS-Token, gefolgt von den Sprach-Tokens der enthaltenen Spuren und `_AUDIO`.
- Bei mehreren Spuren in einer MOV werden die Tokens mit Unterstrich verbunden (`ENG51_ENG20`).

Wenn nur deutsche Tonspuren vorhanden sind, wird keine OV-MOV erzeugt.

## ProRes-Audio im Dateinamen

Bei ProRes-Quellen muss die Reihenfolge der Audiospuren im Dateinamen stehen, wenn die Datei selbst keine verlaesslichen Sprach-Metadaten hat.

Format:

```text
SPRACHEFORMAT
```

Beispiele:

```text
Film_DEU51_ENG20.mov
```

- Spur 1: Deutsch 5.1
- Spur 2: Englisch 2.0

```text
Film_DEU20_DEU51.mov
```

- Spur 1: Deutsch 2.0
- Spur 2: Deutsch 5.1
- Es wird nur eine deutsche Audio-MOV erzeugt.

Unterstuetzt werden dreistellige Sprachcodes wie `DEU`, `GER`, `ENG`, `FRA`, `ITA`, `SPA` usw. `GER` wird intern wie `DEU` behandelt.

## Audio-Regeln

- Das PVD-MP4 bekommt immer deutschen Stereo-Ton.
- Wenn eine deutsche 2.0-Spur vorhanden ist, wird diese verwendet.
- Wenn keine deutsche 2.0-Spur vorhanden ist, wird die erste deutsche Spur per FFmpeg auf Stereo heruntergemischt.
- Alle deutschen Tonspuren werden in eine MOV-Datei mit uncompressed PCM geschrieben.
- Alle nicht-deutschen Tonspuren werden in eine separate MOV-Datei mit uncompressed PCM geschrieben.
- Wenn keine deutsche Tonspur erkannt wird, bricht das Tool mit einer Fehlermeldung ab.

## Video-Regeln

- HD wird mit den HD-Werten aus `config.ini` encodiert, standardmaessig `30M`.
- SD wird mit den SD-Werten aus `config.ini` encodiert, standardmaessig `8M`.
- Interlaced-Material wird mit `bwdif=mode=0:parity=auto` deinterlaced.
- Forced Subtitles werden eingebrannt, wenn neben der Quelle eine Datei mit `_forced.srt` liegt.
- Farbraum-Metadaten werden auf den Ziel-Farbraum gesetzt.
- Der `colorspace`-Filter wird nur verwendet, wenn die Quelle vollstaendige Farbraum-Metadaten liefert. Bei `unknown`-Metadaten wird der Filter uebersprungen, damit FFmpeg nicht abbricht.

Forced-Subtitle-Beispiel:

```text
Film_DEU51_ENG20.mov
Film_DEU51_ENG20_forced.srt
```

## Konfiguration

Die wichtigsten Parameter stehen in [config.ini](config.ini). Das Format ist bewusst einfach gehalten:

- `#` beginnt einen Kommentar
- Werte werden als `name = wert` geschrieben
- mehrere Ordner werden mit Komma getrennt
- leere Werte bedeuten automatische Suche bzw. automatische Auswahl

Default:

```ini
# Amazon PVD Mezzanine Encoder Konfiguration

[ffmpeg]
ffmpeg_exe =
ffprobe_exe =
search_dirs = C:\Tools\FFMPEG, C:\Software

[output]
base_dir =
preferred_dirs = F:\VOD, H:\VOD

[video]
hd_bitrate = 30M
hd_maxrate = 35M
hd_bufsize = 50M
hd_level = 4.1
sd_bitrate = 8M
sd_maxrate = 10M
sd_bufsize = 15M
sd_level = 3.1
preset = slow
tune = film

[audio]
mp4_bitrate = 256k
sample_rate = 48000
pcm_codec = pcm_s24le
```

Hinweise:

- `ffmpeg_exe` und `ffprobe_exe` koennen leer bleiben, dann wird automatisch gesucht.
- `base_dir` ueberschreibt die automatische Zielverzeichniswahl.
- Wenn `config.ini` fehlt, wird sie beim Start mit Default-Werten erzeugt.

## Fehlerbilder

Wenn nach dem Start nur ein Dateidialog erscheint und keine grosse Oberflaeche, fehlt Tkinter in Python. Das ist kein Fehler. Datei auswaehlen und das Tool im Konsolenfenster weiterlaufen lassen.

Wenn eine Datei als Parameter uebergeben wird und der Pfad falsch ist, oeffnet sich kein Dialog. Stattdessen erscheint:

```text
FEHLER: Eingabedatei nicht gefunden: ...
```

Wenn keine deutsche Tonspur erkannt wird, muss der Dateiname ein deutsches Audio-Token enthalten, z.B.:

```text
Film_DEU20.mov
Film_DEU51_ENG20.mov
```

## Repo-Pflege

Die lokale `.env` enthaelt Zugangsdaten und wird nicht versioniert.

Bei jeder Funktionsaenderung muss diese Anleitung aktuell gehalten werden. Neue Aenderungen sollen zusammen mit passender README-Aktualisierung committed und nach `main` gepusht werden.