cuframes-docs/site/i18n/ru/docusaurus-plugin-content-docs/current/integration/python.md

title, sidebar_position

title	sidebar_position
Python bindings	3

Python bindings

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

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

Что появится в 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. 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/ как стартовую точку.

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

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

Roadmap и заметки по milestone Python-пакета лежат в ROADMAP.md в репо cuframes. v0.5 также гейтится HEVC packet-ring путём и небольшим ABI cleanup'ом, поэтому bindings — не единственное на этом релизе.

См. также

• Установка — поставить libcuframes.so в систему, чтобы bindings'ам было что грузить.
• Protocol reference — поверхность C API, которую bindings зеркалят.
• FFmpeg cuframes:// demuxer — сегодняшний практичный путь чтобы данные cuframes попали в любой не-C consumer.