savant_rs.picasso

class savant_rs.picasso.Av1DgpuProps(bitrate=None, control_rate=None, iframeinterval=None, idrinterval=None, preset=None, tuning_info=None, qp_range=None, max_bitrate=None, vbv_buf_size=None, vbv_init=None, cq=None, aq=None, temporal_aq=None)

aq

bitrate

control_rate

cq

idrinterval

iframeinterval

max_bitrate

preset

qp_range

temporal_aq

tuning_info

vbv_buf_size

vbv_init

class savant_rs.picasso.CallbackInvocationOrder

Controls when the on_gpumat callback fires relative to Skia rendering.

GpuMatSkia = CallbackInvocationOrder.GpuMatSkia

GpuMatSkiaGpuMat = CallbackInvocationOrder.GpuMatSkiaGpuMat

SkiaGpuMat = CallbackInvocationOrder.SkiaGpuMat

static from_name(name): Create from string name.

class savant_rs.picasso.Callbacks(on_encoded_frame=None, on_bypass_frame=None, on_render=None, on_object_draw_spec=None, on_gpumat=None, on_eviction=None)

Aggregate holder for all optional Python callbacks.

on_bypass_frame

on_encoded_frame

on_eviction

on_gpumat

on_object_draw_spec

on_render

class savant_rs.picasso.CodecSpec

Describes what to do with each incoming frame for a given source.

This is a tagged union exposed via factory static methods:

CodecSpec.drop_frames() – discard frames entirely.
CodecSpec.bypass() – pass frames through without encoding.
CodecSpec.encode(transform, encoder) – transform + optional render + encode.

static bypass(): Pass the frame through without encoding – only transform bboxes back to initial coordinates.

static drop_frames(): Discard the frame entirely.

static encode(transform, encoder): GPU-transform the frame to a target resolution, optionally render Skia overlays, then encode.

is_bypass: True when this spec bypasses encoding.

is_drop: True when this spec drops frames.

is_encode: True when this spec encodes frames.

class savant_rs.picasso.ConditionalSpec(encode_attribute=None, render_attribute=None)

Attribute-based gates for conditional processing.

When set, the pipeline checks whether the frame carries the specified attribute before proceeding with the corresponding stage.

encode_attribute: Attribute (namespace, name) the frame must carry to be encoded. None means unconditional.

render_attribute: Attribute (namespace, name) the frame must carry for the Skia rendering stage to run. None means unconditional.

class savant_rs.picasso.DgpuPreset

P1 = DgpuPreset.P1

P2 = DgpuPreset.P2

P3 = DgpuPreset.P3

P4 = DgpuPreset.P4

P5 = DgpuPreset.P5

P6 = DgpuPreset.P6

P7 = DgpuPreset.P7

static from_name(name)

class savant_rs.picasso.EncoderConfig(codec, width, height)

encoder_params

format(f): Builder method: set the video format.

fps(num, den): Builder method: set the framerate.

fps_den

fps_num

gpu_id(id): Builder method: set the GPU device ID.

mem_type(mt): Builder method: set the memory type.

properties(props): Builder method: set encoder properties.

class savant_rs.picasso.EncoderProperties

static av1_dgpu(props)

static h264_dgpu(props)

static h264_jetson(props)

static hevc_dgpu(props)

static hevc_jetson(props)

static jpeg(props)

static png(props): Create PNG encoder properties (CPU-based, gst-plugins-good).

class savant_rs.picasso.EvictionDecision

Decision returned by the OnEviction callback.

Construct via the factory static methods [keep_for], [terminate], or [terminate_immediately].

static keep_for(secs): Keep the source alive for at least secs more seconds.

static terminate(): Drain the encoder (send EOS) then terminate the worker.

static terminate_immediately(): Terminate the worker immediately without draining.

class savant_rs.picasso.GeneralSpec(name='picasso', idle_timeout_secs=30, inflight_queue_size=8)

Global defaults for the Picasso engine.

idle_timeout_secs: Default idle timeout in seconds before a source is considered for eviction.

inflight_queue_size: Capacity of the per-worker inflight message queue.

name: Optional name for this engine instance, used internally for logging and future extensibility.

class savant_rs.picasso.H264DgpuProps(bitrate=None, control_rate=None, profile=None, iframeinterval=None, idrinterval=None, preset=None, tuning_info=None, qp_range=None, const_qp=None, init_qp=None, max_bitrate=None, vbv_buf_size=None, vbv_init=None, cq=None, aq=None, temporal_aq=None, extended_colorformat=None)

aq

bitrate

const_qp

control_rate

cq

extended_colorformat

idrinterval

iframeinterval

init_qp

max_bitrate

preset

profile

qp_range

temporal_aq

tuning_info

vbv_buf_size

vbv_init

class savant_rs.picasso.H264JetsonProps(bitrate=None, control_rate=None, profile=None, iframeinterval=None, idrinterval=None, preset_level=None, peak_bitrate=None, vbv_size=None, qp_range=None, quant_i_frames=None, quant_p_frames=None, ratecontrol_enable=None, maxperf_enable=None, two_pass_cbr=None, num_ref_frames=None, insert_sps_pps=None, insert_aud=None, insert_vui=None, disable_cabac=None)

bitrate

control_rate

disable_cabac

idrinterval

iframeinterval

insert_aud

insert_sps_pps

insert_vui

maxperf_enable

num_ref_frames

peak_bitrate

preset_level

profile

qp_range

quant_i_frames

quant_p_frames

ratecontrol_enable

two_pass_cbr

vbv_size

class savant_rs.picasso.H264Profile

BASELINE = H264Profile.BASELINE

HIGH = H264Profile.HIGH

HIGH444 = H264Profile.HIGH444

MAIN = H264Profile.MAIN

static from_name(name)

class savant_rs.picasso.HevcDgpuProps(bitrate=None, control_rate=None, profile=None, iframeinterval=None, idrinterval=None, preset=None, tuning_info=None, qp_range=None, const_qp=None, init_qp=None, max_bitrate=None, vbv_buf_size=None, vbv_init=None, cq=None, aq=None, temporal_aq=None, extended_colorformat=None)

aq

bitrate

const_qp

control_rate

cq

extended_colorformat

idrinterval

iframeinterval

init_qp

max_bitrate

preset

profile

qp_range

temporal_aq

tuning_info

vbv_buf_size

vbv_init

class savant_rs.picasso.HevcJetsonProps(bitrate=None, control_rate=None, profile=None, iframeinterval=None, idrinterval=None, preset_level=None, peak_bitrate=None, vbv_size=None, qp_range=None, quant_i_frames=None, quant_p_frames=None, ratecontrol_enable=None, maxperf_enable=None, two_pass_cbr=None, num_ref_frames=None, enable_lossless=None)

bitrate

control_rate

enable_lossless

idrinterval

iframeinterval

maxperf_enable

num_ref_frames

peak_bitrate

preset_level

profile

qp_range

quant_i_frames

quant_p_frames

ratecontrol_enable

two_pass_cbr

vbv_size

class savant_rs.picasso.HevcProfile

FREXT = HevcProfile.FREXT

MAIN = HevcProfile.MAIN

MAIN10 = HevcProfile.MAIN10

static from_name(name)

class savant_rs.picasso.JetsonPresetLevel

DISABLED = JetsonPresetLevel.DISABLED

FAST = JetsonPresetLevel.FAST

MEDIUM = JetsonPresetLevel.MEDIUM

SLOW = JetsonPresetLevel.SLOW

ULTRA_FAST = JetsonPresetLevel.ULTRA_FAST

static from_name(name)

class savant_rs.picasso.JpegProps(quality=None)

quality

class savant_rs.picasso.ObjectDrawSpec

Static per-object draw specifications keyed by (namespace, label).

Python users insert [crate::draw_spec::ObjectDraw] instances via [insert]; the inner Rust value is cloned through the memory_handle mechanism exposed by savant_core_py.

insert(namespace, label, draw): Insert a draw specification for the given (namespace, label) pair.

is_empty(): Returns True if no draw specs have been inserted.

len(): Number of (namespace, label) entries.

lookup(namespace, label): Look up the draw spec for an exact (namespace, label) match.

class savant_rs.picasso.OutputMessage

Output produced by the encoding pipeline or bypass mode.

Use the is_video_frame / is_eos properties to discriminate, then as_video_frame() or as_eos() to extract the payload.

as_eos()

Extract the EndOfStream signal.

Raises:: RuntimeError – If this is a video-frame output, not EOS.

as_video_frame()

Extract the VideoFrame.

Raises:: RuntimeError – If this is an EOS output, not a video frame.

is_eos: True when this output is an end-of-stream signal.

is_video_frame: True when this output carries a video frame.

class savant_rs.picasso.PicassoEngine(general, callbacks)

The main entry point for the Picasso frame-processing pipeline.

Manages per-source worker threads, a watchdog for idle-source eviction, and dispatches frames to the appropriate worker.

remove_source_spec(source_id): Remove the spec for a source. The worker will be shut down.

send_eos(source_id): Send an end-of-stream signal to a specific source.

send_frame(source_id, frame, buf, src_rect=None)

Submit a video frame for processing.

Accepts one of:

SurfaceView — the preferred input type.
Any object with __cuda_array_interface__ (CuPy array, PyTorch CUDA tensor) — automatically wrapped in a SurfaceView.
GstBuffer or raw int pointer (legacy API) — the buffer is wrapped with SurfaceView.wrap (no surface parameter extraction).

Parameters:

source_id (str) – Source identifier.
frame (VideoFrame) – Frame metadata.
buf – Surface data (SurfaceView, __cuda_array_interface__ object, GstBuffer, or int).
src_rect (Rect | None) – Optional per-frame source crop.

Raises:

RuntimeError – If the engine is shut down.
TypeError – If buf is not a supported type.
ValueError – If buf is null.

set_source_spec(source_id, spec): Set or replace the processing spec for a specific source.

shutdown()

Gracefully shut down all workers and the watchdog.

Releases the GIL while joining worker threads so that any pending Python callbacks (on_encoded_frame, on_render, etc.) can acquire the GIL and complete without deadlocking.

class savant_rs.picasso.Platform

DGPU = Platform.DGPU

JETSON = Platform.JETSON

static from_name(name)

class savant_rs.picasso.PngProps(compression_level=None)

PNG encoder properties (pngenc, CPU-based, gst-plugins-good).

compression_level

6). Higher = smaller file, slower.

Type:: PNG compression level (0–9, default

class savant_rs.picasso.RateControl

CONSTANT_BITRATE = RateControl.CONSTANT_BITRATE

CONSTANT_QP = RateControl.CONSTANT_QP

VARIABLE_BITRATE = RateControl.VARIABLE_BITRATE

static from_name(name)

class savant_rs.picasso.SourceSpec(codec=None, conditional=None, draw=None, font_family=Ellipsis, idle_timeout_secs=None, use_on_render=False, use_on_gpumat=False, callback_order=Ellipsis)

Complete per-source configuration combining all spec facets.

callback_order

codec: What to do with frames (drop / bypass / encode).

conditional: Attribute gates for conditional processing.

draw: Static draw specs for object overlays.

font_family

idle_timeout_secs

use_on_gpumat

use_on_render

class savant_rs.picasso.TuningPreset

HIGH_QUALITY = TuningPreset.HIGH_QUALITY

LOSSLESS = TuningPreset.LOSSLESS

LOW_LATENCY = TuningPreset.LOW_LATENCY

ULTRA_LOW_LATENCY = TuningPreset.ULTRA_LOW_LATENCY

static from_name(name)