gx
12708618d4
- docs/integrations/frigate.md — полный production-tested guide: Dockerfile, docker-compose, config.yml, troubleshooting (s6+pid, scale_cuda, hwaccel issues), build steps - docs/integrations/cctv-cpp.md — C++ pattern: IFrameSource interface + CuframesSource skeleton + CMake setup + runtime requirements - examples/frigate-compose/ — reference compose stack (cuframes-pub + Frigate) с config.yml stub, .env.example, README - examples/python-consumer/ — ctypes-based skeleton для AI/ML pipeline'ов (до v0.3 native pybind11 bindings) - docs/integration.md — превратился в index-страницу, ссылается на specific guides Reorganization упрощает onboarding: пользователь выбирает guide по типу integration'а (Frigate/C++/Python/FFmpeg) и сразу видит реальный code. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
# 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
|