`px_core.media`

Media feeds, sessions, and streaming components.

Module Contents

Classes

`AVContainer`	The container format for the output file
`ConnectionState`	Enumeration for a connection state
`AudioCodec`	The audio codec to use for the output file
`VideoCodec`	The video codec to use for the output file
`MediaSessionFeedType`	Enumerated constant for a media session feed type
`PxMediaErrorCode`	Custom error codes for PxMedia operations, namely Media Server functions.
`BaseMedia`	Base media format type
`MediaType`	Video media types
`GstStructure`	Opaque SDK handle — no Python attributes; pass through only.
`FeedBase`	Base feed object that all feed objects inherit from
`AVOutputFeedFile`	An output feed component that writes video (and optionally audio) to given local file(s).
`AdaptiveQuality`	Adaptive feed quality is a floating point value in the range 0.1
`FeedRequest`	A common base class for feed events and requests
`RequestAdaptiveQuality`	A feed request with an adaptive quality value
`AudioFeedStageComponent`	Base class for audio feed stage components
`AudioFeedStageSequence`	A sequence of audio feed stage components
`AudioInputFeedComponent`	Base class for audio input feed components
`AudioInputComponentSilence`	An audio input feed component that simply sends silence.
`AudioInputFeedAuto`	An audio input component that chooses an appropriate audio source to use.
`AudioInputFeedInter`	An audio input component that accepts audio from a named inter channel.
`AudioInputFeedTestSignal`	An audio input feed component that simply sends a regular beat as an audio signal. The wave type is configurable. If not specified it defaults to ticks.
`AudioOutputFeedComponent`	Base class for audio output feed components
`AudioOutputComponentNull`	An audio output feed component that "swallows" audio output without producing any output.
`AudioOutputFeedAuto`	An audio input component that chooses an appropriate audio output to use.
`AudioOutputFeedInter`	An audio output component that sends audio to a named inter channel.
`AudioOutputFeedWavescope`	An audio output feed component that displays the audio input as a simple waveform in a window. Note that there is a known issue with this component on Ubuntu 24.04 with GStreamer 1.24.2; see full documentation for details.
`AudioPeerRtpDecodeFeedComponent`	Base class for audio peer decoder feed components
`AudioPeerRtpDecodeFeedOpus`	A audio feed component for specifying Opus decoding for SRTP.
`AudioPeerRtpEncodeFeedComponent`	Base class for audio peer encoder feed components
`AudioPeerRtpEncodeFeedOpus`	A audio feed component for specifying Opus encoding for SRTP.
`AudioStageVolume`	Audio feed stage for adjusting audio volume using GStreamer volume element
`AudioStageWebRtcDsp`	Audio feed stage for applying WebRTC DSP effects.
`AudioWebRtcEncodeFeedComponent`	Base class for audio WebRTC encoder feed components
`AudioWebRtcEncodeFeedOpus`	An audio feed component for specifying audio encoding using [Opus](https://opus-codec.org/).
`BitRate`	Encapsulates a bit rate value with varying units of bits (bits, kbits, etc.) per second.
`Configuration`	Singleton for configuring PxMedia module settings
`FeedDiagnosticsRequest`	A request to enable diagnostics on a feed
`FeedPerformanceAssessor`	A rule for assessing performance and quality
`FeedPacketLossAssessor`	A feed performance assessment helper that looks at packet loss
`FeedQualityMonitor`	A class that checks the performance of a set of adaptive feeds, and applies quality requests to adapt their performance accordingly.
`FrameRate`	Encapsulates a formal frame rate value
`H264VideoEncoderComponent`	Base class for H.264 video encoder feed components
`H264VaapiEncoderComponent`	Encapsulates a VA-API hardware-accelerated H.264 encoder element (vaapih264enc) for use in feeds.
`IFeedFeature`	Base interface common to all feed objects
`FeedFeaturePoster`	Base interface common to all feed objects
`IMediaServerFeedFeature`	The interface common to all media server feeds
`MediaServerFeedFeaturePoster`	The interface common to all media server feeds
`IPeerFeedFeature`	The interface common to all peer feeds
`PeerFeedFeaturePoster`	The interface common to all peer feeds
`MediaServerFeed`	Base class for all feeds that are part of a media server session
`MediaServerFeedStats`	Statistics for a given media feed
`MediaServerIncomingVideoFeed`	A class which manages an incoming video feed in a media server session
`MediaServerOutgoingVideoFeed`	A class which manages a local video feed being shared in a media server session
`MediaServerSession`	Manages audio and video connections to media servers
`MediaServerTwoWayAudioFeed`	A class which manages a two-way audio feed in a media server session
`NetworkQualityMonitor`	A class that checks the performance of a set of feeds and summarises an assessment of the overall network quality.
`PeerFeed`	Base class for all peer session feeds
`PeerLocalAudioFeed`	A peer feed that sends local Audio to the remote peer
`PeerLocalVideoFeed`	A peer feed that sends local video to the remote peer
`PeerRemoteAudioFeed`	A peer feed that receives Audio from the remote peer
`PeerRemoteVideoFeed`	A peer feed that receives video from the remote peer
`PeerSession`	A peer session represents a connection between two peers
`PxMediaErrorCategory`	Error category for PxMediaErrorCode
`SrtFeedStats`	A structure representing SRT feed statistics.
`SrtFeedStatsRequest`	A feed request to obtain SRT feed statistics.
`UtilityAudioLocalFeed`	A simple utility audio feed
`UtilityVideoLocalFeed`	A simple utility video feed
`VideoAdaptiveFrameRateComponent`	A video processing stage that alters the video frame rate adaptively
`VideoAdaptivePropertyComponent`	Base class for video components for adaptive properties (e.g. frame rate, resolution)
`VideoAdaptiveResolutionComponent`	A video processing stage that alters the video resolution adaptively
`VideoCapabilities`	Provide capability settings that are common to all video media types
`VideoFeedStageComponent`	Base class for video feed stage components
`VideoFeedStageSequence`	A sequence of video feed stage components
`VideoInputFeedComponent`	Base class for video input feed components
`VideoFormattedInputFeedComponent`	Base class for video formatted input feed components
`VideoInputFeedFile`	A video input feed component that reads a video or image file as the video feed.
`VideoInputFeedInter`	A video input feed component that accepts video from a named inter channel.
`VideoInputFeedPipewire`	A video input feed component capturing a pipewire video source.
`VideoInputFeedSharedMemory`	A video input feed component that reads raw video from a shared memory area using GStreamer's `shmsrc` element.
`VideoInputFeedTestPattern`	A video input feed component that sends a "test card" pattern as the video feed.
`VideoInputFeedUdp`	A video input feed using a UDP source
`VideoInputFeedV4Linux2`	A video input feed component using a [Video4Linux2](https://en.wikipedia.org/wiki/Video4Linux) device.
`VideoInputFeedXImage`	A video input feed component capturing an X desktop or window.
`VideoOutputFeedComponent`	Base class for video output feed components
`VideoOutputComponentNull`	A placeholder video output feed component that does not actually output video.
`VideoOutputFeedAuto`	A video output component that chooses an appropriate output to use.
`VideoOutputFeedInter`	A video output component that outputs video to a named inter channel.
`VideoOutputFeedSharedMemory`	A video output feed component that writes raw video to a shared memory area using GStreamer's `shmsink` element.
`VideoOutputFeedUdp`	A video output feed component that sends video output to a given UDP port.
`VideoOutputFeedV4Linux2`	A video output feed component that sends video output to a V4L2 loopback device.
`VideoStageCrop`	A processing stage that applies cropping to the video
`VideoStageFaceBlur`	A processing stage that applies basic Open CV-based face blurring to a video
`VideoStageFrameRate`	A processing stage that alters the video frame rate
`VideoStageGaussianBlur`	A processing stage that applies a Gaussian blur to a video feed
`VideoStagePrivacy`	A video stage which allows the video to be obscured at runtime by sending a feed request. Video is obscured by setting the brightness and saturation of the video to fixed values that produce a solid black output, ensuring that no pixel data survives. Pixel data destruction is validated in unit tests, which are automatically run before every release.
`VideoStageResize`	A processing stage that resizes a video feed
`VideoStageRotateFlip`	A processing stage that applies a rotation to or flips a video
`VideoStageTextOverlay`	A processing stage that overlays text on a video
`VideoWebRtcEncodeFeedComponent`	Base class for video WebRTC encoder feed components
`VideoWebRtcEncodeFeedH264`	A video feed component for specifying H264 encoding for WebRTC.
`VideoWebRtcEncodeFeedVp8`	A video feed component for specifying VP8 encoding for WebRTC.
`WebRtcStats`	Statistics gather from a WebRTC feed
`WebRtcStatsRequest`	A feed request to obtain SRT feed statistics.
`X264EncoderFeedComponent`	Encapsulates X264 encoder element for use in feed components
`VideoPeerRtpEncodeFeedComponent`	Class for video Peer encoder feed components
`VideoPeerRtpDecodeFeedComponent`	Class for video Peer decoder feed components
`PeerSrtpEncryptFeedComponent`	Class for SRTP-based peer feed encryption components
`PeerSrtpDecryptFeedComponent`	Class for SRTP-based peer feed decryption components
`PeerUdpSinkFeedComponent`	Class for Peer feed Udp Sink component
`PeerUdpSourceFeedComponent`	Class for Peer feed Udp Source component
`AdaptiveFrameRateRule`	Definition for a rule which takes an adaptive quality value and gives back an outcome value
`AdaptiveResolutionRule`	Definition for a rule which takes an adaptive quality value and gives back an outcome value
`AdaptiveMinMaxFrameRateRule`	General adaptive rule which interpolates between a minimum and maximum value of the templated type.
`AdaptiveMinMaxResolutionRule`	General adaptive rule which interpolates between a minimum and maximum value of the templated type.
`FrameRateQualityMapping`	A set of adaptive quality bands, which are used to map quality values to target values of type T
`ResolutionQualityMapping`	A set of adaptive quality bands, which are used to map quality values to target values of type T
`BitRateQualityMapping`	A set of adaptive quality bands, which are used to map quality values to target values of type T

Functions

`media_type_format_to_string`(→ str)
`media_type_from_format_string`(→ MediaType)
`media_type_to_string`(→ str)
`validate_enum_value`(→ Optional[MediaSessionFeedType])

Attributes

`AdaptiveMinMaxRule`
`AdaptiveQualityMapping`
`AdaptiveRule`

class px_core.media.AVContainer

Bases: enum.IntEnum

The container format for the output file

MP4: int = 0

MKV: int = 1

AVI: int = 2

FLV: int = 3

class px_core.media.ConnectionState

Bases: enum.IntEnum

Enumeration for a connection state

READY: int = 0

CONNECTING: int = 1

CONNECTED: int = 2

DISCONNECTING: int = 3

class px_core.media.AudioCodec

Bases: enum.IntEnum

The audio codec to use for the output file

AAC: int = 0

MP3: int = 1

OPUS: int = 2

VORBIS: int = 3

class px_core.media.VideoCodec

Bases: enum.IntEnum

The video codec to use for the output file

H264: int = 0

H265: int = 1

VP8: int = 2

VP9: int = 3

AV1: int = 4

class px_core.media.MediaSessionFeedType

Bases: enum.IntEnum

Enumerated constant for a media session feed type

None_: int = 0

Audio: int = 1

Camera: int = 2

Screen: int = 3

RemoteHand: int = 4

Monitor: int = 5

class px_core.media.PxMediaErrorCode

Bases: enum.IntEnum

Custom error codes for PxMedia operations, namely Media Server functions.

Successful: int = 0

FeedIdNotFound: int = 100

InvalidFeedId: int = 101

FeedRequestUnhandled: int = 102

SessionNotConnected: int = 200

SessionActive: int = 201

InvalidSession: int = 202

SessionNotActive: int = 203

SessionCreateFailed: int = 204

SessionFeedNotFound: int = 205

SessionFeedExists: int = 206

SessionDisconnected: int = 207

NotConnected: int = 200

PluginAttachFailed: int = 300

PluginConnectionActive: int = 301

PluginConnectionClosed: int = 302

CreateMediaRoomFailed: int = 303

JoinMediaRoomFailed: int = 304

WebRtcAnswerFailed: int = 305

WebRtcOfferFailed: int = 306

MediaRoomStartFailed: int = 307

MediaRoomConfigureFailed: int = 308

MediaRoomConfigureError: int = 309

MediaRoomConfigurePubFullError: int = 310

WebRtcCandidateFailed: int = 311

MediaDeviceMetadataInvalid: int = 312

WebSocketError: int = 313

MediaServerHangup: int = 314

MediaServerHangupClosePC: int = 315

NoPipeline: int = 400

PipelineExists: int = 401

PipelineIsStopped: int = 402

PipelineStreamError: int = 403

PipelineParseError: int = 404

PipelineElementNotFound: int = 405

PipelineNoElementName: int = 406

PipelineElementBadProps: int = 407

PipelineBindingInvalid: int = 408

PipelineInputAlreadyAdded: int = 409

PipelineInvalidUUID: int = 410

PipelineElementOperationFailed: int = 411

KeepaliveTimeout: int = 500

ExpectedAck: int = 501

InvalidResponseContent: int = 502

InvalidPeerChannel: int = 600

InvalidEncryptionKey: int = 601

InvalidAdaptiveRule: int = 700

InvalidAdaptiveBand: int = 701

InvalidMediaType: int = 800

InvalidMediaFormat: int = 801

MediaServiceNotConnected: int = 900

MediaServiceStarted: int = 901

MediaServiceConnectFailed: int = 902

MediaServiceDisconnected: int = 903

MediaServiceReconnecting: int = 904

MediaServiceErrorStatus: int = 905

MediaServiceEventInvalid: int = 906

class px_core.media.BaseMedia

Bases: enum.IntEnum

Base media format type

See: https://gstreamer.freedesktop.org/documentation/plugin-development/advanced/media-types.html#table-of-video-types

IMAGE: int = 0

VIDEO_ENCODED: int = 1

VIDEO_XRAW: int = 2

class px_core.media.MediaType

Bases: enum.IntEnum

Video media types

IMAGE: int = 0

IMAGE_JPEG: int = 1

VIDEO_ENCODED: int = 65536

VIDEO_XRAW: int = 131072

VIDEO_XRAW_I420: int = 131073

VIDEO_XRAW_YV12: int = 131074

VIDEO_XRAW_YUY2: int = 131075

VIDEO_XRAW_YVYU: int = 131076

VIDEO_XRAW_UYVY: int = 131077

VIDEO_XRAW_AYUV: int = 131078

VIDEO_XRAW_RGBx: int = 131079

VIDEO_XRAW_BGRx: int = 131080

VIDEO_XRAW_xRGB: int = 131081

VIDEO_XRAW_xBGR: int = 131082

VIDEO_XRAW_RGBA: int = 131083

VIDEO_XRAW_BGRA: int = 131084

VIDEO_XRAW_ARGB: int = 131085

VIDEO_XRAW_ABGR: int = 131086

VIDEO_XRAW_RGB: int = 131087

VIDEO_XRAW_BGR: int = 131088

VIDEO_XRAW_Y41B: int = 131089

VIDEO_XRAW_Y42B: int = 131090

VIDEO_XRAW_Y444: int = 131091

VIDEO_XRAW_v210: int = 131092

VIDEO_XRAW_v216: int = 131093

VIDEO_XRAW_NV12: int = 131094

VIDEO_XRAW_NV21: int = 131095

VIDEO_XRAW_GRAY8: int = 131096

VIDEO_XRAW_GRAY16_BE: int = 131097

VIDEO_XRAW_GRAY16_LE: int = 131098

VIDEO_XRAW_Y16: int = 131099

VIDEO_XRAW_v308: int = 131100

VIDEO_XRAW_IYU2: int = 131101

VIDEO_XRAW_RGB16: int = 131102

VIDEO_XRAW_BGR16: int = 131103

VIDEO_XRAW_RGB15: int = 131104

VIDEO_XRAW_BGR15: int = 131105

VIDEO_XRAW_UYVP: int = 131106

VIDEO_XRAW_A420: int = 131107

VIDEO_XRAW_RGB8P: int = 131108

VIDEO_XRAW_YUV9: int = 131109

VIDEO_XRAW_YVU9: int = 131110

VIDEO_XRAW_IYU1: int = 131111

VIDEO_XRAW_ARGB64: int = 131112

VIDEO_XRAW_AYUV64: int = 131113

VIDEO_XRAW_r210: int = 131114

VIDEO_XRAW_I420_10LE: int = 131115

VIDEO_XRAW_I420_10BE: int = 131116

VIDEO_XRAW_I422_10LE: int = 131117

VIDEO_XRAW_I422_10BE: int = 131118

VIDEO_XRAW_Y444_10BE: int = 131119

VIDEO_XRAW_Y444_10LE: int = 131120

VIDEO_XRAW_GBR: int = 131121

VIDEO_XRAW_GBR_10BE: int = 131122

VIDEO_XRAW_GBR_10LE: int = 131123

VIDEO_XRAW_RGBP: int = 131124

VIDEO_XRAW_BGRP: int = 131125

VIDEO_XRAW_RGBA64_LE: int = 131126

VIDEO_XRAW_RGBA64_BE: int = 131127

VIDEO_XRAW_BGRA64_LE: int = 131128

VIDEO_XRAW_BGRA64_BE: int = 131129

VIDEO_XRAW_ARGB64_LE: int = 131130

VIDEO_XRAW_ARGB64_BE: int = 131131

VIDEO_XRAW_ABGR64_LE: int = 131132

VIDEO_XRAW_ABGR64_BE: int = 131133

VIDEO_XRAW_NV16: int = 131134

VIDEO_XRAW_NV61: int = 131135

VIDEO_XRAW_NV24: int = 131136

VIDEO_XRAW_NV12_64Z32: int = 131137

VIDEO_XRAW_P012_LE: int = 131138

VIDEO_XRAW_P012_BE: int = 131139

VIDEO_XRAW_Y212_LE: int = 131140

VIDEO_XRAW_Y212_BE: int = 131141

VIDEO_XRAW_Y412_LE: int = 131142

VIDEO_XRAW_Y412_BE: int = 131143

class px_core.media.GstStructure: Opaque SDK handle — no Python attributes; pass through only.

class px_core.media.FeedBase

Base feed object that all feed objects inherit from

class FeedBaseProperties(label: str = ...)

Properties that apply to the whole feed

property label: str

id() → str

label() → str

property playing: bool

start_feed() → None

stop_feed() → None

on_feed_started(func: Callable[[FeedBase], None]) → None

on_feed_stopped(func: Callable[[FeedBase, int], None]) → None

get_pipeline_graph() → str

Obtain GStreaming pipeline graph for the feed with all details

Returns:: The graph is returned as a string in the .dot format as an outcome

write_pipeline_graph_to_file(filename: str) → str

Write a pipeline .dot graph to a file with all details

The file name may be absolute or relative, if relative it will use the diagnostics folder from the Configuration

Returns:: The path to the file written

get_pipeline_graph_with_details(details: int) → str

write_pipeline_graph_with_details_to_file(filename: str, details: int) → str

feed_request(request: FeedDiagnosticsRequest) → None: Set feed request (FeedDiagnosticsRequest)

feed_request(request: RequestAdaptiveQuality) → None: Set feed request (RequestAdaptiveQuality)

feed_request(request: VideoStagePrivacy.RequestPrivacy) → None: Set feed request (RequestPrivacy)

feed_request(request: VideoStageTextOverlay.RequestSetText) → None: Set feed request (RequestSetText)

feed_request(request: SrtFeedStatsRequest) → None: Set feed request (SrtFeedStatsRequest)

feed_request(request: WebRtcStatsRequest) → None: Set feed request (WebRtcStatsRequest)

class px_core.media.AVOutputFeedFile

Bases: FeedBase

An output feed component that writes video (and optionally audio) to given local file(s).

This feed component provides properties to specify how the feed is encoded and saved to a file.

class AVOutputFeedFileSettings

Settings for the AVOutputFeedFile

destination_directory(dir: str) → int

Set the directory to save output files to

When empty, destinationFilenamePattern is used as-is (relative to working directory). Default: “” (empty, pattern used as-is)

Parameters:: dir (str) – The destination directory path (empty = use pattern as-is)
Returns:: error code indicating success or failure

destination_filename_pattern(pattern: str) → int

Set the filename pattern for output files

Pattern must be relative; absolute paths and parent directory (..) references are always rejected to prevent escaping destinationDirectory. Supported specifiers: %d, %i, %u with optional width (e.g., %02d, %05d, up to %99d). Default: “video%02d.mp4” (printf-style pattern with sequence number)

Parameters:: pattern (str) – Printf-compatible pattern (e.g., “video%02d.mp4”)
Returns:: error code indicating success or validation failure

enable_timestamp_in_filename(enable: bool) → int

Enable UTC timestamp embedding in filenames

When enabled, generates filenames like “video_1708185600000_00.mp4” (UTC ms) for multi-stream synchronization. Default: false (backwards compatible, no timestamp embedding)

Parameters:: enable (bool) – True to enable timestamp embedding
Returns:: error code indicating success or failure

video_codec(codec: VideoCodec) → int

Set the video codec

Currently only VideoCodec.H264 is supported. Default: VideoCodec.H264

Parameters:: codec (VideoCodec) – The video codec to use
Returns:: error code indicating success or failure

audio_codec(codec: AudioCodec) → int

Set the audio codec

Currently only AudioCodec.AAC is supported. Default: AudioCodec.AAC

Parameters:: codec (AudioCodec) – The audio codec to use
Returns:: error code indicating success or failure

av_container(container: AVContainer) → int

Set the container format

Currently only AVContainer.MP4 is supported. Default: AVContainer.MP4

Parameters:: container (AVContainer) – The container format to use
Returns:: error code indicating success or failure

max_files(maxFiles: int) → int

Set the maximum number of files to create

Default: 0 (unlimited)

Parameters:: maxFiles (int) – Maximum file count (0 = unlimited)
Returns:: error code indicating success or failure

Note

Incompatible with timestamp embedding (has no effect when enabled).

max_file_size_mb(maxSizeMB: int) → int

Set the maximum size of a file in MB

Default: 0 (unlimited - no file size limit)

Parameters:: maxSizeMB (int) – Maximum file size in megabytes (0 = unlimited)
Returns:: error code indicating success or failure

Note

Validates that maxSizeMB 1048576 won’t overflow int. Returns an error if validation fails.

max_file_duration_s(maxDurationS: int) → int

Set the maximum duration of a file in seconds

Default: 0 (unlimited - no file duration limit)

Parameters:: maxDurationS (int) – Maximum file duration in seconds (0 = unlimited)
Returns:: error code indicating success or failure

Note

Validates that maxDurationS 1000000000 won’t overflow int. Returns an error if validation fails.

destination_directory() → str: Get the destination directory

destination_filename_pattern() → str: Get the filename pattern

enable_timestamp_in_filename() → bool: Get timestamp embedding flag

video_codec() → VideoCodec: Get video codec

audio_codec() → AudioCodec: Get audio codec

av_container() → AVContainer: Get container format

max_files() → int: Get maximum file count

max_file_size_mb() → int: Get maximum file size in MB

max_file_duration_s() → int: Get maximum file duration in seconds

static create(context: px_core.core.ProximieContext, props: FeedBase.FeedBaseProperties, settings: AVOutputFeedFile.AVOutputFeedFileSettings, input: VideoInputFeedComponent, audioInputs: list[AudioInputFeedComponent] = ...) → AVOutputFeedFile

Factory method to create a recording feed that takes a video input, zero or more audio inputs, and writes it to disk with default X264 encoder

Parameters:

context (ProximieContext) – The Proximie context to use for the feed
props (FeedProperties) – Feed properties (label, etc.)
settings (AVOutputFeedFile.AVOutputFeedFileSettings) – File output settings (directory, filename pattern, size/duration limits)
input (VideoInputFeedComponent) – Video input feed component
audioInputs (list[AudioInputFeedComponent]) – Optional vector of audio input feed components

Returns:

NotNullOutcome containing the created AVOutputFeedFile or an error

static create(context: px_core.core.ProximieContext, props: FeedBase.FeedBaseProperties, settings: AVOutputFeedFile.AVOutputFeedFileSettings, input: VideoInputFeedComponent, encoder: H264VideoEncoderComponent, audioInputs: list[AudioInputFeedComponent] = ...) → AVOutputFeedFile

Factory method to create a recording feed that takes a video input, specific H264 encoder (X264, VAAPI), zero or more audio inputs, and writes it to disk

Parameters:

context (ProximieContext) – The Proximie context to use for the feed
props (FeedProperties) – Feed properties (label, etc.)
settings (AVOutputFeedFile.AVOutputFeedFileSettings) – File output settings (directory, filename pattern, size/duration limits)
input (VideoInputFeedComponent) – Video input feed component
encoder (H264VideoEncoderComponent) – H264 encoder component (X264, VAAPI, etc.)
audioInputs (list[AudioInputFeedComponent]) – Optional vector of audio input feed components

Returns:

NotNullOutcome containing the created AVOutputFeedFile or an error

static default_recording_encoder() → X264EncoderFeedComponent

Return an encoder with default settings for recording

Callers can take this encoder with basic settings, and tune them as required

Additional features that this type of feed supports

on_feed_file_finished(func: Callable[[AVOutputFeedFile, str], None]) → None: Notify that a feed file has finished and can be read/used

file_output_location_handler(handler: Callable[[int], str]) → None

Override default file naming behaviour Important note: This function is called during the file recording and streaming process.

The provided handler should return a value promptly and not block processing unduly. NOTE: If a custom handler is set and returns a non-empty filename, it overrides all built-in filename generation including timestamp embedding (enableTimestampInFilename). If the handler returns an empty string, the built-in naming (including timestamp embedding when enabled) will be used. If you need both custom naming AND timestamps, implement the timestamp logic within your custom handler.

class px_core.media.AdaptiveQuality

class px_core.media.AdaptiveQuality(quality: float)

Adaptive feed quality is a floating point value in the range 0.1

property max_quality: bool

property value: float

class px_core.media.FeedRequest

A common base class for feed events and requests

Feed requests are used to make a request to a feed object to change behaviour or settings. Since a feed may be made up of various feed components decided at runtime, requests have a general base class and are handled or ignored by the feed depending on its makeup.

unhandled_error() → int: Requests that are not handled by a feed should use this status/error

class px_core.media.RequestAdaptiveQuality(quality: AdaptiveQuality)

Bases: FeedRequest

A feed request with an adaptive quality value

quality() → AdaptiveQuality: Get the quality value

class px_core.media.AudioFeedStageComponent: Base class for audio feed stage components

class px_core.media.AudioFeedStageSequence

A sequence of audio feed stage components

sequence(components: px_core.utility.ComponentSequence) → None: Set the sequence of feed stages with a sequence of components

class px_core.media.AudioInputFeedComponent

Base class for audio input feed components

audio_stages() → AudioFeedStageSequence: Obtain the audio feed stage sequence object, which can be used to set additional audio processing stages for the component.

class px_core.media.AudioInputComponentSilence

Bases: AudioInputFeedComponent

An audio input feed component that simply sends silence.

class px_core.media.AudioInputFeedAuto

Bases: AudioInputFeedComponent

An audio input component that chooses an appropriate audio source to use.

This feed component can be used to simply add an audio input without the application needing to provide device details itself.

class px_core.media.AudioInputFeedInter(arg0: AudioInputFeedInter)

class px_core.media.AudioInputFeedInter(arg0: AudioInputFeedInter)

Bases: AudioInputFeedComponent

An audio input component that accepts audio from a named inter channel.

Instances must be obtained via AudioOutputFeedInter.makeInput(), which ensures each consumer receives its own isolated sub-channel so that multiple consumers never share a GStreamer inter ring-buffer read pointer.

class Properties

The properties required to specify the audio inter channel.

property channel: str

property consumed: bool

properties() → AudioInputFeedInter.Properties: Returns a read-only reference to the properties for the object

class px_core.media.AudioInputFeedTestSignal

Bases: AudioInputFeedComponent

An audio input feed component that simply sends a regular beat as an audio signal. The wave type is configurable. If not specified it defaults to ticks.

This component can be used to use test audio without a physical device. This can be useful when testing to avoid acoustic feedback loops when testing.

class Wave

Bases: enum.IntEnum

Wave type for audiotestsrc

Sine: int = 0

Square: int = 1

Saw: int = 2

Triangle: int = 3

WhiteNoise: int = 4

PinkNoise: int = 5

Ticks: int = 6

GaussianNoise: int = 7

RedNoise: int = 8

BlueNoise: int = 9

VioletNoise: int = 10

class Properties

The properties required to specify the audio input device and its settings.

property wave: AudioInputFeedTestSignal.Wave | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

wave(set: AudioInputFeedTestSignal.Wave) → AudioInputFeedTestSignal: Set the audio wave type; see AudioInputFeedTestSignal.Wave

properties() → AudioInputFeedTestSignal.Properties: Returns a read-only reference to the properties for the object

class px_core.media.AudioOutputFeedComponent

Base class for audio output feed components

audio_stages() → AudioFeedStageSequence: Obtain the audio feed stage sequence object, which can be used to set additional audio processing stages for the component.

class px_core.media.AudioOutputComponentNull

Bases: AudioOutputFeedComponent

An audio output feed component that “swallows” audio output without producing any output.

class px_core.media.AudioOutputFeedAuto

Bases: AudioOutputFeedComponent

An audio input component that chooses an appropriate audio output to use.

This feed component can be used to simply add a suitable audio output without the application needing to provide device details itself.

class px_core.media.AudioOutputFeedInter

class px_core.media.AudioOutputFeedInter(label: str)

Bases: AudioOutputFeedComponent

An audio output component that sends audio to a named inter channel.

This feed component can be used to send an audio stream to another pipeline. It is most commonly used in conjunction with the AudioInputFeedInter component, which accepts audio from a named inter channel.

class Properties

The properties required to specify the inter audio channel

property channel: str

make_input() → AudioInputFeedInter

Create an input feed that consumes exclusively from this output.

Each call registers a new uniquely-named sub-channel so that multiple consumers never share a ring-buffer read pointer. When more than one input has been registered the output segment automatically inserts a GStreamer @c tee element with one @c interaudiosink branch per consumer. All calls to makeInput() must be made before the owning pipeline is built (i.e. before the feed @c create() call that receives this output).

Accessors

properties() → AudioOutputFeedInter.Properties: Returns a read-only reference to the properties for the object

Note

The channel name is auto-generated at construction time.

output_channels() → list[str]: Returns the list of sub-channel names registered via makeInput()

class px_core.media.AudioOutputFeedWavescope

Bases: AudioOutputFeedComponent

An audio output feed component that displays the audio input as a simple waveform in a window. Note that there is a known issue with this component on Ubuntu 24.04 with GStreamer 1.24.2; see full documentation for details.

This component can be used to use test audio without a physical output device such as a speaker. This can be useful when testing to avoid acoustic feedback loops when testing. This component automatically opens a window to output the waveform. The ability to specify an output target/window will be added in a subsequent SDK release.

class px_core.media.AudioPeerRtpDecodeFeedComponent: Base class for audio peer decoder feed components

class px_core.media.AudioPeerRtpDecodeFeedOpus

Bases: AudioPeerRtpDecodeFeedComponent

A audio feed component for specifying Opus decoding for SRTP.

class Properties: The properties required to decode the audio feed for SRTP using Opus. No properties are currently supported.

class px_core.media.AudioPeerRtpEncodeFeedComponent: Base class for audio peer encoder feed components

class px_core.media.AudioPeerRtpEncodeFeedOpus

Bases: AudioPeerRtpEncodeFeedComponent

A audio feed component for specifying Opus encoding for SRTP.

class Properties: The properties required to encode the audio feed for SRTP using Opus

class px_core.media.AudioStageVolume(volume: float = ...)

Bases: AudioFeedStageComponent

Audio feed stage for adjusting audio volume using GStreamer volume element

property volume: float

class px_core.media.AudioStageWebRtcDsp

class px_core.media.AudioStageWebRtcDsp(properties: AudioStageWebRtcDsp.Properties)

Bases: AudioFeedStageComponent

Audio feed stage for applying WebRTC DSP effects.

This stage encapsulated a voice enhancement filter based on WebRTC Audio Processing library. The currently enabled enhancements are High Pass Filter, Noise Suppression, and Automatic Gain Control. All three are enabled by default.

class NoiseSuppressionLevel

Bases: enum.IntEnum

Noise suppression levels that can be applied by the WebRTC DSP.

Low: int = 0

Moderate: int = 1

High: int = 2

VeryHigh: int = 3

class GainControlMode

Bases: enum.IntEnum

Automatic gain control modes that can be applied by the WebRTC DSP.

AdaptiveAnalog: int = 0

AdaptiveDigital: int = 1

FixedDigital: int = 2

class Properties

Properties for the WebRTC audio DSP stage.

property compression_gain_db: int | None

property gain_control: bool | None

property gain_control_mode: AudioStageWebRtcDsp.GainControlMode | None

property high_pass_filter: bool | None

property limiter: bool | None

property noise_suppression: bool | None

property noise_suppression_level: AudioStageWebRtcDsp.NoiseSuppressionLevel | None

property target_level_dbfs: int | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

compression_gain_db(set: int) → AudioStageWebRtcDsp

Set the maximum gain in dB that the compression stage of the filter can apply.

Defaults to 9.

gain_control(set: bool) → AudioStageWebRtcDsp

Enable automatic gain control.

Defaults to enabled.

gain_control_mode(set: AudioStageWebRtcDsp.GainControlMode) → AudioStageWebRtcDsp

Set gain control mode applied (if enabled).

Defaults to Adaptive Digital.

high_pass_filter(set: bool) → AudioStageWebRtcDsp

Enable high-pass filter.

Defaults to enabled.

limiter(set: bool) → AudioStageWebRtcDsp

Enable limiter.

When enabled, the compression stage will hard limit the signal to the target level. Otherwise, the signal will be compressed but not limited above the target level. Defaults to enabled.

noise_suppression(set: bool) → AudioStageWebRtcDsp

Enable noise suppression.

Defaults to enabled.

noise_suppression_level(set: AudioStageWebRtcDsp.NoiseSuppressionLevel) → AudioStageWebRtcDsp

Set noise suppression level.

Defaults to Moderate.

target_level_dbfs(set: int) → AudioStageWebRtcDsp

Set target peak level in dBFS (decibels from digital full-scale).

Defaults to 3.

properties() → AudioStageWebRtcDsp.Properties: Returns a read-only reference to the properties for the object

class px_core.media.AudioWebRtcEncodeFeedComponent: Base class for audio WebRTC encoder feed components

class px_core.media.AudioWebRtcEncodeFeedOpus

Bases: AudioWebRtcEncodeFeedComponent

An audio feed component for specifying audio encoding using [Opus](https://opus-codec.org/).

The Opus encoder component uses fixed settings at this stage. In a later SDK update the component will expose settings that the application can set itself.

class px_core.media.BitRate

class px_core.media.BitRate(value: int, unit: BitRate.UnitType)

Encapsulates a bit rate value with varying units of bits (bits, kbits, etc.) per second.

BitRate defines some convenient literals for creating bit rate values. Enable the literals by including the following:

class UnitType

Bases: enum.IntEnum

Units of bits per second

Bits: int = 0

KBits: int = 1

MBits: int = 2

GBits: int = 3

class ScaleMethod

Bases: enum.IntEnum

How to round when scaling to a specified unit

Nearest: int = 0

Down: int = 1

Up: int = 2

DownNotZero: int = 3

NearestNotZero: int = 4

Get bit rate values

bits_per_second() → int: Bit rate in bits per second

bit_rate_with_units(unit: BitRate.UnitType, rounding: BitRate.ScaleMethod, remainder: int = None) → int

Scales the bit rate to the specified unit.

When scaling a bit rate to a larger unit without floating point, there is the possibility of rounding being needed. This function allows the caller to specify how rounding should be performed, including how to handle non-zero bit rates that would otherwise be rounded to a zero value.

Parameters:

unit (BitRate.UnitType) – The units to convert the bitrate value to
rounding (BitRate.ScaleMethod) – How to round the value when converting
remainder (int) – Optionally output the remainder in bits

Returns:

The bit rate converted to the requested units

decimal_bit_rate_with_units(unit: BitRate.UnitType) → float: Scaled bit rate to a given unit type, as a decimal value.

Comparison & testing of the bit rate value

property zero: bool

class px_core.media.Configuration

Singleton for configuring PxMedia module settings

Use the Configuration.get() method to access the singleton instance, and then chain setter methods to configure the settings.

class GStreamerLogger

Bases: enum.IntEnum

Enumeration to specify where GStreamer output is targeted

CONSOLE: int = 0

PXLOGGER: int = 1

static get() → Configuration: Access the configuration singleton

Configuration settings

Accessors to get & set configuration settings. Note that setter methods typically return the configuration instance to allow chaining. However, where setters have error return, these are not chainable.

property gstreamer_debug_level: int

property gstreamer_log_target: Configuration.GStreamerLogger

diagnostics_folder(folder: str) → None

Set the diagnostics folder for PxMedia

Returns an error if the path is not an existing directory

diagnostics_folder_or_throw(folder: str) → Configuration

Set the diagnostics folder for PxMedia

Throws an error if the path is not an existing directory

diagnostics_folder() → str

Returns the diagnostics folder for PxMedia

If no folder has been set, the configuration will default to the system temp folder. If the folder (set or defaulted) does not exist, an error will be returned.

class px_core.media.FeedDiagnosticsRequest(enabled: bool)

class px_core.media.FeedDiagnosticsRequest(logLevel: px_core.core.PxLogger.LogSeverity)

Bases: FeedRequest

A request to enable diagnostics on a feed

Diagnostics in this context are triggered by certain conditions or events, e.g. queue overruns, rather than periodic reports or stats tracking.

enabled() → bool: Whether the diagnostics are enabled

log_level() → px_core.core.PxLogger.LogSeverity: Get the logging level, which only applies if diagnostics are enabled

class px_core.media.FeedPerformanceAssessor

A rule for assessing performance and quality

class FeedPerformanceStats(feed: MediaServerOutgoingVideoFeed)

Information shared with the monitor for each feed being monitored

property feed: MediaServerOutgoingVideoFeed

property current_quality: AdaptiveQuality

property web_rtc_stats: WebRtcStats

property packet_loss_ratio: float

property packet_loss_ratio_average: float | None

assess_performance(details: FeedPerformanceAssessor.FeedPerformanceStats) → float: Given the current stats of a feed, return the delta to apply to the current quality level.

class px_core.media.FeedPacketLossAssessor

class px_core.media.FeedPacketLossAssessor(settings: FeedPacketLossAssessor.Settings)

Bases: FeedPerformanceAssessor

A feed performance assessment helper that looks at packet loss

class Settings

Settings for the packet loss assessment instances

property low_packet_loss_ratio_threshold: float

property severe_packet_loss_ratio_threshold: float

property quality_improve_delta: float

property quality_reduce_gentle_delta: float

property quality_reduce_severe_delta: float

static assess_packet_loss_delta(settings: FeedPacketLossAssessor.Settings, currentQuality: AdaptiveQuality, packetLossRatioAverage: float) → float: Compute the quality delta for packet-loss conditions without requiring a feed instance.

assess_performance(details: FeedPerformanceAssessor.FeedPerformanceStats) → float: Subclass overrides

class px_core.media.FeedQualityMonitor(assessor: FeedPerformanceAssessor)

A class that checks the performance of a set of adaptive feeds, and applies quality requests to adapt their performance accordingly.

property running: bool

start(interval: int) → None

Start the feed quality monitor with the given interval.

If the monitor is already running, it will reset with the given new timing internal.

stop() → None: Stop the feed quality monitor. If the monitor is not running, this is a no-op.

is_feed_registered(feed: MediaServerOutgoingVideoFeed) → bool: Check if a feed is being monitored already.

register_feed(feed: MediaServerOutgoingVideoFeed) → None: Register a feed to be monitored. Ignored if the feed is already registered.

unregister_feed(feed: MediaServerOutgoingVideoFeed) → None: Unregister a feed from being monitored. Ignored if the feed is not registered.

unregister_all_feeds() → None: Unregister all currently registered feeds

class px_core.media.FrameRate

class px_core.media.FrameRate(frameRate: int)

class px_core.media.FrameRate(numerator: int, denominator: int)

Encapsulates a formal frame rate value

set(frameRate: int) → None: Set a frame rate value with a simple frame rate integer (i.e. the denominator defaults to 1).

set(numerator: int, denominator: int) → None: Set a frame rate value with numerator/denominator values

numerator() → int: Obtain the frame rate ratio numerator value

denominator() → int: Obtain the frame rate ratio denominator value

property zero: bool

to_frame_rate_string() → str: Obtain a string/printable version of the frame rate value

to_double() → float: Convert to a double value

from_double(value: float) → None: Convert from a double value

static create_from_double(value: float) → FrameRate: Make a frame rate from a double value

class px_core.media.H264VideoEncoderComponent

Base class for H.264 video encoder feed components

Provides H.264-specific functionality and type safety. All H.264 encoder implementations (x264, VAAPI) should inherit from this class.

class px_core.media.H264VaapiEncoderComponent

Bases: H264VideoEncoderComponent

Encapsulates a VA-API hardware-accelerated H.264 encoder element (vaapih264enc) for use in feeds.

This encoder provides hardware-accelerated H.264 encoding on Intel and AMD GPUs using the Video Acceleration API (VAAPI).

Note

Default Configuration: Optimized for WebRTC real-time communication with settings that prioritize low latency and predictable bandwidth usage: - Rate Control: CBR (Constant Bitrate) for stable network streaming - Bitrate: 2000 kbps (matching X.264 software encoder defaults) - Keyframe Period: 30 frames (~1 second at 30fps) - B-Frames: 0 (P-frames only) for minimal encoding latency - QoS: Disabled to prevent adaptive frame dropping These defaults match the X.264 software encoder for consistency, allowing you to switch between encoders without reconfiguration. Customize all properties as needed for your specific use case (e.g., higher bitrate and VBR for file recording).

Requirements: - Your runtime environment must support VA-API - The vaapih264enc GStreamer element must be available (install gstreamer1.0-vaapi) - CBR rate control requires the non-free Intel media driver (intel-media-va-driver-non-free) - Docker environments need –device /dev/dri and possibly –privileged

Adaptive-streaming bitrate clamp: the underlying VA-API encoder sizes its coded (output) buffer from the encode resolution alone, while CBR rate control budgets bitrate/(8*framerate) bytes per frame. A low resolution combined with a low frame rate at a high bitrate makes the per-frame budget exceed the coded buffer, which wedges the encoder permanently (the feed freezes with no recovery). To make simultaneous resolution + frame-rate adaptation safe, this component automatically clamps the effective bitrate to what the coded buffer can carry at the current resolution and frame rate. The clamp is transparent for typical configurations; it only reduces bitrate at very low resolutions and/or frame rates, where a lower bitrate is the desired behaviour for a low-quality band anyway. The clamp applies to bitrate-driven rate control (CBR - the default - and the VBR family); it is skipped for the QP-driven modes (CQP, ICQ), which ignore the bitrate property and are not prone to the overflow. The x264 and VP8 software encoders are unaffected and need no clamp. See the internal vaapi-coded-buffer-clamp dev-doc for the full analysis.

class RateControlMode

Bases: enum.IntEnum

Rate control modes for the vaapih264enc encoder.

CQP: int = 0

CBR: int = 1

VBR: int = 2

VBR_CONSTRAINED: int = 3

ICQ: int = 4

QVBR: int = 5

class ComplianceMode

Bases: enum.IntEnum

Compliance mode values for tuning encode quality/performance.

STRICT: int = 0

RESTRICT_BUF_ALLOC: int = 1

class PredictionType

Bases: enum.IntEnum

Reference Picture Selection Modes.

DEFAULT: int = 0

HIERARCHICAL_P: int = 1

HIERARCHICAL_B: int = 2

class Mbbrc

Bases: enum.IntEnum

Macroblock level Bitrate Control mode.

AUTO: int = 0

ON: int = 1

OFF: int = 2

class Tune

Bases: enum.IntEnum

Encoder tuning options.

NONE: int = 0

HIGH_COMPRESSION: int = 1

LOW_POWER: int = 2

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

aud() → bool | None: Get AU delimiter setting

bitrate() → BitRate | None: Get target bitrate

cabac() → bool | None: Get CABAC entropy coding setting

compliance_mode() → H264VaapiEncoderComponent.ComplianceMode | None: Get compliance mode

cpb_length() → int | None: Get CPB length

dct8x8() → bool | None: Get DCT 8x8 transforms setting

roi_delta_qp() → int | None: Get ROI delta QP

init_qp() → int | None: Get initial QP

keyframe_period() → int | None: Get keyframe period

max_bframes() → int | None: Get maximum B frames

max_qp() → int | None: Get maximum QP

mbbrc() → H264VaapiEncoderComponent.Mbbrc | None: Get macroblock bitrate control

min_force_key_unit_interval() → int | None: Get minimum force key unit interval

min_qp() → int | None: Get minimum QP

num_slices() → int | None: Get number of slices

num_views() → int | None: Get number of views

prediction_type() → H264VaapiEncoderComponent.PredictionType | None: Get prediction type

qos() → bool | None: Get QoS setting

qp_ib() → int | None: Get QP difference between I and B frames

qp_ip() → int | None: Get QP difference between I and P frames

quality_factor() → int | None: Get quality factor

quality_level() → int | None: Get quality level

rate_control() → H264VaapiEncoderComponent.RateControlMode | None: Get rate control mode

refs() → int | None: Get number of reference frames

target_percentage() → int | None: Get target percentage

temporal_levels() → int | None: Get temporal levels

trellis() → bool | None: Get trellis quantization setting

tune() → H264VaapiEncoderComponent.Tune | None: Get encoder tuning option

view_ids() → str | None: Get view IDs

adaptive_quality() → BitRateQualityMapping | None: Get adaptive quality mapping

aud(set: bool) → H264VaapiEncoderComponent: Set AU delimiter

default_aud() → H264VaapiEncoderComponent: Reset AU delimiter to GStreamer default

bitrate(set: BitRate) → H264VaapiEncoderComponent: Set target bitrate

default_bitrate() → H264VaapiEncoderComponent: Reset bitrate to GStreamer default

cabac(set: bool) → H264VaapiEncoderComponent: Set CABAC entropy coding

default_cabac() → H264VaapiEncoderComponent: Reset CABAC to GStreamer default

compliance_mode(set: H264VaapiEncoderComponent.ComplianceMode) → H264VaapiEncoderComponent: Set compliance mode

default_compliance_mode() → H264VaapiEncoderComponent: Reset compliance mode to GStreamer default

cpb_length(set: int) → H264VaapiEncoderComponent: Set CPB length

default_cpb_length() → H264VaapiEncoderComponent: Reset CPB length to GStreamer default

dct8x8(set: bool) → H264VaapiEncoderComponent: Set DCT 8x8 transforms

default_dct8x8() → H264VaapiEncoderComponent: Reset DCT 8x8 to GStreamer default

roi_delta_qp(set: int) → H264VaapiEncoderComponent: Set ROI delta QP

Note

The underlying GStreamer property is named “default-roi-delta-qp”, but we use roiDeltaQp() for the setter to avoid confusion with the reset method pattern.

default_roi_delta_qp() → H264VaapiEncoderComponent: Reset ROI delta QP to GStreamer default

init_qp(set: int) → H264VaapiEncoderComponent: Set initial QP

default_init_qp() → H264VaapiEncoderComponent: Reset initial QP to GStreamer default

keyframe_period(set: int) → H264VaapiEncoderComponent: Set keyframe period

default_keyframe_period() → H264VaapiEncoderComponent: Reset keyframe period to GStreamer default

max_bframes(set: int) → H264VaapiEncoderComponent: Set maximum B frames

default_max_bframes() → H264VaapiEncoderComponent: Reset maximum B frames to GStreamer default

max_qp(set: int) → H264VaapiEncoderComponent: Set maximum QP

default_max_qp() → H264VaapiEncoderComponent: Reset maximum QP to GStreamer default

mbbrc(set: H264VaapiEncoderComponent.Mbbrc) → H264VaapiEncoderComponent: Set macroblock bitrate control

default_mbbrc() → H264VaapiEncoderComponent: Reset macroblock bitrate control to GStreamer default

min_force_key_unit_interval(set: int) → H264VaapiEncoderComponent: Set minimum force key unit interval

default_min_force_key_unit_interval() → H264VaapiEncoderComponent: Reset minimum force key unit interval to GStreamer default

min_qp(set: int) → H264VaapiEncoderComponent: Set minimum QP

default_min_qp() → H264VaapiEncoderComponent: Reset minimum QP to GStreamer default

num_slices(set: int) → H264VaapiEncoderComponent: Set number of slices

default_num_slices() → H264VaapiEncoderComponent: Reset number of slices to GStreamer default

num_views(set: int) → H264VaapiEncoderComponent: Set number of views

default_num_views() → H264VaapiEncoderComponent: Reset number of views to GStreamer default

prediction_type(set: H264VaapiEncoderComponent.PredictionType) → H264VaapiEncoderComponent: Set prediction type

default_prediction_type() → H264VaapiEncoderComponent: Reset prediction type to GStreamer default

qos(set: bool) → H264VaapiEncoderComponent: Set QoS

default_qos() → H264VaapiEncoderComponent: Reset QoS to GStreamer default

qp_ib(set: int) → H264VaapiEncoderComponent: Set QP difference between I and B frames

default_qp_ib() → H264VaapiEncoderComponent: Reset QP IB to GStreamer default

qp_ip(set: int) → H264VaapiEncoderComponent: Set QP difference between I and P frames

default_qp_ip() → H264VaapiEncoderComponent: Reset QP IP to GStreamer default

quality_factor(set: int) → H264VaapiEncoderComponent: Set quality factor

default_quality_factor() → H264VaapiEncoderComponent: Reset quality factor to GStreamer default

quality_level(set: int) → H264VaapiEncoderComponent: Set quality level

default_quality_level() → H264VaapiEncoderComponent: Reset quality level to GStreamer default

rate_control(set: H264VaapiEncoderComponent.RateControlMode) → H264VaapiEncoderComponent: Set rate control mode

default_rate_control() → H264VaapiEncoderComponent: Reset rate control to GStreamer default

refs(set: int) → H264VaapiEncoderComponent: Set number of reference frames

default_refs() → H264VaapiEncoderComponent: Reset number of reference frames to GStreamer default

target_percentage(set: int) → H264VaapiEncoderComponent: Set target percentage

default_target_percentage() → H264VaapiEncoderComponent: Reset target percentage to GStreamer default

temporal_levels(set: int) → H264VaapiEncoderComponent: Set temporal levels

default_temporal_levels() → H264VaapiEncoderComponent: Reset temporal levels to GStreamer default

trellis(set: bool) → H264VaapiEncoderComponent: Set trellis quantization

default_trellis() → H264VaapiEncoderComponent: Reset trellis quantization to GStreamer default

tune(set: H264VaapiEncoderComponent.Tune) → H264VaapiEncoderComponent: Set encoder tuning option

default_tune() → H264VaapiEncoderComponent: Reset encoder tuning to GStreamer default

view_ids(set: str) → H264VaapiEncoderComponent: Set view IDs

default_view_ids() → H264VaapiEncoderComponent: Reset view IDs to GStreamer default

adaptive_quality(mapping: BitRateQualityMapping) → None: Set adaptive quality mapping (pre-validated)

adaptive_quality(bands: list[BitRateQualityMapping.BandItem]) → None: Set adaptive quality mapping from bands (validates bands)

no_adaptive_quality() → None: Remove adaptive quality mapping

class px_core.media.IFeedFeature

Base interface common to all feed objects

id() → str: The unique ID for the feed

label() → str: The human-readable label for the feed

start_feed() → None

Start the feed playing

No effect if the feed is already playing

property playing: bool

stop_feed() → None

Stop the feed playing

No effect if the feed is not already playing

feed_request(request: FeedRequest) → None

Send a request to the feed

If there is an error processing the request, this will be reflected in the outcome error. Note that requests that use the WhenUnhandled.ERROR policy will return a PxMediaErrorCode.FeedRequestUnhandled when unhandled, allowing the caller to decide how to handle that case.

Returns:: An outcome indicating if the request was handled successfully.

get_pipeline_graph_with_details(details: int) → str

Obtain GStreaming pipeline graph for the feed at a given detail level

Returns:: The graph is returned as a string in the .dot format as an outcome

write_pipeline_graph_with_details_to_file(filename: str, details: int) → str

Write a pipeline .dot graph to a file at a given detail level

The file name may be absolute or relative, if relative it will use the diagnostics folder from the Configuration

Returns:: The path to the file written

on_feed_started(func: Callable[[FeedBase], None]) → None: Notify that a feed has successfully started

on_feed_stopped(func: Callable[[FeedBase, int], None]) → None: Notify that a feed has stopped, which may be intentionally or in error

class px_core.media.FeedFeaturePoster(target: IFeedFeature)

Bases: IFeedFeature

Base interface common to all feed objects

id() → str: Implement IFeedFeature

label() → str: The human-readable label for the feed

property playing: bool

start_feed() → None

Start the feed playing

No effect if the feed is already playing

stop_feed() → None

Stop the feed playing

No effect if the feed is not already playing

feed_request(request: FeedRequest) → None

Send a request to the feed

If there is an error processing the request, this will be reflected in the outcome error. Note that requests that use the WhenUnhandled.ERROR policy will return a PxMediaErrorCode.FeedRequestUnhandled when unhandled, allowing the caller to decide how to handle that case.

Returns:: An outcome indicating if the request was handled successfully.

on_feed_started(func: Callable[[FeedBase], None]) → None: Notify that a feed has successfully started

on_feed_stopped(func: Callable[[FeedBase, int], None]) → None: Notify that a feed has stopped, which may be intentionally or in error

get_pipeline_graph_with_details(details: int) → str

Obtain GStreaming pipeline graph for the feed at a given detail level

Returns:: The graph is returned as a string in the .dot format as an outcome

write_pipeline_graph_with_details_to_file(filename: str, details: int) → str

Write a pipeline .dot graph to a file at a given detail level

The file name may be absolute or relative, if relative it will use the diagnostics folder from the Configuration

Returns:: The path to the file written

class px_core.media.IMediaServerFeedFeature

The interface common to all media server feeds

session() → MediaServerSession: Obtain the media session this feed belongs to. This may be null if the session has shut down.

feed_statistics(callback: Callable[[MediaServerFeedStats], None]) → bool

Request the feed’s statistics

This function is asynchronous, calling the provided callback with the results when collected.

class px_core.media.MediaServerFeedFeaturePoster(target: IMediaServerFeedFeature)

Bases: IMediaServerFeedFeature

The interface common to all media server feeds

session() → MediaServerSession: Implement IMediaServerFeedFeature

feed_statistics(callback: Callable[[MediaServerFeedStats], None]) → bool

Request the feed’s statistics

This function is asynchronous, calling the provided callback with the results when collected.

class px_core.media.IPeerFeedFeature

The interface common to all peer feeds

session() → PeerSession: Obtain the peer session this feed belongs to. Note that the peer session may be null if the session has shut down.

class px_core.media.PeerFeedFeaturePoster(target: IPeerFeedFeature)

Bases: IPeerFeedFeature

The interface common to all peer feeds

session() → PeerSession: Implement IPeerFeedFeature

class px_core.media.MediaServerFeed

Bases: FeedBase

Base class for all feeds that are part of a media server session

media_server_feed() → IMediaServerFeedFeature: Supports the media server feed feature

class px_core.media.MediaServerFeedStats(feed: MediaServerFeed, webRtcStats: WebRtcStats)

Statistics for a given media feed

property feed: MediaServerFeed

property web_rtc_stats: WebRtcStats

class px_core.media.MediaServerIncomingVideoFeed

Bases: MediaServerFeed

A class which manages an incoming video feed in a media server session

class FeedProperties(feedId: str)

class FeedProperties(label: str, feedId: str)

Properties that apply to the whole feed

property subscribe_feed_id: str

static create(session: MediaServerSession, props: MediaServerIncomingVideoFeed.FeedProperties, output: VideoOutputFeedComponent) → MediaServerIncomingVideoFeed: Factory method to create an incoming video feed associated with a media server session

class px_core.media.MediaServerOutgoingVideoFeed

Bases: MediaServerFeed

A class which manages a local video feed being shared in a media server session

class FeedProperties(label: str = ..., indexHint: int = 0)

Properties that apply to the whole feed

property index_hint: int

class PublicProviders(input: VideoInputFeedComponent)

class Builder(session: MediaServerSession, props: MediaServerOutgoingVideoFeed.FeedProperties, input: VideoInputFeedComponent)

Builder for constructing an outgoing video feed with additional/optional components

Construct with the required session, properties, and input, then optionally configure output components before calling create() or createAsync().

local_output(out: VideoOutputFeedComponent) → MediaServerOutgoingVideoFeed.Builder: Set the pre-adaptive local output

adaptive_frame_rate(adaptiveFrameRate: VideoAdaptiveFrameRateComponent) → MediaServerOutgoingVideoFeed.Builder: Set adaptive frame rate (experimental)

adaptive_resolution(adaptiveResolution: VideoAdaptiveResolutionComponent) → MediaServerOutgoingVideoFeed.Builder: Set adaptive resolution (experimental)

encoder(encoder: VideoWebRtcEncodeFeedComponent) → MediaServerOutgoingVideoFeed.Builder: set the WebRTC video encoder

monitor_output(out: VideoOutputFeedComponent) → MediaServerOutgoingVideoFeed.Builder: Set the post-encoder monitor output

create() → MediaServerOutgoingVideoFeed: Create the outgoing video feed

create_async() → MediaServerOutgoingVideoFeed

Asynchronously create the outgoing video feed

Blocks until the operation completes; returns None and raises SdkError on failure.

static create(session: MediaServerSession, props: MediaServerOutgoingVideoFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent = ...) → MediaServerOutgoingVideoFeed

Factory method to create an outgoing video feed in a media server session

For feeds requiring additional components, see Builder.

Parameters:

session (MediaServerSession) – The media server session
props (FeedProperties) – Feed properties
input (VideoInputFeedComponent) – Video input source
localOut (VideoOutputFeedComponent) – Optional pre-adaptive local output component

static create_async(session: MediaServerSession, props: MediaServerOutgoingVideoFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent = ...) → MediaServerOutgoingVideoFeed

Factory method to asynchronously create an outgoing video feed in a media server session

For feeds requiring additional components, see Builder.

Parameters:

session (MediaServerSession) – The media server session
props (FeedProperties) – Feed properties
input (VideoInputFeedComponent) – Video input source
localOut (VideoOutputFeedComponent) – Optional pre-adaptive local output component

Blocks until the operation completes; returns None and raises SdkError on failure.

static create(session: MediaServerSession, props: MediaServerOutgoingVideoFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent, monitorOut: VideoOutputFeedComponent) → MediaServerOutgoingVideoFeed

Factory method to create an outgoing video feed with explicit output components

Parameters:

session (MediaServerSession) – The media server session
props (FeedProperties) – Feed properties
input (VideoInputFeedComponent) – Video input source
localOut (VideoOutputFeedComponent) – Pre-adaptive local output
monitorOut (VideoOutputFeedComponent) – Post-encoder monitor output

Deprecated since version Use: Builder to configure optional outputs

static create_async(session: MediaServerSession, props: MediaServerOutgoingVideoFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent, monitorOut: VideoOutputFeedComponent) → MediaServerOutgoingVideoFeed

Factory method to asynchronously create an outgoing video feed with explicit output components

Parameters:

session (MediaServerSession) – The media server session
props (FeedProperties) – Feed properties
input (VideoInputFeedComponent) – Video input source
localOut (VideoOutputFeedComponent) – Pre-adaptive local output
monitorOut (VideoOutputFeedComponent) – Post-encoder monitor output

Deprecated since version Use: Builder to configure optional outputs

Blocks until the operation completes; returns None and raises SdkError on failure.

Adaptive streaming support

apply_adaptive_quality(quality: AdaptiveQuality) → None: Request the connection adjust its quality

adaptive_quality() → AdaptiveQuality: Obtain the current adaptive quality

class px_core.media.MediaServerSession(arg0: MediaServerSession)

class px_core.media.MediaServerSession(arg0: MediaServerSession)

Manages audio and video connections to media servers

Maintains audio and video media connections to session media server. Local devices can be shared with other session participants, and their streams are made available to the host application using the session object.

class FeedMetadata(withId: str, withType: MediaSessionFeedType.Enum, withLabel: str)

Metadata for a given feed

property feed_id: str

property feed_type: MediaSessionFeedType.Enum

property label: str | None

class RequestedSession

Details required to request a media server session in single struct

property session_id: str

property remote_env: px_core.core.RemoteEnvironment

property request_fields: px_core.rest.ProximieServices.RequestFields

class SessionRecordingState

Recording state for the session

The recording state is set asynchronously, and so comprises both the current value and whether an update is pending. When the client application requests a state change, the state ‘on’ value will be not set immediately, and the ‘updatePending’ flag will be set until the media server acknowledges the update. Once the change is acknowledged, the ‘updatePending’ flag will be cleared.

total_running_duration_ms() → int: Helper to calculate the total running duration of the recording so far

property on: bool

property update_pending: bool

property total_segment_duration_ms: int

property status_updated: int | None

class Experimental

Proxy object providing access to experimental MediaServerSession features

Experimental features may change or be removed in future releases. Accessible via mediaSession->experimental().

subscribe_to_annotations(streamId: str) → None

Subscribe to annotation events for a given stream

Subscription is local state — may be called regardless of connection status; persists across reconnections. Cleared on disconnect.

unsubscribe_from_annotations(streamId: str) → None

Unsubscribe from annotation events for a given stream

May be called regardless of connection status.

Returns:: FeedIdNotFound if the stream was not subscribed

unsubscribe_from_all_annotations() → None

Unsubscribe from annotation events for all streams

Clears all local subscription state immediately. May be called regardless of connection status. Subscriptions are also cleared automatically on disconnect.

fetch_annotation_history(streamId: str) → str

Fetch annotation history for a stream via REST

Returns the result directly; raises SdkError on failure.

on_annotation_received(func: Callable[[MediaServerSession, str, Any], None]) → None: Notifies when an annotation event is received for a subscribed stream

state() → ConnectionState: Connectivity state of the session

static create(context: px_core.core.ProximieContext) → MediaServerSession: Create a new MediaServerSession into a shared pointer

connect_to_session(sessionId: str, env: px_core.core.RemoteEnvironment, serviceSettings: px_core.utility.HttpFetch.RequestFields) → None

Start to connect to a given session

Also the MediaServerSession.onSessionConnected callback is always called (i.e. immediately or later), with the error in case of an error.

Blocks until the operation completes; returns None and raises SdkError on failure.

connect_to_session(session: MediaServerSession.RequestedSession) → None: Blocks until the operation completes; returns None and raises SdkError on failure.

disconnect_from_session() → None

Disconnect from the current session

Also the MediaServerSession.onSessionDisconnected callback is always called (i.e. immediately or later), with the error in case of an error.

Blocks until the operation completes; returns None and raises SdkError on failure.

list_session_feed_ids() → list[str]: Obtain a list of all feed IDs owned by the session

list_session_feeds() → list[MediaServerFeed]: List all feeds currently associated with the session

get_feed(feedId: str) → MediaServerFeed

Obtain a feed from its ID

Returns:: A shared pointer to the feed, or nullptr if not found

audio_encoder(encoder: AudioWebRtcEncodeFeedComponent) → None: Set the default audio encoder for newly created feeds

video_encoder(encoder: VideoWebRtcEncodeFeedComponent) → None: Set the default video encoder for newly created feeds

on_session_connected(func: Callable[[MediaServerSession, int], None]) → None: Notifies when a session has connected, either with an error or successfully

on_session_error(func: Callable[[MediaServerSession, int], None]) → None: Notify when there is an error with the media session after connection

on_new_remote_feed(func: Callable[[MediaServerSession, MediaServerSession.FeedMetadata], None]) → None: Notify that a new remote feed is available from the media server

on_remote_feed_removed(func: Callable[[MediaServerSession, str], None]) → None: Notify that a remote feed is no longer available

on_feed_started(func: Callable[[MediaServerSession, str], None]) → None: Notify that a feed has successfully started

on_feed_stopped(func: Callable[[MediaServerSession, str, int], None]) → None: Notify that a feed has stopped, which may be intentionally or in error

on_session_disconnected(func: Callable[[MediaServerSession, int], None]) → None: Notifies when a session has disconnected, either in error or by request

Session services

on_session_services_connected(func: Callable[[MediaServerSession], None]) → None: Notifies when session services have connected and are available

are_session_services_connected() → bool: Check if session services are currently connected

on_session_services_disconnected(func: Callable[[MediaServerSession, int], None]) → None: Notifies when the session services disconnected When gracefully disconnected the error code will indicate success, otherwise in case of an error condition the error code indicates the reason.

session_recording_state() → MediaServerSession.SessionRecordingState: Obtain the current recording state for the session

request_session_recording(recordingOn: bool) → None

Request a change in the recording state for the session

The change is requested asynchronously, and the application is notified using the onRecordingStateChanged event

on_recording_state_changed(func: Callable[[MediaServerSession, MediaServerSession.SessionRecordingState], None]) → None: Notifies when the session recording state has changed

experimental() → MediaServerSession.Experimental: Access experimental SDK features

class px_core.media.MediaServerTwoWayAudioFeed

Bases: MediaServerFeed

A class which manages a two-way audio feed in a media server session

static create(session: MediaServerSession, props: FeedBase.FeedBaseProperties, input: AudioInputFeedComponent, output: AudioOutputFeedComponent) → MediaServerTwoWayAudioFeed: Factory method to create a two-way audio feed associated with a media server session

static create_async(session: MediaServerSession, props: FeedBase.FeedBaseProperties, input: AudioInputFeedComponent, output: AudioOutputFeedComponent) → MediaServerTwoWayAudioFeed

Factory method to asynchronously create a two-way audio feed associated with a media server session

Blocks until the operation completes; returns None and raises SdkError on failure.

class px_core.media.NetworkQualityMonitor

A class that checks the performance of a set of feeds and summarises an assessment of the overall network quality.

This is an experimental feature that will be expanded and improved in future releases.

static create(context: px_core.core.ProximieContext) → NetworkQualityMonitor

Create a new network monitor

After creation, the owner can add feeds and start the monitor.

property running: bool

start(interval: int) → None

Start the feed quality monitor with the given interval.

If the monitor is already running, it will change the interval after any ongoing collection pass is complete.

stop() → None: Stop the feed quality monitor. If the monitor is not running, this is a no-op.

is_feed_registered(feed: FeedBase) → bool: Check if a feed is being monitored already.

register_feed(feed: FeedBase) → None: Register a feed to be monitored. Ignored if the feed is already registered.

unregister_feed(feed: FeedBase) → None: Unregister a feed from being monitored. Ignored if the feed is not registered.

unregister_all_feeds() → None: Unregister all currently registered feeds

class px_core.media.PeerFeed

Bases: FeedBase

Base class for all peer session feeds

class FeedProperties(label: str = ...)

Bases: FeedBase.FeedBaseProperties

Properties that apply to the whole feed

Note that feed properties always require a channel key

property channel: str

peer_feed() → IPeerFeedFeature: Supports the peer feed feature

class px_core.media.PeerLocalAudioFeed

Bases: PeerFeed

A peer feed that sends local Audio to the remote peer

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: AudioInputFeedComponent) → PeerLocalAudioFeed: Factory method to create an outgoing feed associated with a peer session

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: AudioInputFeedComponent, localOut: AudioOutputFeedComponent) → PeerLocalAudioFeed: Factory method to create an outgoing feed associated with a peer session, which also outputs locally.

class px_core.media.PeerLocalVideoFeed

Bases: PeerFeed

A peer feed that sends local video to the remote peer

class Builder(session: PeerSession, props: PeerFeed.FeedProperties, input: VideoInputFeedComponent)

Builder for constructing a local peer video feed

Construct with the required session, properties, and input, then optionally configure the encoder and output components before calling create(). If no encoder is set a default X264 encoder is used.

encoder(enc: H264VideoEncoderComponent) → PeerLocalVideoFeed.Builder

Set the H264 encoder configuration

Parameters:: enc (H264VideoEncoderComponent) – Encoder component (if not called a default X264 encoder is used)

local_output(out: VideoOutputFeedComponent) → PeerLocalVideoFeed.Builder: Set the pre-encoder local output

monitor_output(out: VideoOutputFeedComponent) → PeerLocalVideoFeed.Builder: Set the post-encoder monitor output

create() → PeerLocalVideoFeed: Create the peer local video feed

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: VideoInputFeedComponent) → PeerLocalVideoFeed

Factory method to create an outgoing feed associated with a peer session

Parameters:

session (PeerSession) – The peer session
props (FeedProperties) – Feed properties
input (VideoInputFeedComponent) – Video input source

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: VideoInputFeedComponent, encoderProperties: H264VideoEncoderComponent) → PeerLocalVideoFeed

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent, encoderProperties: H264VideoEncoderComponent = None) → PeerLocalVideoFeed

static create(session: PeerSession, props: PeerFeed.FeedProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent, monitorOut: VideoOutputFeedComponent, encoderProperties: H264VideoEncoderComponent = None) → PeerLocalVideoFeed

class px_core.media.PeerRemoteAudioFeed

Bases: PeerFeed

A peer feed that receives Audio from the remote peer

static create(session: PeerSession, props: PeerFeed.FeedProperties, output: AudioOutputFeedComponent) → PeerRemoteAudioFeed: Factory method to create an incoming feed associated with a peer session

class px_core.media.PeerRemoteVideoFeed

Bases: PeerFeed

A peer feed that receives video from the remote peer

static create(session: PeerSession, props: PeerFeed.FeedProperties, output: VideoOutputFeedComponent) → PeerRemoteVideoFeed: Factory method to create an incoming feed associated with a peer session

class px_core.media.PeerSession

A peer session represents a connection between two peers

class PeerHost

Details needed to locate a peer host

property hostname: str

class PeerChannel

Details needed to declare a channel sent by the peer

property label: str

property port: int

class PeerDetails

The details of a peer connection and it’s “channels”

property label: str

property host: PeerSession.PeerHost

property channels: dict[str, PeerSession.PeerChannel]

class PeerSessionSettings(local: PeerSession.PeerDetails, remote: PeerSession.PeerDetails, key: str)

Settings and parameters for a session between peers

property encryption_key: str

property local: PeerSession.PeerDetails

property remote: PeerSession.PeerDetails

static create(context: px_core.core.ProximieContext, settings: PeerSession.PeerSessionSettings) → PeerSession: Factory method to create a new peer session

list_session_feed_ids() → list[str]: List all feeds currently associated with the session

list_session_feeds() → list[PeerFeed]: List all feeds currently associated with the session

get_feed(feedId: str) → PeerFeed: Obtain a feed by its ID

create_recording_feed(videoFeedId: str, audioFeedIds: list[str], settings: AVOutputFeedFile.AVOutputFeedFileSettings) → AVOutputFeedFile

Add a feed that will record a video feed to local storage

The new feed will record a video feed and (optionally) audio feed(s) to files on local storage. Supplied audio feeds will be mixed to a single audio track in the resulting files.

Parameters:

videoFeedId (str) – The ID of the video feed to record
audioFeedIds (list[str]) – The IDs of the audio feeds to mix into the recording
settings (AVOutputFeedFile.AVOutputFeedFileSettings) – The settings for the recording feed, such as file path, max size, and max duration

class px_core.media.PxMediaErrorCategory

Error category for PxMediaErrorCode

static category() → PxMediaErrorCategory: Returns the category instance for the PxMediaErrorCategory

static message_from_error_code(code: PxMediaErrorCode) → str: Helper to translate an error code into a message string

Error category

Implements the error_category interface

name() → str: Returns the error category name as a string

message(code: int) → str: Returns the message for the provided error code

class px_core.media.SrtFeedStats

A structure representing SRT feed statistics.

class SrtSenderCallerStats

SRT sender caller stats

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property packets_sent: int

property packets_sent_lost: int

property packets_retransmitted: int

property packet_ack_received: int

property packet_nack_received: int

property packets_sent_dropped: int

property bytes_sent: int

property bytes_retransmitted: int

property bytes_sent_dropped: int

property send_rate_mbps: float

property send_duration_us: int

property negotiated_latency_ms: int

property bandwidth_mbps: float

property rtt_ms: float

class SrtSenderStats

SRT sender stats

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property callers: list[SrtFeedStats.SrtSenderCallerStats] | None

property bytes_sent_total: int

class SrtReceiverStatsDetail

SRT receiver stats detail

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property packets_received: int

property packets_received_lost: int

property packet_ack_sent: int

property packet_nack_sent: int

property bytes_received: int

property bytes_received_lost: int

property receive_rate_mbps: float

property negotiated_latency_ms: int

property bandwidth_mbps: float

property rtt_ms: float

class SrtReceiverStats

SRT receiver stats

check_read_object_from_json(source: dict) → bool: Read from a GST structure for SRT stats Due to a slightly unconventional layout of the SRT stats, we cannot read simply with the SDK JsonSerializer

property detail: SrtFeedStats.SrtReceiverStatsDetail | None

property bytes_received_total: int

property sender_stats: SrtFeedStats.SrtSenderStats

property receiver_stats: SrtFeedStats.SrtReceiverStats

class px_core.media.SrtFeedStatsRequest(callback: Callable[[Any], None])

Bases: FeedRequest

A feed request to obtain SRT feed statistics.

callback() → Callable[[Any], None]: The callback to receive the stats

class px_core.media.UtilityAudioLocalFeed

Bases: FeedBase

A simple utility audio feed

Utility feeds are pipelines which don’t have a remote element, and are not associated with or managed by a session. If it is given multiple inputs they will be mixed together.

static create(context: px_core.core.ProximieContext, props: FeedBase.FeedBaseProperties, inputs: px_core.utility.AudioInputFeedComponents, localOut: AudioOutputFeedComponent) → UtilityAudioLocalFeed: Factory method to create a utility feed that takes one or more audio inputs and mixes them together before sending onwards to some audio output

static create(context: px_core.core.ProximieContext, props: FeedBase.FeedBaseProperties, input: AudioInputFeedComponent, localOut: AudioOutputFeedComponent) → UtilityAudioLocalFeed: Factory method to create a utility feed that takes a audio input and sends onward to some audio output

add_input(input: AudioInputFeedComponent) → str

Add an audio input feed component to the feed.

Returns a generated uuid for it The input will be removed when the feed is stopped or removeInput called with the uuid

remove_input(uuid: str) → int: Remove a audio input from the feed given its uuid

class px_core.media.UtilityVideoLocalFeed

Bases: FeedBase

A simple utility video feed

Utility feeds are pipelines which don’t have a remote element, and are not associated with or managed by a session.

static create(context: px_core.core.ProximieContext, props: FeedBase.FeedBaseProperties, input: VideoInputFeedComponent, localOut: VideoOutputFeedComponent) → UtilityVideoLocalFeed: Factory method to create a utility feed that takes a video input and sends onward to some video output

class px_core.media.VideoAdaptiveFrameRateComponent(mapping: FrameRateQualityMapping)

A video processing stage that alters the video frame rate adaptively

static create(bands: list[FrameRateQualityMapping.BandItem]) → VideoAdaptiveFrameRateComponent: Also allow factory creation from a set of quality bands, which will be validated

Getters and setters

property drop_only: bool

property skip_to_first: bool

class px_core.media.VideoAdaptivePropertyComponent: Base class for video components for adaptive properties (e.g. frame rate, resolution)

class px_core.media.VideoAdaptiveResolutionComponent(mapping: ResolutionQualityMapping)

A video processing stage that alters the video resolution adaptively

static create(bands: list[ResolutionQualityMapping.BandItem]) → VideoAdaptiveResolutionComponent: Also allow factory creation from a set of quality bands, which will be validated

class px_core.media.VideoCapabilities

Provide capability settings that are common to all video media types

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property media_type: MediaType

property height: int

property width: int

property resolution: px_core.utility.SizeUInt

property adaptive_resolution: AdaptiveResolutionRule

property frame_rate: FrameRate

property adaptive_frame_rate: AdaptiveFrameRateRule

class px_core.media.VideoFeedStageComponent: Base class for video feed stage components

class px_core.media.VideoFeedStageSequence

A sequence of video feed stage components

sequence(components: px_core.utility.ComponentSequence) → None: Set the sequence of feed stages with a sequence of components

class px_core.media.VideoInputFeedComponent

Base class for video input feed components

class VideoInputProperties

Properties for video inputs

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property do_timestamp: bool

Get and set properties

video_input_properties() → VideoInputFeedComponent.VideoInputProperties: Obtain the general video input properties, which can be used to change settings

video_stages() → VideoFeedStageSequence: Obtain the video feed stage sequence object, which can be used to set additional video processing stages for the component.

class px_core.media.VideoFormattedInputFeedComponent

Bases: VideoInputFeedComponent

Base class for video formatted input feed components

video_capabilities() → VideoCapabilities: Obtain video capabilities object, which can be used to set video capabilities settings for the component.

class px_core.media.VideoInputFeedFile

Bases: VideoFormattedInputFeedComponent

A video input feed component that reads a video or image file as the video feed.

This component can be used to use test video without a physical device.

class Properties

The properties required to specify the video input device and its settings.

property filename: str

property base_format: BaseMedia

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

To set video feed sub-properties, use the VideoInputFeedFile.videoCapabilities accessor function.

filename(set: str) → VideoInputFeedFile: Set the filename

base_format(set: BaseMedia) → VideoInputFeedFile: Set the base format

properties() → VideoInputFeedFile.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoInputFeedInter(arg0: VideoInputFeedInter)

class px_core.media.VideoInputFeedInter(arg0: VideoInputFeedInter)

Bases: VideoFormattedInputFeedComponent

A video input feed component that accepts video from a named inter channel.

Instances must be obtained via @c VideoOutputFeedInter.makeInput() before the associated output is passed to a feed @c create() call. Each instance represents exclusive ownership of a consumer slot and can only be used in a single feed. Because @c intervideosrc uses a last-frame model, multiple independent VideoInputFeedInter instances (each obtained via a separate makeInput() call) may consume the same output simultaneously without corrupting the stream.

class Properties

The properties required to specify the video inter channel.

property channel: str

Accessors

properties() → VideoInputFeedInter.Properties: Returns a read-only reference to the properties for the object

property consumed: bool

class px_core.media.VideoInputFeedPipewire

Bases: VideoFormattedInputFeedComponent

A video input feed component capturing a pipewire video source.

This feed component provides properties to specify which pipewire video source to capture, and the VideoCapabilities (such as resolution and frame rate).

class Properties

The properties required to specify the video input device and its settings.

property always_copy: bool | None

property autoconnect: bool | None

property automatic_eos: bool | None

property blocksize: int | None

property client_name: str | None

property client_properties: str | None

property do_timestamp: bool | None

property fd: int | None

property keepalive_time: int | None

property max_buffers: int | None

property min_buffers: int | None

property name: str | None

property num_buffers: int | None

property parent: str | None

property path: str | None

property resend_last: bool | None

property stream_properties: str | None

property target_object: str | None

property typefind: bool | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

To set video feed sub-properties, use the VideoInputFeedPipewire.videoCapabilities accessor function.

always_copy(set: bool) → VideoInputFeedPipewire: Set whether to always copy the buffer data

autoconnect(set: bool) → VideoInputFeedPipewire: Set whether to autoconnect

automatic_eos(set: bool) → VideoInputFeedPipewire: Set whether to automatically send EOS when the segment is done

blocksize(set: int) → VideoInputFeedPipewire: Set the size in bytes to read per buffer

client_name(set: str) → VideoInputFeedPipewire: Set the client name to use

client_properties(set: str) → VideoInputFeedPipewire: Set the list of PipeWire client properties

do_timestamp(set: bool) → VideoInputFeedPipewire: Set whether to apply current stream time to buffers

fd(set: int) → VideoInputFeedPipewire: Set the fd to connect with

keepalive_time(set: int) → VideoInputFeedPipewire: Set the keepalive time

max_buffers(set: int) → VideoInputFeedPipewire: Set the maximum number of buffers to negotiate with PipeWire

min_buffers(set: int) → VideoInputFeedPipewire: Set the minimum number of buffers to negotiate with PipeWire

name(set: str) → VideoInputFeedPipewire: Set the name of the object

num_buffers(set: int) → VideoInputFeedPipewire: Set the number of buffers to output before sending EOS

parent(set: str) → VideoInputFeedPipewire: Set the parent of the object

path(set: str) → VideoInputFeedPipewire: Set the source path to connect to

resend_last(set: bool) → VideoInputFeedPipewire: Set whether to resend last buffer on EOS

stream_properties(set: str) → VideoInputFeedPipewire: Set the list of PipeWire stream properties

target_object(set: str) → VideoInputFeedPipewire: Set the source name/serial to connect to

typefind(set: bool) → VideoInputFeedPipewire: Set whether to run typefind before negotiating

properties() → VideoInputFeedPipewire.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoInputFeedSharedMemory

Bases: VideoFormattedInputFeedComponent

A video input feed component that reads raw video from a shared memory area using GStreamer’s shmsrc element.

This component receives buffers from a matching shared memory sink (such as the VideoOutputFeedSharedMemory component, backed by shmsink). The two endpoints communicate over a control socket identified by a shared socketPath. Shared memory transfers raw bytes with no inherent format information, so the expected video format must be described using the component’s VideoCapabilities (resolution, frame rate and pixel format). These must match the format being written by the producer.

class Properties

The properties required to specify the shared memory source and its settings.

property socket_path: str

property is_live: bool

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

To set video feed sub-properties, use the VideoInputFeedSharedMemory.videoCapabilities accessor function.

socket_path(set: str) → VideoInputFeedSharedMemory: Set the shared memory control socket path

is_live(set: bool) → VideoInputFeedSharedMemory: Set whether the source is treated as a live source

properties() → VideoInputFeedSharedMemory.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoInputFeedTestPattern

Bases: VideoFormattedInputFeedComponent

A video input feed component that sends a “test card” pattern as the video feed.

This component can be used to use test video without a physical device.

class AnimationMode

Bases: enum.IntEnum

For pattern=ball, which counter defines the position of the ball.

Frames: int = 0

WallTime: int = 1

RunningTime: int = 2

class Pattern

Bases: enum.IntEnum

Pattern type for videotestsrc

SMPTE: int = 0

Snow: int = 1

Black: int = 2

White: int = 3

Red: int = 4

Green: int = 5

Blue: int = 6

Checkers1: int = 7

Checkers2: int = 8

Checkers4: int = 9

Checkers8: int = 10

Circular: int = 11

Blink: int = 12

SMPTE75: int = 13

ZonePlate: int = 14

Gamut: int = 15

ChromaZonePlate: int = 16

SolidColor: int = 17

Ball: int = 18

SMPTE100: int = 19

Bar: int = 20

Pinwheel: int = 21

Spokes: int = 22

Gradient: int = 23

Colors: int = 24

SMPTERP219: int = 25

class MotionType

Bases: enum.IntEnum

Motion type for videotestsrc

Wavy: int = 0

Sweep: int = 1

HSweep: int = 2

class Properties

The properties required to specify the video input device and its settings.

property animation_mode: VideoInputFeedTestPattern.AnimationMode | None

property pattern: VideoInputFeedTestPattern.Pattern | None

property flip: bool | None

property horizontal_speed: int | None

property motion: VideoInputFeedTestPattern.MotionType | None

property timestamp_offset: int | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

To set video feed sub-properties, use the VideoInputFeedTestPattern.videoCapabilities accessor function.

animation_mode(set: VideoInputFeedTestPattern.AnimationMode) → VideoInputFeedTestPattern: Set the animation mode; see VideoInputFeedTestPattern.AnimationMode

pattern(set: VideoInputFeedTestPattern.Pattern) → VideoInputFeedTestPattern: Set the pattern type; see VideoInputFeedTestPattern.Pattern

flip(set: bool) → VideoInputFeedTestPattern: Set flip; for pattern=ball, invert colors every second.

horizontal_speed(set: int) → VideoInputFeedTestPattern

Set horizontal scroll speed in pixels per frame.

Positive values scroll to the left.

motion(set: VideoInputFeedTestPattern.MotionType) → VideoInputFeedTestPattern: Set motion type; see VideoInputFeedTestPattern.MotionType

timestamp_offset(set: int) → VideoInputFeedTestPattern: Set timestamp offset; An offset added to timestamps set on buffers (in ns)

properties() → VideoInputFeedTestPattern.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoInputFeedUdp

Bases: VideoInputFeedComponent

A video input feed using a UDP source

This feed component provides properties to specify how the feed obtains H264 encoded video using RTP from a given UDP port.

class UdpSourceProperties

UDP source properties

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

By default, the UDP host is set to “localhost” and the port is set to the default 5004.

property host: str

localhost() → VideoInputFeedUdp.UdpSourceProperties: Sets the UDP host as localhost

property port: int

property mtu: int

default_mtu() → VideoInputFeedUdp.UdpSourceProperties: Set the maximum expected packet size (mtu) to the default

property timeout: int

no_timeout() → VideoInputFeedUdp.UdpSourceProperties: Disable the timeout for the UDP source

class RtpProperties

RTP properties

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property clock_rate: int

udp_properties() → VideoInputFeedUdp.UdpSourceProperties: Access the UDP source properties

rtp_properties() → VideoInputFeedUdp.RtpProperties: Access the RTP properties

class px_core.media.VideoInputFeedV4Linux2

Bases: VideoFormattedInputFeedComponent

A video input feed component using a [Video4Linux2](https://en.wikipedia.org/wiki/Video4Linux) device.

This feed component provides properties to specify which actual device to use, and the VideoCapabilities (such as resolution and frame rate).

class IOMode

Bases: enum.IntEnum

IO Mode for the device

AUTO: int = 0

RW: int = 1

MMAP: int = 2

USERPTR: int = 3

DMABUF: int = 4

DMABUF_IMPORT: int = 5

class DeviceProperties

Device properties

The device can be specified in various ways, including path/location, file descriptor and by name. The caller should choose one value to set to specify the device. If no device is specified, the default is to use device /dev/video0.

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property device: str

property device_fd: int

property device_name: str

io_mode() → VideoInputFeedV4Linux2.IOMode | None: Get the IO mode

io_mode(set: VideoInputFeedV4Linux2.IOMode) → VideoInputFeedV4Linux2.DeviceProperties: Set the IO mode

default_io_mode() → VideoInputFeedV4Linux2.DeviceProperties: Set the default IO mode

device_properties() → VideoInputFeedV4Linux2.DeviceProperties: Returns the device properties for selecting the device to use.

class px_core.media.VideoInputFeedXImage

Bases: VideoFormattedInputFeedComponent

A video input feed component capturing an X desktop or window.

This feed component provides properties to specify which X display or window to capture, and the VideoCapabilities (such as resolution and frame rate).

class Properties

The properties required to specify the video input device and its settings.

property enable_navigation_events: bool

property remote: bool

property show_pointer: bool

property use_damage: bool

property capture_area: px_core.utility.Rectangle

property xid: int

property display_name: str

property xname: str

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

To set video feed sub-properties, use the VideoInputFeedXImage.videoCapabilities accessor function.

display_name(set: str) → VideoInputFeedXImage: Set the display name

xid(set: int) → VideoInputFeedXImage: Set the XID of the window to capture

xname(set: str) → VideoInputFeedXImage: Set the name of the window to capture

capture_area(set: px_core.utility.RectangleInt) → VideoInputFeedXImage: Set the capture area pixel coordinates

startx(set: int) → VideoInputFeedXImage: Set the top-left X coordinate of area to capture

starty(set: int) → VideoInputFeedXImage: Set the top-left Y coordinate of area to capture

endx(set: int) → VideoInputFeedXImage: Set the bottom-right X coordinate of area to capture

endy(set: int) → VideoInputFeedXImage: Set the bottom-right Y coordinate of area to capture

use_damage(set: bool) → VideoInputFeedXImage: Set whether to use XDamage to only capture changed regions

show_pointer(set: bool) → VideoInputFeedXImage: Set whether to show mouse pointer

remote(set: bool) → VideoInputFeedXImage: Set whether the X display is remote

enable_navigation_events(set: bool) → VideoInputFeedXImage: Set whether to enable navigation events

properties() → VideoInputFeedXImage.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoOutputFeedComponent: Base class for video output feed components

class px_core.media.VideoOutputComponentNull

Bases: VideoOutputFeedComponent

A placeholder video output feed component that does not actually output video.

This feed component can be used to disable or skip an output when creating feeds.

Note

When used, the underlying pipeline implementation may optimize away unused processing elements (e.g., tee, queues) for improved performance when the output is not needed.

static is_video_output_component_null(component: VideoOutputFeedComponent) → bool

Check if a component is a VideoOutputComponentNull.

Parameters:: component (VideoOutputFeedComponent) – The video output feed component to check.
Returns:: true if the component is a VideoOutputComponentNull, false otherwise.

class px_core.media.VideoOutputFeedAuto

Bases: VideoOutputFeedComponent

A video output component that chooses an appropriate output to use.

This feed component can be used to simply add a suitable video output; in practice, this will open a new window to stream video to. This can be useful to test video feeds, but real world applications will typically want to control and manage video output windows using other output components.

class px_core.media.VideoOutputFeedInter

class px_core.media.VideoOutputFeedInter(label: str)

Bases: VideoOutputFeedComponent

A video output component that outputs video to a named inter channel.

This feed component allows (multiple) uses of the video stream in other pipelines, via VideoInputFeedInter.

class Properties

The properties required to specify the inter video channel

property channel: str

make_input() → VideoInputFeedInter

Create an input feed that consumes from this output.

Because @c intervideosrc uses a last-frame model each consumer reads independently, so all inputs share the same channel name. All calls to makeInput() must be made before the owning pipeline is built (i.e. before the feed @c create() call that receives this output).

Accessors

properties() → VideoOutputFeedInter.Properties: Returns a read-only reference to the properties for the object

Note

The channel name is auto-generated at construction time.

class px_core.media.VideoOutputFeedSharedMemory

Bases: VideoOutputFeedComponent

A video output feed component that writes raw video to a shared memory area using GStreamer’s shmsink element.

This feed component publishes raw video buffers over a shared memory transport for consumption by a matching shared memory source (such as the VideoInputFeedSharedMemory component, backed by shmsrc). The two endpoints communicate over a control socket identified by a shared socketPath. No encoding is performed; shmsink transfers the raw video data directly.

class Properties

The properties required to specify the shared memory sink settings.

property socket_path: str

property shared_memory_bytes: int | None

property wait_for_connection: bool | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

socket_path(set: str) → VideoOutputFeedSharedMemory: Set the shared memory control socket path

shared_memory_bytes(set: int) → VideoOutputFeedSharedMemory: Set the shared memory area size in bytes

default_shared_memory_bytes() → VideoOutputFeedSharedMemory: Use the default shared memory area size

wait_for_connection(set: bool) → VideoOutputFeedSharedMemory: Set whether to block the stream until a consumer is connected

video_capabilities() → VideoCapabilities

Mutable access to the output video capabilities.

Use the returned object to pin the exact format (pixel format, resolution and frame rate) published to shared memory, e.g. output.videoCapabilities().mediaType(...).width(...).height(...). When set, a conversion to these capabilities is inserted before the sink, which both guarantees the published format and normalises the buffer memory layout so the reading endpoint can interpret it. The reading endpoint must be configured with matching capabilities. If never set, no capabilities are enforced and the format published is whatever the upstream pipeline produces.

video_capabilities() → VideoCapabilities | None: Read-only access to the (optional) output video capabilities

properties() → VideoOutputFeedSharedMemory.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoOutputFeedUdp

Bases: VideoOutputFeedComponent

A video output feed component that sends video output to a given UDP port.

This feed component provides properties to specify how the feed is encoded using H264 streamed to UDP port using RTP.

class RtpAggregateMode

Bases: enum.IntEnum

Settings for RTP aggregate mode

NONE: int = 0

ZERO_LATENCY: int = 1

MAX_STAP: int = 2

class Properties

The properties required to specify the video output encoder and UDP settings.

property encoder: H264VideoEncoderComponent

property config_interval: int

property aggregate_mode: VideoOutputFeedUdp.RtpAggregateMode

property host: str

property port: int

static make_default_encoder() → X264EncoderFeedComponent: The default encoder this component uses is X264

config_interval(set: int) → VideoOutputFeedUdp: Set RTP config interval

aggregate_mode(set: VideoOutputFeedUdp.RtpAggregateMode) → VideoOutputFeedUdp: Set RTP aggregate mode

host(set: str) → VideoOutputFeedUdp: Set UDP host

port(set: int) → VideoOutputFeedUdp: Set UDP port

encoder() → H264VideoEncoderComponent: Get encoder (read-only access)

encoder(enc: H264VaapiEncoderComponent) → VideoOutputFeedUdp: Set encoder (H264VaapiEncoderComponent)

encoder(enc: X264EncoderFeedComponent) → VideoOutputFeedUdp: Set encoder (X264EncoderFeedComponent)

default_encoder() → VideoOutputFeedUdp: Reset encoder to default X264 encoder

encoder_properties() → X264EncoderFeedComponent

Returns X264 encoder properties object for backwards compatibility.

Returns:: Reference to X264 encoder settings
Raises:: RuntimeError – if the current encoder is not X264 (e.g., if VAAPI encoder was set)

Deprecated since version Use: encoder() setter with encoder configuration instead

Note

For backwards compatibility only. To set a non-X264 encoder, use encoder() setter.

properties() → VideoOutputFeedUdp.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoOutputFeedV4Linux2

Bases: VideoOutputFeedComponent

A video output feed component that sends video output to a V4L2 loopback device.

This feed component provides properties to specify the V4L2 loopback device for raw video output. No encoding is performed as v4l2sink handles raw video data.

class Properties

The properties required to specify the V4L2 loopback device settings.

property device: str

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

device(set: str) → VideoOutputFeedV4Linux2: Set V4Linux2 device path

default_device() → VideoOutputFeedV4Linux2: Reset V4Linux2 device path to default (empty string, uses gstreamer default)

properties() → VideoOutputFeedV4Linux2.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoStageCrop

Bases: VideoFeedStageComponent

A processing stage that applies cropping to the video

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property crop_rectangle: px_core.utility.RectangleUInt

class px_core.media.VideoStageFaceBlur

Bases: VideoFeedStageComponent

A processing stage that applies basic Open CV-based face blurring to a video

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property do_canny_pruning: bool

min_neighbours() → int | None: Get minimum number of neighbours

min_neighbours(set: int) → VideoStageFaceBlur: Set minimum number of neighbours

min_neighbours_default() → VideoStageFaceBlur: Set minimum number of neighbours to the default

property min_size: px_core.utility.SizeUInt

min_size_default() → VideoStageFaceBlur: Set window minimum size to default

property profile: str

profile_default() → VideoStageFaceBlur: Set profile name to default

scale_factor() → float | None: Get scale factor

scale_factor(set: float) → VideoStageFaceBlur: Set scale factor

scale_factor_default() → VideoStageFaceBlur: Set scale factor to default

class px_core.media.VideoStageFrameRate(frameRate: FrameRate = ...)

Bases: VideoFeedStageComponent

A processing stage that alters the video frame rate

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property frame_rate: FrameRate

property drop_only: bool

property skip_to_first: bool

class px_core.media.VideoStageGaussianBlur(sigma: float = 0)

Bases: VideoFeedStageComponent

A processing stage that applies a Gaussian blur to a video feed

Note that this is a simple CPU-based blur, so not suitable for high resolutions or frame rates.

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property sigma: float

class px_core.media.VideoStagePrivacy

Bases: VideoFeedStageComponent

A video stage which allows the video to be obscured at runtime by sending a feed request. Video is obscured by setting the brightness and saturation of the video to fixed values that produce a solid black output, ensuring that no pixel data survives. Pixel data destruction is validated in unit tests, which are automatically run before every release.

class RequestPrivacy(privacyOn: bool)

Bases: FeedRequest

A request to set the privacy on/off that is handled by this component

privacy_on() → bool: Get the privacy setting

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property initial_privacy: bool

class px_core.media.VideoStageResize(resolution: px_core.utility.SizeUInt = ...)

Bases: VideoFeedStageComponent

A processing stage that resizes a video feed

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property height: int

property width: int

property resolution: px_core.utility.SizeUInt

class px_core.media.VideoStageRotateFlip

class px_core.media.VideoStageRotateFlip(method: VideoStageRotateFlip.Method)

Bases: VideoFeedStageComponent

A processing stage that applies a rotation to or flips a video

class Method

Bases: enum.IntEnum

Rotation/flip method

None_: int = 0

Clockwise90: int = 1

Rotate180: int = 2

Anticlockwise90: int = 3

FlipHorizontal: int = 4

FlipVertical: int = 5

FlipDiagonalUL: int = 6

FlipDiagonalUR: int = 7

static rotation_to_method(rotation: int) → VideoStageRotateFlip.Method: Convert a rotation amount to a Method enum If the rotation is not a multiple of 90, returns the nearest Method

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property method: VideoStageRotateFlip.Method

class px_core.media.VideoStageTextOverlay

Bases: VideoFeedStageComponent

A processing stage that overlays text on a video

class HorizontalAlignment

Bases: enum.IntEnum

Horizontal alignment options

Left: int = 0

Center: int = 1

Right: int = 2

Position: int = 3

Absolute: int = 4

class VerticalAlignment

Bases: enum.IntEnum

Vertical alignment options

Top: int = 0

Center: int = 1

Bottom: int = 2

Baseline: int = 3

Position: int = 4

Absolute: int = 5

class LineAlignment

Bases: enum.IntEnum

Alignment of text lines relative to each other

Left: int = 0

Center: int = 1

Right: int = 2

class TextWrapMode

Bases: enum.IntEnum

Text wrap mode

None_: int = 0

Word: int = 1

Char: int = 2

WordChar: int = 3

class RequestSetText(text: str)

Bases: FeedRequest

A request to change the overlay text

text() → str: Get the text to set

Getters and setters

Setter functions return a reference to the parent object, allowing callers to chain setting functions.

property text: str

property auto_resize: bool

property text_color: px_core.utility.Color

property text_offset: px_core.utility.PointInt

property outline_color: px_core.utility.Color

property draw_outline: bool

property draw_shadow: bool

property font_description: str

property horizontal_alignment: VideoStageTextOverlay.HorizontalAlignment

property horizontal_alignment_absolute: bool

property line_alignment: VideoStageTextOverlay.LineAlignment

property vertical_alignment: VideoStageTextOverlay.VerticalAlignment

property vertical_alignment_absolute: bool

absolute_alignment() → px_core.utility.PointDouble | None: Get the absolute alignment position (0..1 relative to canvas)

absolute_alignment(set: px_core.utility.PointDouble) → VideoStageTextOverlay: Set the absolute alignment position (0..1 relative to canvas)

reset_absolute_alignment() → VideoStageTextOverlay: Reset the absolute alignment position

positional_alignment() → px_core.utility.PointDouble | None: Get the positional alignment position (0..1 relative to canvas)

positional_alignment(set: px_core.utility.PointDouble) → VideoStageTextOverlay: Set the positional alignment position (0..1 relative to canvas)

reset_positional_alignment() → VideoStageTextOverlay: Reset the positional alignment position

property padding_size: px_core.utility.SizeInt

property text_wrap_mode: VideoStageTextOverlay.TextWrapMode

property response_time_compensation: bool

class px_core.media.VideoWebRtcEncodeFeedComponent: Base class for video WebRTC encoder feed components

class px_core.media.VideoWebRtcEncodeFeedH264

Bases: VideoWebRtcEncodeFeedComponent

A video feed component for specifying H264 encoding for WebRTC.

class Properties

The properties required to encode the video feed for WebRTC using H264

property encoding: H264VideoEncoderComponent

property rtp_mtu: int

static make_default_encoder() → X264EncoderFeedComponent: The default encoder this component uses is X264

rtp_mtu(set: int) → VideoWebRtcEncodeFeedH264: Set the RTP MTU value

encoder() → H264VideoEncoderComponent: Get encoder (read-only access)

encoder(enc: H264VaapiEncoderComponent) → VideoWebRtcEncodeFeedH264: Set encoder (H264VaapiEncoderComponent)

encoder(enc: X264EncoderFeedComponent) → VideoWebRtcEncodeFeedH264: Set encoder (X264EncoderFeedComponent)

default_encoder() → VideoWebRtcEncodeFeedH264: Reset encoder to default X264 encoder

encoding_properties() → X264EncoderFeedComponent

Returns X264 encoding properties object for backwards compatibility.

Returns:: Reference to X264 encoder settings
Raises:: RuntimeError – if the current encoder is not X264 (e.g., if VAAPI encoder was set)

Deprecated since version Use: encoder() setter with encoder configuration instead

Note

For backwards compatibility only. To set a non-X264 encoder, use encoder() setter.

properties() → VideoWebRtcEncodeFeedH264.Properties: Returns a read-only reference to the properties for the object

video_web_rtc_encode_feed_h264(enc: H264VaapiEncoderComponent) → None: Set video web rtc encode feed h264 (H264VaapiEncoderComponent)

video_web_rtc_encode_feed_h264(enc: X264EncoderFeedComponent) → None: Set video web rtc encode feed h264 (X264EncoderFeedComponent)

class px_core.media.VideoWebRtcEncodeFeedVp8

Bases: VideoWebRtcEncodeFeedComponent

A video feed component for specifying VP8 encoding for WebRTC.

class EndUsageType

Bases: enum.IntEnum

End usage type specifies the bit rate control mode

VBR: int = 0

CBR: int = 1

CQ: int = 2

class ErrorResilienceType

Bases: enum.IntEnum

Error resilience setting

Default: int = 0

Partitions: int = 1

class Properties

The properties required to encode the video feed for WebRTC using VP8 See https://www.webmproject.org/docs/encoder-parameters/

property target_bitrate: BitRate

property deadline: int

property keyframe_max_dist: int

property cpu_used: int

property threads: int

property rtp_mtu: int

property end_usage: VideoWebRtcEncodeFeedVp8.EndUsageType

property error_resilient: VideoWebRtcEncodeFeedVp8.ErrorResilienceType

property adaptive_quality: BitRateQualityMapping | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

target_bitrate(set: BitRate) → VideoWebRtcEncodeFeedVp8: Set the target bitrate, where zero indicates “auto”

deadline(set: int) → VideoWebRtcEncodeFeedVp8: Set the frame deadline

keyframe_max_dist(set: int) → VideoWebRtcEncodeFeedVp8: Set the keyframe maximum distance

cpu_used(set: int) → VideoWebRtcEncodeFeedVp8: Set CPU used: Encoder speed/quality trade-off (-16=best quality, 16=fastest) behaviour depends on deadline mode (see https://www.webmproject.org/docs/encoder-parameters/)

threads(set: int) → VideoWebRtcEncodeFeedVp8: Set threads to use

rtp_mtu(set: int) → VideoWebRtcEncodeFeedVp8: Set RTP MTU (maximum size of one packet for rtp)

end_usage(set: VideoWebRtcEncodeFeedVp8.EndUsageType) → VideoWebRtcEncodeFeedVp8: Set end usage rate control mode

error_resilient(set: VideoWebRtcEncodeFeedVp8.ErrorResilienceType) → VideoWebRtcEncodeFeedVp8: Set error resilience

properties() → VideoWebRtcEncodeFeedVp8.Properties: Returns a read-only reference to the properties for the object

Adaptive quality

adaptive_quality(bands: list[BitRateQualityMapping.BandItem]) → None: Set adaptive quality mapping for the target bitrate, from a vector of bands

adaptive_quality(mapping: BitRateQualityMapping) → None: Set adaptive quality mapping for the target bitrate, from a validated quality mapping

no_adaptive_quality() → None: Remove any adaptive quality mapping

class px_core.media.WebRtcStats

Statistics gather from a WebRTC feed

WebRTC stats are based on the webrtc-stats spec available from https://www.w3.org/TR/webrtc-stats/. Since the webrtc-stats spec is a draft and subject to change, the stats are represented by a JSON object rather than strongly typed at this stage. Note: timestamp fields in the output are based on the host system’s “monotonic clock”, in microseconds. The basis of the clock value is undefined/system dependent, and applications should use the values for relative comparisons only.

class BaseWebRtcStats

Base/common properties for all WebRTC stats

serialize_base(serializer: px_core.utility.JsonSerializer, type: str) → px_core.utility.JsonSerializer: Helper to serialize with type

property id: str

property timestamp: float

class PeerConnectionStats

Bases: BaseWebRtcStats

Stats for a peer connection

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property data_channels_opened: int

property data_channels_closed: int

property data_channels_requested: int

property data_channels_accepted: int

class CodecStats

Bases: BaseWebRtcStats

Stats for a codec

Note that in some cases the codec stats are omitted

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property payload_type: int | None

property ssrc: int | None

property mime_type: str | None

property codec_type: str | None

property clock_rate: int | None

property channels: int | None

property sdp_fmtp_line: str | None

class TransportStats

Bases: BaseWebRtcStats

Stats for a transport

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

class GstRtpSourceStats

GST RTP source stats

See https://gstreamer.freedesktop.org/documentation/rtpmanager/RTPSource.html#RTPSource:stats

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property ssrc: int

property internal: bool

property validated: bool

property received_bye: bool

property is_csrc: bool

property is_sender: bool

property seq_num_base: int

property clock_rate: int

property octets_sent: int

property packets_sent: int

property octets_received: int

property packets_received: int

property bytes_received: int

property bit_rate: int

property packets_lost: int

property jitter: int

property sent_pli_count: int

property recv_pli_count: int

property sent_fir_count: int

property recv_fir_count: int

property sent_nack_count: int

property recv_nack_count: int

property recv_packet_rate: int

property have_sr: bool

property sr_ntp_time: int

property sr_rtp_time: int

property sr_octet_count: int

property sr_packet_count: int

class GstRtpSourceStatsWithRb

Bases: GstRtpSourceStats

GST RTP source stats, with RB details

See https://gstreamer.freedesktop.org/documentation/rtpmanager/RTPSource.html#RTPSource:stats

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property sent_rb: bool

property sent_rb_fraction_lost: int

property sent_rb_packets_lost: int

property sent_rb_ext_highest_seq: int

property sent_rb_jitter: int

property sent_rb_lsr: int

property sent_rb_dlsr: int

property have_rb: bool

property rb_ssrc: int

property rb_fraction_lost: int

property rb_packets_lost: int

property rb_ext_highest_seq: int

property rb_jitter: int

property rb_lsr: int

property rb_dlsr: int

property rb_round_trip: int

class GstRtpJitterBufferStats

GST RTP jitter buffer stats

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property num_pushed: int

property num_lost: int

property num_late: int

property num_duplicates: int

property avg_jitter: int

property rtx_count: int

property rtx_success_count: int

property rtx_per_packet: float

property rtx_rtt: int

class OutboundRtpStats

Bases: BaseWebRtcStats

Stats for outbound RTP

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property ssrc: int

property codec_id: str

property transport_id: str

property bytes_sent: int

property packets_sent: int

property fir_count: int

property pli_count: int

property nack_count: int

property gst_rtp_source_stats: WebRtcStats.GstRtpSourceStats

class InboundRtpStats

Bases: BaseWebRtcStats

Stats for inbound RTP

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property ssrc: int

property codec_id: str

property transport_id: str

property packets_received: int

property jitter: float

property remote_id: str

property bytes_received: int

property fir_count: int

property pli_count: int

property nack_count: int

property packets_lost: int | None

property packets_discarded: int | None

property packets_duplicated: int | None

property gst_rtp_jitter_buffer_stats: WebRtcStats.GstRtpJitterBufferStats | None

property gst_rtp_source_stats: WebRtcStats.GstRtpSourceStatsWithRb

class RemoteInboundRtpStats

Bases: BaseWebRtcStats

Stats for remote inbound RTP

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property local_id: str

property ssrc: int

property codec_id: str

property transport_id: str

property packets_lost: int

property jitter: float

property fraction_lost: float

property round_trip_time: float

property gst_rtp_source_stats: WebRtcStats.GstRtpSourceStatsWithRb

class RemoteOutboundRtpStats

Bases: BaseWebRtcStats

Stats for remote outbound RTP

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property ssrc: int

property codec_id: str

property transport_id: str

property bytes_sent: int

property packets_sent: int

property remote_timestamp: float

property local_id: str

class CandidatePairStats

Bases: BaseWebRtcStats

Stats for a candidate pair

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property available_incoming_bitrate: float | None

property available_outgoing_bitrate: float | None

property bytes_received: int | None

property bytes_sent: int | None

property current_round_trip_time: float | None

property last_packet_received_timestamp: float | None

property last_packet_sent_timestamp: float | None

property local_candidate_id: str | None

property nominated: bool | None

property remote_candidate_id: str | None

property requests_received: int | None

property requests_sent: int | None

property responses_received: int | None

property responses_sent: int | None

property state: str | None

property total_round_trip_time: float | None

property transport_id: str | None

class IceCandidateStats

Bases: BaseWebRtcStats

Stats for an ICE candidate

serialize(serializer: px_core.utility.JsonSerializer) → None: Serialize with JsonSerializer

property address: str | None

property candidate_type: str

property deleted: bool | None

property port: int | None

property priority: int | None

property protocol: str | None

property relay_protocol: str | None

property transport_id: str

property url: str | None

class StatsElements

All the WebRTC stats elements

property peer_connections: dict[str, WebRtcStats.PeerConnectionStats]

property codecs: dict[str, WebRtcStats.CodecStats]

property transports: dict[str, WebRtcStats.TransportStats]

property inbound_rtps: dict[str, WebRtcStats.InboundRtpStats]

property outbound_rtps: dict[str, WebRtcStats.OutboundRtpStats]

property remote_inbound_rtps: dict[str, WebRtcStats.RemoteInboundRtpStats]

property remote_outbound_rtps: dict[str, WebRtcStats.RemoteOutboundRtpStats]

property candidate_pairs: dict[str, WebRtcStats.CandidatePairStats]

property ice_candidates: dict[str, WebRtcStats.IceCandidateStats]

property unparsed_stats: list[str]

property elements: WebRtcStats.StatsElements

class px_core.media.WebRtcStatsRequest(callback: Callable[[Any], None])

Bases: FeedRequest

A feed request to obtain SRT feed statistics.

callback() → Callable[[Any], None]: The callback to receive the stats

class px_core.media.X264EncoderFeedComponent

Bases: H264VideoEncoderComponent

Encapsulates X264 encoder element for use in feed components

class EncoderPreset

Bases: enum.IntEnum

Encoder speed/quality tradeoff preset options

NONE: int = 0

ULTRAFAST: int = 1

SUPERFAST: int = 2

VERYFAST: int = 3

FASTER: int = 4

FAST: int = 5

MEDIUM: int = 6

SLOW: int = 7

SLOWER: int = 8

VERYSLOW: int = 9

PLACEBO: int = 10

class EncoderPass

Bases: enum.IntEnum

Encoding pass type

CBR: int = 0

QUANT: int = 1

QUAL: int = 2

PASS1: int = 3

PASS2: int = 4

PASS3: int = 5

class EncoderTuneClass

Encapsulating class for encoder tuning flags

class Enum

Bases: enum.IntEnum

Bit flag values for EncoderTune

STILLIMAGE: int = 1

FASTDECODE: int = 2

ZEROLATENCY: int = 4

class Properties

Properties required to encode video with X264

property bitrate: BitRate

property speed_preset: X264EncoderFeedComponent.EncoderPreset

property tune: int

property key_int_max: int

property pass_: X264EncoderFeedComponent.EncoderPass

property byte_stream: bool

property threads: int

property adaptive_quality: BitRateQualityMapping | None

Setters

These setter functions return a reference to the parent object, allowing callers to chain setting functions.

bitrate(set: BitRate) → X264EncoderFeedComponent: Set bitrate

speed_preset(set: X264EncoderFeedComponent.EncoderPreset) → X264EncoderFeedComponent: Set speed preset type

tune(set: Any) → X264EncoderFeedComponent: Set encoder tuning as a single flag

tune(set: int) → X264EncoderFeedComponent: Set encoder tuning as one or more EncoderTune bit flags

tune_none() → X264EncoderFeedComponent: Set no encoder tuning

key_int_max(set: int) → X264EncoderFeedComponent: Set maximum between two key-frames (0 = auto)

pass_(set: X264EncoderFeedComponent.EncoderPass) → X264EncoderFeedComponent: Set encoder pass setting

byte_stream(set: bool) → X264EncoderFeedComponent: Set byte stream flag

threads(set: int) → X264EncoderFeedComponent: Set threads used (0 = auto)

Adaptive quality

adaptive_quality(bands: list[BitRateQualityMapping.BandItem]) → None: Set adaptive quality mapping for the target bitrate, from a vector of bands

adaptive_quality(mapping: BitRateQualityMapping) → None: Set adaptive quality mapping for the target bitrate, from a validated quality mapping

no_adaptive_quality() → None: Remove any adaptive quality mapping

properties() → X264EncoderFeedComponent.Properties: Returns a read-only reference to the properties for the object

class px_core.media.VideoPeerRtpEncodeFeedComponent: Class for video Peer encoder feed components

class px_core.media.VideoPeerRtpDecodeFeedComponent: Class for video Peer decoder feed components

class px_core.media.PeerSrtpEncryptFeedComponent: Class for SRTP-based peer feed encryption components

class px_core.media.PeerSrtpDecryptFeedComponent: Class for SRTP-based peer feed decryption components

class px_core.media.PeerUdpSinkFeedComponent: Class for Peer feed Udp Sink component

class px_core.media.PeerUdpSourceFeedComponent: Class for Peer feed Udp Source component

class px_core.media.AdaptiveFrameRateRule

Definition for a rule which takes an adaptive quality value and gives back an outcome value

value_for_quality(quality: AdaptiveQuality) → FrameRate | None

Given a quality, set the target value to the outcome

The return value is optional, allowing the rule to return nothing to indicate no change.

class px_core.media.AdaptiveResolutionRule

Definition for a rule which takes an adaptive quality value and gives back an outcome value

value_for_quality(quality: AdaptiveQuality) → px_core.utility.SizeUInt | None

Given a quality, set the target value to the outcome

The return value is optional, allowing the rule to return nothing to indicate no change.

class px_core.media.AdaptiveMinMaxFrameRateRule(min: FrameRate, max: FrameRate)

General adaptive rule which interpolates between a minimum and maximum value of the templated type.

The type must have a lerp function defined for it.

static create(minValue: FrameRate, maxValue: FrameRate) → AdaptiveMinMaxFrameRateRule: Factory function to create an instance of the rule as a shared pointer. The caller provides a defined minimum and maximum value to lerp with.

property minimum: FrameRate

property maximum: FrameRate

value_for_quality(quality: AdaptiveQuality) → FrameRate | None

class px_core.media.AdaptiveMinMaxResolutionRule(min: px_core.utility.SizeUInt, max: px_core.utility.SizeUInt)

General adaptive rule which interpolates between a minimum and maximum value of the templated type.

The type must have a lerp function defined for it.

static create(minValue: px_core.utility.SizeUInt, maxValue: px_core.utility.SizeUInt) → AdaptiveMinMaxResolutionRule: Factory function to create an instance of the rule as a shared pointer. The caller provides a defined minimum and maximum value to lerp with.

property minimum: px_core.utility.SizeUInt

property maximum: px_core.utility.SizeUInt

value_for_quality(quality: AdaptiveQuality) → px_core.utility.SizeUInt | None

class px_core.media.FrameRateQualityMapping

A set of adaptive quality bands, which are used to map quality values to target values of type T

A mapping will always contain at least one band, and is never empty or invalid

class BandItem

A quality band value used in an AdaptiveQualityMapping to convert a quality value into a target value matching the band

Quality values are always 0.1 but for convenience the band size is the proportion in the full collection of bands, allowing the application to use any scale of band size values.

property size: float

property value: FrameRate

static create(bands: list[FrameRateQualityMapping.BandItem]) → FrameRateQualityMapping

Create a new, validated adaptive quality mapping with the given bands

If the provided bands are invalid, the returned outcome will contain an error code

value_for_quality(quality: AdaptiveQuality) → FrameRate: Get the value for a given quality Returns a value based on capped quality value 0..1

best_quality_value() → FrameRate: Get the best/highest quality value

worst_quality_value() → FrameRate: Get the worst/lowest quality value

class px_core.media.ResolutionQualityMapping

A set of adaptive quality bands, which are used to map quality values to target values of type T

A mapping will always contain at least one band, and is never empty or invalid

class BandItem

A quality band value used in an AdaptiveQualityMapping to convert a quality value into a target value matching the band

Quality values are always 0.1 but for convenience the band size is the proportion in the full collection of bands, allowing the application to use any scale of band size values.

property size: float

property value: px_core.utility.Size

static create(bands: list[ResolutionQualityMapping.BandItem]) → ResolutionQualityMapping

Create a new, validated adaptive quality mapping with the given bands

If the provided bands are invalid, the returned outcome will contain an error code

value_for_quality(quality: AdaptiveQuality) → px_core.utility.SizeUInt: Get the value for a given quality Returns a value based on capped quality value 0..1

best_quality_value() → px_core.utility.SizeUInt: Get the best/highest quality value

worst_quality_value() → px_core.utility.SizeUInt: Get the worst/lowest quality value

class px_core.media.BitRateQualityMapping

A set of adaptive quality bands, which are used to map quality values to target values of type T

A mapping will always contain at least one band, and is never empty or invalid

class BandItem

A quality band value used in an AdaptiveQualityMapping to convert a quality value into a target value matching the band

Quality values are always 0.1 but for convenience the band size is the proportion in the full collection of bands, allowing the application to use any scale of band size values.

property size: float

property value: BitRate

static create(bands: list[BitRateQualityMapping.BandItem]) → BitRateQualityMapping

Create a new, validated adaptive quality mapping with the given bands

If the provided bands are invalid, the returned outcome will contain an error code

value_for_quality(quality: AdaptiveQuality) → BitRate: Get the value for a given quality Returns a value based on capped quality value 0..1

best_quality_value() → BitRate: Get the best/highest quality value

worst_quality_value() → BitRate: Get the worst/lowest quality value

px_core.media.AdaptiveMinMaxRule

px_core.media.AdaptiveQualityMapping

px_core.media.AdaptiveRule

px_core.media.media_type_format_to_string(type: MediaType) → str

px_core.media.media_type_from_format_string(format: str) → MediaType

px_core.media.media_type_to_string(type: MediaType) → str

px_core.media.validate_enum_value(value: int) → MediaSessionFeedType | None

px_core.media

Module Contents

Classes

Functions

Attributes

`px_core.media`