---
title: Python bindings
sidebar_position: 3
---

# Python bindings

**Статус: запланировано на v0.5+. Ещё не поставляется.**

Эта страница — placeholder, чтобы integration story честно говорила, что есть, а чего нет. Если Python-доступ к cuframes нужен сегодня, читай [Workaround для v0.4](#workaround-для-v04) ниже.

## Что появится в v0.5+

Небольшой Python-пакет `cuframes`, распространяемый как wheel, который даёт:

- **`ctypes`-bindings** поверх существующего C API (`cuframes_publisher_create`, `cuframes_subscriber_create`, `cuframes_acquire`, `cuframes_release` и т. д.). Никакого нового ABI, ни SWIG, ни C++-обёртки.
- **Zero-copy доступ к NumPy / PyTorch** к decoded NV12 surface через [CUDA Array Interface](https://numba.readthedocs.io/en/stable/cuda/cuda_array_interface.html). Subscribed frame экспонируется как CuPy / PyTorch tensor, указывающий на ту же GPU-память что писал publisher — никакого `cudaMemcpy` на host и никакой копии на девайсе.
- **Context-manager API** для acquire / release, чтобы frame-слоты не текли при исключениях.

Целевые use case'ы:

- **PyTorch inference на shared frames** — детектор / классификатор подписывается на `cuframes://camN`, получает tensor, запускает `model(tensor)` напрямую. Сегодня это требует либо re-decode RTSP-stream'а, либо копирования frame'ов через Unix pipe.
- **OpenCV CUDA processing** — `cv2.cuda_GpuMat` строится из cuframes-pointer'а, после чего любая cv2.cuda-операция (resize, color convert, optical flow) выполняется in place.
- **Быстрое прототипирование** — Jupyter-ноутбук, который подписывается на живую камеру, вырезает region of interest и визуализирует его без поднятия полного FFmpeg pipeline'а.

CPU-side NumPy fallback добавлять не планируется. Frame'ы — это GPU surfaces; если нужны на CPU — делай явный `tensor.cpu()` и принимай копирование.

## Workaround для v0.4

Пока bindings'ов нет, поддерживаемый путь — звать `libcuframes.so` напрямую из Python через `ctypes` или `cffi`. C API маленький (≈ 10 функций) и стабилен внутри v0.x релиза.

Реалистично говоря, большинство v0.4-deployment'ов не зовут cuframes из Python вообще. Они используют существующий C / FFmpeg-путь:

- Для inference: подписаться на **packet** ring через `ffmpeg -f cuframes_packets -i cuframes_packets://camN` и пайпить decoded frame'ы в твой Python-процесс. Zero-copy теряется, но pipeline сегодня рабочий.
- Для прототипирования: брать C-примеры в [`examples/`](https://git.goldix.org/gx/cuframes) как стартовую точку.

Если zero-copy путь на Python нужен *прямо сейчас*, придётся писать `ctypes`-обёртки самому. Зеркаль прототипы из [`include/cuframes/cuframes.h`](/docs/reference/protocol), держи handle'ы opaque (`void *`), используй `cuMemAlloc` / CuPy `UnownedMemory` чтобы view'ить импортированную VMM-allocation. Жди шероховатостей — bindings v0.5 существуют именно потому, что руками это удовольствие сомнительное.

## Отслеживать прогресс

Roadmap и заметки по milestone Python-пакета лежат в [`ROADMAP.md`](https://git.goldix.org/gx/cuframes) в репо cuframes. v0.5 также гейтится HEVC packet-ring путём и небольшим ABI cleanup'ом, поэтому bindings — не единственное на этом релизе.

## См. также

- [Установка](/docs/getting-started/install) — поставить `libcuframes.so` в систему, чтобы bindings'ам было что грузить.
- [Protocol reference](/docs/reference/protocol) — поверхность C API, которую bindings зеркалят.
- [FFmpeg `cuframes://` demuxer](/docs/integration/ffmpeg-demuxer) — сегодняшний практичный путь чтобы данные cuframes попали в любой не-C consumer.