# Integration guide

Хочешь подключить cuframes к своему проекту? Выбери guide по типу integration'а:

## Готовые reference guides

| Тип integration'а | Guide | Reference deployment |
|---|---|---|
| **Frigate NVR** (через FFmpeg `cuframes://` demuxer) | [integrations/frigate.md](integrations/frigate.md) | Production: Frigate 0.17.1 + RTX 5090 + Dahua HEVC |
| **C++ project** (через `CuframesSource` pattern) | [integrations/cctv-cpp.md](integrations/cctv-cpp.md) | Production: [gx/cctv](https://git.goldix.org/gx/cctv) C++17 processor |
| **Python AI/ML pipeline** (через ctypes wrapper) | [examples/python-consumer/](../examples/python-consumer/) | Skeleton ready; v0.3 даст native bindings |
| **FFmpeg-based custom tool** (своя сборка ffmpeg) | [filter/README.md](../filter/README.md) | Out-of-tree patch + build instructions |

## Целевой сценарий (motivation)

В типичной CCTV / video-analytics системе один и тот же RTSP-поток
декодируется **несколько раз**:

```
   Камера ──► RTSP ──► Frigate          (decode #1: detection + recording)
                  ─►   mosaic-сервер    (decode #2: компоновка сетки)
                  ─►   AI-скрипт        (decode #3: классификация / OCR)
```

На 16 камер × 25 fps × 3 consumer'а = **1200 NVDEC operations/sec**. RTX 5090
имеет ~3 NVDEC-движка с capacity ~50 FHD25 streams → загрузка близка к лимиту,
плюс tax на PCIe bandwidth и memory.

С cuframes:

```
   Камера ──► cuframes-rtsp-source ──► CUDA frame в VRAM + IPC handles
                                              │
                                              ├──► Frigate          (zero-copy)
                                              ├──► mosaic-сервер    (zero-copy)
                                              └──► AI-скрипт        (zero-copy)
```

Decode выполняется **один раз** на источник, потребители получают тот же CUDA
device pointer без копий. **3× меньше NVDEC operations** на том же setup'е.

## Текущие ограничения (v0.1)

- **Decoded frame sharing only** (не encoded). Для `record` path в Frigate
  (mux без decode) consumer всё ещё открывает свой RTSP — это решит **v0.2
  encoded packet sharing** (см. [issue #2](https://git.goldix.org/gx/cuframes/issues/2)).

- **NV12 frame format only**. Other formats (YUV420P, RGB) — v0.2.

- **GPU → CPU copy** в FFmpeg demuxer'е (`cudaMemcpy2DAsync`). Zero-copy через
  `AVHWFramesContext` — v0.2.

- **Cross-container CUDA IPC** требует shared `ipc + pid` namespace. Если
  consumer использует s6-overlay (как Frigate) — pid не shareable, нужен
  workaround (см. [integrations/frigate.md](integrations/frigate.md)
  troubleshooting).

- **Только Linux + NVIDIA GPU** compute capability ≥ 7.5 (Turing+).

## Production reference deployments

| Setup | Версия | Где смотреть |
|---|---|---|
| 1 publisher (1× NVDEC) → Frigate (detect) + cctv-backend (motion+grid→RTSP→TV) | v0.1.0 | [BENCHMARKS.md](../BENCHMARKS.md), [integrations/frigate.md](integrations/frigate.md) |

## Roadmap для v0.2+

Полный roadmap — [ROADMAP.md](../ROADMAP.md). Highlights:

- **v0.2**: encoded packet sharing (Frigate record без второго RTSP), FFmpeg upstream PR, publisher-side resize для устранения scale_cuda dependency
- **v0.3**: pybind11 Python bindings, Jetson/arm64 support
- **v1.0**: stable ABI, multi-GPU, env-based credentials