# vf-cuda-grid

**GPU-native video grid composer** — FFmpeg filter + control-plane sidecar для
multi-camera mosaic composition с runtime layout switching, rich overlays
и интеграцией с Home Assistant / Frigate / любой MQTT-системой.

**Статус:** дизайн зафиксирован — см. [`docs/design.md`](docs/design.md). Имплементация
не начата.

## Что это

- **`vf_cuda_grid`** — FFmpeg video filter (`libavfilter/vf_cuda_grid.c`), out-of-tree
  patch для FFmpeg n7.1+. Принимает N CUDA-frames на входе, выдаёт один composed
  frame с N-cell layout. End-to-end CUDA (без CPU round-trip).
- **`cuda-grid-controller`** — Python sidecar process (FastAPI + asyncio + pyzmq +
  aiomqtt). Принимает commands через ZeroMQ / MQTT / HTTP REST / HA Discovery,
  транслирует в FFmpeg `process_command` через `zmq` filter. Также publishes
  events наружу — для bidirectional integration с Home Assistant и Node-RED.

## Ключевые возможности (planned)

- ✅ **Multi-input** — N CUDA-frames в filter (`[in0][in1][in2]...cuda_grid=...`)
- ✅ **Multi-output** — несколько filter instances (разные TV, public stream, private)
- ✅ **Per-cell camera binding** — cells привязаны к camera_id, не к input slot
- ✅ **Layout DSL** — predefined templates + runtime-created custom layouts
- ✅ **Runtime layout switching** без teardown filter graph
- ✅ **Rich overlays** — rectangles, text, icons, image overlays, dim/darken,
  графики, чаты с alpha blending. Всё GPU-side.
- ✅ **Control plane** — ZeroMQ, MQTT, HTTP REST, HA Discovery
- ✅ **Bidirectional events** — controller publishes `layout_switched`,
  `cell_camera_changed`, `fps_drop`, `overlay_added` etc.
- ✅ **Audio orchestration** — controller координирует video grid + audio
  (`amix`, `sidechaincompress` через стандартные FFmpeg filters)
- ✅ **Privacy filtering** — на public screen overlays можно выборочно отключить

## Use cases

- **NVR с несколькими TV** — каждый TV имеет свой layout (например full-house quad
  в гостиной + door-focus в холле + private-only mosaic в спальне)
- **Public stream + private monitor** — на public stream без LPR-text и без
  privacy-camera; на private — всё
- **Domofon scenario** — звонок в дверь → controller переключает layout
  на focus-door + ducked music + door audio focused
- **Frigate detection visualization** — overlay bounding boxes, LPR numbers,
  face names с alpha blending поверх video grid

## Architecture (high level)

```
        ┌────────── Home Assistant / Node-RED / custom apps ──────────┐
        │            (MQTT / ZeroMQ / HTTP REST / SSE)                │
        └─────────────────────────────┬───────────────────────────────┘
                                      │
                          ┌───────────▼────────────┐
                          │   cuda-grid-controller │  (Python sidecar)
                          │  (FastAPI + pyzmq +    │
                          │   aiomqtt + pycairo)   │
                          └───────────┬────────────┘
                                      │  process_command
                                      │  via FFmpeg's zmq filter
                                      ▼
            ┌─────────────────── FFmpeg ───────────────────┐
   cuframes://cam1 ─┐                                       │
   cuframes://cam2 ─┼─►  vf_cuda_grid  ──►  h264_nvenc  ──► output
   cuframes://cam3 ─┤    (instance N)                       │
   cuframes://camN ─┘    runtime sendcmd via zmq            │
            └───────────────────────────────────────────────┘
```

Полная архитектура, layout DSL, CUDA kernels, overlay system, multi-instance
behaviour, audio orchestration, 6 phase implementation plan и migration path
для cctv-processor — см. [`docs/design.md`](docs/design.md).

## Связано

- **`gx/cuframes`** ([repo](https://git.goldix.org/gx/cuframes)) — zero-copy CUDA IPC frame sharing. Frames из cuframes — основной input source для vf_cuda_grid в нашей экосистеме.
- **`gx/ffmpeg-patched`** — FFmpeg fork с `cuframes://` demuxer. vf_cuda_grid будет добавлен сюда (или в отдельный patched fork).
- **`gx/cctv` #22** — performance investigation для текущего custom C++ GridComposer. vf_cuda_grid v1.0 закрывает Phase 4 (end-to-end GPU).
- **`gx/cctv` #24** — initial MQTT plugin design для cctv-processor. Superseded — controller cuda-grid-controller покрывает 60-70% этого scope, см. design §14.

## Status / Phases

См. epic issue `#1` для tracking прогресса.

| Phase | Что | Status |
|---|---|---|
| 1 | MVP filter — fixed quad layout, 4 CUDA inputs → 1 output | planned |
| 2 | Dynamic layouts (DSL) + scaling per cell | planned |
| 3 | `cuda-grid-controller` sidecar (ZMQ + MQTT + HTTP + HA Discovery) | planned |
| 4 | Overlay primitives (rect/text/icon) — CUDA rendering | planned |
| 5 | Image overlays, dim areas, graphs/charts (Cairo→texture pipeline) | planned |
| 6 | Audio orchestration use cases в controller | planned |

## License

LGPL-2.1+ — для совместимости с FFmpeg LGPL builds и cuframes.

## Контакты

Issues и discussions — в этом репо. Project maintainer — gx@goldix.org.