gx/cuframes

Fork 0

Files

T

gx 4a6a6f4a6c

build / cmake build (CUDA 12.4, Ubuntu 22.04) (push) Failing after 1m4s

Details

build / ffmpeg filter patch (out-of-tree) (push) Has been skipped

Details

ci: gitea Actions workflows (build, release) + README badges

- .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>

2026-05-18 21:43:55 +01:00

5.9 KiB

Raw Permalink Blame History

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/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

# 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.

5.9 KiB Raw Permalink Blame History Unescape Escape