spdl.io.NvDecDecoder¶

class NvDecDecoder¶

Decodes video packets using NVDEC hardware acceleration.

Use nvdec_decoder() to instantiate.

This decoder supports two decoding workflows:

Batch decoding - Decode all packets at once:

decoder = spdl.io.nvdec_decoder(cuda_config, codec)
nv12_buffer = decoder.decode_packets(packets)
rgb = spdl.io.nv12_to_rgb(nv12_buffer, cuda_config)
# Buffer shape: [num_frames, height*1.5, width]

Streaming decoding - Process packets incrementally with batched output:

decoder = spdl.io.nvdec_decoder(cuda_config, codec)
decoder.init_buffer(num_frames)  # Initialize frame buffer

for packets in packet_stream:
    for batch in decoder.streaming_decode_packets(packets):
        # batch is CUDABuffer with shape [num_frames, h*1.5, w]
        rgb = spdl.io.nv12_to_rgb(batch, cuda_config)
        # Process rgb frames

# Flush and get remaining frames
for batch in decoder.flush():
    rgb = spdl.io.nv12_to_rgb(batch, cuda_config)
    # Process final frames

Note

To decode H264 and HEVC videos, packets must be in Annex B format. Use apply_bsf() to convert:

if codec.name in ("h264", "hevc"):
    packets = spdl.io.apply_bsf(packets, f"{codec.name}_mp4toannexb")

See also

decode_packets_nvdec(): Decode video packets using NVDEC
streaming_load_video_nvdec(): Decode video frames in streaming fashion
streaming_nvdec_decoding: Tutorial for streaming video decode

Attributes

`decode_packets`	Decode all packets and return NV12 buffer.
`flush`	Flush the decoder and yield remaining batches.
`init_buffer`	Initialize frame buffer for streaming decode.
`init_decoder`	Initialize the decoder.
`streaming_decode_packets`	Streaming decode packets and yield batches.

decode_packets¶

Decode all packets and return NV12 buffer.

This method decodes all packets and flushes the decoder in one operation, and returns the resulting frames as one contiguous memory buffer.

Parameters:: packets – Video packets to decode.
Returns:: A CUDABuffer containing NV12 frames with shape [num_frames, h*1.5, width], where num_frames reflects the actual number of decoded frames, which should match the number of packets.

flush¶

Flush the decoder and yield remaining batches.

Call this method at the end of video stream to flush the decoder and retrieve any remaining buffered frames as batches.

Returns:: Iterator that yields remaining CUDABuffer batches in NV12 format.

init_buffer¶

Initialize frame buffer for streaming decode.

This must be called before using streaming_decode_packets() for streaming decode.

Parameters:: num_frames – The number of frames per batch.

init_decoder¶

Initialize the decoder.

Changed in version 0.2.0: This method was renamed from init().

Deprecated since version 0.1.7: This method was merged with nvdec_decoder(). Pass these parameters directly to initialize the decoder. The old pattern of calling decoder.init() after nvdec_decoder() will be removed in a future version.

Note

Creation of underlying decoder object is expensive. Typically, it takes about 300ms or more.

To mitigate this the implementation tries to reuse the decoder. This works if the new video uses the same codecs as the previous one, and the difference is limited to the resolution of the video.

If you are processing videos of different codecs, then the decoder has to be re-created.

Parameters:

cuda_config – The device configuration. Specifies the GPU of which video decoder chip is used, the CUDA memory allocator and CUDA stream used to fetch the result from the decoder engine.
codec – The information of the source video.
crop_left (int) – Optional: Crop the given number of pixels from each side.
crop_top (int) – Optional: Crop the given number of pixels from each side.
crop_right (int) – Optional: Crop the given number of pixels from each side.
crop_bottom (int) – Optional: Crop the given number of pixels from each side.
scale_width (int) – Optional: Resize the frame. Resizing is applied after cropping.
scale_height (int) – Optional: Resize the frame. Resizing is applied after cropping.

streaming_decode_packets¶

Streaming decode packets and yield batches.

This method decodes packets and yields batches of frames as they become ready. The frame buffer must be initialized with init_buffer() before calling this.

Parameters:: packets – Video packets to decode.
Returns:: Iterator that yields CUDABuffer batches in NV12 format.