nvidia-deepstream-videodecode-cu13

This project is currently not accepting contributions.

GPU-resident video decode via NVIDIA DeepStream — single-wheel install that bundles the DS shared libraries in a flat _libs/ directory and configures GStreamer + libv4l plugin discovery on Python import.

Install

apt update
apt install gstreamer1.0-tools gstreamer1.0-plugins-{base,good,bad,ugly} \
            gstreamer1.0-libav python3-gi python3-gst-1.0 libv4l-0

pip install nvidia-deepstream-videodecode-cu13

Quickstart

# Built-in selftest — verifies lib resolution, plugin discovery, CUDA context.
deepstream-videodecode-selftest

# Decode a file
python3 examples/decode_example.py /path/to/video.mp4

# File + live RTSP source
python3 examples/decode_example.py /path/to/video.mp4 \
    --rtsp rtsp://10.24.217.130:8554/ --workers 4 --frames 16

Successful output ends with frames shape : (N, H, W, 3) on torch.uint8, cuda:0 — the GPU tensor is ready for downstream consumers with no D2H copy.

Public API

from nvidia.deepstream_videodecode import (
    DecodePool,        # pool of N file-decode pipelines on N threads
    StreamHandle,      # one persistent pipeline for an RTSP/URI stream
    DecodeFrames,      # @dataclass: frames, n_kept, n_total, fps, error
    probe_metadata,    # GStreamer-only metadata probe (no decode, no PyAV)
    lib_dir,           # path to the bundled _libs/ directory
)

probe_metadata(data) -> (frame_count, fps, duration_sec, width, height, codec)

Read container metadata from raw bytes using GStreamer only — no frames are decoded, no external library (PyAV / libmediainfo) needed.

DecodePool.decode(data, *, target_indices, codec="", max_frames, timeout_sec) -> DecodeFrames

Decode raw container bytes on a pool worker and keep the frames whose decode-order index is in target_indices.

from nvidia.deepstream_videodecode import DecodePool, probe_metadata

pool = DecodePool(num_workers=8)
data = open("/path/to/video.mp4", "rb").read()

fc, fps, dur, w, h, codec = probe_metadata(data)
import numpy as np
indices = np.linspace(0, fc - 1, 8, dtype=int).tolist()

out = pool.decode(data, target_indices=indices, codec=codec,
                  max_frames=len(indices))
# out.frames: CUDA tensor (out.n_kept, H, W, 3) uint8 — no D2H copy.

What ships in the wheel

nvidia/
└── deepstream_videodecode/
    ├── __init__.py
    ├── _ds_dec.py        # DecodePool / StreamHandle API
    ├── _runtime.py       # _libs/ path resolver
    ├── _selftest.py      # deepstream-videodecode-selftest CLI
    ├── _version.py
    └── _libs/                           # flat layout
        ├── libnvbufsurface.so
        ├── libnvbufsurftransform.so     (~26 MB)
        ├── libnvbuf_fdmap.so
        ├── libnvds_meta.so
        ├── libnvdsbufferpool.so
        ├── libnvdsgst_helper.so
        ├── libnvdsgst_meta.so
        ├── libgstnvdsseimeta.so
        ├── libgstnvcustomhelper.so
        ├── libnvv4l2.so
        ├── libcuvidv4l2.so
        ├── libv4l2.so.0                 (symlink → libnvv4l2.so)
        ├── libgstnvvideo4linux2.so      (GStreamer plugin)
        ├── libgstnvvideoconvert.so      (GStreamer plugin)
        └── v4l_plugins/
            └── libcuvidv4l2_plugin.so   (libv4l plugin)

Troubleshooting

GStreamer element creation failed: ['nvdec', 'nvvconv']

GStreamer caches a plugin registry at ~/.cache/gstreamer-1.0/. If the cache was built before the CUDA libraries were installed, it records "this plugin failed to load" and never retries.

rm -rf ~/.cache/gstreamer-1.0/
python3 -c "import nvidia.deepstream_videodecode"   # forces rescan
gst-inspect-1.0 nvv4l2decoder                       # should now print Factory Details

libnppig.so.13: cannot open shared object file

CUDA NPP runtime is missing:

apt install -y --no-install-recommends cuda-libraries-13-0

deepstream-videodecode-selftest says "DeepStream libs not found"

The _libs/ directory is empty or missing. Reinstall:

pip install --force-reinstall --no-deps nvidia-deepstream-videodecode-cu13

Opening in BLOCKING MODE printed during decode

Informational message from nvv4l2decoder — not an error. Silence with:

GST_DEBUG=2 python3 your_script.py

dlsym failed: libcuvidv4l2.so: undefined symbol: libv4l2_plugin

You're on an old wheel that placed libcuvidv4l2_plugin.so alongside the main libs. Current builds isolate it in v4l_plugins/. Reinstall:

pip install --force-reinstall nvidia-deepstream-videodecode-cu13