cuframes/CHANGELOG.md

Changelog

Все заметные изменения в этом проекте документируются в этом файле.

Формат основан на Keep a Changelog, проект следует Semantic Versioning.

[0.2.0] — 2026-05-19

Encoded packet ring — параллельный канал для record/mux consumer'ов без второго RTSP-подключения к камере.

См. issue #2, PRs #4 (cuframes) + gx/ffmpeg-patched#1 (FFmpeg demuxer).

Added

• Encoded packet ring — параллельный ring для H.264/H.265 NAL units (отдельный SHM /dev/shm/cuframes-<key>-packets, variable-length byte buffer + slot index, seqlock-style read для защиты от overrun).
• Wire protocol v2 (proto_version = 2 в SHM header). Backward-compat: v2 publishers принимают v1 subscribers (frames-only).
• Public C API (include/cuframes/cuframes.h):
  • cuframes_publisher_enable_packets(opts) — активирует ring
  • cuframes_publisher_set_codec_extradata(data, size) — SPS/PPS
  • cuframes_publisher_publish_packet(data, size, pts, dts, flags)
  • cuframes_subscriber_enable_packets() + _next_packet() + accessors
  • cuframes_subscriber_get_codec_params(codec_id, extradata, size)
• cuframes::Publisher (C++ RAII): enable_packets, set_codec_extradata, publish_packet методы.
• cuframes-rtsp-source: новый CLI flag --enable-packet-ring. Дублирует AVPacket в encoded ring до передачи декодеру.
• FFmpeg demuxer cuframes_packets://<key> (отдельная ветка gx/ffmpeg-patched PR #1). Companion к cuframes://. Use case: Frigate record role без второго RTSP к камере.
• 4 новых error codes: PACKET_OVERSIZED, NO_PACKET_RING, NO_CODEC_PARAMS, PACKET_OVERRUN.
• Stress test libcuframes/tests/test_packet_ring.c: 2 scenarios — normal flow (1 pub × 1 sub × 2000 packets, integrity check) + slow consumer (must hit OVERRUN + library auto-resync на keyframe).
• Protocol spec §10 в docs/protocol.md (397 строк): byte-exact layout, seqlock semantics, late-subscriber GOP-aligned start.

Limitations (документировано)

• Sub-stream selection отложено в v0.3 (<key>-substream-<N> naming).
• Audio packets — v0.3 (тот же ring layout, codec_id = audio).
• Codec change mid-stream — требует publisher destroy+recreate.

[0.1.0] — 2026-05-17

Первый функциональный release с production deployment.

Added

• libcuframes.so — main shared library:
  • Producer/consumer ring buffer в CUDA-памяти (через cudaIpcGetMemHandle)
  • Cross-process sync через cudaIpcEventHandle_t (NVIDIA Programming Guide §3.2.8)
  • Handshake protocol по Unix domain socket (/run/cuframes/<key>.sock)
  • Shared metadata в POSIX SHM (/dev/shm/cuframes-<key>)
  • Поддержка EXTERNAL ownership (publisher передаёт свои pre-allocated CUDA pointers)
  • 32 одновременных subscriber'а на publisher (configurable bit-mask)
• cuframes.hpp — header-only C++17 RAII обёртка над C API
• cuframes-rtsp-source — standalone tool: RTSP → libavformat decode (hwaccel CUDA) → cuframes IPC
• FFmpeg input demuxer cuframes:// (out-of-tree patch для n7.1):
  • --enable-libcuframes configure option
  • URL form cuframes://<key>, опция -cuda_device и -connect_timeout
  • NV12 frame output через cudaMemcpy2DAsync GPU→host (v1 path, zero-copy в v2)
• CMake install rules для downstream проектов
• Docker runtime image (gx/cuframes:0.1) — publisher + sub_count + libs
• Integration guides:
  • docs/integration.md — общая интеграция с cctv-стeком
  • filter/README.md — FFmpeg patch + smoke test
• Reference deployments:
  • cctv-processor C++ через CuframesSource (см. gx/cctv PR #19, #20)
  • Frigate 0.17.1 через patched FFmpeg (Frigate image rebuild — см. gx/frigate:cuframes)

Tested

• Stress: 1 publisher × 4 consumer × 2000 frames @ 120 fps — 0 torn frames, 0 gaps
• E2E: реальная камера Dahua 192.168.88.98 (1920×1080 HEVC 25 fps) — 100/100 frames, 0 drops, avg_fps=25.03
• Production: 1 publisher обслуживает одновременно Frigate (detect) + cctv-backend (motion+grid+encode→RTSP→TV) на одном NVDEC, ~24h uptime

Limitations (документировано — см. docs/integration.md)

• Только NV12 frame format (v1)
• GPU→CPU copy в FFmpeg demuxer (zero-copy через AVHWFramesContext — v0.2)
• Cross-container CUDA IPC требует ipc + pid namespace share. Если consumer использует s6-overlay (как Frigate) — pid не shareable, нужны альтернативы.
• Только Linux + NVIDIA GPU compute capability ≥ 7.5

[0.0.1] — 2026-05-14

Added

• Initial repository, LICENSE (LGPL-2.1+), README.md, CONTRIBUTING.md
• Design specification (docs/architecture.md)
• Prior art analysis