gx
f10413580d
Реальный тест на 192.168.88.98 (1920x1080 HEVC, 25fps) показал: для отдельных consumer-container'ов недостаточно ipc=container:X — нужен также pid=container:X, иначе cudaIpcOpenEventHandle падает с invalid device context. CUDA driver валидирует IPC peer через /proc/<pid>/... E2E на реальной камере проверен: publisher (отдельный контейнер) -> consumer (docker exec): 250 frames, 0 gaps publisher (отдельный контейнер) -> consumer (отдельный с pid+ipc): 200, 0 gaps Обновлено: - docs/integration.md compose snippet, verification, troubleshooting section - docker-compose.example.yml — добавлен pid: container:cuframes-cam-test - README.md quickstart — добавлен --pid в docker run subscriber Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
123 lines
5.5 KiB
Markdown
123 lines
5.5 KiB
Markdown
# cuframes
|
||
|
||
Zero-copy sharing декодированных видеокадров между процессами через CUDA IPC.
|
||
|
||
**Статус:** v0.1 — libcuframes готов, cuframes-rtsp-source готов, e2e-pipeline
|
||
протестирован (4×subscriber × 2000 frames, 0 torn). FFmpeg filter — v0.2.
|
||
**Лицензия:** LGPL-2.1+
|
||
|
||
## Минимальные требования
|
||
|
||
| | Минимум | Рекомендуется |
|
||
|---|---|---|
|
||
| OS | Linux kernel ≥ 5.4 | Ubuntu 24.04 |
|
||
| GPU | NVIDIA с compute capability ≥ 7.5 (Turing+) | Ampere/Ada/Blackwell |
|
||
| NVIDIA driver | 525 (для CUDA 12) | 555+ (для CUDA 13) |
|
||
| CUDA Toolkit (build) | 12.0 | 13.0+ |
|
||
| GCC / Clang | 11 / 14 | 12+ / 17+ |
|
||
| CMake | 3.20 | 3.28+ |
|
||
| Docker | 24.x + nvidia-container-toolkit 1.14+ | — |
|
||
|
||
**Не работает** на Windows, macOS, WSL2, AMD/Intel GPU, multi-GPU producer/consumer.
|
||
Подробно — [docs/requirements.md](docs/requirements.md).
|
||
|
||
## Идея в одну минуту
|
||
|
||
Типичный setup с несколькими сервисами видеоаналитики:
|
||
|
||
```
|
||
Camera ─► ffmpeg #1 (NVR, decode + record)
|
||
─► ffmpeg #2 (AI-detector, decode + inference)
|
||
─► ffmpeg #3 (custom analytics, decode + ...)
|
||
```
|
||
|
||
Каждый сервис делает **свой** decode на GPU. На 16 cameras × 25 fps × 3 consumers
|
||
это сотни лишних NVDEC operations и GB/s VRAM-bandwidth впустую.
|
||
|
||
`cuframes` устраняет дублирование:
|
||
|
||
```
|
||
Camera ─► ffmpeg + cuframes filter ─► VRAM ─┬─► consumer 1 (NVR)
|
||
├─► consumer 2 (AI)
|
||
└─► consumer 3 (analytics)
|
||
```
|
||
|
||
Один decode, frame остаётся в VRAM, любое количество consumers читают
|
||
**zero-copy** через CUDA IPC.
|
||
|
||
## Состав
|
||
|
||
- **`libcuframes`** — C library + C++ RAII wrapper (header-only) для producer/consumer
|
||
- **`cuframes-rtsp-source`** — standalone bridge RTSP → cuframes IPC (используется
|
||
как input для AI/mosaic consumer'ов; альтернатива FFmpeg-filter'а до v0.2)
|
||
- **`sub_count`** (examples/) — reference subscriber + smoke-test tool
|
||
- **Docker images** — runtime для drop-in deployment (см. docker/Dockerfile.runtime)
|
||
- **FFmpeg filter `cuda_ipc_export`** — *planned для v0.2*
|
||
|
||
## Quickstart
|
||
|
||
```bash
|
||
# Publisher: декодирует RTSP в CUDA, публикует через cuframes IPC
|
||
docker run -d --name cuframes-cam --runtime=nvidia --ipc=shareable \
|
||
-v /run/cuframes:/run/cuframes \
|
||
gx/cuframes:0.1 \
|
||
/usr/local/bin/cuframes-rtsp-source \
|
||
--rtsp 'rtsp://user:pass@cam/stream' --key cam1 --ring 6
|
||
|
||
# Subscriber: получает декодированные frames zero-copy
|
||
# (для cross-container CUDA IPC нужны и --ipc, и --pid — см. docs/integration.md)
|
||
docker run --rm --runtime=nvidia \
|
||
--ipc=container:cuframes-cam --pid=container:cuframes-cam \
|
||
-v /run/cuframes:/run/cuframes:ro \
|
||
gx/cuframes:0.1 \
|
||
/usr/local/bin/sub_count --key cam1 --max-frames 100
|
||
|
||
# Или C++ кодом:
|
||
#include <cuframes/cuframes.hpp>
|
||
cuframes::SubscriberOptions opt;
|
||
opt.key = "cam1";
|
||
cuframes::Subscriber sub(opt);
|
||
cudaStream_t s; cudaStreamCreate(&s);
|
||
while (auto frame = sub.next(s, 1000)) { // 1s timeout
|
||
cudaStreamSynchronize(s);
|
||
process_on_cuda(frame->cuda_ptr(), frame->width(), frame->height());
|
||
}
|
||
```
|
||
|
||
**Полный integration guide** (docker-compose, cctv-processor, troubleshooting):
|
||
[docs/integration.md](docs/integration.md).
|
||
|
||
## Документация
|
||
|
||
- [docs/architecture.md](docs/architecture.md) — полный design document
|
||
- [docs/protocol.md](docs/protocol.md) — bit-exact wire protocol spec
|
||
- [docs/requirements.md](docs/requirements.md) — system requirements (hardware, software, build, Docker, k8s)
|
||
- [docs/integration.md](docs/integration.md) — **integration guide** для CCTV-стека (cuframes-rtsp-source + cctv-processor + Frigate)
|
||
- [docs/benchmarks-phase0.md](docs/benchmarks-phase0.md) — Phase 0 latency/throughput measurements
|
||
|
||
## Why
|
||
|
||
Подтверждённый спрос в Frigate community ([#17033](https://github.com/blakeblackshear/frigate/discussions/17033),
|
||
[#20191](https://github.com/blakeblackshear/frigate/discussions/20191), [#21559](https://github.com/blakeblackshear/frigate/discussions/21559))
|
||
— люди тычатся в NVDEC saturation при многокамерных setup'ах. Решения уровня
|
||
NVIDIA DeepStream закрытые / vendor-locked. Open source FFmpeg-plugin для этой
|
||
ниши **не существует**. См. подробный prior-art analysis в `docs/architecture.md`.
|
||
|
||
## Roadmap
|
||
|
||
| Phase | Что | Статус |
|
||
|---|---|---|
|
||
| 0 | PoC spike, CUDA IPC latency measurements | ✅ done |
|
||
| 1 | `libcuframes` (producer/consumer ring buffer + handshake protocol) | ✅ done |
|
||
| 1.5 | C++ RAII wrapper, cuframes-rtsp-source, integration docs | ✅ done |
|
||
| 2 | FFmpeg filter `vf_cuda_ipc_input` + patched FFmpeg build | planned |
|
||
| 3 | Python bindings (pybind11) | planned |
|
||
| 4 | Docker runtime-images в реестре, Frigate plugin POC | planned |
|
||
| 5 | Reference: 16-камерный mosaic consumer | planned |
|
||
| 6 | OSS launch (HN, reddit, FFmpeg upstream PR) | planned |
|
||
|
||
## Contributing
|
||
|
||
Проект на ранней стадии. Перед PR сверьтесь с [docs/architecture.md](docs/architecture.md)
|
||
и [CONTRIBUTING.md](CONTRIBUTING.md).
|