python_vali

python_vali

GetNumGpus()	Get the number of available CUDA-capable GPUs in the system.
GetNvencParams()	Get the list of parameters that can be used to initialize PyNvEncoder.
SetFFMpegLogLevel(level)	Set the logging level for FFmpeg operations.
PySurfaceResizer	CUDA-accelerated Surface resizer.
PySurfaceDownloader	This class is used to copy Surface to numpy ndarray using CUDA DtoH memcpy.
PySurfaceConverter	CUDA-accelerated converter between different pixel formats.
PyNvEncoder	HW-accelerated video encoder which uses Nvenc.
PyDecoder	Video decoder class.
PyFrameUploader	This class is used to upload numpy array to Surface using CUDA HtoD memcpy.
PyNvJpegEncoder
SeekContext	Context object for video frame seeking operations.
SurfacePlane	Continious 2D chunk of memory stored in vRAM which represents single plane / channel of video frame.
Surface	Image stored in vRAM.
CudaStreamEvent	CUDA stream synchronization event
PySurfaceRotator	CUDA-accelerated Surface rotator.
PySurfaceUD	CUDA-accelerated Surface Upsampler-Downscaler

class python_vali._python_vali.ColorRange

Members:

MPEG : Narrow or MPEG color range. Doesn’t use full [0;255] range.

JPEG : Full of JPEG color range. Uses full [0;255] range.

UDEF : Undefined color range.

property name

class python_vali._python_vali.ColorSpace

Members:

BT_601 : BT.601 color space.

BT_709 : BT.709 color space.

UNSPEC : Unspecified color space.

property name

class python_vali._python_vali.ColorspaceConversionContext

Context for color space and range conversion operations

property color_range

Color range setting (e.g., MPEG, JPEG)

property color_space

Color space setting (e.g., BT_601, BT_709)

class python_vali._python_vali.CudaBuffer

GPU memory buffer for data storage and manipulation

Clone(self: python_vali._python_vali.CudaBuffer) → python_vali._python_vali.CudaBuffer

Create a deep copy of the buffer.

Allocates new GPU memory and copies the contents of this buffer. The caller is responsible for managing the returned buffer’s lifetime.

Returns:

New CudaBuffer instance with copied data

Return type:

CudaBuffer

CopyFrom(*args, **kwargs)

Overloaded function.

1. CopyFrom(self: python_vali._python_vali.CudaBuffer, other: python_vali._python_vali.CudaBuffer, stream: int) -> None

   Copy data from another CudaBuffer using a specific CUDA stream.

   param other:

   Source CudaBuffer to copy from

   type other:

   CudaBuffer

   param stream:

   CUDA stream to use for the copy operation

   type stream:

   int

   raises RuntimeError:

   If buffer sizes don’t match

2. CopyFrom(self: python_vali._python_vali.CudaBuffer, other: python_vali._python_vali.CudaBuffer, gpu_id: int) -> None

   Copy data from another CudaBuffer using the default stream of a GPU.

   param other:

   Source CudaBuffer to copy from

   type other:

   CudaBuffer

   param gpu_id:

   GPU device ID to use for the copy operation

   type gpu_id:

   int

   raises RuntimeError:

   If buffer sizes don’t match

property ElemSize

Get the size of a single element in bytes.

Returns:

Size of one element in bytes

Return type:

int

property GpuMem

Get the CUDA device pointer to the buffer memory.

Returns:

CUDA device pointer as integer

Return type:

int

static Make(elem_size: int, num_elems: int, gpu_id: int) → python_vali._python_vali.CudaBuffer

Create a new CudaBuffer instance.

Allocates GPU memory for the specified number of elements.

Parameters:

• elem_size (int) – Size of each element in bytes

• num_elems (int) – Number of elements to allocate

• gpu_id (int) – GPU device ID to allocate memory on

Returns:

New CudaBuffer instance

Return type:

CudaBuffer

Raises:

RuntimeError – If memory allocation fails

property NumElems

Get the number of elements in the buffer.

Returns:

Number of elements

Return type:

int

property RawMemSize

Get the total size of the buffer in bytes.

Returns:

Total buffer size in bytes

Return type:

int

class python_vali._python_vali.CudaStreamEvent

CUDA stream synchronization event

Record(self: python_vali._python_vali.CudaStreamEvent) → None

Record the current state of the CUDA stream.

Creates a synchronization point in the CUDA stream. Equivalent to cuEventRecord in the CUDA API.

Note:

This operation is asynchronous and returns immediately

Wait(self: python_vali._python_vali.CudaStreamEvent) → None

Wait for the recorded event to complete.

Blocks until all operations in the CUDA stream up to the recorded event have completed. Equivalent to cuEventSynchronize in the CUDA API.

Note:

This operation is synchronous and will block until completion

class python_vali._python_vali.DLDeviceType

Members:

kDLCPU : CPU device.

kDLCUDA : CUDA GPU device.

kDLCUDAHost : Pinned CUDA CPU memory by cudaMallocHost.

kDLCUDAManaged : CUDA managed/unified memory allocated by cudaMallocManaged.

property name

class python_vali._python_vali.DecodeMode

Members:

KEY_FRAMES : Decode key frames only.

ALL_FRAMES : Decode everything.

property name

class python_vali._python_vali.FfmpegLogLevel

Members:

PANIC : AV_LOG_PANIC

FATAL : AV_LOG_FATAL

ERROR : AV_LOG_ERROR

WARNING : AV_LOG_WARNING

INFO : AV_LOG_INFO

VERBOSE : AV_LOG_VERBOSE

DEBUG : AV_LOG_DEBUG

property name

python_vali._python_vali.GetNumGpus() → int

Get the number of available CUDA-capable GPUs in the system.

Returns:

Number of available GPUs

Return type:

int

python_vali._python_vali.GetNvencParams() → dict[str, str]

Get the list of parameters that can be used to initialize PyNvEncoder.

Returns:

Dictionary of available encoder parameters

Return type:

dict

class python_vali._python_vali.MotionVector

This class stores information about motion vector.

property dst_x

Absolute X coordinate of the destination macroblock. May be outside frame boundaries.

property dst_y

Absolute Y coordinate of the destination macroblock. May be outside frame boundaries.

property h

Height of the macroblock in pixels.

property motion_scale

Motion vector precision factor. For example, 4 indicates quarter-pixel precision.

property motion_x

X component of the motion vector in pixels.

property motion_y

Y component of the motion vector in pixels.

property source

Frame reference direction indicator. Negative value indicates past reference, positive value indicates future reference.

property src_x

Absolute X coordinate of the source macroblock. May be outside frame boundaries.

property src_y

Absolute Y coordinate of the source macroblock. May be outside frame boundaries.

property w

Width of the macroblock in pixels.

class python_vali._python_vali.NV_ENC_CAPS

Members:

NUM_MAX_BFRAMES

SUPPORTED_RATECONTROL_MODES

SUPPORT_FIELD_ENCODING

SUPPORT_MONOCHROME

SUPPORT_FMO

SUPPORT_QPELMV

SUPPORT_BDIRECT_MODE

SUPPORT_CABAC

SUPPORT_ADAPTIVE_TRANSFORM

SUPPORT_STEREO_MVC

NUM_MAX_TEMPORAL_LAYERS

SUPPORT_HIERARCHICAL_PFRAMES

SUPPORT_HIERARCHICAL_BFRAMES

LEVEL_MAX

LEVEL_MIN

SEPARATE_COLOUR_PLANE

WIDTH_MAX

HEIGHT_MAX

SUPPORT_TEMPORAL_SVC

SUPPORT_DYN_RES_CHANGE

SUPPORT_DYN_BITRATE_CHANGE

SUPPORT_DYN_FORCE_CONSTQP

SUPPORT_DYN_RCMODE_CHANGE

SUPPORT_SUBFRAME_READBACK

SUPPORT_CONSTRAINED_ENCODING

SUPPORT_INTRA_REFRESH

SUPPORT_CUSTOM_VBV_BUF_SIZE

SUPPORT_DYNAMIC_SLICE_MODE

SUPPORT_REF_PIC_INVALIDATION

PREPROC_SUPPORT

ASYNC_ENCODE_SUPPORT

MB_NUM_MAX

MB_PER_SEC_MAX

SUPPORT_YUV444_ENCODE

SUPPORT_LOSSLESS_ENCODE

SUPPORT_SAO

SUPPORT_MEONLY_MODE

SUPPORT_LOOKAHEAD

SUPPORT_TEMPORAL_AQ

SUPPORT_10BIT_ENCODE

NUM_MAX_LTR_FRAMES

SUPPORT_WEIGHTED_PREDICTION

DYNAMIC_QUERY_ENCODER_CAPACITY

SUPPORT_BFRAME_REF_MODE

SUPPORT_EMPHASIS_LEVEL_MAP

WIDTH_MIN

HEIGHT_MIN

SUPPORT_MULTIPLE_REF_FRAMES

SUPPORT_ALPHA_LAYER_ENCODING

EXPOSED_COUNT

property name

class python_vali._python_vali.PacketData

Video frame metadata container

property bsl

Number of bytes consumed by the decoder for this frame’s packet. Useful for seeking operations to find previous key frames.

property dts

Decoding timestamp of the frame.

property duration

Duration of the frame’s packet in stream timebase units.

property key

Frame type indicator. 1 for I-frames (key frames), 0 for other frames.

property pos

Byte position of the frame’s packet in the input bitstream.

property pts

Presentation timestamp of the frame.

class python_vali._python_vali.PixelFormat

Members:

Y : Grayscale.

RGB : Interleaved 8 bit RGB.

NV12 : Semi planar 8 bit: full resolution Y + quarter resolution interleaved UV.

YUV420 : Planar 8 bit: full resolution Y + quarter resolution U + quarter resolution V.

RGB_PLANAR : Planar 8 bit R+G+B.

BGR : Planar 8 bit R+G+B.

YUV444 : Planar 8 bit Y+U+V.

YUV444_10bit : 10 bit YUV444.

YUV420_10bit : 10 bit YUV420

UNDEFINED : Undefined pixel format, use to signal unsupported formats

RGB_32F : 32 bit float RGB.

RGB_32F_PLANAR : 32 bit float planar RGB

YUV422 : 8 bit planar: full resolution Y + half resolution U + half resolution V.

P10 : 10 bit NV12.

P12 : 12 bit NV12.

property name

class python_vali._python_vali.PyDecoder

Video decoder class.

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.

class python_vali._python_vali.PyFrameConverter

libswscale converter between different pixel formats.

property Format

Get the current pixel format configuration.

Returns a tuple containing the source and destination pixel formats that this converter is configured to use.

Returns:

Tuple of (source_format, destination_format)

Return type:

tuple[Pixel_Format, Pixel_Format]

Run(self: python_vali._python_vali.PyFrameConverter, src: numpy.ndarray, dst: numpy.ndarray, cc_ctx: python_vali._python_vali.ColorspaceConversionContext) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Convert a frame between pixel formats.

Performs pixel format conversion on the input frame using libswscale. The input array must have the correct size for the configured resolution and source format. The output array will be automatically resized if needed to accommodate the converted frame.

Parameters:

• src (numpy.ndarray) – Input numpy array containing the frame to convert

• dst (numpy.ndarray) – Output numpy array that will receive the converted frame

• cc_ctx (ColorspaceConversionContext) – Colorspace conversion context specifying color space and range

Returns:

Tuple containing: - success (bool): True if conversion was successful, False otherwise - info (TaskExecInfo): Detailed information about the conversion operation

Return type:

tuple[bool, TaskExecInfo]

Raises:

• RuntimeError – If the conversion fails

• ValueError – If the input array has incorrect dimensions

class python_vali._python_vali.PyFrameUploader

This class is used to upload numpy array to Surface using CUDA HtoD memcpy.

Run(self: python_vali._python_vali.PyFrameUploader, src: numpy.ndarray, dst: VPF::Surface) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Perform a blocking host-to-device memory copy.

Transfers data from a numpy array in host memory to a Surface in device memory. The operation is performed synchronously, meaning it will block until the transfer is complete.

Parameters:

• src (numpy.ndarray) – Source numpy array containing the data to transfer

• dst (Surface) – Destination Surface that will receive the data

Returns:

Tuple containing: - success (bool): True if the transfer was successful, False otherwise - info (TaskExecInfo): Detailed information about the transfer operation

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the memory transfer fails

class python_vali._python_vali.PyNvEncoder

HW-accelerated video encoder which uses Nvenc.

property Capabilities

Get the capabilities of the NVENC encoder.

Returns a dictionary containing all supported capabilities of the NVENC encoder, such as maximum resolution, supported codecs, and encoding features.

Returns:

Dictionary mapping capability types to their values

Return type:

dict[NV_ENC_CAPS, int]

EncodeSingleSurface(*args, **kwargs)

Overloaded function.

1. EncodeSingleSurface(self: python_vali._python_vali.PyNvEncoder, surface: VPF::Surface, packet: numpy.ndarray, sei: numpy.ndarray, sync: bool, append: bool) -> bool

   Encode a single surface with SEI data and synchronization options.

   Encodes a single surface into a compressed video packet. The function may not return immediately with a compressed packet, depending on the encoder’s internal buffering and the sync parameter.

   param surface:

   Input surface containing the frame to encode

   type surface:

   Surface

   param packet:

   Output buffer for the compressed video packet

   type packet:

   numpy.ndarray

   param sei:

   Optional SEI (Supplemental Enhancement Information) data to attach

   type sei:

   numpy.ndarray

   param sync:

   Whether to wait for the encoded packet before returning

   type sync:

   bool

   param append:

   Whether to append the new packet to existing data

   type append:

   bool

   return:

   True if encoding was successful, False otherwise

   rtype:

   bool

   raises RuntimeError:

   If encoding fails

2. EncodeSingleSurface(self: python_vali._python_vali.PyNvEncoder, surface: VPF::Surface, packet: numpy.ndarray, sei: numpy.ndarray, sync: bool) -> bool

   Encode a single surface with SEI data.

   Encodes a single surface into a compressed video packet with optional SEI data. The sync parameter determines whether to wait for the encoded packet before returning.

   param surface:

   Input surface containing the frame to encode

   type surface:

   Surface

   param packet:

   Output buffer for the compressed video packet

   type packet:

   numpy.ndarray

   param sei:

   Optional SEI data to attach to the encoded frame

   type sei:

   numpy.ndarray

   param sync:

   Whether to wait for the encoded packet before returning

   type sync:

   bool

   return:

   True if encoding was successful, False otherwise

   rtype:

   bool

   raises RuntimeError:

   If encoding fails

3. EncodeSingleSurface(self: python_vali._python_vali.PyNvEncoder, surface: VPF::Surface, packet: numpy.ndarray, sync: bool) -> bool

   Encode a single surface with synchronization option.

   Encodes a single surface into a compressed video packet. The sync parameter determines whether to wait for the encoded packet before returning.

   param surface:

   Input surface containing the frame to encode

   type surface:

   Surface

   param packet:

   Output buffer for the compressed video packet

   type packet:

   numpy.ndarray

   param sync:

   Whether to wait for the encoded packet before returning

   type sync:

   bool

   return:

   True if encoding was successful, False otherwise

   rtype:

   bool

   raises RuntimeError:

   If encoding fails

4. EncodeSingleSurface(self: python_vali._python_vali.PyNvEncoder, surface: VPF::Surface, packet: numpy.ndarray, sei: numpy.ndarray) -> bool

   Encode a single surface with SEI data.

   Encodes a single surface into a compressed video packet with optional SEI data. The function operates asynchronously by default.

   param surface:

   Input surface containing the frame to encode

   type surface:

   Surface

   param packet:

   Output buffer for the compressed video packet

   type packet:

   numpy.ndarray

   param sei:

   Optional SEI data to attach to the encoded frame

   type sei:

   numpy.ndarray

   return:

   True if encoding was successful, False otherwise

   rtype:

   bool

   raises RuntimeError:

   If encoding fails

5. EncodeSingleSurface(self: python_vali._python_vali.PyNvEncoder, surface: VPF::Surface, packet: numpy.ndarray) -> bool

   Encode a single surface.

   Encodes a single surface into a compressed video packet. The function operates asynchronously by default.

   param surface:

   Input surface containing the frame to encode

   type surface:

   Surface

   param packet:

   Output buffer for the compressed video packet

   type packet:

   numpy.ndarray

   return:

   True if encoding was successful, False otherwise

   rtype:

   bool

   raises RuntimeError:

   If encoding fails

Flush(self: python_vali._python_vali.PyNvEncoder, packets: numpy.ndarray) → bool

Flush the encoder’s internal buffers.

Forces the encoder to process any remaining frames in its internal buffers and output them as compressed packets.

Parameters:

packets (numpy.ndarray) – Output buffer for the compressed packets

Returns:

True if any packets were flushed, False otherwise

Return type:

bool

Raises:

RuntimeError – If flushing fails

FlushSinglePacket(self: python_vali._python_vali.PyNvEncoder, packets: numpy.ndarray) → bool

Flush the encoder’s internal buffers.

Forces the encoder to process remaining frame in its internal buffers and output it as compressed packet.

param packet:

Output buffer for 1 compressed packet

type packet:

numpy.ndarray

return:

True if any packet was flushed, False otherwise

rtype:

bool

raises RuntimeError:

If flushing fails

property Format

Get the pixel format of the encoded video stream.

Returns:

Pixel format used for encoding

Return type:

Pixel_Format

property FrameSizeInBytes

Get the size of a single frame in bytes.

Calculates the size of a single frame based on the current pixel format and resolution. This is useful for allocating memory for frame buffers.

Returns:

Size of a single frame in bytes

Return type:

int

Raises:

ValueError – If the pixel format is not supported

property Height

Get the height of the encoded video stream.

Returns:

Height of the encoded video in pixels

Return type:

int

Reconfigure(self: python_vali._python_vali.PyNvEncoder, settings: dict[str, str], force_idr: bool = False, reset_encoder: bool = False, verbose: bool = False) → bool

Reconfigure the encoder with new settings.

Updates the encoder configuration with new settings. This can be used to change encoding parameters during runtime, such as bitrate or resolution.

Parameters:

• settings (dict[str, str]) – Dictionary containing new NVENC encoder settings

• force_idr (bool) – Force the next encoded frame to be an IDR key frame

• reset_encoder (bool) – Force a complete encoder reset

• verbose (bool) – Whether to output detailed logging information

Returns:

True if reconfiguration was successful, False otherwise

Return type:

bool

Raises:

RuntimeError – If reconfiguration fails

property Width

Get the width of the encoded video stream.

Returns:

Width of the encoded video in pixels

Return type:

int

class python_vali._python_vali.PySurfaceConverter

CUDA-accelerated converter between different pixel formats.

static Conversions() → list[tuple[python_vali._python_vali.PixelFormat, python_vali._python_vali.PixelFormat]]

Get list of supported pixel format conversions.

Returns a list of tuples containing supported input and output pixel format pairs that can be processed by the converter.

Returns:

List of tuples containing supported (input_format, output_format) pairs

Return type:

list[tuple[Pixel_Format, Pixel_Format]]

Run(self: python_vali._python_vali.PySurfaceConverter, src: VPF::Surface, dst: VPF::Surface, cc_ctx: Optional[python_vali._python_vali.ColorspaceConversionContext] = None) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Perform pixel format conversion synchronously.

Converts the input surface to the specified output format. This method blocks until the conversion is complete. The input surface must be in a format supported by the converter. The output surface must be in a format that can be converted to from the input format.

Parameters:

• src (Surface) – Input surface to be converted

• dst (Surface) – Output surface to store the converted result

• cc_ctx (ColorspaceConversionContext, optional) – Optional colorspace conversion context that describes the color space and color range to use for conversion. If not provided, VALI will automatically select supported color conversion parameters.

Returns:

Tuple containing: - success (bool): True if conversion was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the conversion fails or if the formats are not compatible

RunAsync(self: python_vali._python_vali.PySurfaceConverter, src: VPF::Surface, dst: VPF::Surface, cc_ctx: Optional[python_vali._python_vali.ColorspaceConversionContext] = None) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Perform pixel format conversion asynchronously.

Converts the input surface to the specified output format. This method returns immediately without waiting for the conversion to complete. The input surface must be in a format supported by the converter. The output surface must be in a format that can be converted to from the input format.

Parameters:

• src (Surface) – Input surface to be converted

• dst (Surface) – Output surface to store the converted result

• cc_ctx (ColorspaceConversionContext, optional) – Optional colorspace conversion context that describes the color space and color range to use for conversion. If not provided, VALI will automatically select supported color conversion parameters.

Returns:

Tuple containing: - success (bool): True if conversion was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the conversion fails or if the formats are not compatible

property Stream

Get the CUDA stream associated with this instance.

Returns the handle to the CUDA stream used for conversion processing.

Returns:

CUDA stream handle

Return type:

int

class python_vali._python_vali.PySurfaceDownloader

This class is used to copy Surface to numpy ndarray using CUDA DtoH memcpy.

Run(self: python_vali._python_vali.PySurfaceDownloader, src: VPF::Surface, dst: numpy.ndarray) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Perform device-to-host memory copy from Surface to numpy array.

Copies the contents of a GPU Surface to a numpy array using CUDA DtoH memcpy. The numpy array must be pre-allocated with sufficient size to hold the Surface data. The GIL is released during the copy operation to allow other Python threads to run.

Parameters:

• src (Surface) – Input Surface to be downloaded from GPU

• dst (numpy.ndarray) – Pre-allocated numpy array to store the downloaded data

Returns:

Tuple containing: - success (bool): True if download was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the download operation fails or if the numpy array is too small

class python_vali._python_vali.PySurfaceResizer

CUDA-accelerated Surface resizer.

Run(self: python_vali._python_vali.PySurfaceResizer, src: VPF::Surface, dst: VPF::Surface) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Resize input Surface synchronously.

Processes the input surface and stores the resized result in the output surface. This method blocks until the resize operation is complete. Both input and output surfaces must use the same pixel format that was specified when creating the resizer instance.

Parameters:

• src (Surface) – Input surface to be resized

• dst (Surface) – Output surface to store the resized result

Returns:

Tuple containing: - success (bool): True if resize was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the resize operation fails or if surface formats don’t match

RunAsync(self: python_vali._python_vali.PySurfaceResizer, src: VPF::Surface, dst: VPF::Surface) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Resize input Surface asynchronously.

Processes the input surface and stores the resized result in the output surface. This method returns immediately without waiting for the resize operation to complete. Both input and output surfaces must use the same pixel format that was specified when creating the resizer instance.

Parameters:

• src (Surface) – Input surface to be resized

• dst (Surface) – Output surface to store the resized result

Returns:

Tuple containing: - success (bool): True if resize was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the resize operation fails or if surface formats don’t match

property Stream

Get the CUDA stream associated with this instance.

Returns the handle to the CUDA stream used for resize processing.

Returns:

CUDA stream handle

Return type:

int

class python_vali._python_vali.PySurfaceRotator

CUDA-accelerated Surface rotator.

Run(self: python_vali._python_vali.PySurfaceRotator, src: python_vali._python_vali.Surface, dst: python_vali._python_vali.Surface, angle: float, shift_x: float = 0.0, shift_y: float = 0.0) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Rotate input Surface synchronously.

Processes the input surface and stores the rotated result in the output surface. This method blocks until the rotation is complete. For 90-degree rotations with no shift, the method optimizes the operation by handling display matrix rotation cases.

Parameters:

• src (Surface) – Input surface to be rotated

• dst (Surface) – Output surface to store the rotated result

• angle (float) – Rotation angle in degrees

• shift_x (float) – Shift along X axis in pixels (default: 0.0)

• shift_y (float) – Shift along Y axis in pixels (default: 0.0)

Returns:

Tuple containing: - success (bool): True if rotation was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the rotation fails

RunAsync(self: python_vali._python_vali.PySurfaceRotator, src: python_vali._python_vali.Surface, dst: python_vali._python_vali.Surface, angle: float, shift_x: float = 0.0, shift_y: float = 0.0) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Rotate input Surface asynchronously.

Processes the input surface and stores the rotated result in the output surface. This method returns immediately without waiting for the rotation to complete. For 90-degree rotations with no shift, the method optimizes the operation by handling display matrix rotation cases.

Parameters:

• src (Surface) – Input surface to be rotated

• dst (Surface) – Output surface to store the rotated result

• angle (float) – Rotation angle in degrees

• shift_x (float) – Shift along X axis in pixels (default: 0.0)

• shift_y (float) – Shift along Y axis in pixels (default: 0.0)

Returns:

Tuple containing: - success (bool): True if rotation was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the rotation fails

property Stream

Get the CUDA stream associated with this instance.

Returns the handle to the CUDA stream used for rotation processing.

Returns:

CUDA stream handle

Return type:

int

property SupportedFormats

Get list of supported pixel formats for rotation.

Returns a list of pixel formats that can be processed by the rotator. Supported formats include: Y, GRAY12, RGB, BGR, RGB_PLANAR, YUV420, YUV422, YUV444, RGB_32F, RGB_32F_PLANAR, YUV444_10bit, YUV420_10bit.

Returns:

List of supported pixel formats

Return type:

list[Pixel_Format]

class python_vali._python_vali.PySurfaceUD

CUDA-accelerated Surface Upsampler-Downscaler

Run(self: python_vali._python_vali.PySurfaceUD, src: python_vali._python_vali.Surface, dst: python_vali._python_vali.Surface) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Convert input Surface synchronously.

Processes the input surface and stores the result in the output surface. This method blocks until the conversion is complete.

Parameters:

• src (Surface) – Input surface to be processed

• dst (Surface) – Output surface to store the result

Returns:

Tuple containing: - success (bool): True if conversion was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the conversion fails

RunAsync(self: python_vali._python_vali.PySurfaceUD, src: python_vali._python_vali.Surface, dst: python_vali._python_vali.Surface) → tuple[bool, python_vali._python_vali.TaskExecInfo]

Convert input Surface asynchronously.

Processes the input surface and stores the result in the output surface. This method returns immediately without waiting for the conversion to complete.

Parameters:

• src (Surface) – Input surface to be processed

• dst (Surface) – Output surface to store the result

Returns:

Tuple containing: - success (bool): True if conversion was successful, False otherwise - info (TaskExecInfo): Detailed execution information

Return type:

tuple[bool, TaskExecInfo]

Raises:

RuntimeError – If the conversion fails

property Stream

Get the CUDA stream associated with this instance.

Returns the handle to the CUDA stream used for processing.

Returns:

CUDA stream handle

Return type:

int

static SupportedFormats() → list[tuple[python_vali._python_vali.PixelFormat, python_vali._python_vali.PixelFormat]]

Get list of supported pixel format conversions.

Returns a list of tuples containing supported input and output pixel format pairs that can be processed by the upsampler-downscaler.

Returns:

List of tuples containing supported (input_format, output_format) pairs

Return type:

list[tuple[Pixel_Format, Pixel_Format]]

class python_vali._python_vali.SeekContext

Context object for video frame seeking operations.

property seek_frame

Target frame number for seeking.

The frame number to seek to when using frame-based seeking. This is a 0-based index into the video stream.

property seek_tssec

Target timestamp for seeking.

The timestamp in seconds to seek to when using timestamp-based seeking.

python_vali._python_vali.SetFFMpegLogLevel(level: python_vali._python_vali.FfmpegLogLevel) → None

Set the logging level for FFmpeg operations.

Parameters:

level (FfmpegLogLevel) – Logging level to set (e.g., ERROR, WARNING, INFO)

class python_vali._python_vali.StreamParams

Video stream parameters container

property avg_fps

Average frame rate of the stream

property bit_rate

Stream bitrate in bits per second

property codec_id

Codec identifier

property color_range

Color range of the stream

property color_space

Color space of the stream

property duration_sec

Stream duration in seconds

property fourcc

FourCC code identifying the codec

property fps

Nominal frame rate of the stream

property height

Height of the video stream in pixels

property level

Codec level identifier

property num_frames

Total number of frames in the stream

property profile

Codec profile identifier

property start_time

Stream start time in stream timebase units

property start_time_sec

Stream start time in seconds

property time_base

Time base of the stream (1/fps)

property width

Width of the video stream in pixels

class python_vali._python_vali.Surface

Image stored in vRAM. Consists of 1+ SurfacePlane(s).

Clone(self: python_vali._python_vali.Surface) → python_vali._python_vali.Surface

Create a deep copy of the surface.

Allocates new CUDA memory and copies all surface data. The returned object is managed by the Python interpreter.

Returns:

A new surface containing a copy of the data

Return type:

Surface

property Format

Get the pixel format of the surface.

Returns:

Pixel format of the surface

Return type:

Pixel_Format

property Height

Get the height of the first plane in pixels.

Returns:

Height of the first plane in pixels

Return type:

int

property HostSize

Get the total amount of host memory needed for device-to-host copy.

This is the total size in bytes required to store all planes of the surface in host memory, taking into account the pitch and height of each plane.

Returns:

Required host memory size in bytes

Return type:

int

property IsEmpty

Check if the surface has allocated memory.

Returns:

True if the surface has no allocated memory, False otherwise

Return type:

bool

property IsOwnMemory

Check if the surface owns its memory.

Returns:

True if the surface owns its memory, False if it only references memory owned by another object

Return type:

bool

static Make(*args, **kwargs)

Overloaded function.

1. Make(format: python_vali._python_vali.PixelFormat, width: int, height: int, gpu_id: int) -> python_vali._python_vali.Surface

   Create a new surface with the specified parameters.

   Allocates a new surface with the given pixel format and dimensions on the specified GPU. The surface will be managed by the Python interpreter.

   param format:

   Pixel format for the new surface

   type format:

   Pixel_Format

   param width:

   Width of the surface in pixels

   type width:

   int

   param height:

   Height of the surface in pixels

   type height:

   int

   param gpu_id:

   ID of the GPU to allocate memory on

   type gpu_id:

   int

   return:

   New surface with allocated memory

   rtype:

   Surface

   raises RuntimeError:

   If memory allocation fails

2. Make(format: python_vali._python_vali.PixelFormat, width: int, height: int, context: int) -> python_vali._python_vali.Surface

   Constructor method.

   param format:

   target pixel format

   param width:

   width in pixels

   param height:

   height in pixels

   param context:

   CUDA contet to use

property NumPlanes

Get the number of planes in the surface.

Different pixel formats may have different numbers of planes. For example, RGB has 1 plane while YUV420 has 3 planes.

Returns:

Number of planes in the surface

Return type:

int

property Pitch

Get the pitch (stride) of the first plane in bytes.

The pitch represents the number of bytes between the start of consecutive rows in the first plane. This may be larger than the width * element size due to memory alignment requirements.

Returns:

Pitch of the first plane in bytes

Return type:

int

property Planes

Get SurfacePlane reference

Parameters:

plane – SurfacePlane index

property Shape

Get the numpy-like shape of the surface.

For multi-plane formats (like YUV420), returns the total memory size. The shape represents the dimensions of the surface data.

Returns:

Tuple containing the dimensions of the surface

Return type:

tuple

property Width

Get the width of the first plane in pixels.

Returns:

Width of the first plane in pixels

Return type:

int

static from_cai(dict: object, format: python_vali._python_vali.PixelFormat = <PixelFormat.RGB: 2>) → python_vali._python_vali.Surface

DLPack: Make Surface from CAI, don not own memory.

Parameters:

• dict – dictionary which corresponds to CUDA Array Interface specs.

• fmt – pixel format, by default python_vali.PixelFormat.RGB

Returns:

Surface

Return type:

python_vali.Surface

static from_dlpack(capsule: capsule, format: python_vali._python_vali.PixelFormat = <PixelFormat.RGB: 2>) → python_vali._python_vali.Surface

DLPack: Make Surface from dlpack, don not own memory.

Parameters:

• capsule – capsule object with manager dltensor inside

• fmt – pixel format, by default python_vali.PixelFormat.RGB

Returns:

Surface

Return type:

python_vali.Surface

class python_vali._python_vali.SurfacePlane

Continious 2D chunk of memory stored in vRAM which represents single plane / channel of video frame. It supports DLPack specification.

property ElemSize

Get the size of each element in the surface plane in bytes.

Returns:

Size of each element in bytes

Return type:

int

property GpuMem

Get the CUDA device pointer to the surface plane data.

Returns:

CUDA device pointer to the plane’s data

Return type:

int

property Height

Get the height of the surface plane in pixels.

Returns:

Height of the plane in pixels

Return type:

int

property HostFrameSize

Get the amount of host memory needed to store this surface plane.

This is the total size in bytes required to store the plane’s data in host memory, taking into account the pitch and height.

Returns:

Required host memory size in bytes

Return type:

int

property Pitch

Get the pitch (stride) of the surface plane in bytes.

The pitch represents the number of bytes between the start of consecutive rows in the surface plane. This may be larger than the width * element size due to memory alignment requirements.

Returns:

Pitch of the plane in bytes

Return type:

int

property Width

Get the width of the surface plane in pixels.

Returns:

Width of the plane in pixels

Return type:

int

class python_vali._python_vali.TaskExecDetails

Container for task execution status and information

property info

Detailed execution information (TaskExecInfo enum)

property message

Optional error or status message

property status

Execution status (TaskExecStatus enum)

class python_vali._python_vali.TaskExecInfo

Members:

SUCCESS : Success

FAIL : Fail

END_OF_STREAM : End of file

MORE_DATA_NEEDED : More data needed to complete

BIT_DEPTH_NOT_SUPPORTED : Bit depth isn’t supported

INVALID_INPUT : Invalid input

UNSUPPORTED_FMT_CONV_PARAMS : Unsupported color conversion parameters

NOT_SUPPORTED : Unsupported feature

RES_CHANGE : Video resolution change happened

SRC_DST_SIZE_MISMATCH : Input and output size mismatch

SRC_DST_FMT_MISMATCH : Input and output pixel format mismatch

property name