gx
101 lines
6.1 KiB
Markdown
101 lines
6.1 KiB
Markdown
# 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.
|