pixtreme-transport

pixtreme-transport provides pixtreme.transport, the core of pixtreme's companion for connecting external video streams with px.core.Frame. Protocol and codec modules provide stream I/O, decoding and encoding through separately installed distributions.

One core wheel includes the C++ shared library, public C++ headers, CMake package configuration, nanobind Python bindings and the pixtreme.transport.testing package. The core supplies the common contracts and SDK that modules use.

Install

pip install pixtreme-transport

For a uv project:

uv add pixtreme-transport

The core depends on pixtreme>=1.9, which the package installer resolves automatically. Module developers can install the conformance suite's pytest dependency with the testing extra:

pip install 'pixtreme-transport[testing]'
# Or, in a uv project:
uv add 'pixtreme-transport[testing]'

The testing package is included in the core wheel and shares its version. Ordinary import pixtreme.transport defers native loading and does not import the testing package or pytest.

Supported environments

PyPI wheels support Linux x86_64 with glibc 2.28 or later (manylinux_2_28_x86_64), with separate wheels for CPython 3.12 and 3.13. Runtime use requires an NVIDIA GPU and an NVIDIA driver that supports the CUDA 13 runtime. Native GPU code targets sm 86, sm 89 and sm 120.

PyPI releases contain wheels only; no source distribution is uploaded. Installation on another operating system, CPU architecture or Python version fails with no matching distribution. The package does not provide a CPU-only runtime mode.

Protocol and codec modules

Install only the module distributions needed by your application. Modules use distribution names of the form pixtreme-transport-<module> and import names of the form pixtreme.transport.<module>. Each module documents its supported protocols, codecs and additional dependencies. Installing the core alone does not install protocol or codec modules.

Build a C++ module

Modules that use the core's native API build against the SDK in the installed wheel. Find its CMake package directory with:

import pixtreme.transport

print(pixtreme.transport.get_cmake_dir())

Pass that directory to CMake as pixtreme_transport_DIR. In the module's CMakeLists.txt, discover the package and link its public target:

find_package(pixtreme_transport CONFIG REQUIRED)
target_link_libraries(your_module PRIVATE pixtreme::transport)

The CMake package version is the distribution's X.Y.Z; an optional requested version sets a lower bound. Keep the core library's location in the module's installed RPATH using a path relative to $ORIGIN. Do not copy the core library into the module's wheel.

Include <pixtreme/transport/abi.h> and call pixtreme::transport::require_abi() after the core shared library loads and before any other core operation. The default argument records the module's build header ABI version. A mismatch with the loaded library throws std::runtime_error with both versions.

Development

The repository has a standalone C++ project in cpp/ and a Python project in python/. Source builds require Python 3.12+, a C++20 compiler and the CUDA 13 toolkit. Install CMake 3.31+ and Ninja on PATH, for example with uv tool install 'cmake>=3.31' and uv tool install ninja. From python/, run uv sync, uv build, uv run ruff check and uv run mypy. Run headless tests with CUDA_VISIBLE_DEVICES="" uv run pytest; select an explicit device for GPU tests. The development environment is python/.venv, and uv build creates a source archive and a wheel rebuilt from that archive.