frigate-camera-control-bridge/README.md

# 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.