Installation

From source

To install SPDL, you need uv. Please check out the official documentation for the installation instruction.

The following command will build and install spdl Python package.

uv pip install . -v

Note

Make sure to use -v to see the log from the actual build process. The build front end by defaults hide the log of build process.

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.

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)

• libzip (BSD-3) and its dependency zlib (Zlib)

• 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.

1. Add FREE_THREADED to nanobind_add_module. Please refer to the doc.