Claude: Dokumentation

doc/07_multipleCam_roadmap.md

@@ -68,16 +68,19 @@ Liegt im Projektverzeichnis, wird beim Start geladen und validiert.
       "position":  "right",
       "stream":    true,
       "hires":     true,
-      "liveSize":  "1280x720",
-      "liveFps":   30,
       "hiresSize": "1920x1080",
-      "hiresFps":  30,
       "note":      "usb-046d_HD_Pro_Webcam_C920_9C5591DF-video-index0"
     }
   ]
 }
 ```
 
+> **cam2 (C920):** Live läuft auf dem globalen Default 640×480 (USB-schonend, flüssig),
+> nur der HD-Grab geht auf 1920×1080. `encode`/`hiresEncode` sind **nicht** gesetzt →
+> beide nutzen `copybsf` (Kamera-JPEG ohne Re-Encode = beste Standbild-Qualität, s.u.).
+> Der Wechsel 640→1920 beim Grab funktioniert direkt; **kein** Warmup/Zwischenformat nötig
+> (auf dem Host verifiziert, 2026-06-06). Details: `05_screenShot_roadmap.md`.
+
 ### Felder
 
 | Feld | Typ | Pflicht | Bedeutung |
@@ -92,7 +95,8 @@ Liegt im Projektverzeichnis, wird beim Start geladen und validiert.
 | `liveFps` | int | | Überschreibt globales `LIVE_FPS`-Env |
 | `hiresSize` | string | | Überschreibt globales `HIRES_SIZE`-Env |
 | `hiresFps` | int | | Überschreibt globales `HIRES_FPS`-Env |
-| `encode` | string | | `"copybsf"` oder `"mjpeg"` — überschreibt globales `ENCODE_MODE`-Env |
+| `encode` | string | | `"copybsf"` oder `"mjpeg"` — überschreibt `ENCODE_MODE`-Env (gilt für Live; und für Grab, falls `hiresEncode` fehlt) |
+| `hiresEncode` | string | | Encode **nur** für den HD-Grab; überschreibt `encode`. Default = `encode`. Für Standbilder `copybsf` bevorzugen (s.u.) |
 | `note` | string | | Freitext; empfohlen: by-id-Name des Geräts (Dokumentation) |
 
 **Globale Env-Defaults** (gelten wenn das Feld in cameras.json fehlt):
@@ -136,9 +140,31 @@ v4l2-ctl --list-formats-ext -d /dev/video4 | grep -A 20 MJPG
 Nur Auflösungen unter `'MJPG'` in `liveSize`/`hiresSize` eintragen.
 Falls eine Auflösung nur unter `'YUYV'` erscheint → andere Auflösung wählen.
 
-Falls der Stream schwarz bleibt obwohl die Auflösung als MJPG gelistet ist:
-`"encode": "mjpeg"` in cameras.json für diese Kamera erzwingt Re-Encode
-(kompatibel mit jedem Kamera-MJPEG, aber höhere CPU-Last).
+> **Lehrgeld (2026-06-06):** Beim Einbau der C920 schien 1920×1080 „nur 720 zu liefern".
+> Ursache war **nicht** die Kamera (1920×1080 MJPEG ist nativ, auf dem Host verifiziert),
+> sondern (a) veralteter Code im Container und (b) ein nachträglich eingebauter
+> „Warmup-Zwischenformat"-Schritt, der einen zweiten FFmpeg auf dem Gerät startete
+> (`Device or resource busy`). Beides entfernt. Lehre: erst auf dem **Host** mit
+> `ffmpeg`/`ffprobe` verifizieren, was die Kamera real liefert, bevor man Code-Theorien baut.
+
+---
+
+## Standbild-Qualität: Encode-Wahl
+
+Eine USB-Kamera liefert das Bild bei `input_format mjpeg` bereits **JPEG-komprimiert**
+(Hardware, unvermeidbar). Wie der HD-Grab das ausgibt, entscheidet `hiresEncode`/`encode`:
+
+| Modus | Was passiert | Qualität / Größe | Wann |
+|---|---|---|---|
+| `copybsf` (Default) | Kamera-JPEG **durchreichen** (`-c:v copy -bsf:v mjpeg2jpeg`), keine zweite Kompression | beste JPEG-Qualität, klein, niedrigste CPU | **Standardwahl, auch für Standbilder** |
+| `mjpeg` | Re-Encode (`-c:v mjpeg -q:v 5`) — **zweite** Kompression | sichtbare Artefakte bei Standbildern, ~50 % CPU | nur als Fallback, wenn copybsf bei einer Kamera zickt |
+
+→ Für scharfe Standbilder **`copybsf`** verwenden (kein `hiresEncode` setzen). `mjpeg`
+war ein Workaround und erzeugte bei cam2 sichtbare Artefakte (131 kB vs. ~350 kB copybsf).
+
+**Wirklich verlustfrei** ginge nur über das rohe **YUYV**-Format → PNG (kein JPEG-Verlust
+überhaupt). Das ist ein eigener Grab-Pfad (große Dateien ~3–6 MB, langsamer) und noch
+**nicht implementiert** — bei Bedarf siehe „Offene Punkte".
 
 ---
 
@@ -222,5 +248,6 @@ Blockiert ~8–10 s. Nur sinnvoll wenn der Aufrufer synchron warten kann.
 | Punkt | Priorität | Massnahme |
 |---|---|---|
 | Phase 4B/C WebService-Push | niedrig | erst wenn aufrufender Container konkret |
+| Verlustfreie Standbilder (YUYV→PNG) | niedrig | eigener Grab-Pfad: rohes YUYV lesen → PNG; nur wenn JPEG-Qualität nicht reicht |
 | USB-Bandbreite bei >4 aktiven Streams | mittel | `lsusb -t` prüfen, Kameras auf Controller verteilen |
 | Stream-Freeze (selten) | niedrig | bekannt; noch kein reproduzierbarer Fall |