python_vali.PyNvEncoder

class python_vali.PyNvEncoder

HW-accelerated video encoder which uses Nvenc.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: python_vali._python_vali.PyNvEncoder, settings: dict[str, str], gpu_id: int, format: python_vali._python_vali.PixelFormat = <PixelFormat.NV12: 3>, verbose: bool = False) -> None

   Create a new hardware-accelerated video encoder.

   Initializes an NVIDIA hardware-accelerated video encoder with the specified settings and pixel format. The encoder uses NVIDIA’s NVENC hardware encoder for efficient video compression.

   param settings:

   Dictionary containing NVENC encoder settings (e.g., bitrate, codec, etc.)

   type settings:

   dict[str, str]

   param gpu_id:

   ID of the GPU to use for encoding

   type gpu_id:

   int

   param format:

   Pixel format for input frames (default: NV12)

   type format:

   Pixel_Format

   param verbose:

   Whether to output detailed logging information

   type verbose:

   bool

   raises RuntimeError:

   If encoder initialization fails

2. __init__(self: python_vali._python_vali.PyNvEncoder, settings: dict[str, str], gpu_id: int, stream: int, format: python_vali._python_vali.PixelFormat = <PixelFormat.NV12: 3>, verbose: bool = False) -> None

   Create a new hardware-accelerated video encoder with a specific CUDA stream.

   Initializes an NVIDIA hardware-accelerated video encoder with the specified settings, pixel format, and CUDA stream. This constructor allows for more control over CUDA stream management.

   param settings:

   Dictionary containing NVENC encoder settings

   type settings:

   dict[str, str]

   param gpu_id:

   ID of the GPU to use for encoding

   type gpu_id:

   int

   param stream:

   CUDA stream to use for encoding operations

   type stream:

   int

   param format:

   Pixel format for input frames (default: NV12)

   type format:

   Pixel_Format

   param verbose:

   Whether to output detailed logging information

   type verbose:

   bool

   raises RuntimeError:

   If encoder initialization fails

Methods

EncodeSingleSurface(*args, **kwargs)	Overloaded function.
Flush(self, packets)	Flush the encoder's internal buffers.
FlushSinglePacket(self, packets)	Flush the encoder's internal buffers.
Reconfigure(self, settings[, force_idr, ...])	Reconfigure the encoder with new settings.
__init__(*args, **kwargs)	Overloaded function.

Attributes

Capabilities	Get the capabilities of the NVENC encoder.
Format	Get the pixel format of the encoded video stream.
FrameSizeInBytes	Get the size of a single frame in bytes.
Height	Get the height of the encoded video stream.
Width	Get the width of the encoded video stream.

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