Erster Commit: MJPEG-Relay, Stream-Tool und README

README.md

@@ -0,0 +1,87 @@
+# Webcam
+
+Zwei kleine Python-Tools für MJPEG-Kameras:
+
+- **`relay.py`** – holt den MJPEG-Stream jeder Kamera nur **einmal** ab und stellt ihn für beliebig viele Zuschauer per HTTP bereit (gedacht für den Betrieb hinter einem Reverse Proxy wie Zoraxy).
+- **`webcam.py`** – Kommandozeilenwerkzeug, um einen MJPEG-Stream zu testen, Einzelbilder/Frames zu speichern oder live anzuzeigen.
+
+## Voraussetzungen
+
+- Python 3
+- [`requests`](https://pypi.org/project/requests/)
+- Optional für `webcam.py --show`: `opencv-python` und `numpy`
+
+```bash
+pip install requests
+pip install opencv-python numpy   # nur für --show
+```
+
+## Relay (`relay.py`)
+
+### Konfiguration
+
+Die Konfiguration erfolgt über eine `.env`-Datei neben `relay.py` oder über Umgebungsvariablen (echte Umgebungsvariablen haben Vorrang).
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Beschreibung | Standard |
+|---|---|---|
+| `CAMERA_<name>` | Stream-URL einer Kamera, eine Zeile pro Kamera. Der Name wird Teil der URL (`/cam1/`). | – (mindestens eine nötig) |
+| `PORT` | Port, auf dem der Relay lauscht | `8000` |
+| `AUTH_USER` / `AUTH_PASS` | Optional: Basic-Auth. Nur sinnvoll mit HTTPS (z. B. in Zoraxy). | aus |
+
+Beispiel:
+
+```ini
+CAMERA_cam1=http://192.168.10.82:8080/stream.mjpg
+CAMERA_cam2=http://192.168.10.83:8080/stream.mjpg
+PORT=8000
+#AUTH_USER=joachim
+#AUTH_PASS=geheim
+```
+
+> `.env` enthält ggf. Zugangsdaten – nicht ins Repository einchecken.
+
+### Starten
+
+```bash
+python3 relay.py
+```
+
+### Endpunkte
+
+| Pfad | Beschreibung |
+|---|---|
+| `/` | Übersicht aller Kameras |
+| `/<name>/` | Webseite mit Livebild einer Kamera |
+| `/<name>/stream.mjpg` | Livestream (`multipart/x-mixed-replace`) |
+| `/<name>/snapshot.jpg` | Aktuelles Einzelbild |
+| `/stream.mjpg`, `/snapshot.jpg` | Alias für die erste Kamera (Abwärtskompatibilität) |
+| `/health` | Status aller Kameras (`200` wenn alle liefern, sonst `503`); ohne Authentifizierung erreichbar |
+
+### Funktionsweise
+
+- Pro Kamera läuft ein Hintergrund-Thread, der den Stream liest und die JPEG-Frames anhand der Marker `FFD8`/`FFD9` ausschneidet.
+- Bei Verbindungsfehlern wird nach 3 Sekunden automatisch neu verbunden.
+- Alle Zuschauer bekommen jeweils das neueste Frame – die Kamera wird unabhängig von der Zuschauerzahl nur einmal belastet.
+- Der Header `X-Accel-Buffering: no` verhindert Pufferung durch den Proxy.
+
+## Stream-Tool (`webcam.py`)
+
+```bash
+python3 webcam.py                       # Verbindung testen, Frame-Infos ausgeben
+python3 webcam.py --snapshot bild.jpg   # ein Einzelbild speichern
+python3 webcam.py --save frames/ -n 50  # 50 Frames als JPEG speichern
+python3 webcam.py --show                # Live-Fenster (q oder Esc beendet)
+python3 webcam.py --url http://IP:PORT/stream.mjpg
+```
+
+| Option | Beschreibung |
+|---|---|
+| `--url` | Stream-URL (Standard ist in `webcam.py` hinterlegt) |
+| `--snapshot DATEI` | Ein Frame speichern und beenden |
+| `--save ORDNER` | Frames im Ordner speichern |
+| `-n N` | Nach N Frames beenden (`0` = endlos) |
+| `--show` | Live-Fenster anzeigen (OpenCV) |