Initial containerized Frigate camera control bridge

2026-08-03 00:21:18 +02:00
commit 26e042d2d7
15 changed files with 2466 additions and 0 deletions
@@ -0,0 +1,194 @@
+# Frigate Camera Control Bridge
+
+## PL
+
+Ten projekt jest uniwersalnym sidecarem dla pojedynczej instancji Frigate.
+Kontener pobiera konfiguracje Frigate przez `/api/config`, wykrywa kamery z
+`go2rtc` oraz z bezposrednich URL-i `ffmpeg.inputs[].path`, a potem wystawia
+sterowanie swiatlem/syrena przez MQTT Discovery dla Home Assistant i awaryjne
+GUI HTTP.
+
+Najwazniejsze zalozenia:
+- Ten sam obraz obsluguje Podman dzisiaj i Kubernetes pozniej.
+- Konfiguracja runtime jest przez zmienne srodowiskowe, bez montowania pliku
+  konfiguracyjnego Frigate.
+- Sidecar czeka na Frigate przy starcie i ponawia odczyt `/api/config`.
+- Jesli `ffmpeg.inputs[].path` wskazuje na `rtsp://127.0.0.1:8554/...`,
+  sidecar traktuje to jako brame go2rtc i szuka prawdziwego URL-a kamery w
+  `go2rtc.streams`.
+- Aktualny Podman uzywa pliku env per sidecar, np.
+  `/etc/frigate-camera-control-bridge/frigate-main.env`.
+- Kubernetes powinien podawac `MQTT_HOST`, `MQTT_USER`, `MQTT_PASSWORD`,
+  `DEFAULT_CAMERA_USER`, `DEFAULT_CAMERA_PASSWORD` przez `Secret`/`ConfigMap`.
+- W trybie env brak tych wartosci jest bledem startu; sidecar nie szuka
+  credentiali w Quadletach ani w konfiguracji Frigate.
+- GUI fallback domyslnie slucha na `5011`, bo `5001` jest juz uzywany przez
+  czesc instancji Frigate.
+- Jezyki GUI sa standardowym gettext: `locale/<lang>/LC_MESSAGES/*.po` i `.mo`.
+
+Podstawowe zmienne:
+
+| Zmienna | Znaczenie |
+| --- | --- |
+| `FRIGATE_NAME` | Nazwa tej instancji, np. `frigate-main`. |
+| `FRIGATE_URL` | URL API Frigate, np. `http://frigate-main.example.test:5000`. |
+| `MQTT_HOST`, `MQTT_PORT` | Broker MQTT. |
+| `MQTT_USER`, `MQTT_PASSWORD` | Credentiale MQTT. |
+| `DEFAULT_CAMERA_USER`, `DEFAULT_CAMERA_PASSWORD` | Domyslne credentiale kamer odkrytych z Frigate. |
+| `BASE_TOPIC` | Bazowy topic MQTT, np. `frigate_camera_control/frigate-main`. |
+| `DISCOVERY_PREFIX` | Prefix Home Assistant MQTT Discovery, zwykle `homeassistant`. |
+| `UI_LANGUAGE` | Domyslny jezyk GUI i encji HA, domyslnie `en`. |
+| `HTTP_PORT` | Port GUI fallback, domyslnie `5011`. |
+| `HTTP_TOKEN` | Opcjonalny token dla GUI/API HTTP. |
+| `SNAPSHOT_RETRY_SECONDS` | Co ile probowac ponownie, gdy migawki brakuja, domyslnie `600`. |
+| `SNAPSHOT_REFRESH_SECONDS` | Co ile odswiezac poprawnie pobrane migawki, domyslnie `3600`. |
+| `SNAPSHOT_LIVE_ON_GUI` | Czy pobierac swieza migawke z Frigate przy otwieraniu GUI, domyslnie `true`. |
+
+Przyklad `/etc/frigate-camera-control-bridge/frigate-main.env`:
+
+```bash
+MQTT_HOST=mqtt.example.test
+MQTT_PORT=1883
+MQTT_USER=...
+MQTT_PASSWORD=...
+DEFAULT_CAMERA_USER=admin
+DEFAULT_CAMERA_PASSWORD=...
+```
+
+Budowanie:
+
+```bash
+docker build -t frigate-camera-control-bridge:1.0 .
+docker build -f Dockerfile.dev -t frigate-camera-control-bridge:dev .
+```
+
+Przyklady uruchomienia:
+- Podman Quadlet: `examples/podman-quadlet/`
+- Kubernetes sidecar: `examples/kubernetes-sidecar.yaml`
+
+Lokalny test kontenera:
+
+```bash
+docker run --rm \
+  -e FRIGATE_NAME=example \
+  -e FRIGATE_URL=http://frigate:5000 \
+  -e MQTT_HOST=mqtt.local \
+  -e MQTT_USER=user \
+  -e MQTT_PASSWORD=password \
+  -e DEFAULT_CAMERA_USER=admin \
+  -e DEFAULT_CAMERA_PASSWORD=password \
+  -p 5011:5011 \
+  frigate-camera-control-bridge:1.0 --check
+```
+
+Jezyki:
+
+1. Dodaj katalog `locale/de/LC_MESSAGES/`.
+2. Skopiuj `frigate_camera_control_bridge.po` z `locale/en/LC_MESSAGES/`.
+3. Przetlumacz `msgstr`.
+4. Uruchom `python3 tools/compile_gettext.py locale`.
+5. Po przebudowaniu obrazu GUI samo pokaze nowy jezyk.
+
+Manualne komendy w kontenerze:
+
+```bash
+/app/frigate-camera-control-bridge.py --list
+/app/frigate-camera-control-bridge.py --check
+/app/frigate-camera-control-bridge.py --all-off
+/app/frigate-camera-control-bridge.py --action frigate_main_camera_a_red_blue off
+```
+
+HTTP fallback:
+
+```text
+http://<ip-frigate>:5011/
+http://<ip-frigate>:5011/?lang=pl
+http://<ip-frigate>:5011/api/actions
+http://<ip-frigate>:5011/snapshot/<action_id>.jpg
+http://<ip-frigate>:5011/healthz
+http://<ip-frigate>:5011/readyz
+```
+
+Jesli ustawiono `HTTP_TOKEN`, dodaj `?token=<token>` albo naglowek
+`X-Bridge-Token: <token>`.
+
+## EN
+
+This project is a generic sidecar for one Frigate instance. The container reads
+Frigate configuration from `/api/config`, discovers cameras from `go2rtc` and
+direct `ffmpeg.inputs[].path` stream URLs, then exposes light/siren controls
+through Home Assistant MQTT Discovery plus an emergency HTTP fallback GUI.
+
+Main design points:
+- One image works for Podman now and Kubernetes later.
+- Runtime configuration is environment-based; no Frigate config mount is needed.
+- The sidecar waits for Frigate startup and retries `/api/config`.
+- If `ffmpeg.inputs[].path` points at `rtsp://127.0.0.1:8554/...`, the sidecar
+  treats it as a go2rtc gateway and resolves the real camera URL from
+  `go2rtc.streams`.
+- Current Podman deployment uses one env file per sidecar, for example:
+  `/etc/frigate-camera-control-bridge/frigate-main.env`.
+- Kubernetes should pass `MQTT_HOST`, `MQTT_USER`, `MQTT_PASSWORD`,
+  `DEFAULT_CAMERA_USER`, and `DEFAULT_CAMERA_PASSWORD` from a `Secret`/`ConfigMap`.
+- In env mode, missing values are startup errors; the sidecar does not look up
+  credentials in Quadlets or Frigate config.
+- The fallback GUI listens on `5011` by default because `5001` is already used
+  by some Frigate instances.
+- GUI languages use standard gettext files:
+  `locale/<lang>/LC_MESSAGES/*.po` and `.mo`.
+
+Core env vars:
+
+| Variable | Meaning |
+| --- | --- |
+| `FRIGATE_NAME` | Instance name, for example `frigate-main`. |
+| `FRIGATE_URL` | Frigate API URL, for example `http://frigate-main.example.test:5000`. |
+| `MQTT_HOST`, `MQTT_PORT` | MQTT broker. |
+| `MQTT_USER`, `MQTT_PASSWORD` | MQTT credentials. |
+| `DEFAULT_CAMERA_USER`, `DEFAULT_CAMERA_PASSWORD` | Default credentials for cameras discovered from Frigate. |
+| `BASE_TOPIC` | MQTT base topic, for example `frigate_camera_control/frigate-main`. |
+| `DISCOVERY_PREFIX` | Home Assistant MQTT Discovery prefix, usually `homeassistant`. |
+| `UI_LANGUAGE` | Default GUI and HA entity language, defaults to `en`. |
+| `HTTP_PORT` | Fallback GUI port, defaults to `5011`. |
+| `HTTP_TOKEN` | Optional HTTP GUI/API token. |
+| `SNAPSHOT_RETRY_SECONDS` | Retry interval while a snapshot is missing, defaults to `600`. |
+| `SNAPSHOT_REFRESH_SECONDS` | Refresh interval after snapshots are available, defaults to `3600`. |
+| `SNAPSHOT_LIVE_ON_GUI` | Fetch a fresh Frigate snapshot when the GUI loads, defaults to `true`. |
+
+Build:
+
+```bash
+docker build -t frigate-camera-control-bridge:1.0 .
+docker build -f Dockerfile.dev -t frigate-camera-control-bridge:dev .
+```
+
+Run examples:
+- Podman Quadlet: `examples/podman-quadlet/`
+- Kubernetes sidecar: `examples/kubernetes-sidecar.yaml`
+
+Development container:
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/workspace \
+  frigate-camera-control-bridge:dev
+```
+
+HTTP fallback:
+
+```text
+http://<frigate-ip>:5011/
+http://<frigate-ip>:5011/?lang=pl
+http://<frigate-ip>:5011/api/actions
+http://<frigate-ip>:5011/snapshot/<action_id>.jpg
+http://<frigate-ip>:5011/healthz
+http://<frigate-ip>:5011/readyz
+```
+
+Kubernetes sidecar notes:
+- Put the bridge container in the same pod as Frigate, or point `FRIGATE_URL`
+  at the Frigate service.
+- Use `readinessProbe` on `/readyz`.
+- Pass secrets through env vars from `Secret`.
+- Keep `/var/lib/frigate-camera-control-bridge` on a small persistent volume if
+  you want stale Home Assistant discovery cleanup to survive pod recreation.