savant_rs.gstreamer

class savant_rs.gstreamer.Codec

Video codec tag used on VideoFrame and by savant_rs.gstreamer.Mp4Muxer / Mp4Demuxer.

Registered under both savant_rs.primitives and savant_rs.gstreamer as Codec — the two exports refer to the same class, so equality and isinstance work across modules.

Av1 = Codec.Av1

H264 = Codec.H264

Hevc = Codec.Hevc

Jpeg = Codec.Jpeg

Png = Codec.Png

RawNv12 = Codec.RawNv12

RawRgb = Codec.RawRgb

RawRgba = Codec.RawRgba

SwJpeg = Codec.SwJpeg

Vp8 = Codec.Vp8

Vp9 = Codec.Vp9

static from_name(name)

Parse a codec from a string name.

Accepted names (case-insensitive): h264, hevc, h265, jpeg, swjpeg, av1, png, vp8, vp9, raw_rgba, raw_rgb, raw_nv12.

name(): Canonical wire name (e.g. "hevc", "swjpeg").

class savant_rs.gstreamer.DemuxedPacket

A single demuxed elementary stream packet.

data

Encoded bitstream payload.

Type:: bytes

pts_ns

Presentation timestamp in nanoseconds.

Type:: int

dts_ns

Decode timestamp in nanoseconds, if present.

Type:: int | None

duration_ns

Frame duration in nanoseconds, if present.

Type:: int | None

is_keyframe

Whether this packet is a keyframe (sync point).

Type:: bool

data: Encoded bitstream payload.

dts_ns: Decode timestamp in nanoseconds, or None.

duration_ns: Frame duration in nanoseconds, or None.

is_keyframe: Whether this packet is a keyframe.

pts_ns: Presentation timestamp in nanoseconds.

class savant_rs.gstreamer.FlowResult

CustomError = FlowResult.CustomError

CustomError1 = FlowResult.CustomError1

CustomError2 = FlowResult.CustomError2

CustomSuccess = FlowResult.CustomSuccess

CustomSuccess1 = FlowResult.CustomSuccess1

CustomSuccess2 = FlowResult.CustomSuccess2

Eos = FlowResult.Eos

Error = FlowResult.Error

Flushing = FlowResult.Flushing

NotLinked = FlowResult.NotLinked

NotNegotiated = FlowResult.NotNegotiated

NotSupported = FlowResult.NotSupported

Ok = FlowResult.Ok

class savant_rs.gstreamer.InvocationReason

Buffer = InvocationReason.Buffer

IngressMessageTransformer = InvocationReason.IngressMessageTransformer

SinkEvent = InvocationReason.SinkEvent

SourceEvent = InvocationReason.SourceEvent

StateChange = InvocationReason.StateChange

class savant_rs.gstreamer.Mp4Demuxer(input_path, result_callback, parsed=True)

Callback-based GStreamer pipeline: filesrc -> qtdemux -> queue -> appsink.

Reads encoded packets from an MP4 (QuickTime) container and delivers them through the result_callback supplied at construction.

When parsed=True (the default), codec-specific parsers are inserted so that H.264/HEVC output uses byte-stream (Annex-B) format instead of container-native AVC/HEV1 length-prefixed NALUs.

The pipeline starts immediately on construction. Use wait() to block until all packets have been delivered (EOS) or an error occurs.

Threading: the callback fires on GStreamer’s internal streaming thread. Do not call finish() from within the callback.

Parameters:

input_path (str) – Filesystem path to the .mp4 file.
result_callback – Callable[[Mp4DemuxerOutput], None] invoked for every packet, EOS, or error.
parsed (bool) – If True, insert parsers for byte-stream output. Defaults to True.

Example:

from savant_rs.gstreamer import Mp4Demuxer

packets = []
def on_output(out):
    if out.is_packet:
        packets.append(out.as_packet())

demuxer = Mp4Demuxer("/data/clip.mp4", on_output)
demuxer.wait()
for pkt in packets:
    print(pkt.pts_ns, len(pkt.data))

detected_codec: Auto-detected video codec from the container, or None.

finish()

Shut down the demuxer pipeline.

Safe to call multiple times. After this call, no more callbacks will fire.

Must not be called from within the result_callback.

is_finished: Whether the demuxer has been finalized.

video_info: Auto-detected video-stream metadata, or None if caps have not been observed yet.

wait()

Block until the demuxer reaches EOS, encounters an error, or finish() is called.

The GIL is released while waiting so the callback can fire.

wait_for_video_info(timeout_ms)

Block until VideoInfo is known, the pipeline terminates, or the timeout expires.

Parameters:: timeout_ms (int) – Timeout in milliseconds.
Returns:: None on timeout or if the pipeline ended before caps were observed.
Return type:: Optional[VideoInfo]

The GIL is released while waiting.

wait_timeout(timeout_ms)

Block until the demuxer finishes or the timeout expires.

Parameters:: timeout_ms (int) – Timeout in milliseconds.
Returns:: True if finished, False on timeout.
Return type:: bool

class savant_rs.gstreamer.Mp4DemuxerOutput

Callback payload from Mp4Demuxer.

Use the is_* properties to determine the variant, then call the corresponding as_* method to get a typed value.

Variants:

StreamInfo - auto-detected VideoInfo.
Packet — a demuxed DemuxedPacket.
Eos — end of stream; all packets have been delivered.
Error — a pipeline error message (string).

as_error_message(): Return the error message string, or None.

as_packet(): Downcast to DemuxedPacket, or None.

as_stream_info(): Downcast to VideoInfo, or None.

is_eos: True if this is an end-of-stream marker.

is_error: True if this is an error variant.

is_packet: True if this is a DemuxedPacket variant.

is_stream_info: True if this is a VideoInfo variant.

class savant_rs.gstreamer.Mp4Muxer(codec, output_path, fps_num=30, fps_den=1)

Minimal GStreamer pipeline: appsrc -> parser -> qtmux -> filesink.

Accepts raw encoded frames (H.264, HEVC, JPEG, AV1) and writes them into an MP4 (QuickTime) container.

Parameters:

codec (Codec | str) – Video codec — a Codec enum value or a string name ("h264", "hevc" / "h265", "jpeg", "av1").
output_path (str) – Filesystem path for the output .mp4 file.
fps_num (int) – Framerate numerator (default 30).
fps_den (int) – Framerate denominator (default 1).

Example:

from savant_rs.gstreamer import Mp4Muxer, Codec

muxer = Mp4Muxer(Codec.Hevc, "/tmp/out.mp4", fps_num=30)
muxer.push(b"\\x00\\x00\\x00\\x01...", pts_ns=0,
           dts_ns=0, duration_ns=33_333_333)
muxer.finish()

finish()

Send EOS and shut down the muxer pipeline.

Safe to call multiple times. After this call, push() will raise.

is_finished: Whether the muxer has been finalized.

push(data, pts_ns, dts_ns=None, duration_ns=None)

Push an encoded frame into the muxer pipeline.

Parameters:

data (bytes) – Raw encoded bitstream for a single frame.
pts_ns (int) – Presentation timestamp in nanoseconds.
dts_ns (int | None) – Optional decode timestamp in nanoseconds. Required for streams with B-frames where DTS != PTS.
duration_ns (int | None) – Optional frame duration in nanoseconds.

Raises:

RuntimeError – On push failure or if the muxer has been finalized.

class savant_rs.gstreamer.VideoInfo

Video-stream metadata extracted from the MP4 container at demux time.

codec

Detected video codec.

Type:: Codec

width

Encoded frame width in pixels.

Type:: int

height

Encoded frame height in pixels.

Type:: int

framerate_num

Framerate numerator (0 if unknown).

Type:: int

framerate_den

Framerate denominator (1 if unknown).

Type:: int

Dimensions are the encoded values - any QuickTime display-orientation transform is NOT applied here.

codec

framerate_den

framerate_num

height

width