From 06be41d245f5f084bb89ecb084b682fba503bcc1 Mon Sep 17 00:00:00 2001
From: gx <gx@goldix.org>
Date: Tue, 19 May 2026 20:37:41 +0100
Subject: [PATCH] readme: project overview + architecture diagram + phase table

---
 README.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 98 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e7f4c94..85e13a3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,100 @@
 # vf-cuda-grid
 
-GPU-native video grid composer — FFmpeg filter + control-plane sidecar для multi-camera mosaic compositions с runtime layout switching, rich overlays и MQTT/ZeroMQ/HTTP/HA Discovery integration
\ No newline at end of file
+**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.