API Reference

Complete API documentation for the on_demand_video_decoder package.

class accvlab.on_demand_video_decoder.PyNvGopDecoder(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, maxfiles: int, iGpu: int = 0, suppressNoColorRangeWarning: bool = False)

Bases: pybind11_object

Initialize decoder with set of particular parameters.

Parameters:

maxfiles – Maximum number of unique files that can be processed concurrently
iGpu – GPU device ID to use for decoding (0 for primary GPU)
suppressNoColorRangeWarning – Suppress warning when no color range can be extracted from video files (limited/MPEG range is assumed)

Raises:

RuntimeError – If GPU initialization fails or parameters are invalid

Decode(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, filepaths: List[str], frame_ids: List[int], fastStreamInfos: List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo] = []) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt]

Decodes video file stream into uncompressed YUV data.

This method performs GPU-accelerated decoding of video frames using NVIDIA hardware. It supports multiple video files and can decode specific frame IDs from each file. The method uses GOP-based decoding for efficient random access.

Parameters:

filepaths – List of video file paths to decode from. All files must be accessible and contain valid video streams.
frame_ids – List of frame IDs to decode. Each frame ID corresponds to a specific frame in the video sequence.
fastStreamInfos – Optional list of FastStreamInfo objects containing pre-extracted stream information by GetFastInitInfo(). If provided, this can improve performance by avoiding stream analysis.

Returns:

List of DecodedFrameExt objects containing the decoded frame data. Each frame includes YUV pixel data, metadata, and timing information.

Raises:

RuntimeError – If video files cannot be opened or decoded
ValueError – If frame_ids contain invalid indices

Example

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> frames = decoder.Decode(['video1.mp4', 'video2.mp4'], [0, 10])
>>> print(f"Decoded {len(frames)} frames")

DecodeFromGOP(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, numpy_data: numpy.ndarray[numpy.uint8], filepaths: List[str], frame_ids: List[int]) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt]

Decodes video GOP data into YUV frames without demuxing again.

This method decodes previously extracted GOP data into YUV frames. It’s useful for scenarios where you want to separate GOP extraction from decoding, or when you have pre-extracted GOP data.

Parameters:

numpy_data – Numpy array containing serialized GOP data from GetGOP()
filepaths – List of video file paths (for metadata purposes)
frame_ids – List of frame IDs to decode from the GOP data

Returns:

List of DecodedFrameExt objects containing the decoded YUV frame data

Raises:

RuntimeError – If GOP data is invalid or decoding fails
ValueError – If frame_ids don’t match the GOP data

Example

>>> gop_data, first_ids, gop_lens = decoder.GetGOP(['video.mp4', 'video2.mp4'], [0, 10])
>>> frames = decoder.DecodeFromGOP(gop_data, ['video.mp4', 'video2.mp4'], [0, 10])

DecodeFromGOPListRGB(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, numpy_datas: List[numpy.ndarray[numpy.uint8]], filepaths: List[str], frame_ids: List[int], as_bgr: bool = False) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Decodes multiple serialized GOP bundles into RGB/BGR frames.

This method parses each bundle, reconstructs per-frame packet queues, and decodes via a unified pipeline. Useful for processing multiple GOP bundles simultaneously.

Parameters:

numpy_datas – List of numpy arrays, each containing a SerializedPacketBundle from GetGOP()
filepaths – List of source file paths for each requested frame (aggregated)
frame_ids – List of target frame IDs (aggregated across all bundles)
as_bgr – Whether to output in BGR format (True) or RGB format (False)

Returns:

List of decoded RGB/BGR frames

Raises:

RuntimeError – If GOP data is invalid or decoding fails
ValueError – If input arrays have mismatched dimensions

Example

Ref to Sample: samples/SampleSeparationAccessGOPListAPI.py

Note

The method parses each bundle, reconstructs per-frame packet queues, and decodes via a unified pipeline.

DecodeFromGOPRGB(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, numpy_data: numpy.ndarray[numpy.uint8], filepaths: List[str], frame_ids: List[int], as_bgr: bool = False) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Decodes video GOP data into RGB frames without demuxing again.

This method decodes previously extracted GOP data into RGB/BGR frames. It’s useful for scenarios where you want to separate GOP extraction from decoding and need RGB output.

Parameters:

numpy_data – Numpy array containing serialized GOP data from GetGOP()
filepaths – List of video file paths (for metadata purposes)
frame_ids – List of frame IDs to decode from the GOP data
as_bgr – Whether to output in BGR format (True) or RGB format (False)

Returns:

List of RGBFrame objects containing the decoded and color-converted frame data

Raises:

RuntimeError – If GOP data is invalid or decoding fails
ValueError – If frame_ids don’t match the GOP data

Example

Ref to Sample: samples/SampleSeparationAccess.py

>>> gop_data, first_ids, gop_lens = decoder.GetGOP(['video.mp4', 'video2.mp4'], [0, 10])
>>> rgb_frames = decoder.DecodeFromGOPRGB(gop_data, ['video.mp4', 'video2.mp4'], [0, 10], as_bgr=True)

DecodeFromPacketListInitialize(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, codec_ids: List[int]) → int

Initializes NvDecoder instances for video files.

This method creates NvDecoder instances for each video file, preparing them for efficient decoding operations. It is used before DecodeFromPacketListRGB().

Parameters:

codec_ids – List of video codec IDs from ParseSerializedPacketBundle()

Returns:

0 if initialization successful

Raises:

RuntimeError – If any parameters are invalid or initialization fails
ValueError – If codec_ids is empty

Example

Ref to Sample: samples/SampleDecodeFromBinaryData.py

DecodeFromPacketListRGB(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, numpy_datas: List[List[numpy.ndarray[numpy.uint8]]], packet_idxs: List[List[int]], widths: List[int], heights: List[int], frame_ids: List[int], as_bgr: bool = False) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Decodes video packets into RGB frames using separate packet data arrays (V2 interface).

This advanced interface allows direct control over packet data by providing separate numpy arrays for each frame’s binary data even from other demuxer lib, enabling more flexible packet management and processing.

Parameters:

numpy_datas – List of lists of numpy arrays containing binary packet data for each frame. Each inner list contains numpy arrays for packets of one frame. The function automatically extracts packet sizes and data pointers from these arrays.
packet_idxs – List of lists containing decode indices for each frame
widths – List of frame widths for each frame
heights – List of frame heights for each frame
frame_ids – List of frame IDs to decode
as_bgr – Whether to output in BGR format (True) or RGB format (False)

Returns:

List of decoded RGB/BGR frames

Raises:

RuntimeError – If packet data is invalid or decoding fails
ValueError – If input arrays have mismatched dimensions

Example

Ref to Sample: samples/SampleDecodeFromBinaryData.py

Note

This interface allows direct control over packet data by providing separate numpy arrays for each frame’s binary data. The function automatically extracts packet sizes and data pointers from the numpy arrays, enabling more flexible packet management and processing.

DecodeN12ToRGB(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, filepaths: List[str], frame_ids: List[int], as_bgr: bool = False, fastStreamInfos: List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo] = []) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Decodes video file stream into uncompressed RGB/BGR data.

This method performs GPU-accelerated decoding and color space conversion from YUV to RGB/BGR format. It’s optimized for machine learning applications that require RGB input data.

Parameters:

filepaths – List of video file paths to decode from
frame_ids – List of frame IDs to decode from the video files
as_bgr – Whether to output in BGR format (True) or RGB format (False). BGR is commonly used in OpenCV applications.
fastStreamInfos – Optional list of FastStreamInfo objects containing pre-extracted stream information by GetFastInitInfo(). If provided, this can improve performance by avoiding stream analysis.

Returns:

List of RGBFrame objects containing the decoded and color-converted frame data. Each frame includes RGB/BGR pixel data and metadata.

Raises:

RuntimeError – If video files cannot be opened or decoded
ValueError – If frame_ids contain invalid indices

Example

Ref to Sample: samples/SampleRandomAccess.py and samples/SampleRandomAccessWithFastInit.py

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> rgb_frames = decoder.DecodeN12ToRGB(['video.mp4', 'video2.mp4'], [0, 10], as_bgr=True)
>>> print(f"Decoded {len(rgb_frames)} RGB frames")

GetGOP(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, filepaths: List[str], frame_ids: List[int], fastStreamInfos: List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo] = []) → tuple

Extracts video GOP data without performing the decode step.

This method extracts video GOP (Group of Pictures) data from the specified frames and returns them in a self-contained binary format. The GOP data can be decoded later using DecodeFromPacketListRGB() method, enabling separation of demuxing and decoding.

Parameters:

filepaths – List of video file paths to extract GOP data from
frame_ids – List of frame IDs to extract GOP data for
fastStreamInfos – Optional list of FastStreamInfo objects containing pre-extracted stream information by GetFastInitInfo(). If provided, this can improve performance by avoiding stream analysis.

Returns:

Tuple containing

numpy array with serialized GOP data
list of first frame IDs for each GOP
list of GOP lengths for each GOP

The numpy array contains a self-contained binary format with embedded frame offset table:

Header: total_frames (uint32_t) + frame_offsets array (size_t[total_frames])
Frame data blocks follow the header
Parse the header once to get direct access to any frame
Enables efficient random access and parallel processing
No external metadata files needed

Raises:: RuntimeError – If video files cannot be opened or GOP extraction fails

Example

Ref to Sample: samples/SampleSeparationAccess.py

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> gop_data, first_ids, gop_lens = decoder.GetGOP(['video.mp4', 'video2.mp4'], [0, 10])
>>> print(f"Extracted GOP data for {len(first_ids)} GOPs")

GetGOPList(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, filepaths: List[str], frame_ids: List[int], fastStreamInfos: List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo] = []) → list

Extracts video GOP data for multiple videos and returns them as separate bundles.

This method is similar to GetGOP() but returns a separate bundle for each video file instead of merging all data into one bundle. This is useful when you want to cache or process each video’s data independently.

Parameters:

filepaths – List of video file paths to extract GOP data from
frame_ids – List of frame IDs to extract GOP data for (one per video)
fastStreamInfos – Optional list of FastStreamInfo objects containing pre-extracted stream information by GetFastInitInfo(). If provided, this can improve performance by avoiding stream analysis.

Returns:

List of tuples, one per video file, each containing

numpy array with serialized GOP data for that video
list of first frame IDs for each GOP in that video
list of GOP lengths for each GOP in that video

Each numpy array contains a self-contained binary format with embedded frame offset table:

Header: total_frames (uint32_t) + frame_offsets array (size_t[total_frames])
Frame data blocks follow the header
Parse the header once to get direct access to any frame
Enables efficient random access and parallel processing
No external metadata files needed

Raises:: RuntimeError – If video files cannot be opened or GOP extraction fails

Example

Ref to Sample: samples/SampleSeparationAccessGOPListAPI.py

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> results = decoder.GetGOPList(
...     ['video1.mp4', 'video2.mp4'],
...     [0, 10]
... )
>>> for i, (gop_data, first_ids, gop_lens) in enumerate(results):
...     print(f"Video {i}: GOP data size = {len(gop_data)}")
...     print(f"  First frame IDs: {first_ids}")
...     print(f"  GOP lengths: {gop_lens}")

LoadGops(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, file_paths: List[str]) → numpy.ndarray[numpy.uint8]

Merges multiple binary packet files into a single numpy array.

This method merges multiple binary packet files into a single contiguous numpy array for efficient processing.

Parameters:

file_paths – List of file paths to binary packet files

Returns:

Numpy array containing merged packet data compatible with decode_from_packet

Raises:

RuntimeError – If files cannot be read or merged
ValueError – If file_paths is empty

Example

Ref to Sample: samples/SampleDecodeFromGopFiles.py

LoadGopsToList(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, file_paths: List[str]) → list

Load GOP data from multiple binary files and return as a list of numpy arrays.

This method loads serialized GOP bundles from binary files (previously saved with SavePacketsToFile()) and returns them as separate numpy arrays, one per file. This is the companion function to GetGOPList(), enabling distributed GOP caching and selective loading workflows.

Key Differences from LoadGops():

LoadGops(): Merges all files into ONE numpy array (for use with DecodeFromGOPRGB())
LoadGopsToList(): Returns separate numpy arrays (for use with DecodeFromGOPListRGB())

Parameters:

file_paths – List of paths to GOP binary files to load

Returns:

List of numpy arrays, each containing the GOP data from one file. Each numpy array has the same format as returned by GetGOP/GetGOPList.

Raises:

RuntimeError – If any file cannot be read or has invalid format
ValueError – If file_paths is empty or files have invalid GOP format

Example

Ref to Sample: samples/SampleSeparationAccessGOPToListAPI.py

>>> # Workflow 1: Save GOP data to separate files (from GetGOPList)
>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> gop_list = decoder.GetGOPList(['v1.mp4', 'v2.mp4'], [0, 10])
>>> for i, (gop_data, _, _) in enumerate(gop_list):
...     SavePacketsToFile(gop_data, f'gop_{i}.bin')

>>> # Workflow 2: Load GOP data back and decode
>>> loaded_gop_list = decoder.LoadGopList(['gop_0.bin', 'gop_1.bin'])
>>> frames = decoder.DecodeFromGOPListRGB(
...     loaded_gop_list,
...     ['v1.mp4', 'v2.mp4'],
...     [0, 10],
...     as_bgr=True
... )

>>> # Workflow 3: Selective loading (only load needed videos)
>>> # Only load video 1's GOP data
>>> loaded_gop = decoder.LoadGopList(['gop_1.bin'])
>>> frames = decoder.DecodeFromGOPListRGB(
...     loaded_gop,
...     ['v2.mp4'],
...     [10],
...     as_bgr=True
... )

MergePacketDataToOne(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, packet_data_arrays: List[numpy.ndarray[numpy.uint8]]) → numpy.ndarray[numpy.uint8]

Merges multiple packet data arrays into a single numpy array.

This method takes multiple numpy arrays containing SerializedPacketBundle data and merges them into a single contiguous numpy array. This is useful for combining packet data from different sources or files into one unified data structure for processing.

Parameters:

packet_data_arrays – List of numpy arrays, each containing SerializedPacketBundle data

Returns:

Numpy array containing merged packet data

Raises:

RuntimeError – If arrays cannot be merged
ValueError – If packet_data_arrays is empty

Note

This method is designed to work efficiently with large datasets and uses parallel processing for optimal performance.

ParseSerializedPacketBundle(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder, numpy_data: numpy.ndarray[numpy.uint8]) → tuple

Parses a SerializedPacketBundle and extracts parameters for DecodeFromPacketListRGB().

This method takes serialized packet data and extracts all the necessary parameters required for the DecodeFromPacketListRGB() interface, including creating numpy arrays for the packet binary data. You can use this method to get the parameters from GetGOP().

Parameters:

numpy_data – Numpy array containing serialized packet data from GetGOP()

Returns:

Tuple containing

color_ranges: List of color ranges for each frame
codec_ids: List of codec IDs for each frame
widths: List of frame widths for each frame
heights: List of frame heights for each frame
frame_sizes: List of frame sizes for each frame
gop_lens: List of GOP lengths for each frame
first_frame_ids: List of first frame IDs for each GOP
packet_binary_data_arrays: List of numpy arrays containing binary packet data for each frame
packet_binary_data_sizes: List of sizes of the packet binary data for each frame
packets_bytes: List of lists containing packet sizes for each frame
decode_idxs: List of lists containing decode indices for each frame

Raises:

RuntimeError – If packet data is invalid or parsing fails

Example

Ref to Sample: samples/SampleDecodeFromBinaryData.py

release_decoder(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder) → None

Release all decoder instances to free up GPU memory.

This method clears all decoder instances, which releases NvDecoder instances and their GPU frame buffers

This is useful for freeing GPU memory occupied by decoder instances.

Note: After calling this method, decoder instances will need to be re-created on the next decode operation.

Example

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> frames = decoder.Decode(['video1.mp4'], [0, 10, 20])
>>> decoder.release_decoder()  # Free decoder instances

release_device_memory(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvGopDecoder) → None

Release GPU device memory pool to free up GPU memory.

This method releases the GPU memory pool and resets the pool state. This is useful for temporarily freeing excessive GPU memory usage.

Note: After calling this method, the memory pool will need to be re-allocated on the next decode operation.

Example

>>> decoder = PyNvGopDecoder(maxfiles=10)
>>> frames = decoder.Decode(['video1.mp4'], [0, 10, 20])
>>> decoder.release_device_memory()  # Free GPU memory pool

class accvlab.on_demand_video_decoder.PyNvSampleReader(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader, num_of_set: int, num_of_file: int, iGpu: int = 0, suppressNoColorRangeWarning: bool = False)

Bases: pybind11_object

NVIDIA GPU-accelerated sample reader for multi-file video processing.

This class provides high-performance video reading capabilities using NVIDIA hardware acceleration for multiple video files with multiple readers per file. It’s designed for scenarios requiring high-throughput processing of multiple video streams simultaneously.

Key Features:

GPU-accelerated decoding using NVIDIA hardware
Multiple video readers per file for parallel processing
Multi-file support with configurable reader pools
RGB and YUV output formats
Resource management with explicit cleanup
Optimized for high-throughput batch processing

Initialize sample reader with set of particular parameters.

Parameters:

num_of_set – Number of video readers per file for parallel processing
num_of_file – Number of files to handle simultaneously
iGpu – GPU device ID to use for decoding (0 for primary GPU)
suppressNoColorRangeWarning – Suppress warning when no color range can be extracted from video files (limited/MPEG range is assumed)

Raises:

RuntimeError – If GPU initialization fails or parameters are invalid

Note

The parameter num_of_set in nvc.CreateSampleReader controls the decoding cycle: - For a specific decoder instance, if you are decoding clipA, after calling DecodeN12ToRGB num_of_set times, the input returns to clipA again - If you are continuously decoding the same clip, then num_of_set can be set to 1

Decode(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader, filepaths: List[str], frame_ids: List[int]) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt]

Decodes video frames into uncompressed YUV data.

This method performs GPU-accelerated decoding of specific frames from multiple video files using the configured reader pools. It returns frames in YUV format with metadata.

Parameters:

filepaths – List of video file paths to decode from
frame_ids – List of frame IDs to decode from the video files

Returns:

List of DecodedFrameExt objects containing the decoded frame data. Each frame includes YUV pixel data, metadata, and timing information.

Raises:

RuntimeError – If video files cannot be decoded or frame IDs are invalid
ValueError – If frame_ids contain invalid indices or filepaths is empty

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> frames = reader.Decode(['video1.mp4', 'video2.mp4'], [0, 10])
>>> print(f"Decoded {len(frames)} frames")

DecodeN12ToRGB(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader, filepaths: List[str], frame_ids: List[int], as_bgr: bool = False) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Decodes video frames and converts them to RGB/BGR format.

This method performs GPU-accelerated decoding and color space conversion from YUV to RGB/BGR format for multiple video files. It’s optimized for machine learning applications that require RGB input data.

Parameters:

filepaths – List of video file paths to decode from
frame_ids – List of frame IDs to decode from the video files
as_bgr – Whether to output in BGR format (True) or RGB format (False). BGR is commonly used in OpenCV applications.

Returns:

List of RGBFrame objects containing the decoded and color-converted frame data. Each frame includes RGB/BGR pixel data and metadata.

Raises:

RuntimeError – If video files cannot be decoded or frame IDs are invalid
ValueError – If frame_ids contain invalid indices or filepaths is empty

Example

Ref to Sample: samples/SampleStreamAccess.py

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> rgb_frames = reader.DecodeN12ToRGB(['video1.mp4', 'video2.mp4'], [0, 10], as_bgr=True)
>>> print(f"Decoded {len(rgb_frames)} RGB frames")

DecodeN12ToRGBAsync(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader, filepaths: List[str], frame_ids: List[int], as_bgr: bool = False) → None

Asynchronously decode video frames and convert them to RGB/BGR format.

This method submits a decode task to a background thread and returns immediately. The decoded frames will be stored in an internal buffer and can be retrieved using DecodeN12ToRGBAsyncGetBuffer.

Important

Buffer Clearing Behavior: Calling this method will clear any pending results from the internal buffer. You MUST ensure that you have already retrieved all buffered results using DecodeN12ToRGBAsyncGetBuffer before calling this method again. Otherwise, pending decoded frames will be discarded and cannot be recovered.

Deep Copy Requirement: After retrieving frames via DecodeN12ToRGBAsyncGetBuffer, you MUST ensure that the frames have been deep-copied (e.g., using PyTorch’s clone(), or other deep-copy operations) or have been fully consumed by post-processing operations (e.g., resize) before calling DecodeN12ToRGBAsync again. This is because RGBFrame objects use zero-copy semantics and reference GPU memory from the internal memory pool. The memory pool may reuse the same GPU memory allocation for new decode operations, which could corrupt data if the previous frames are still being referenced.

Warning

GPU Memory Management: The GPU memory used by decoded frames is managed by an internal GPU memory pool (GPUMemoryPool), not by the RGBFrame objects themselves. This has important implications:

Zero-Copy Memory Access: RGBFrame objects use zero-copy semantics through the __cuda_array_interface__ protocol. When you convert them to PyTorch tensors using torch.as_tensor(frame), the tensor directly references the GPU memory from the memory pool without copying.
No Explicit Memory Release: You cannot explicitly release the GPU memory of individual RGBFrame objects. The memory is only released when: - The PyNvVideoReader instance that owns the memory pool is destroyed - The memory pool is explicitly released via ReleaseMemPools()
Memory Lifetime: Even after calling DecodeN12ToRGBAsyncGetBuffer and getting the frames, the GPU memory remains allocated in the memory pool until the reader is destroyed or the pool is released. PyTorch tensors created from RGBFrame objects will continue to reference this memory.

If a previous async decode task is still running, this method will wait for it to complete before starting the new task, and print a warning.

Parameters:

filepaths – List of video file paths to decode from
frame_ids – List of frame IDs to decode from the video files
as_bgr – Whether to output in BGR format (True) or RGB format (False). BGR is commonly used in OpenCV applications.

Note

Only one async decode task can be pending at a time. If you call this method while a previous task is still running, it will wait for the previous task to complete and print a warning.

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> reader.DecodeN12ToRGBAsync(['video1.mp4', 'video2.mp4'], [0, 10], as_bgr=False)
>>> # Do other work...
>>> frames = reader.DecodeN12ToRGBAsyncGetBuffer(['video1.mp4', 'video2.mp4'], [0, 10], False)
>>> # Process frames (memory is zero-copy referenced by PyTorch tensors)
>>> tensor_list = [torch.as_tensor(frame, device='cuda').clone() for frame in frames]
>>> # Note: GPU memory is still allocated in the memory pool
>>> # Memory will be released when reader is destroyed or ReleaseMemPools() is called

DecodeN12ToRGBAsyncGetBuffer(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader, filepaths: List[str], frame_ids: List[int], as_bgr: bool = False) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame]

Get decoded frames from the async decode buffer.

This method retrieves decoded frames from the internal buffer that were previously submitted via DecodeN12ToRGBAsync. It validates that the requested filepaths and frame_ids match the buffered result.

Warning

Zero-Copy GPU Memory Access: The returned RGBFrame objects use zero-copy semantics through the __cuda_array_interface__ protocol. This means:

Memory Ownership: The GPU memory is NOT owned by the RGBFrame objects. It is managed by an internal GPU memory pool (GPUMemoryPool) within the PyNvVideoReader instance.
PyTorch Tensor Conversion: When you convert RGBFrame to PyTorch tensors using torch.as_tensor(frame, device='cuda'), PyTorch will create a zero-copy tensor that directly references the GPU memory from the memory pool. No data is copied.
Memory Lifetime: The GPU memory remains allocated in the memory pool even after this method returns. It will NOT be released when: - RGBFrame objects go out of scope - PyTorch tensors are deleted - Python garbage collection runs
Memory Release: The GPU memory is only released when: - The PyNvSampleReader instance is destroyed - ReleaseMemPools() is explicitly called on the reader
Memory Pool Behavior: The memory pool reuses the same GPU memory allocation across multiple decode operations. Calling this method does NOT free the GPU memory - it only removes the frame data from the internal buffer queue.

Parameters:

filepaths – List of video file paths (must match the async request)
frame_ids – List of frame IDs (must match the async request)
as_bgr – BGR format flag (must match the async request)

Returns:

List of RGBFrame objects containing the decoded and color-converted frame data. Each frame includes RGB/BGR pixel data and metadata. The GPU memory is managed by the internal memory pool and uses zero-copy semantics.

Raises:

RuntimeError – If no matching result is found in buffer, validation fails, or decoding failed

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> reader.DecodeN12ToRGBAsync(['video1.mp4', 'video2.mp4'], [0, 10], as_bgr=False)
>>> # Do other work...
>>> frames = reader.DecodeN12ToRGBAsyncGetBuffer(['video1.mp4', 'video2.mp4'], [0, 10], False)
>>> # Convert to PyTorch tensors (zero-copy, no memory allocation)
>>> tensor_list = [torch.as_tensor(frame, device='cuda').clone() for frame in frames]
>>> # Note: GPU memory is still in the memory pool, referenced by tensors
>>> # Memory will persist until reader is destroyed or ReleaseMemPools() is called

clearAllReaders(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader) → None

Clear all video readers and release associated resources.

This method releases all video reader instances and their associated GPU resources. It should be called when the reader is no longer needed to free up GPU memory and other system resources.

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> frames = reader.Decode(['video1.mp4'], [0, 10, 20])
>>> reader.clearAllReaders()  # Clean up resources

release_decoder(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader) → None

Release all video decoder instances to free up GPU memory.

This method clears all video readers, which releases: - NvDecoder instances and their GPU frame buffers - Each video reader’s GPUMemoryPool instances

This is useful for freeing GPU memory occupied by decoder instances.

Note: After calling this method, video readers will need to be re-created on the next decode operation.

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> frames = reader.Decode(['video1.mp4'], [0, 10, 20])
>>> reader.release_decoder()  # Free decoder instances

release_device_memory(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.PyNvSampleReader) → None

Release GPU device memory pool to free up GPU memory.

This method releases the GPU memory pool and resets the pool state. This is useful for temporarily freeing excessive GPU memory usage.

Note: After calling this method, the memory pool will need to be re-allocated on the next decode operation.

Example

>>> reader = PyNvSampleReader(num_of_set=2, num_of_file=3)
>>> frames = reader.Decode(['video1.mp4'], [0, 10, 20])
>>> reader.release_device_memory()  # Free GPU memory pool

class accvlab.on_demand_video_decoder.FastStreamInfo(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo)

Bases: pybind11_object

Fast stream information structure for video files.

This structure contains essential metadata about video streams that can be extracted quickly without full video analysis. Used for performance optimization in multi-file decoding scenarios.

property avg_frame_rate_den: Average frame rate denominator)

property avg_frame_rate_num: Average frame rate numerator)

property codec_id: FFmpeg codec ID (AVCodecID enum value, e.g., AV_CODEC_ID_H264=27)

property codec_type: FFmpeg codec type (AVMediaType enum value)

property duration: Duration of the stream in time base units)

property format: Pixel format (AVPixelFormat enum value)

property height: Video frame height in pixels)

property r_frame_rate_den: Real frame rate denominator)

property r_frame_rate_num: Real frame rate numerator)

property start_time: Start time of the stream in time base units)

property time_base_den: Time base denominator for timestamp calculations)

property time_base_num: Time base numerator for timestamp calculations)

property width: Video frame width in pixels)

class accvlab.on_demand_video_decoder.DecodedFrameExt

Bases: pybind11_object

GetPtrToPlane(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt, arg0: int) → int: return pointer to base address for plane index :param planeIdx : index to the plane

property color_range

cuda(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.CAIMemoryView]: return underlying views which implement CAI :param None: None

property dtype: Get the data type of the buffer

property format

framesize(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt) → int: return underlying views which implement CAI :param None: None

nvcv_image(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.DecodedFrameExt) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.CAIMemoryView]: return underlying views which implement CAI :param None: None

property shape: Get the shape of the buffer as an array

property strides: Get the strides of the buffer

property timestamp

class accvlab.on_demand_video_decoder.RGBFrame(self: accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.RGBFrame, arg0: List[int], arg1: List[int], arg2: str, arg3: int, arg4: int, arg5: bool, arg6: bool)

Bases: pybind11_object

property data

property dataptr

property isBGR

property shape

property stride

accvlab.on_demand_video_decoder.CreateSampleReader(num_of_set: int, num_of_file: int, iGpu: int = 0, suppressNoColorRangeWarning: bool = False) → PyNvSampleReader

Initialize sample reader with multiple video readers.

This factory function creates a PyNvSampleReader instance with the specified configuration for high-throughput multi-file video processing. It’s the recommended way to create sample reader instances.

Parameters:

num_of_set – Number of video readers per file for parallel processing
num_of_file – Number of files to handle simultaneously
iGpu – GPU device ID to use for decoding (0 for primary GPU)
suppressNoColorRangeWarning – Suppress warning when no color range can be extracted from video files (limited/MPEG range is assumed)

Returns:

PyNvSampleReader instance configured with the specified parameters

Raises:

RuntimeError – If GPU initialization fails or parameters are invalid

Example

>>> reader = CreateSampleReader(num_of_set=2, num_of_file=3, iGpu=0)
>>> frames = reader.Decode(['v0.mp4', 'v1.mp4'], [0, 10])

Note

The parameter num_of_set in nvc.CreateSampleReader controls the decoding cycle: - For a specific decoder instance, if you are decoding clipA, after calling DecodeN12ToRGB num_of_set times, the input returns to clipA again - If you are continuously decoding the same clip, then num_of_set can be set to 1

accvlab.on_demand_video_decoder.GetFastInitInfo(filepaths: List[str]) → List[accvlab.on_demand_video_decoder._PyNvOnDemandDecoder.FastStreamInfo]

Extracts FastStreamInfo from video files automatically.

This function quickly extracts essential stream information from video files without performing full video analysis. The extracted information can be used to optimize decoding performance in multi-file scenarios.

Parameters:

filepaths – List of video file paths to analyze

Returns:

List of FastStreamInfo objects containing stream information for each file

Raises:

RuntimeError – If files cannot be opened or stream information cannot be extracted
ValueError – If filepaths is empty

Example

>>> stream_infos = GetFastInitInfo(['video1.mp4', 'video2.mp4'])

accvlab.on_demand_video_decoder.SavePacketsToFile(numpy_data: numpy.ndarray[numpy.uint8], dst_filepath: str) → None

Saves numpy array data to a binary file.

This function saves serialized packet data to a binary file for later use. Useful for caching packet data to avoid repeated extraction.

Parameters:

numpy_data – Numpy array containing binary data to save
dst_filepath – Destination file path where data will be saved

Raises:

RuntimeError – If file cannot be written or data is invalid
ValueError – If dst_filepath is empty

Example

>>> gop_data, first_ids, gop_lens = decoder.GetGOP(['v0.mp4', 'v1.mp4', 'v2.mp4'], [0, 10, 20])
>>> SavePacketsToFile(packets, 'cached_packets.bin')

class accvlab.on_demand_video_decoder.CachedGopDecoder(decoder, *, _key=None)[source]

Bases: object

GOP decoder with caching support.

Use CreateGopDecoder() to create instances of this class.

This class extends PyNvGopDecoder with transparent GOP caching. All methods available in PyNvGopDecoder (such as DecodeFromGOPRGB(), DecodeFromGOPListRGB(), etc.) are also available in this class.

The following methods are enhanced with caching support:

GetGOP() - with optional useGOPCache parameter
GetGOPList() - with optional useGOPCache parameter

The caching can significantly reduce redundant demuxing operations when the same GOP data is requested multiple times.

Caching behavior (controlled by useGOPCache parameter):

When useGOPCache=False (default): Demuxes the video files and returns the GOP data.
When useGOPCache=True: Caches GOP data and returns cached results when the requested frame_id falls within a previously cached GOP range

Cache hit condition for each file: first_frame_id <= frame_id < first_frame_id + gop_len