# Video-Encoding – Dokumentationsindex und Projektstand

**Dokumenten-ID:** GNENC-000-DOC
**Stand:** 2026-10-19
**Status:** Planungsabschluss; Pipeline geplant, Implementierung noch nicht begonnen

## Dokumente

| Dokument | Zweck / Zielgruppe |
| --- | --- |
| [GNENC-001-PLAN_Architecture.md](GNENC-001-PLAN_Architecture.md) | finale Architektur, Repository-Grenzen, Ressourcenmodell und offene Entscheidungen; Infrastrukturadministratoren |
| [GNENC-002-PLAN_Pipeline.md](GNENC-002-PLAN_Pipeline.md) | operative Pipeline: Komponenten, Konten, Verzeichnislayout, Datenfluss, Validierung, Statusmodell; Infrastrukturadministratoren und Betreiber |

Dashboard und Systemmetriken sind in den Monitoring-Bereich ausgelagert:
[Monitoring → GNMON-000](../monitoring/GNMON-000-DOC_Index.md).
Die Samba-/NFS-Anbindung auf CT-101 ist in
[GNAI-017](../../proxmox-server/lxc/ct-101-samba/GNAI-017-PLAN_Samba-NFS-Export.md)
beschrieben.

## Bestätigter Stand

- Planungsabschluss am 19.10.2026: Die Pipeline besteht aus VPN-Sidecar
  (ProtonVPN), jDownloader2 (Download), Encoding-Worker (HandBrakeCLI +
  ffmpeg); Handover ausschließlich über das Filesystem, In-Progress-Schutz
  über Work-Ordner und atomares `mv`.
- Speicherort: CT-101 (Samba/NAS, 10.0.0.9) — NFS-Export
  `/media/datenhdd3/Encoding`, gemountet auf `/var/lib/ghostnet-encoding`
  (ghostnet-ki hat nur eine 2-TB-NVMe; die Medienbibliothek liegt auf CT-101).
- Verzeichnislayout: `input/<Profil>/*.dlc`, `jd/`, `queue/<Profil>/<Release>/`,
  `work/`, `output/<Profil>/<Release>/` + `output/_failed/`, `state/jobs/` +
  `state/system.json`.
- Konten: `gn-encoding` (982, eingerichtet und verifiziert), `gn-download`
  (983, jDownloader2 + VPN-Sidecar), `gn-dashboard` (984, Dashboard,
  Monitoring-Bereich); gemeinsame Gruppe `gn-media` (GID 970, auch auf CT-101).
- VPN: gesamter jDownloader2-Verkehr über ProtonVPN-WireGuard
  (gluetun-Sidecar mit Kill Switch); WireGuard-Credentials server-lokal in
  `/etc/ghostnet-download/vpn.env`, nicht in git.
- Profile: drei versionierte HandBrake-Presets (SVT-AV1 10-bit, MKV,
  Audio-Passthrough) unter `llm-server/encoding/profiles/`; Auswahl über
  gleichnamige Ordner, keine Auto-Detection.
- Zeitplan: dauerhaft laufende Dienste; der Worker startet neue Releases nur
  00:00–06:00 Uhr Europe/Berlin, laufende Jobs laufen über das Fenster hinaus
  (kein Abbruch am Fensterende).
- Validierung: Exit 0, nicht-leere Zieldatei, Videostream vorhanden,
  ffmpeg-Volldecodierung ohne stderr-Fehler, Dauerabweichung ≤ 1 s.
- Fehlerbehandlung: Quarantäne pro Datei nach `output/_failed/`; Status
  `failed` bis zur manuellen Prüfung.
- Abholung: fertige Outputs per SMB über CT-101 (Share `[Encode]`, RW für
  `ghost`; Entnahme per `mv` räumt auf; optionaler Clean-Job nach 30 Tagen);
  `.dlc`-Drop über Share `[Encode-In]`; kein smbd auf `ghostnet-ki`.
- Statusmodell: JSON pro Videodatei in `state/jobs/`, atomar geschrieben;
  Systemmetriken in `state/system.json` (Metrics-Collector des
  Monitoring-Bereichs).
- Ressourcenlimits: Quadlet/cgroup (Worker MemoryMax 16G, Nice 10, IOWeight 50;
  jDownloader2 MemoryMax 2G, CPUWeight 50, IOWeight 20; VPN-Sidecar 256M).
- Images: Worker als Eigenbau auf Basis des gepinnten HandBrake-Digests
  (`linuxserver/handbrake:1.11.2-ls48`, `sha256:fda92bd1…48a3c7`) mit python3
  und ffmpeg; `jlesage/jdownloader-2` und `qmcgaw/gluetun` gepinnt.
- Credentials: server-lokal unter `/etc/ghostnet-download/` (`jdownloader/`,
  `vpn.env`), nicht in git; Platzhalter im Repository.
- Der Ansible-Grundzustand für `gn-encoding` ist eingerichtet und verifiziert
  (Check-Mode und Idempotenzlauf `changed=0`); es existieren noch keine
  Quadlets, Container oder Timer für den Encoding-Workload.

## Noch offen

1. Feinjustierung der Ressourcenlimits nach einem repräsentativen Encoding-Test
   unter gleichzeitiger Inferenzlast.
2. Rootless-TUN-Verifizierung für den VPN-Sidecar auf dem Host.
3. Implementierung: CT-101 (NFS-Export, Shares `[Encode]`/`[Encode-In]`,
   Gruppe `gn-media`/GID-Abgleich — GNAI-017), Konten `gn-download`/
   `gn-dashboard`, NFS-Mount, Image-Bauten, Quadlet-Units (inkl. VPN-Sidecar),
   Skripte, Monitoring-Bereich (Collector, Dashboard).