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. Имплементация не начата.

Что это

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

Связано

• gx/cuframes (repo) — 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.