python_vali.PyDecoder

class python_vali.PyDecoder

Video decoder class.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: python_vali._python_vali.PyDecoder, input: str, opts: dict[str, str], gpu_id: int = 0) -> None

   Create a new video decoder instance from a file.

   Initializes a video decoder that can decode frames from a video file. The decoder can operate in either CPU or GPU mode depending on the gpu_id parameter.

   param input:

   Path to the input video file

   type input:

   str

   param opts:

   Dictionary of options to pass to libavcodec API. Can include: - preferred_width: Select a stream with desired width from multiple video streams - Other FFmpeg options as key-value pairs

   type opts:

   dict[str, str]

   param gpu_id:

   GPU device ID to use for hardware acceleration. Default is 0. Use negative value for CPU-only decoding.

   type gpu_id:

   int

   raises RuntimeError:

   If decoder initialization fails

2. __init__(self: python_vali._python_vali.PyDecoder, buffered_reader: object, opts: dict[str, str], gpu_id: int = 0) -> None

   Create a new video decoder instance from a buffered reader.

   Initializes a video decoder that can decode frames from a buffered reader object. The decoder can operate in either CPU or GPU mode depending on the gpu_id parameter.

   param buffered_reader:

   Python object with a ‘read’ method (e.g., io.BufferedReader)

   type buffered_reader:

   object

   param opts:

   Dictionary of options to pass to libavcodec API. Can include: - preferred_width: Select a stream with desired width from multiple video streams - Other FFmpeg options as key-value pairs

   type opts:

   dict[str, str]

   param gpu_id:

   GPU device ID to use for hardware acceleration. Default is 0. Use negative value for CPU-only decoding.

   type gpu_id:

   int

   raises RuntimeError:

   If decoder initialization fails

Methods

DecodeSingleFrame(*args, **kwargs)	Overloaded function.
DecodeSingleSurface(*args, **kwargs)	Overloaded function.
DecodeSingleSurfaceAsync(*args, **kwargs)	Overloaded function.
Probe(input)	Probe input without decoding.
SetMode(self, arg0)	Set the decoder operation mode.
__init__(*args, **kwargs)	Overloaded function.

Attributes

AvgFramerate	Return encoded video file average framerate.
Bitrate	Return encoded video bitrate in bits per second.
ColorRange	Get color range information stored in video file.
ColorSpace	Get color space information stored in video file.
Delay	Return encoded video delay.
DisplayRotation	Return last decoded frame display rotation info.
Duration	Return video duration time in seconds.
Format	Return encoded video file pixel format.
Framerate	Return encoded video file framerate.
GopSize	Return encoded video GOP size.
Height	Return encoded video file height in pixels.
HostFrameSize	Return amount of bytes needed to store decoded frame.
IsAccelerated	Return true if decoder has HW acceleration support, false otherwise.
IsVFR	Return true if video has variable framerate, false otherwise.
Level	Return encoded video level coding parameter.
Metadata	Return dictionary with video file metadata.
Mode	Get the current decoder operation mode.
MotionVectors	Return motion vectors of last decoded frame.
NumFrames	Return number of video frames in encoded video file.
NumStreams	audio and video.
Profile	Return encoded video profile coding parameter.
StartTime	Return video start time in seconds.
Stream	Get the CUDA stream used by the decoder.
StreamIndex	Return number of current video stream in file.
Timebase	Return encoded video file time base.
Width	Return encoded video file width in pixels.

property AvgFramerate

Return encoded video file average framerate.

property Bitrate

Return encoded video bitrate in bits per second.

property ColorRange

Get color range information stored in video file. Please not that some video containers may not store this information.

Returns:

color range information

property ColorSpace

Get color space information stored in video file. Please not that some video containers may not store this information.

Returns:

color space information

DecodeSingleFrame(*args, **kwargs)

Overloaded function.

1. DecodeSingleFrame(self: python_vali._python_vali.PyDecoder, frame: numpy.ndarray, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame from the input source.

   This method is for CPU-only decoding (non-accelerated decoder). The frame will be decoded into the provided numpy array.

   param frame:

   Numpy array to store the decoded frame

   type frame:

   numpy.ndarray

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called with hardware acceleration enabled

2. DecodeSingleFrame(self: python_vali._python_vali.PyDecoder, frame: numpy.ndarray, pkt_data: python_vali._python_vali.PacketData, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame with packet data from the input source.

   This method is for CPU-only decoding (non-accelerated decoder). The frame will be decoded into the provided numpy array, and packet metadata will be stored in pkt_data.

   param frame:

   Numpy array to store the decoded frame

   type frame:

   numpy.ndarray

   param pkt_data:

   Object to store packet metadata

   type pkt_data:

   PacketData

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called with hardware acceleration enabled

DecodeSingleSurface(*args, **kwargs)

Overloaded function.

1. DecodeSingleSurface(self: python_vali._python_vali.PyDecoder, surf: VPF::Surface, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame into a CUDA surface.

   This method is for hardware-accelerated decoding. The frame will be decoded directly into the provided CUDA surface. The operation is synchronous and will wait for completion.

   param surf:

   CUDA surface to store the decoded frame

   type surf:

   Surface

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called without hardware acceleration

2. DecodeSingleSurface(self: python_vali._python_vali.PyDecoder, surf: VPF::Surface, pkt_data: python_vali._python_vali.PacketData, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame into a CUDA surface with packet data.

   This method is for hardware-accelerated decoding. The frame will be decoded directly into the provided CUDA surface, and packet metadata will be stored in pkt_data. The operation is synchronous and will wait for completion.

   param surf:

   CUDA surface to store the decoded frame

   type surf:

   Surface

   param pkt_data:

   Object to store packet metadata

   type pkt_data:

   PacketData

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called without hardware acceleration

DecodeSingleSurfaceAsync(*args, **kwargs)

Overloaded function.

1. DecodeSingleSurfaceAsync(self: python_vali._python_vali.PyDecoder, surf: VPF::Surface, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame into a CUDA surface asynchronously.

   This method is for hardware-accelerated decoding. The frame will be decoded directly into the provided CUDA surface. The operation is asynchronous and returns immediately.

   param surf:

   CUDA surface to store the decoded frame

   type surf:

   Surface

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called without hardware acceleration

2. DecodeSingleSurfaceAsync(self: python_vali._python_vali.PyDecoder, surf: VPF::Surface, pkt_data: python_vali._python_vali.PacketData, seek_ctx: Optional[python_vali._python_vali.SeekContext] = None) -> tuple[bool, python_vali._python_vali.TaskExecInfo]

   Decode a single video frame into a CUDA surface with packet data asynchronously.

   This method is for hardware-accelerated decoding. The frame will be decoded directly into the provided CUDA surface, and packet metadata will be stored in pkt_data. The operation is asynchronous and returns immediately.

   param surf:

   CUDA surface to store the decoded frame

   type surf:

   Surface

   param pkt_data:

   Object to store packet metadata

   type pkt_data:

   PacketData

   param seek_ctx:

   Optional seek context for frame positioning

   type seek_ctx:

   Optional[SeekContext]

   return:

   Tuple containing: - success (bool): True if decoding was successful - info (TaskExecInfo): Detailed execution information

   rtype:

   tuple[bool, TaskExecInfo]

   raises RuntimeError:

   If called without hardware acceleration

property Delay

Return encoded video delay.

property DisplayRotation

Return last decoded frame display rotation info.

If there’s no such data, 361.0 will be returned.

Returns:

value in degrees

property Duration

Return video duration time in seconds. May not be present.

property Format

Return encoded video file pixel format.

property Framerate

Return encoded video file framerate.

property GopSize

Return encoded video GOP size.

property Height

Return encoded video file height in pixels.

property HostFrameSize

Return amount of bytes needed to store decoded frame.

property IsAccelerated

Return true if decoder has HW acceleration support, false otherwise.

property IsVFR

Return true if video has variable framerate, false otherwise.

property Level

Return encoded video level coding parameter.

property Metadata

Return dictionary with video file metadata.

property Mode

Get the current decoder operation mode.

Returns:

Current decode mode (e.g., KEY_FRAMES, ALL_FRAMES)

Return type:

DecodeMode

property MotionVectors

Return motion vectors of last decoded frame.

If there are no movion vectors it will return empty list.

Returns:

list of motion vectors

Return type:

List[vali.MotionVector]

property NumFrames

Return number of video frames in encoded video file. Please note that some video containers doesn’t store this infomation.

property NumStreams

audio and video.

Type:

Return number of streams in video file. E. g. 2 streams

static Probe(input: str) → list[python_vali._python_vali.StreamParams]

Probe input without decoding. Information about streams will be returned without codec initialization.

Parameters:

input – path to input file

Returns:

list of structures with stream parameters

property Profile

Return encoded video profile coding parameter.

SetMode(self: python_vali._python_vali.PyDecoder, arg0: python_vali._python_vali.DecodeMode) → None

Set the decoder operation mode.

Changes how the decoder processes frames and handles seeking operations. When in KEY_FRAMES mode, seeking will return the closest previous key frame. When switching modes, the internal frame queue is preserved to avoid discarding decoded frames that may be needed for future operations.

Parameters:

new_mode (DecodeMode) – The new decode mode to set

Note:

Mode changes affect seek behavior and frame processing strategy

property StartTime

Return video start time in seconds.

property Stream

Get the CUDA stream used by the decoder.

Returns:

CUDA stream handle as an integer

Return type:

int

property StreamIndex

Return number of current video stream in file. E. g. video stream has index 0, and audio stream has index 1. This method will return 0 then.

property Timebase

Return encoded video file time base.

property Width

Return encoded video file width in pixels.