# cuframes

[![build](https://git.goldix.org/gx/cuframes/actions/workflows/build.yml/badge.svg?branch=main)](https://git.goldix.org/gx/cuframes/actions?workflow=build.yml)
[![release](https://img.shields.io/badge/release-v0.1.0-blue)](https://git.goldix.org/gx/cuframes/releases/tag/v0.1.0)
[![license](https://img.shields.io/badge/license-LGPL--2.1+-green)](LICENSE)

Zero-copy sharing декодированных видеокадров между процессами через CUDA IPC.

**Статус:** v0.1.0 released — production-deployed на multi-camera CCTV-стeке
(Frigate + custom C++ processor, оба используют один publisher на одном NVDEC).
См. [BENCHMARKS.md](BENCHMARKS.md) для measurements, [ROADMAP.md](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](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

```bash
# 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/integration.md).

## Документация

- [docs/architecture.md](docs/architecture.md) — полный design document
- [docs/protocol.md](docs/protocol.md) — bit-exact wire protocol spec
- [docs/requirements.md](docs/requirements.md) — system requirements (hardware, software, build, Docker, k8s)
- [docs/integration.md](docs/integration.md) — **integration guide** для CCTV-стека (cuframes-rtsp-source + cctv-processor + Frigate)
- [docs/benchmarks-phase0.md](docs/benchmarks-phase0.md) — Phase 0 latency/throughput measurements

## Why

Подтверждённый спрос в Frigate community ([#17033](https://github.com/blakeblackshear/frigate/discussions/17033),
[#20191](https://github.com/blakeblackshear/frigate/discussions/20191), [#21559](https://github.com/blakeblackshear/frigate/discussions/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](docs/architecture.md)
и [CONTRIBUTING.md](CONTRIBUTING.md).