Installation¶

From source¶

The following command will build and install spdl Python package.

Note

Make sure to use -v to see the log from the actual build process.

Regular installation

pip install . -v

Development installation

pip install -e . -v

The build process first downloads/builds/installs some third-party dependencies, then it builds SPDL and its binding code.

Build can be customized through the environment variables;

SPDL_USE_CUDA=1: Enable CUDA integration, such as background data transfer.
SPDL_USE_NVCODEC=1: Enable NVIDIA VIDEO CODEC integration, i.e. GPU video decoder and direct CUDA memory placement
SPDL_USE_TRACING=1: Enable Perfetto integration for performance profiling.
SPDL_USE_FFMPEG_VERSION: Specify the version of FFmpeg you want to use to reduce the build time. By default, SPDL compiles against FFmpeg 4, 5, 6 and 7, and pick available one at run time.
SPDL_RELASE_GIL=0: I/O module does not release GIL. This is intended to be used for experimenting with free-threaded Python (3.13+).

See setup.py for the up-to-date available options.

Trouble Shooting¶

If you hit an error like the following, --no-build-isolation can help.

Installing collected packages: ninja, wheel, setuptools, cmake
  Creating /tmp/pip-build-env-1ac3bsc_/overlay/bin
  changing mode of /tmp/pip-build-env-1ac3bsc_/overlay/bin/ninja to 775
  changing mode of /tmp/pip-build-env-1ac3bsc_/overlay/bin/wheel to 775
  changing mode of /tmp/pip-build-env-1ac3bsc_/overlay/bin/cmake to 775
  changing mode of /tmp/pip-build-env-1ac3bsc_/overlay/bin/cpack to 775
  changing mode of /tmp/pip-build-env-1ac3bsc_/overlay/bin/ctest to 775
Successfully installed cmake-3.30.5 ninja-1.11.1.1 setuptools-75.2.0 wheel-0.44.0

...

CMake Error at CMakeLists.txt:3 (project):
  Running

   '/tmp/pip-build-env-xic7ygls/overlay/bin/ninja' '--version'

  failed with:

   no such file or directory

This happens because, somehow cmake command is not pointing the ninja installed by pip.

One workaround is to use --no-build-isolation option. e.g. TMPDIR="${PWD}/build" pip install . -v --no-build-isolation

Requirements¶

Supported OS: Linux, macOS
Build requirements
- C++20 compiler (Tested on GCC 11 and Clang 15)
- CMake, Ninja
- (Optional) CUDA Toolkit
Runtime Requirements and dependencies
- Python 3.10+
- NumPy
- (Optional) PyTorch
- (Optional) Numba
- (Optional) CUDA runtime

Dependencies¶

The libspdl uses the following third party libraries, which are fetched and built automatically during the build process.

{fmt} (MIT)
gflags (BSD-3)
glog (BSD-3)
nanobind (BSD-3) and its dependency robin-map (MIT)
FFmpeg (LGPL †)

Note

† FFmpeg is a dual-licensed software. One can choose LGPL or GPL.

When building libspdl, pre-built LGPL version of FFmpeg library files are downloaded and linked against libspdl. These FFmpeg library files are compiled in a way that no GPL component is used and runtime search path is not hard-coded. Therefore, the resulting libspdl is not obliged to be GPL, and users can (need to) provide own FFmpeg library files.

Users are free to dynamically link GPL or non-distributable version of FFmpeg libraries. However, please note that linking a non-LGPL binary might change the condition for redistribution of your application.

Optional Dependencies¶

Perfetto (Apache 2.0)
CUDA Toolkit †† (CUDA Toolkit EULA) and the following family of libraries covered by the same EULA
- nvJPEG
- NPP
The header files of Video Codec SDK ††

The header files of video codec SDK (nvcuvid.h and cuviddec.h), which are distributed under MIT license, is used when compiling SPDL with hardware video decoder enabled.

Note

†† This software contains source code provided by NVIDIA Corporation.

Building with Free-Threaded Python¶

To build SPDL with Free-Threaded Python, the following manual changes are required. We intend to incorporate these changes in build process, once Python 3.13 and FT-aware nanobind is released.

Add FREE_THREADED to nanobind_add_module. Please refer to the doc.