gx
4cb0321a6f
Публичные функции в include/cuframes/cuframes.h: - cuframes_publisher_enable_packets(opts) — активирует ring на существующем publisher'е; default sizing (64 slots, 8MiB data, 2MiB max). - cuframes_publisher_set_codec_extradata(data, size) — SPS/PPS bytes. - cuframes_publisher_publish_packet(data, size, pts, dts, flags) - cuframes_subscriber_enable_packets() — открывает packet shm у subscriber'а. - cuframes_subscriber_next_packet(pkt_out, timeout_ms) с поллингом 1ms. - cuframes_packet_data/size/pts/dts/flags/seq accessors. - cuframes_subscriber_release_packet() - cuframes_subscriber_get_codec_params() Internal: - producer.c: расширена struct cuframes_publisher (has_pkt_ring, max_packet_size, pkt_ring); cleanup в destroy(); enable_packets() bump'ит proto_version=2 в frames header. - consumer.c: расширена struct cuframes_subscriber (has_pkt_ring, pkt_ring, last_packet_seq, packet_obj); single-packet pattern (как frame_obj — busy flag, переиспользование buffer). enable_packets() стартует с last_keyframe_seq-1 для late subscriber resync. На PACKET_OVERRUN автоматически resync на last_keyframe и возвращает ERR наружу для signalling discontinuity. Связано: #2, PR #4.
cuframes
Zero-copy sharing декодированных видеокадров между процессами через CUDA IPC.
Статус: v0.1.0 released — production-deployed на multi-camera CCTV-стeке (Frigate + custom C++ processor, оба используют один publisher на одном NVDEC). См. BENCHMARKS.md для measurements, 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.
Идея в одну минуту
Типичный 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/consumercuframes-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
# 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/architecture.md — полный design document
- docs/protocol.md — bit-exact wire protocol spec
- docs/requirements.md — system requirements (hardware, software, build, Docker, k8s)
- docs/integration.md — integration guide для CCTV-стека (cuframes-rtsp-source + cctv-processor + Frigate)
- docs/benchmarks-phase0.md — Phase 0 latency/throughput measurements
Why
Подтверждённый спрос в Frigate community (#17033,
#20191, #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 и CONTRIBUTING.md.