Python API for Savant GStreamer

savant_gstreamer — GStreamer utilities for Savant pipelines.

Provides the Codec enum and Mp4Muxer for muxing encoded video bitstreams into MP4 containers.

Quick start:

from savant_gstreamer import Codec, Mp4Muxer

muxer = Mp4Muxer(Codec.HEVC, "/tmp/out.mp4", fps_num=30)
muxer.push(encoded_bytes, pts_ns=0, duration_ns=33_333_333)
muxer.finish()
class savant_gstreamer.Codec

Python enum for video codecs.

  • H264 — H.264 / AVC.

  • HEVC — H.265 / HEVC.

  • JPEG — Motion JPEG.

  • AV1 — AV1.

AV1 = Codec.AV1
H264 = Codec.H264
HEVC = Codec.HEVC
JPEG = Codec.JPEG
static from_name(name)

Parse a codec from a string name.

Accepted names (case-insensitive): h264, hevc, h265, jpeg, av1.

Parameters:

name (str) – Codec name.

Returns:

The parsed codec.

Return type:

Codec

Raises:

ValueError – If the name is not recognized.

name()

Return the canonical name of this codec.

class savant_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_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.