python-decoders-benchmarks

A place where one can get guidance on which Python video decoder is best suited for their project based on performance benchmarks.

All benchmarks standardize on numpy arrays in RGB24 (C, H, W) format as the final output. Performance measurements include any necessary color space conversions (e.g., BGR→RGB for OpenCV) to ensure fair comparison across all libraries.

Overview

This project benchmarks the performance (Frames Per Second - FPS) of various Python libraries used for video decoding. The goal is to provide developers with data to make informed decisions when choosing a video decoding backend for their applications.

Features

• Benchmarks multiple popular Python video decoding libraries:
  • PyAV
  • OpenCV (via opencv-python)
  • FFmpeg (via subprocess)
  • ImageIO-FFmpeg
  • FFmpegCV (with block and no-block)
  • Decord ( not recommended due to OOM Issues)
  • TorchAudio ( requires FFMPEG v6, I can't test it. )
  • DeffCode
  • Video-Reader-RS ( Base run uses pure rgb24 decode afaik whilst the "YuvToRGB" run decodes in yuv420p and then converts it to rgb24 on the rust side to speed things up, altho' I am not entirely sure how this would hold up if the input was in other color formats say yuv422, yuv444 or rgb48 )
  • FFmpeg-Python ( Altho' in theory it serves the same purpose as the ffmpeg-subprocess run, I still decided to add it to see if it adds any extra overhead over your run of the mill ffmpeg subprocess pipe )
  • Nelux ( formerly CeLux. A high-performance decoder that uses the latest FFmpeg features and PyTorch for async decoding. Wheels published via GitHub releases. )

Benchmark Results Example

(Results generated by the benchmark script. Actual performance will vary based on your system hardware and the video file.)

Methodology

Each decoder runs 1 untimed warmup pass followed by 3 timed passes. The warmup primes OS page cache and any lazy initialization inside the library (codec context, JIT, GPU upload paths). Timing uses time.perf_counter() measured from the start of the per-frame loop until the last frame is yielded. The reported headline FPS is the median across timed runs; the JSON output also carries fpsMean, fpsStd, fpsMin, fpsMax, and the coefficient of variation (fpsCv).

Override defaults with --runs N --warmup N --cooling SECS.

Performance history

Each successful run is appended to history/{resolution}_history.json together with the runner identifier (RUNNER_NAME / hostname), git commit, OS, Python version and full per-decoder summary. The trend chart history/{resolution}_trend.png is regenerated from that file after every run; series are split per runner so results from different hardware are never plotted on the same axis.

Installation

1. Clone the repository:

   git clone https://github.com/NevermindNilas/python-decoders-benchmarks.git
   cd python-decoders-benchmarks

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Install dependencies:

   pip install -r requirements.txt

   Note: Ensure you have FFmpeg installed and accessible in your system's PATH, as several backends depend on it.

Usage

Run the main benchmark script (main.py) from the root directory:

python main.py

Contributing

Contributions are welcome! If you want to add another decoder, improve the benchmarking methodology, or fix a bug, please feel free to open an issue or submit a pull request.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Plans

• Add 1080p benchmarks