4.2.5. Proximie::PxMedia reference

namespace PxMedia

The PxMedia namespace implements the core media streaming functionality provided the SDK. This includes audio and video feeds being between the host applications and other participants in a media session.

Typedefs

using PxMediaError = PxUtility::ErrorCodeException<PxMediaErrorCategory>: Exception class for PxMediaError errors

using StreamIndexHint = uint16_t

A preferred stream index for presentation in applications.

The index hint is intended to allow a sending application to suggest placement or priority of a given stream. For example, in Proximie’s webapp, the four panes for videos are assigned an index and clients can suggest which pane to use. This is a hint only, since different participants may try to suggest the same index without being aware of each other.

Enums

enum class AVContainer

The container format for the output file.

Values:

enumerator MP4

enumerator MKV

enumerator AVI

enumerator FLV

enum class ConnectionState

Enumeration for a connection state.

Values:

enumerator READY

enumerator CONNECTING

No connection, ready to connect

enumerator CONNECTED

In the process of connecting

enumerator DISCONNECTING

Connected and active

enum class AudioCodec : uint16_t

The audio codec to use for the output file.

Values:

enumerator AAC

enumerator MP3

enumerator OPUS

enumerator VORBIS

enum class VideoCodec : uint16_t

The video codec to use for the output file.

Values:

enumerator H264

enumerator H265

enumerator VP8

enumerator VP9

enumerator AV1

enum class PxMediaErrorCode

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

Values:

enumerator Successful: Success (not an error)

enumerator FeedIdNotFound: The feed ID supplied was not known/found.

enumerator InvalidFeedId: The feed ID supplied is not valid.

enumerator FeedRequestUnhandled: The feed request was not handled, i.e. ignored.

enumerator SessionNotConnected: The session/media server has not connected yet.

enumerator SessionActive: The session is already active.

enumerator InvalidSession: The session requested is invalid.

enumerator SessionNotActive: The session requested is valid, but not active.

enumerator SessionCreateFailed: Session creation failed.

enumerator SessionFeedNotFound: The feed did not belong to the session.

enumerator SessionFeedExists: The feed already exists in the session.

enumerator SessionDisconnected: The session was unexpectedly disconnected.

enumerator NotConnected

Deprecated:: Use PxMediaErrorCode::SessionNotConnected instead

enumerator PluginAttachFailed: Media server could not connect to the plugin.

enumerator PluginConnectionActive: Connection is already active.

enumerator PluginConnectionClosed: Connection is closed.

enumerator CreateMediaRoomFailed: The media room could not be created.

enumerator JoinMediaRoomFailed: The media room could not be joined.

enumerator WebRtcAnswerFailed: WebRTC answer failed.

enumerator WebRtcOfferFailed: WebRTC offer failed.

enumerator MediaRoomStartFailed: Stream failed to start in the media room.

enumerator MediaRoomConfigureFailed: Stream failed configuring for the media room.

enumerator MediaRoomConfigureError: Configure returned generic error.

enumerator MediaRoomConfigurePubFullError: Configure returned Max Publishers Reached (432) error.

enumerator WebRtcCandidateFailed: WebRTC trickle candidate failed.

enumerator MediaDeviceMetadataInvalid: Media stream metadata was invalid.

enumerator WebSocketError: WebSocket error.

enumerator MediaServerHangup: Received a media server hangup event.

enumerator MediaServerHangupClosePC: Received a close peer connection hangup.

enumerator NoPipeline: Pipeline elements have not be built/set.

enumerator PipelineExists: The pipeline already exists.

enumerator PipelineIsStopped: Pipeline is stopped (error, manually, …)

enumerator PipelineStreamError: Pipeline stream error.

enumerator PipelineParseError: Pipeline parse error.

enumerator PipelineElementNotFound: The pipeline element was not found.

enumerator PipelineNoElementName: Element name was not set as expected.

enumerator PipelineElementBadProps: A pipeline element’s (combination of) properties is invalid.

enumerator PipelineBindingInvalid: A pipeline segment binding was invalid.

enumerator PipelineInputAlreadyAdded: Input UUID already exists in the feed’s pipeline.

enumerator PipelineInvalidUUID: Invalid UUID.

enumerator PipelineElementOperationFailed: A GStreamer element/pad/bin operation failed.

enumerator KeepaliveTimeout: No keepalive answer within expected timeout.

enumerator ExpectedAck: Expected ack, but received another type.

enumerator InvalidResponseContent: The response JSON’s content was incorrect.

enumerator InvalidPeerChannel: The requested channel is invalid.

enumerator InvalidEncryptionKey: The encryption key is invalid.

enumerator InvalidAdaptiveRule: The adaptive rule is invalid.

enumerator InvalidMediaType: The media type is not valid.

enumerator InvalidMediaFormat: The media format is not valid.

enumerator MediaServiceNotConnected: The media service is not connected.

enumerator MediaServiceStarted: The media service has already been started.

enumerator MediaServiceConnectFailed: The media service connection failed.

enumerator MediaServiceDisconnected: The media service got disconnected.

enumerator MediaServiceReconnecting: The media service is trying to reconnect.

enumerator MediaServiceErrorStatus: The media service returned an error status.

enumerator MediaServiceEventInvalid: A media service event was invalid.

Functions

const PxUtility::EnumMapper<AudioCodec> &audioCodecMapper(): Mapper to convert between audio codec enum and string.

const PxUtility::EnumMapper<VideoCodec> &videoCodecMapper(): Mapper to convert between video codec enum and string.

inline error_code make_error_code(const PxMediaErrorCode code): Provides support to make an error_code for the PxMediaErrorCode type.

inline error_condition make_error_condition(const PxMediaErrorCode code): Provides support to make an error_condition for the PxMediaErrorCode type.

template<typename T> class AdaptiveBandsRule : public Proximie::PxMedia::AdaptiveRule<T>

#include <PxMedia/AdaptiveBandsRule.h>

An adaptive rule that takes a number of bands matching a quality range to a target value of the templated type.

Public Types

using Bands = std::vector<Band>

A vector of bands to choose between.

The bands are ordered, where the first band is the value to apply as the lowest quality band, and the band size is indicated by the weight. The bands are normalised so the bands will always encapsulate the full 0..1 quality range to apply.

Public Functions

AdaptiveBandsRule() = default: Construct an empty adaptive bands rule.

inline outcome::result<void> bands(const Bands &bands): Set the bands for the rule.

inline virtual boost::optional<T> valueForQuality(AdaptiveQuality quality) const override

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.

Public Static Functions

static inline std::shared_ptr<AdaptiveBandsRule<T>> create(): Factory function to create an empty adaptive bands rule.

static inline SharedOutcome<AdaptiveBandsRule<T>> create(const Bands &bands)

Factory function to create an instance of the rule as a shared pointer. The caller provides a defined number of bands to interpolate between.

The function validates the bands are valid, and thus returns an error outcome if they are not.

struct Band

#include <PxMedia/AdaptiveBandsRule.h>

The definition of a band in the adaptive rule.

A band is a (non-negative) weight and a value. For convenience, the caller can use any scale of weight values, and these are normalized for choosing a band for a 0..1 quality.

Public Members

double weight: The (non-negative) weight of the band.

T value: When the band is matched, the value is applied.

template<typename T> class AdaptiveMinMaxRule : public Proximie::PxMedia::AdaptiveRule<T>

#include <PxMedia/AdaptiveMinMaxRule.h>

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.

Public Functions

inline AdaptiveMinMaxRule(T min, T max): Construct a min/max rule, providing a defined minimum and maximum value to lerp with.

inline AdaptiveMinMaxRule &minimum(T min): Set the minimum value

inline const T &minimum() const: Get the minimum value

inline AdaptiveMinMaxRule &maximum(T max): Set the maximum value

inline const T &maximum() const: Get the maximum value

inline virtual boost::optional<T> valueForQuality(AdaptiveQuality quality) const override

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.

Public Static Functions

static inline std::shared_ptr<AdaptiveMinMaxRule<T>> create(const T &minValue, const T &maxValue): 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.

class AdaptiveQuality

#include <PxMedia/AdaptiveQuality.h>

Adaptive feed quality is a floating point value in the range 0..1

Public Types

using QualityValueType = double: The underlying floating point value type for quality

Public Functions

AdaptiveQuality() = default: Feed quality constructor sets the quality to 1

inline AdaptiveQuality(QualityValueType quality): Feed qualities can be inferred from a floating point value

inline bool isMaxQuality() const: Test if at maximum quality

inline QualityValueType value(QualityValueType set)

Set a feed quality.

The value is truncated to the range 0..1

inline QualityValueType value() const: Obtain the feed quality level

Friends

inline friend bool operator==(const AdaptiveQuality &lhs, const AdaptiveQuality &rhs): Equality comparison

inline friend bool operator!=(const AdaptiveQuality &lhs, const AdaptiveQuality &rhs): Inequality comparison

template<typename T> class AdaptiveRule

#include <PxMedia/AdaptiveRule.h>

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

Subclassed by Proximie::PxMedia::AdaptiveBandsRule< T >, Proximie::PxMedia::AdaptiveMinMaxRule< T >

Public Types

using ValueType = T : Type alias for the value type that the rule returns.

Public Functions

virtual boost::optional<T> valueForQuality(AdaptiveQuality quality) const = 0

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.

virtual ~AdaptiveRule() = default: Virtual destructor, always subclassed.

class AudioFeedStageComponent : public Proximie::PxMedia::FeedComponent<AudioFeedStageComponentProvider>

#include <PxMedia/AudioFeedStage.h>

Base class for audio feed stage components.

Subclassed by Proximie::PxMedia::AudioStageVolume, Proximie::PxMedia::AudioStageWebRtcDsp

class AudioFeedStageSequence

#include <PxMedia/AudioFeedStage.h>

A sequence of audio feed stage components.

Public Types

using ComponentSequence = std::vector<std::reference_wrapper<const AudioFeedStageComponent>>: A sequence of feed stage component references to set a sequence.

Public Functions

inline void sequence(const ComponentSequence &components): Set the sequence of feed stages with a sequence of components.

class AudioInputComponentSilence : public Proximie::PxMedia::AudioInputFeedComponent 

#include <PxMedia/AudioInputComponentSilence.h>

An audio input feed component that simply sends silence.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AudioInputFeedAuto : public Proximie::PxMedia::AudioInputFeedComponent 

#include <PxMedia/AudioInputFeedAuto.h>

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.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AudioInputFeedComponent : public Proximie::PxMedia::FeedComponent<AudioInputFeedComponentProvider>

#include <PxMedia/feed-components-audio.h>

Base class for audio input feed components.

Subclassed by Proximie::PxMedia::AudioInputComponentSilence, Proximie::PxMedia::AudioInputFeedAuto, Proximie::PxMedia::AudioInputFeedInter, Proximie::PxMedia::AudioInputFeedTestSignal

Public Functions

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

inline const AudioFeedStageSequence &audioStages() const: Read-only access to the audio feed stage sequence.

class AudioInputFeedInter : public Proximie::PxMedia::AudioInputFeedComponent 

#include <PxMedia/AudioInputFeedInter.h>

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.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

~AudioInputFeedInter() override = default: Destructor.

AudioInputFeedInter(AudioInputFeedInter&&) = default: Move constructor — transfers ownership of the sub-channel.

AudioInputFeedInter &operator=(AudioInputFeedInter&&) = default: Move assignment — transfers ownership of the sub-channel.

inline bool isConsumed() const: Returns true if this input has already been consumed by a feed.

inline const Properties &properties() const: Returns a read-only reference to the properties for the object

struct Properties

#include <PxMedia/AudioInputFeedInter.h>

The properties required to specify the audio inter channel.

Inter settings

These settings describe the inter and its content.

std::string channel: Channel name.

class AudioInputFeedTestSignal : public Proximie::PxMedia::AudioInputFeedComponent 

#include <PxMedia/AudioInputFeedTestSignal.h>

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.

Setters

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

inline AudioInputFeedTestSignal &wave(Wave set): Set the audio wave type; see AudioInputFeedTestSignal::Wave

inline const Properties &properties() const: Returns a read-only reference to the properties for the object

Public Types

enum class Wave

Wave type for audiotestsrc.

Values:

enumerator Sine: Sine wave.

enumerator Square: Square wave.

enumerator Saw: Saw wave.

enumerator Triangle: Triangle wave.

enumerator WhiteNoise: White noise.

enumerator PinkNoise: Pink noise.

enumerator Ticks: Periodic ticks.

enumerator GaussianNoise: White Gaussian noise.

enumerator RedNoise: Red (brownian) noise.

enumerator BlueNoise: Blue noise.

enumerator VioletNoise: Violet noise.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

Public Static Functions

static const PxUtility::EnumMapper<Wave> &patternMapper(): Map between Pattern and string.

struct Properties

#include <PxMedia/AudioInputFeedTestSignal.h>

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

Public Members

boost::optional<Wave> wave: Type of test wave to generate.

class AudioOutputComponentNull : public Proximie::PxMedia::AudioOutputFeedComponent 

#include <PxMedia/AudioOutputComponentNull.h>

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

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AudioOutputFeedAuto : public Proximie::PxMedia::AudioOutputFeedComponent 

#include <PxMedia/AudioOutputFeedAuto.h>

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.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AudioOutputFeedComponent : public Proximie::PxMedia::FeedComponent<AudioOutputFeedComponentProvider>

#include <PxMedia/feed-components-audio.h>

Base class for audio output feed components.

Subclassed by Proximie::PxMedia::AudioOutputComponentNull, Proximie::PxMedia::AudioOutputFeedAuto, Proximie::PxMedia::AudioOutputFeedInter, Proximie::PxMedia::AudioOutputFeedWavescope

Public Functions

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

inline const AudioFeedStageSequence &audioStages() const: Read-only access to the audio feed stage sequence.

class AudioOutputFeedInter : public Proximie::PxMedia::AudioOutputFeedComponent 

#include <PxMedia/AudioOutputFeedInter.h>

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.

Accessors

inline const Properties &properties() const: Returns a read-only reference to the properties for the object

Note

The channel name is auto-generated at construction time.

inline const std::vector<std::string> &outputChannels() const: Returns the list of sub-channel names registered via makeInput()

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

AudioOutputFeedInter(): Default constructor — generates a unique internal channel identifier.

explicit AudioOutputFeedInter(string_view label)

Constructor with optional debug label.

The internal channel name will be “<label>-<uuid>”, which appears in GStreamer debug output for easier identification.

Parameters:: label – A short human-readable prefix for the generated channel name.

AudioInputFeedInter makeInput()

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 tee element with one interaudiosink branch per consumer.

All calls to makeInput() must be made before the owning pipeline is built (i.e. before the feed create() call that receives this output).

struct Properties

#include <PxMedia/AudioOutputFeedInter.h>

The properties required to specify the inter audio channel.

Inter settings

These settings describe the interaudiosink settings.

std::string channel: Channel name.

class AudioOutputFeedWavescope : public Proximie::PxMedia::AudioOutputFeedComponent 

#include <PxMedia/AudioOutputFeedWavescope.h>

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.

Known issue on Ubuntu 24.04 with GStreamer 1.24.2

There is a known issue in GStreamer 1.24.2, the version of GStreamer available on Ubuntu 24.04, which causes audio visualization plugins to accumulate waveform data indefinitely, making visualizations incorrect and causing high CPU usage. This was addressed in GStreamer 1.24.4 (see merge request). This affects AudioOutputFeedWavescope outputs on Ubuntu 24.04.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AudioPeerRtpDecodeFeedComponent : public Proximie::PxMedia::FeedComponent<AudioPeerRtpDecodeFeedComponentProvider>

#include <PxMedia/feed-components-peer.h>

Base class for audio peer decoder feed components.

Subclassed by Proximie::PxMedia::AudioPeerRtpDecodeFeedOpus

class AudioPeerRtpDecodeFeedOpus : public Proximie::PxMedia::AudioPeerRtpDecodeFeedComponent 

#include <PxMedia/AudioPeerRtpDecodeFeedOpus.h>

A audio feed component for specifying Opus decoding for SRTP.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

struct Properties: #include <PxMedia/AudioPeerRtpDecodeFeedOpus.h>

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

class AudioPeerRtpEncodeFeedComponent : public Proximie::PxMedia::FeedComponent<AudioPeerRtpEncodeFeedComponentProvider>

#include <PxMedia/feed-components-peer.h>

Base class for audio peer encoder feed components.

Subclassed by Proximie::PxMedia::AudioPeerRtpEncodeFeedOpus

class AudioPeerRtpEncodeFeedOpus : public Proximie::PxMedia::AudioPeerRtpEncodeFeedComponent 

#include <PxMedia/AudioPeerRtpEncodeFeedOpus.h>

A audio feed component for specifying Opus encoding for SRTP.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

struct Properties: #include <PxMedia/AudioPeerRtpEncodeFeedOpus.h>

The properties required to encode the audio feed for SRTP using Opus.

class AudioStageVolume : public Proximie::PxMedia::AudioFeedStageComponent 

#include <PxMedia/AudioStageVolume.h>

Audio feed stage for adjusting audio volume using GStreamer volume element.

Public Functions

explicit AudioStageVolume(float volume = 1.0F): Construct with initial volume (default 1.0 = unchanged)

void volume(float volume): Set the audio volume (0.0 = mute, 1.0 = unchanged, >1.0 = amplify)

float volume() const: Get the current audio volume.

virtual shared_not_null<AudioFeedStageComponentProvider> makeProvider() const override: Required override to create a provider for the component

class AudioStageWebRtcDsp : public Proximie::PxMedia::AudioFeedStageComponent 

#include <PxMedia/AudioStageWebRtcDsp.h>

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.

AudioStageWebRtcDsp is unavailable on Ubuntu 24.04

The AudioStageWebRtcDsp stage requires that the webrtcdsp gstreamer plugin is installed on the system. Seemingly due to an oversight, this plugin is not available by default on Ubuntu 24.04. See webrtcdsp Gstreamer plugin for details.

Setters

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

inline AudioStageWebRtcDsp &compressionGainDb(int set): Set the maximum gain in dB that the compression stage of the filter can apply. Defaults to 9.

inline AudioStageWebRtcDsp &gainControl(bool set): Enable automatic gain control. Defaults to enabled.

inline AudioStageWebRtcDsp &gainControlMode(GainControlMode set): Set gain control mode applied (if enabled). Defaults to Adaptive Digital.

inline AudioStageWebRtcDsp &highPassFilter(bool set): Enable high-pass filter. Defaults to enabled.

inline AudioStageWebRtcDsp &limiter(bool set): 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.

inline AudioStageWebRtcDsp &noiseSuppression(bool set): Enable noise suppression. Defaults to enabled.

inline AudioStageWebRtcDsp &noiseSuppressionLevel(NoiseSuppressionLevel set): Set noise suppression level. Defaults to Moderate.

inline AudioStageWebRtcDsp &targetLevelDbfs(int set): Set target peak level in dBFS (decibels from digital full-scale). Defaults to 3.

Public Types

enum class NoiseSuppressionLevel

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

Values:

enumerator Low: Low noise suppression.

enumerator Moderate: Moderate noise suppression.

enumerator High: High noise suppression.

enumerator VeryHigh: Very high noise suppression.

enum class GainControlMode

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

Values:

enumerator AdaptiveAnalog: Adaptive analog gain control.

enumerator AdaptiveDigital: Adaptive digital gain control.

enumerator FixedDigital: Fixed digital gain control.

Public Functions

explicit AudioStageWebRtcDsp() = default: Construct with default properties.

inline explicit AudioStageWebRtcDsp(Properties properties)

Construct with specified properties.

Parameters:: properties – The properties to use for the WebRTC DSP stage.

inline const Properties &properties() const: Returns a read-only reference to the properties for the object

virtual shared_not_null<AudioFeedStageComponentProvider> makeProvider() const override: Required override to create a provider for the component

Public Static Functions

static const PxUtility::EnumMapper<NoiseSuppressionLevel> &noiseSuppressionLevelMapper(): Map between NoiseSuppressionLevel and string.

static const PxUtility::EnumMapper<GainControlMode> &gainControlModeMapper(): Map between GainControlMode and string.

struct Properties

#include <PxMedia/AudioStageWebRtcDsp.h>

Properties for the WebRTC audio DSP stage.

Public Members

boost::optional<int> compressionGainDb: The maximum gain in dB that the compression stage of the filter can apply; defaults to 9

boost::optional<bool> gainControl: Enable automatic gain control; defaults to enabled.

boost::optional<GainControlMode> gainControlMode: Gain control mode; defaults to AdaptiveDigital.

boost::optional<bool> highPassFilter: Enable high-pass filter; defaults to enabled.

boost::optional<bool> 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 true.

boost::optional<bool> noiseSuppression: Enable noise suppression; defaults to enabled.

boost::optional<NoiseSuppressionLevel> noiseSuppressionLevel: Noise suppression level.

boost::optional<int> targetLevelDbfs: The target peak |level| (or envelope) of the gain control in dBFS (decibels from digital full-scale). Defaults to 3.

class AudioWebRtcEncodeFeedComponent : public Proximie::PxMedia::FeedComponent<AudioWebRtcEncodeFeedComponentProvider>

#include <PxMedia/feed-components-audio.h>

Base class for audio WebRTC encoder feed components.

Subclassed by Proximie::PxMedia::AudioWebRtcEncodeFeedOpus

class AudioWebRtcEncodeFeedOpus : public Proximie::PxMedia::AudioWebRtcEncodeFeedComponent 

#include <PxMedia/AudioWebRtcEncodeFeedOpus.h>

An audio feed component for specifying audio encoding using Opus.

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.

Public Functions

virtual shared_not_null<Provider> makeProvider() const override: Required override to create a provider for the component

class AVOutputFeedFile : public Proximie::PxMedia::FeedBase 

#include <PxMedia/AVOutputFeedFile.h>

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.

Additional features that this type of feed supports

void onFeedFileFinished(const std::function<void(const shared_not_null<AVOutputFeedFile>&, string_view path)> &func): Notify that a feed file has finished and can be read/used.

void fileOutputLocationHandler(const OnFormatLocationHandler &handler)

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.

Public Types

using FeedProperties = FeedBase::FeedBaseProperties : Properties that apply to the whole feed.

using OnFormatLocationHandler = std::function<std::string(guint seq)>: Callback for overriding file output location.

Public Static Functions

static inline NotNullOutcome<AVOutputFeedFile> create(const shared_not_null<PxCore::ProximieContext> &context, const FeedProperties &props, const AVOutputFeedFileSettings &settings, const VideoInputFeedComponent &input, const std::vector<shared_not_null<PxMedia::AudioInputFeedComponent>> &audioInputs = {})

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 – The Proximie context to use for the feed
props – Feed properties (label, etc.)
settings – File output settings (directory, filename pattern, size/duration limits)
input – Video input feed component
audioInputs – Optional vector of audio input feed components

Returns:

NotNullOutcome containing the created AVOutputFeedFile or an error

static inline NotNullOutcome<AVOutputFeedFile> create(const shared_not_null<PxCore::ProximieContext> &context, const FeedProperties &props, const AVOutputFeedFileSettings &settings, const VideoInputFeedComponent &input, const H264VideoEncoderComponent &encoder, const std::vector<shared_not_null<PxMedia::AudioInputFeedComponent>> &audioInputs = {})

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 – The Proximie context to use for the feed
props – Feed properties (label, etc.)
settings – File output settings (directory, filename pattern, size/duration limits)
input – Video input feed component
encoder – H264 encoder component (X264, VAAPI, etc.)
audioInputs – Optional vector of audio input feed components

Returns:

NotNullOutcome containing the created AVOutputFeedFile or an error

static X264EncoderFeedComponent defaultRecordingEncoder()

Return an encoder with default settings for recording.

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

class AVOutputFeedFileSettings

#include <PxMedia/AVOutputFeedFile.h>

Settings for the AVOutputFeedFile.

Setters with validation

These setter functions return std::error_code to indicate validation failures.

std::error_code destinationDirectory(const std::string &dir)

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 – The destination directory path (empty = use pattern as-is)
Returns:: std::error_code indicating success or failure

std::error_code destinationFilenamePattern(const std::string &pattern)

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 – Printf-compatible pattern (e.g., “video%02d.mp4”)
Returns:: std::error_code indicating success or validation failure

std::error_code enableTimestampInFilename(bool enable)

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 – True to enable timestamp embedding
Returns:: std::error_code indicating success or failure

std::error_code videoCodec(VideoCodec codec)

Set the video codec.

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

Parameters:: codec – The video codec to use
Returns:: std::error_code indicating success or failure

std::error_code audioCodec(AudioCodec codec)

Set the audio codec.

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

Parameters:: codec – The audio codec to use
Returns:: std::error_code indicating success or failure

std::error_code avContainer(AVContainer container)

Set the container format.

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

Parameters:: container – The container format to use
Returns:: std::error_code indicating success or failure

std::error_code maxFiles(uint32_t maxFiles)

Set the maximum number of files to create.

Default: 0 (unlimited)

Note

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

Parameters:: maxFiles – Maximum file count (0 = unlimited)
Returns:: std::error_code indicating success or failure

std::error_code maxFileSizeMB(uint64_t maxSizeMB)

Set the maximum size of a file in MB.

Default: 0 (unlimited - no file size limit)

Note

Validates that maxSizeMB * 1048576 won’t overflow uint64_t. Returns std::errc::value_too_large if validation fails.

Parameters:: maxSizeMB – Maximum file size in megabytes (0 = unlimited)
Returns:: std::error_code indicating success or failure

std::error_code maxFileDurationS(uint64_t maxDurationS)

Set the maximum duration of a file in seconds.

Default: 0 (unlimited - no file duration limit)

Note

Validates that maxDurationS * 1000000000 won’t overflow uint64_t. Returns std::errc::value_too_large if validation fails.

Parameters:: maxDurationS – Maximum file duration in seconds (0 = unlimited)
Returns:: std::error_code indicating success or failure

Getters

inline const std::string &destinationDirectory() const: Get the destination directory.

inline const std::string &destinationFilenamePattern() const: Get the filename pattern.

inline bool enableTimestampInFilename() const: Get timestamp embedding flag.

inline VideoCodec videoCodec() const: Get video codec.

inline AudioCodec audioCodec() const: Get audio codec.

inline AVContainer avContainer() const: Get container format.

inline uint32_t maxFiles() const: Get maximum file count.

inline uint64_t maxFileSizeMB() const: Get maximum file size in MB.

inline uint64_t maxFileDurationS() const: Get maximum file duration in seconds.

class BitRate

#include <PxMedia/BitRate.h>

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:

using namespace Proximie::PxMedia::Literals;

Then, you can create bit rate values using the following:

constexpr auto H264_BITRATE = 2000_kbps;

The following literals are supported: bps, kbps, mbps, gbps.

Get bit rate values

using RemainderType = std::make_signed_t<ValueType>: Remainder type for bit rate scaling.

inline ValueType bitsPerSecond() const: Bit rate in bits per second

ValueType bitRateWithUnits(UnitType unit, ScaleMethod rounding, RemainderType *remainder = nullptr) const

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 – [in] The units to convert the bitrate value to
rounding – [in] How to round the value when converting
remainder – [out] Optionally output the remainder in bits

Returns:

The bit rate converted to the requested units

inline double decimalBitRateWithUnits(UnitType unit) const: Scaled bit rate to a given unit type, as a decimal value.

Creation

Also see the main BitRate description for details on how to use bit rate literals.

constexpr BitRate() = default: Default construction is a zero bit rate

inline BitRate(ValueType value, UnitType unit): Construct with value and unit type as a parameter.

template<UnitType U> static inline constexpr BitRate make(ValueType value): Make a constexpr BitRate, with a value of a given unit as the template.

Comparison & testing of the bit rate value

inline bool isZero() const: Test if the bitrate value is zero

inline bool operator==(const BitRate &rhs) const: Equality with another BitRate

inline bool operator!=(const BitRate &rhs) const: Inequality

inline bool operator<(const BitRate &rhs) const: Less than

inline bool operator<=(const BitRate &rhs) const: Less than or equal to

inline bool operator>(const BitRate &rhs) const: Greater than

inline bool operator>=(const BitRate &rhs) const: Greater than or equal to

Public Types

enum class UnitType

Units of bits per second

Values:

enumerator Bits

enumerator KBits

enumerator MBits

enumerator GBits

enum class ScaleMethod

How to round when scaling to a specified unit

Values:

enumerator Nearest: Round to the nearest unit.

enumerator Down: Round down to the nearest unit.

enumerator Up: Round up to the nearest unit.

enumerator DownNotZero: Round down, but only to when already zero.

enumerator NearestNotZero: Round nearest, but only to when already zero.

using ValueType = std::uint64_t: A number of bits

class Configuration

#include <PxMedia/Configuration.h>

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.

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.

Configuration &gstreamerDebugLevel(GstDebugLevel level)

Set the GStreamer debugging level.

Note that the debug level is the GStreamer library debug level type GstDebugLevel, not the Proximie SDK logging severity level.

The SDK does not set/override any GStreamer debugging level itself, only when the application itself calls this function.

GstDebugLevel gstreamerDebugLevel() const: Returns the current GStreamer debug level

Configuration &gstreamerLogTarget(GStreamerLogger target)

Set the target for GStreamer log output.

When using the Proximie SDK logger target, GStreamer debug levels are translated to the corresponding SDK logger severity levels.

inline GStreamerLogger gstreamerLogTarget() const: Returns the current GStreamer target

Public Types

enum class GStreamerLogger

Enumeration to specify where GStreamer output is targeted

Values:

enumerator CONSOLE: Output to console (default)

enumerator PXLOGGER: Direct output to the Proximie SDK logger.

using fspath = boost::filesystem::path: Alias for the filesystem path type.

Public Functions

outcome::result<void> diagnosticsFolder(const fspath &folder)

Set the diagnostics folder for PxMedia.

Returns an error if the path is not an existing directory

Configuration &diagnosticsFolderOrThrow(const fspath &folder)

Set the diagnostics folder for PxMedia.

Throws an error if the path is not an existing directory

outcome::result<fspath> diagnosticsFolder() const

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.

Public Static Functions

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

class FeedBase : public std::enable_shared_from_this<FeedBase>

#include <PxMedia/FeedBase.h>

Base feed object that all feed objects inherit from.

Subclassed by Proximie::PxMedia::AVOutputFeedFile, Proximie::PxMedia::MediaServerFeed, Proximie::PxMedia::PeerFeed, Proximie::PxMedia::UtilityAudioLocalFeed, Proximie::PxMedia::UtilityVideoLocalFeed

Feed object interface

template<typename T> inline bool is() const: Helper to test if a feed is a given derived type.

template<typename T> inline std::shared_ptr<T> as(): Helper to cast a feed to a given derived type Returns nullptr if the feed is not of the given type

Public Functions

inline std::string id() const: The unique ID for the feed

inline std::string label() const: The human-readable label for the feed

inline bool isPlaying() const: Whether the feed is currently playing

inline outcome::result<void> startFeed()

Start the feed playing.

No effect if the feed is already playing

inline outcome::result<void> stopFeed()

Stop the feed playing.

No effect if the feed is not already playing

inline void onFeedStarted(const std::function<void(const shared_not_null<FeedBase>&)> &func): Notify that a feed has successfully started

inline void onFeedStopped(const std::function<void(const shared_not_null<FeedBase>&, error_code)> &func): Notify that a feed has stopped, which may be intentionally or in error

template<typename T, typename = std::enable_if_t<std::is_base_of<FeedRequest, T>::value>> inline outcome::result<void> feedRequest(T request)

Send a request to the feed.

Returns:: An outcome indicating if the request was handled (true) or not (false). If there is an error processing the feed, this will be reflected an an outcome error.

inline outcome::result<std::string> getPipelineGraph() const

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

inline outcome::result<boost::filesystem::path> writePipelineGraphToFile(string_view filename) const

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 PxMedia::Configuration

Returns:: The path to the file written

inline outcome::result<std::string> getPipelineGraphWithDetails(GstDebugGraphDetails details) const

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

inline outcome::result<boost::filesystem::path> writePipelineGraphWithDetailsToFile(string_view filename, GstDebugGraphDetails details) const

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 PxMedia::Configuration

Returns:: The path to the file written

struct FeedBaseProperties

#include <PxMedia/FeedBase.h>

Properties that apply to the whole feed.

Subclassed by Proximie::PxMedia::MediaServerIncomingVideoFeed::FeedProperties, Proximie::PxMedia::MediaServerOutgoingVideoFeed::FeedProperties, Proximie::PxMedia::PeerFeed::FeedProperties

Public Functions

inline explicit FeedBaseProperties(string_view label = {}): Constructor allowing the label to be set.

Public Members

std::string label: Readable label for the feed.

template<class PROVIDER> class FeedComponent

#include <PxMedia/FeedComponent.h>

The basic building block and abstract interface of all feed components.

Template Parameters:: PROVIDER – Opaque “provider” class that is used to create/implement a feed instance’s behaviour

Public Types

using Provider = PROVIDER : The provider template type.

Public Functions

virtual shared_not_null<Provider> makeProvider() const = 0: Required override to create a provider for the component

class FeedPacketLossAssessor : public Proximie::PxMedia::FeedPerformanceAssessor 

#include <PxMedia/FeedPacketLossAssessor.h>

A feed performance assessment helper that looks at packet loss.

Public Functions

FeedPacketLossAssessor() = default: Create the assessor with default settings

inline explicit FeedPacketLossAssessor(const Settings &settings): Create the assessor with custom settings

virtual double assessPerformance(const FeedPerformanceStats &details) const override: Given the current stats of a feed, return the delta to apply to the current quality level.

struct Settings

#include <PxMedia/FeedPacketLossAssessor.h>

Settings for the packet loss assessment instances

Public Functions

Settings(): Construct settings with reasonable default values

Public Members

double lowPacketLossRatioThreshold: The low threshold indicates the point where quality should be reduced to improve the packet loss to an acceptable level. Below this threshold, the quality may be improved.

double severePacketLossRatioThreshold: The severe threshold indicates the point where quality should be reduced more aggressively.

double qualityImproveDelta: When the packet loss ratio is below the low threshold, the quality will be improved by this delta.

double qualityReduceGentleDelta: When the packet loss ratio is moderate, the quality will be reduced by this “gentle” delta.

double qualityReduceSevereDelta: When the packet loss ratio is severe, the quality will be reduced by this “severe” delta.

class FeedPerformanceAssessor

#include <PxMedia/FeedPerformanceAssessor.h>

A rule for assessing performance and quality

Subclassed by Proximie::PxMedia::FeedPacketLossAssessor

Public Functions

virtual ~FeedPerformanceAssessor() = default: Virtual destructor as this class is overrideable

virtual double assessPerformance(const FeedPerformanceStats &details) const = 0: Given the current stats of a feed, return the delta to apply to the current quality level.

struct FeedPerformanceStats

#include <PxMedia/FeedPerformanceAssessor.h>

Information shared with the monitor for each feed being monitored

Public Functions

inline explicit FeedPerformanceStats(const shared_not_null<MediaServerOutgoingVideoFeed> &feed): Create a stats struct with a non-null feed reference

Public Members

shared_not_null<MediaServerOutgoingVideoFeed> feed: The feed being assessed

AdaptiveQuality currentQuality: The current quality setting that was set for the feed

WebRtcStats webRtcStats: WebRTC statistics collected from the feed

double packetLossRatio = 0: Packet loss ratio from the current statistics

boost::optional<double> packetLossRatioAverage: When available, the (moving) average packet loss calculated from recent assessments

class FeedQualityMonitor

#include <PxMedia/FeedQualityMonitor.h>

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

Public Functions

explicit FeedQualityMonitor(std::unique_ptr<FeedPerformanceAssessor> assessor)

Construct a new FeedQualityMonitor object, providing a performance assessment handler.

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

bool isRunning() const: Returns whether the monitor is currently running.

void start(std::chrono::milliseconds interval)

Start the feed quality monitor with the given interval.

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

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

bool isFeedRegistered(const shared_not_null<MediaServerOutgoingVideoFeed> &feed) const: Check if a feed is being monitored already.

void registerFeed(const shared_not_null<MediaServerOutgoingVideoFeed> &feed): Register a feed to be monitored. Ignored if the feed is already registered.

void unregisterFeed(const shared_not_null<MediaServerOutgoingVideoFeed> &feed): Unregister a feed from being monitored. Ignored if the feed is not registered.

void unregisterAllFeeds(): Unregister all currently registered feeds.

class FeedRequest

#include <PxMedia/FeedRequest.h>

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.

Subclassed by Proximie::PxMedia::SrtFeedStatsRequest, Proximie::PxMedia::VideoStagePrivacy::RequestPrivacy, Proximie::PxMedia::VideoStageTextOverlay::RequestSetText, Proximie::PxMedia::WebRtcStatsRequest, Proximie::PxMedia::experimental::FeedDiagnosticsRequest

Public Functions

virtual ~FeedRequest() = default: Virtual destructor as this is always subclassed.

template<typename T> inline bool is() const: Helper to test if a feed request is a given derived type.

template<typename T> inline T *as(): Convert to a given derived type; returns nullptr if the request is not of the given type.

template<typename T> inline const T *as() const: Convert to a given derived type; returns nullptr if the request is not of the given type.

inline error_code unhandledError() const: Requests that are not handled by a feed should use this status/error.

class FrameRate

#include <PxMedia/FrameRate.h>

Encapsulates a formal frame rate value.

Creation

inline FrameRate(): Default construction is a zero frame rate

inline FrameRate(FractionInt frameRate): Construct a frame rate object with a simple frame rate integer (i.e. the denominator defaults to 1).

inline FrameRate(FractionInt numerator, FractionInt denominator): Construct a frame rate object with numerator/denominator values.

Public Types

using FractionInt = gint: Frame rate fraction numerator/denominator integer type

Public Functions

inline void set(FractionInt frameRate): Set a frame rate value with a simple frame rate integer (i.e. the denominator defaults to 1).

inline void set(FractionInt numerator, FractionInt denominator): Set a frame rate value with numerator/denominator values.

inline FractionInt numerator() const: Obtain the frame rate ratio numerator value

inline FractionInt denominator() const: Obtain the frame rate ratio denominator value

inline bool isZero() const: Test if zero numerator (i.e. no frame rate)

inline std::string toFrameRateString() const: Obtain a string/printable version of the frame rate value

inline double toDouble() const: Convert to a double value

inline void fromDouble(double value): Convert from a double value

Public Static Functions

static inline FrameRate createFromDouble(double value): Make a frame rate from a double value

class H264VaapiEncoderComponent : public Proximie::PxMedia::H264VideoEncoderComponent 

#include <PxMedia/H264VaapiEncoderComponent.h>

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).

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).