webp-decoder-gpu

This standalone pybind extension prepares lossy WebP images for VP8 hardware decoding using torchcodec with a GPU (NVDEC) backend:

1. Strictly parse a lossy WebP RIFF file and extract its VP8 payload.
2. Build an in-memory IVF stream from same-resolution VP8 key frames.

This is needed because torchcodec uses CPU backend for webp decoding by default and VP8 still requires a container to be processed. A change in torchcodec is required to avoid the IVF step.

This tool atm deliberately rejects VP8L, embedded alpha, animation, malformed RIFF chunks, non-key frames, and mixed frame dimensions.

API

import webp_decoder_gpu

payload, width, height = webp_decoder_gpu.extract_vp8(webp_bytes)

ivf_bytes = webp_decoder_gpu.build_ivf(
    vp8_payloads,
    width,
    height,
    rate=25,
    scale=1,
)

# Convenience path that performs both operations without exposing the
# intermediate payloads to Python:
ivf_bytes = webp_decoder_gpu.webp_batch_to_ivf(
    webp_byte_list,
    rate=25,
    scale=1,
)

All inputs may be any contiguous bytes-like object. Outputs are Python bytes, ready to pass to torchcodec.decoders.VideoDecoder.

Install

From this repository:

python3 -m pip install -e .

The core extension depends only on pybind11 at build time. Torch, TorchCodec, Matplotlib, FFmpeg, CUDA, NVDEC, and the libwebp development library are required only for the example notebook and benchmark.

Test

After installing the package:

python3 -m unittest tests/test_vp8_ivf.py -v

The TorchCodec example notebook uses tests/assets/cat_wallpaper.webp and requires a CUDA GPU with NVDEC. It decodes the image through TorchCodec/NVDEC, displays the result inline, compares it with a native extension that calls libwebp directly, and preserves the structural, maximum-error, mean-error, and PSNR assertions from the original integration test.

python3 -m pip install -e '.[example]'
jupyter lab examples/test_torchcodec_decode.ipynb

To compare accuracy against direct libwebp calls and measure both paths:

python3 tests/benchmark_cat_decode.py