gx
4a6a6f4a6c
- .gitea/workflows/build.yml — on push/PR:
* cmake build на CUDA 12.4 devel image (Ubuntu 22.04 base)
* compile-only smoke (no GPU нужен): libcuframes.so + tools + examples
* install-prefix layout verify (headers + libs в правильных путях)
* filter/ — clone FFmpeg n7.1 + apply patch + build minimal patched
ffmpeg, verify cuframes demuxer registered
- .gitea/workflows/release.yml — on tag v*:
* build runtime Docker image, push в git.goldix.org/gx/cuframes:<version>
* build source tarball cuframes-<version>.tar.gz как artifact
- README.md badges: build status, release version, license
Runner: gitea act_runner v0.4.1 на R9-88.23 — labels ubuntu-22.04 / ubuntu-24.04
доступны через docker.gitea.com/runner-images. CUDA devel image использует
nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 (уже cached на runner host).
Stress test (требует GPU) намерено НЕ в CI — runner без GPU. Запускать
отдельно на dev-машине через ctest.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
128 lines
5.9 KiB
Markdown
128 lines
5.9 KiB
Markdown
# cuframes
|
||
|
||
[](https://git.goldix.org/gx/cuframes/actions?workflow=build.yml)
|
||
[](https://git.goldix.org/gx/cuframes/releases/tag/v0.1.0)
|
||
[](LICENSE)
|
||
|
||
Zero-copy sharing декодированных видеокадров между процессами через CUDA IPC.
|
||
|
||
**Статус:** v0.1.0 released — production-deployed на multi-camera CCTV-стeке
|
||
(Frigate + custom C++ processor, оба используют один publisher на одном NVDEC).
|
||
См. [BENCHMARKS.md](BENCHMARKS.md) для measurements, [ROADMAP.md](ROADMAP.md)
|
||
для v0.2 plans.
|
||
|
||
## Минимальные требования
|
||
|
||
| | Минимум | Рекомендуется |
|
||
|---|---|---|
|
||
| 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).
|