Metadata-Version: 2.4
Name: pixtreme-transport
Version: 0.16.9
Summary: Core and C++ module SDK connecting external video streams with pixtreme frames
Author-Email: minamik <mia@sync.dev>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: GPU :: NVIDIA CUDA :: 13
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries
Project-URL: repository, https://github.com/sync-dev-org/pixtreme-transport
Project-URL: issues, https://github.com/sync-dev-org/pixtreme-transport/issues
Requires-Python: >=3.12
Requires-Dist: pixtreme>=1.9
Provides-Extra: testing
Requires-Dist: pytest>=8.3.5; extra == "testing"
Description-Content-Type: text/markdown

# 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

```bash
pip install pixtreme-transport
```

For a uv project:

```bash
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:

```bash
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:

```python
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:

```cmake
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.
