# Changelog

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

Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
проект следует [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.2.0] — 2026-05-19

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

См. issue [#2](https://git.goldix.org/gx/cuframes/issues/2),
PRs [#4](https://git.goldix.org/gx/cuframes/pulls/4) (cuframes) +
[gx/ffmpeg-patched#1](https://git.goldix.org/gx/ffmpeg-patched/pulls/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](https://git.goldix.org/gx/ffmpeg-patched/pulls/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](https://git.goldix.org/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