savant_rs.picasso

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, on_stream_reset=None)

Aggregate holder for all optional Python callbacks.

on_bypass_frame

on_encoded_frame

on_eviction

on_gpumat

on_object_draw_spec

on_render

on_stream_reset

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.

Raises ValueError when the supplied [PyEncoderConfig] carries encoder_params whose codec or build-platform variant does not match the configured codec / current build target.

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.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, pts_reset_policy=None)

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.

pts_reset_policy: Policy for handling non-monotonic (decreasing) PTS values.

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.PtsResetPolicy

Policy for handling non-monotonic (decreasing) PTS values.

Construct via the factory static methods [eos_on_decreasing_pts] or [recreate_on_decreasing_pts].

static eos_on_decreasing_pts()

Emit a synthetic EOS before recreating the encoder (default).

Downstream sees a clean EOS boundary between old and new streams.

static recreate_on_decreasing_pts(): Silently recreate the encoder without emitting EOS.

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.StreamResetReason

Reason the worker’s encoder was reset.

Construct via the factory static method [pts_decreased].

last_pts_ns: The PTS of the last successfully accepted frame (nanoseconds).

new_pts_ns: The PTS of the incoming frame that triggered the reset (nanoseconds).