cuframes/ROADMAP.md

Roadmap

cuframes — zero-copy sharing декодированных видеокадров между процессами через CUDA IPC. Текущая публичная версия: v0.1.0 (см. CHANGELOG.md).

Принцип релизов

Семвер: MAJOR.MINOR.PATCH.

• 0.x.y — pre-1.0: API может меняться между minor-релизами. Patch только для bugfixes без ABI-breaking.
• 1.0+ — стабильный ABI в пределах major. Минорные релизы добавляют функции без ломки существующего кода.

Проверять текущий протокол: cuframes_protocol_version() (см. C API). Subscriber с несовместимым protocol отказывается подключаться (CUFRAMES_ERR_PROTOCOL).

v0.1 — Foundation ✅ (released 2026-05-17)

Компонент	Статус
libcuframes.so — producer/consumer ring + CUDA IPC handshake	✅
C++ RAII wrapper cuframes.hpp	✅
cuframes-rtsp-source standalone publisher (RTSP → NVDEC → IPC)	✅
FFmpeg input demuxer cuframes:// (out-of-tree patch для n7.1)	✅
Docker runtime image	✅
CMake install rules	✅
Integration guide для cctv-processor (C++)	✅
Stress test 1×pub × 4×sub × 2000 frames @ 120 fps (0 torn)	✅
Production deployment на multi-camera CCTV-стeке (Frigate + custom processor)	✅

v0.2 — Encoded packet sharing 📋 (planned)

Главное расширение: publisher отдаёт не только decoded NV12 frames, но и encoded packets (H.264/H.265 NAL units) через отдельный shared ring. Use case: Frigate record role (mux в mp4 без re-encode), AI-pipeline которому не нужен decode — фильтруют по metadata + сохраняют encoded clip.

Feature	Зачем
cuframes_publisher_publish_packet() C API	Publisher шлёт AVPacket-эквивалент в shared ring
cuframes_subscriber_next_packet() C API	Consumer читает encoded packets
Variable-length ring buffer для packets	Encoded size variable (≠ fixed NV12)
FFmpeg cuframes_packets:// demuxer	Тhe complement to existing cuframes://
Sub-stream selection (для multi-resolution streams)	Один camera RTSP даёт 2-3 substreams
Scale-cuda alternative: software bilinear resize фильтр для FFmpeg сборок без cuda-llvm	Patched ffmpeg на glibc-2.36 платформах (Debian 12 Frigate base) не имеет cuda-llvm → scale_cuda недоступен. Workaround = CPU scale, регресс. Alt: cuframes-side resize в publisher'е (publish pre-scaled frames).
FFmpeg upstream PR: submit cuframesdec.c в FFmpeg mainline	Снижает trеnding overhead для adoption; патчить FFmpeg не надо будет.

ETA: 1-2 недели focused работы.

v0.3 — Bindings & Platforms 📋 (planned)

Feature	Зачем
Python bindings (pybind11)	AI/ML-скрипты сейчас вынуждены ctypes-обёртку писать
Jetson (Tegra arm64) support	Edge-deployment — Frigate тоже популярен на Jetson
Multi-GPU producer/consumer	NVIDIA IPC поддерживает только same-GPU; нужен fallback через encoded path
pkg-config .pc файл	Downstream cmake/meson — drop --extra-cflags/-ldflags ad-hoc
Frigate plugin POC (Python side, не FFmpeg)	Альтернативный путь для users которые не хотят патчить FFmpeg
Docker images в public registry	Snapshot CI-built tarballs + multi-arch

Future ideas 💡 (не запланированы, без ETA)

Идеи которые не привязаны к конкретной версии и ждут планирования.

gst-cuframes-src — GStreamer source-element

Аналог FFmpeg-демуксера для GStreamer-стэка. Один publisher cuframes-side → potreбители-pipeline'ы в GStreamer (DeepStream, обычный GStreamer-приложения).

Зачем	Что
NVIDIA DeepStream — это GStreamer-native, FFmpeg-демуксер там не работает	gst-cuframes-src как GstBaseSrc-derived element, выдаёт GstBuffer с GstCudaMemory (NVMM в Jetson вариант)
GStreamer-приложения (обычный software)	Drop-in source для любой GStreamer pipeline
GStreamer plugin registry	gst-inspect-1.0 cuframessrc discoverable

Open questions: какой memory-type — memory:CUDAMemory (mainline) vs memory:NVMM (NVIDIA DeepStream-specific). Возможно два варианта/build flags.

vf_cuda_grid — FFmpeg filter с runtime grid composition

CCTV mosaic composition как FFmpeg filter, полностью на GPU. Заменяет custom C++ GridComposer (см. gx/cctv#22 — performance investigation cctv-processor: CPU round-trip pipeline).

Capability	Зачем
Filter принимает N cuda-frames (через [in0][in1][in2]... filter inputs)	Композиция в одном filter graph без custom code
Output — один cuda-frame с N cells в layout	Прямой вход в hwdownload или h264_nvenc
Layout templates (single, quad, main_plus_preview, nine_grid, ...)	Конфигурируемые из CLI или filter command'ом
sendcmd / API для runtime smena layout'а	Не нужно teardown filter graph для переключения сетки
Per-cell overlays (text, bbox) через side data в AVFrame	Frigate detection/LPR/face — overlay внутри pipeline
Полностью CUDA-side: scale/composition/text rendering	Zero CPU round-trip, frame не покидает VRAM

Это превращает cuframes из IPC-библиотеки в полноценную GPU-native video routing platform. Эстетически близко к NVIDIA DeepStream nvstreammux + nvmultistreamtiler, но open-source и с conventional FFmpeg-stack.

Open questions:

• Filter input mode: pull-based (filter pull'ает N inputs) или push-based (через external lock-step). FFmpeg filter API больше pull-friendly.
• Text rendering в CUDA — vf_drawtext имеет CPU path; нужен либо GPU font-renderer (Pango/freetype + texture upload), либо CPU-precomputed glyph atlases.
• Runtime layout commands через filter process_command API.

Это большой scope — отдельная major version (v0.5+) или standalone проект.

v1.0 — Stable ABI 📋

• Стабильный wire-protocol (minor versions add fields в reserved space)
• Multi-GPU официально supported
• Credentials/config через env / Docker secrets (не в config.json)
• Comprehensive test suite (unit + integration + soak)
• FFmpeg upstream merge accomplished
• 2+ независимых production deployments документированы

Связанные документы

• docs/architecture.md — внутренности cuframes IPC
• docs/integration.md — guide для downstream проектов
• BENCHMARKS.md — измерения латентности и throughput
• CHANGELOG.md — release notes
• filter/README.md — FFmpeg demuxer