# cuframes-composer

CUDA-композитор multi-source видео в один H.264 RTSP-поток с
авто-раскладкой по motion и runtime-управлением через ONVIF/ZMQ.

Заменяет монолитный ffmpeg-конвейер (`ffmpeg + vf_cuda_grid` фильтр) для
случаев, когда нужно:

- Поток продолжает работать при потере любого числа источников
  (graceful degradation, blank cells вместо crash'а)
- Композитор сам управляет частотой кадров без зависимости от ffmpeg-демухера
- Минимум перемещений данных: zero-copy CUDA от cuframes-publisher до NVENC
- Auto-layout по движению (Frigate-driven), без оператора
- Управление с TV через ONVIF PTZ

## Что внутри

- **CUDA-композитор** (C++ ООП-ядро + extern "C" ABI, Phase 11b)
- **Auto-layout** с asymmetric hysteresis + best-fit selection
- **PTZ-override** через ONVIF (с auto-возвратом в motion-mode)
- **MQTT-driven text overlays** (температура, статусы, etc.)
- **Detection box overlay** от Frigate, следует за камерой при смене layout
- **ZMQ control plane** для runtime-управления (set_layout, set_text, ...)
- **NVENC** через `dlopen` (LGPL-совместимая интеграция)

## Документация

| | Русский | English |
|---|---|---|
| Для пользователя | [docs/ru/user.md](docs/ru/user.md) | [docs/en/user.md](docs/en/user.md) |
| Для разработчика | [docs/ru/developer.md](docs/ru/developer.md) | [docs/en/developer.md](docs/en/developer.md) |
| Operations / deploy | [docs/ru/operations.md](docs/ru/operations.md) | [docs/en/operations.md](docs/en/operations.md) |

## Статус

**Phase 11b — production.** Развёрнут на R9-88.23 в составе CCTV-стека.

См. [STATE.md](../../localhost-infra/STATE.md) для текущего состояния
infra и git-history `main` для эволюции по фазам.

## Зависимости

- [cuframes](https://git.goldix.org/gx/cuframes) — zero-copy frame
  delivery от RTSP-publisher'а к composer'у. Подключена как git submodule.
- [nv-codec-headers](https://github.com/FFmpeg/nv-codec-headers) —
  MIT-licensed заголовки NVENC API (submodule). `libnvidia-encode.so`
  грузится через `dlopen` в runtime для LGPL-совместимости.
- CUDA Toolkit 12.x+ (cudart, nvcc, driver API)
- NVIDIA driver 525+ (NVENC, cuMemCreate POSIX FD)
- FreeType, libpng, libzmq, libjson-c, libmosquitto, libavformat/avcodec/avutil
- Linux 64-bit (POSIX shm, SCM_RIGHTS, named pipes)

## Quick start (host build)

```bash
git submodule update --init --recursive
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```

Артефакты:
- `build/src/libcuframes_composer.so` — shared library
- `build/examples/grid_record` — main CLI entry (C)
- `build/examples/grid_record_cpp` — C++ smoke test

Запуск (1 камера, motion-mode, JSON-templates):
```bash
build/examples/grid_record \
  --out=/tmp/grid.h264 --fps=25 --bitrate=6000 \
  --width=1920 --height=1080 \
  --source=cam-parking,frigate=parking_overview,priority=100 \
  --motion-mode --motion-ttl=45000 \
  --templates=docker/templates.json \
  --mqtt-overlays=docker/mqtt_overlays.json
```

Production deploy и jammy-build — см.
[docs/ru/operations.md](docs/ru/operations.md).

## Архитектура одной картинкой

```
Frigate ──MQTT events──→ frigate_mqtt subscriber
                                    │
                                    ↓ motion_pulse
cuframes-pub-* ──VMM──→ Composer (C++ Cell/Layout/Decoration)
                          │
                          ↓ best-fit + hysteresis
                       Layout::apply()
                          │
                          ↓ NV12 zero-copy
                       NVENC ──→ H.264 pipe
                                       ↓
                              cfc-grid-ffmpeg
                                       ↓ RTSP push
                              mediamtx ──→ TV/VLC/HLS/WebRTC
                                  ↑
                              cctv-onvif (PTZ → ZMQ set_layout)
```

Подробности — [docs/ru/developer.md](docs/ru/developer.md) §1.

## Лицензия

LGPL-2.1+