Streams

digraph inheritance { rankdir=LR; GObject -> WpObject; WpObject -> WpStream; WpStream -> WpAudioStream; WpStream -> WpVideoStream; }

struct WpStream

WpStream is an abstract base class that represents a data stream belonging to a PipeWire node. A stream is a logical collection of ports with the same direction (input or output) and media type (audio or video).

This class provides an abstraction over the underlying PipeWire ports, allowing for high-level management of streams without dealing directly with port-level details. Each stream tracks its associated ports, their properties, and their configuration.

WpStream is an abstract class with two concrete implementations:

  • WpAudioStream: represents an audio stream (input or output)

  • WpVideoStream: represents a video stream (input or output)

Streams can be linked together using WpStreamLink objects, which automatically manage the underlying PipeWire links between ports. The WpStreamManager is responsible for creating streams automatically for nodes that appear in the system.

A stream emits signals when ports are added, removed, or when the port configuration changes, allowing applications to react to stream topology changes. It also emits the "params-changed" signal when the Props or PropInfo params of the stream change.

struct WpAudioStream

A WpStream that carries audio. It reads the formats the node supports from EnumFormat, both raw and encoded, and it is the only stream kind whose ports are configured: wp_audio_stream_configure_ports() and its variants set PortConfig on the node, choosing the port layout (DSP, convert or passthrough) and whether monitor and control ports exist.

Port configuration is asynchronous. The "ports-configured" signal is emitted once the node has applied a configuration this stream asked for, and "ports-error" if it refused it.

struct WpVideoStream

A WpStream that carries video. Video nodes have a single port per stream and WirePlumber does not configure their ports, so this class only tracks the raw formats the node supports.

An input video stream is exclusive: video cannot be mixed, so it accepts one peer at a time. An output video stream can feed as many peers as ask for it.

enum WpStreamKind

The different kinds a stream can be.

Values:

enumerator WP_STREAM_KIND_UNKNOWN
enumerator WP_STREAM_KIND_SUBJECT
enumerator WP_STREAM_KIND_TARGET
enum WpStreamShape

The different shapes a stream can have.

Values:

enumerator WP_STREAM_SHAPE_UNKNOWN
enumerator WP_STREAM_SHAPE_SINK
enumerator WP_STREAM_SHAPE_SOURCE
enumerator WP_STREAM_SHAPE_INPUT
enumerator WP_STREAM_SHAPE_OUTPUT
enum WpAudioStreamPortsState

The states of the ports of an audio stream.

Values:

enumerator WP_AUDIO_STREAM_PORTS_STATE_UNCONFIGURED

the ports were never configured

enumerator WP_AUDIO_STREAM_PORTS_STATE_CONFIGURING

a port configuration was requested and its ports do not exist yet

enumerator WP_AUDIO_STREAM_PORTS_STATE_CONFIGURED

the ports are configured

enum WpStreamFeatures

Flags to be used as WpObjectFeatures on WpStream.

Values:

enumerator WP_STREAM_FEATURE_ACTIVE = (1 << 0)

Activates the stream

WpNode *wp_stream_get_node(WpStream *self)

Gets the node this stream belongs to.

Parameters:
  • self -- the stream

Returns:

(transfer full): the node this stream belongs to

WpProperties *wp_stream_get_properties(WpStream *self)

Gets the stream properties.

Parameters:
  • self -- the stream

Returns:

(transfer full): the stream properties

const gchar *wp_stream_object_get_property(WpStream *self, const gchar *key)

Gets the value of a single stream property.

Parameters:
  • self -- the stream

  • key -- the property name

Returns:

(transfer none) (nullable): the property value, or NULL if not set

WpDirection wp_stream_get_direction(WpStream *self)

Gets the stream direction.

Parameters:
  • self -- the stream

Returns:

the stream direction

const gchar *wp_stream_get_port_group(WpStream *self)

Gets the stream port group.

Parameters:
  • self -- the stream

Returns:

(nullable): the stream port group

gint64 wp_stream_get_creation_time(WpStream *self)

Gets the stream creation time in microseconds.

Parameters:
  • self -- the stream

Returns:

the stream creation time in microseconds.

guint wp_stream_get_node_bound_id(WpStream *self)

Gets the node's bound id this stream belongs to.

Parameters:
  • self -- the stream

Returns:

node's bound id this stream belongs to

WpStreamKind wp_stream_get_kind(WpStream *self)

Gets the stream's kind value.

Parameters:
  • self -- the stream

Returns:

the stream's kind value

WpStreamShape wp_stream_get_shape(WpStream *self)

Gets the stream's shape value.

Parameters:
  • self -- the stream

Returns:

the stream's shape value

gboolean wp_stream_is_compatible(WpStream *self, WpStream *other, gboolean *encoded_only)

Checks whether the stream supports a common format with another stream.

Parameters:
  • self -- the stream

  • other -- the other stream

  • encoded_only -- (out) (nullable): whether the only common format is an encoded format

Returns:

TRUE if the stream is compatible with other, FALSE otherwise.

guint wp_stream_get_supported_raw_format_count(WpStream *self)

Gets the number of supported raw formats.

Parameters:
  • self -- the stream

Returns:

the number of supported raw formats

guint wp_stream_get_supported_enc_format_count(WpStream *self)

Gets the number of supported encoded formats.

Parameters:
  • self -- the stream

Returns:

the number of supported encoded formats

WpIterator *wp_stream_new_supported_raw_format_iterator(WpStream *self)

Creates an iterator over the supported raw formats.

Parameters:
  • self -- the stream

Returns:

(transfer full): a WpIterator over WpSpaPod raw format objects

WpIterator *wp_stream_new_supported_enc_format_iterator(WpStream *self)

Creates an iterator over the supported encoded formats.

Parameters:
  • self -- the stream

Returns:

(transfer full): a WpIterator over WpSpaPod encoded format objects

gboolean wp_stream_is_exclusive(WpStream *self)
Parameters:
  • self -- the stream

Returns:

TRUE if the stream is exclusive, FALSE otherwise

gboolean wp_stream_has_port(WpStream *self, guint32 port_id)

Checks if the stream has the given port ID or not.

Parameters:
  • self -- the stream

  • port_id -- the port ID to check

Returns:

TRUE if the stream has the port, FALSE otherwise

gboolean wp_stream_has_monitor_port(WpStream *self, guint32 port_id)

Checks if the stream has the given monitor port ID or not.

Parameters:
  • self -- the stream

  • port_id -- the monitor port ID to check

Returns:

TRUE if the stream has the monitor port, FALSE otherwise

gboolean wp_stream_has_control_port(WpStream *self, guint32 port_id)

Checks if the stream has the given control port ID or not.

Parameters:
  • self -- the stream

  • port_id -- the control port ID to check

Returns:

TRUE if the stream has the control port, FALSE otherwise

guint wp_stream_get_ports_count(WpStream *self)

Gets the streams's total number of non-monitor and non-control ports.

Parameters:
  • self -- the stream

Returns:

The total number of non-monitor and non-control ports

guint wp_stream_get_monitor_ports_count(WpStream *self)

Gets the stream's total number of monitor ports.

Parameters:
  • self -- the stream

Returns:

The total number of ports

guint wp_stream_get_control_ports_count(WpStream *self)

Gets the stream's total number of control ports.

Parameters:
  • self -- the stream

Returns:

The total number of ports

WpIterator *wp_stream_new_ports_iterator(WpStream *self)

Iterates through all the stream non-monitor and non-control ports.

Parameters:
  • self -- the stream

Returns:

(transfer full): a WpIterator that iterates over all the stream ports that are not monitor or control ports.

WpIterator *wp_stream_new_monitor_ports_iterator(WpStream *self)

Iterates through all the stream monitor ports.

Parameters:
  • self -- the stream

Returns:

(transfer full): a WpIterator that iterates over all the stream monitor ports.

WpIterator *wp_stream_new_control_ports_iterator(WpStream *self)

Iterates through all the stream control ports.

Parameters:
  • self -- the stream

Returns:

(transfer full): a WpIterator that iterates over all the stream control ports.

WpIterator *wp_stream_enum_params_sync(WpStream *self, const gchar *id)

Enumerates the cached params of the stream with the given id.

Only the "Props" and "PropInfo" params are cached. They are the param objects of the node that belong to this stream, which are the ones of its port group, or all of them if the stream has no port group.

Parameters:
  • self -- the stream

  • id -- the param id to enumerate, either "Props" or "PropInfo"

Returns:

(transfer full) (nullable): an iterator over the cached params, or NULL if no params with this id are cached; the items in the iterator are WpSpaPod

gboolean wp_stream_set_props_param(WpStream *self, const gchar *first_prop, ...)

Sets the Props param of the stream's node from a list of properties.

See wp_stream_set_props_param_array()

Parameters:
  • self -- the stream

  • first_prop -- the name of the first property, such as "volume"

  • ... -- the value of the first property as a (transfer none) WpSpaPod, followed by other name/value pairs, terminated with NULL

Returns:

TRUE if the param was set, FALSE otherwise

gboolean wp_stream_set_props_param_valist(WpStream *self, const gchar *first_prop, va_list args)

The va_list version of wp_stream_set_props_param()

Parameters:
  • self -- the stream

  • first_prop -- the name of the first property, such as "volume"

  • args -- the value of the first property as a (transfer none) WpSpaPod, followed by other name/value pairs, terminated with NULL

Returns:

TRUE if the param was set, FALSE otherwise

gboolean wp_stream_set_props_param_array(WpStream *self, guint n_props, const gchar *const *names, WpSpaPod *const *values)

Sets the Props param of the stream's node.

If the stream has a port group, the param is set with it, so that the node only applies the props to this stream.

Parameters:
  • self -- the stream

  • n_props -- the number of properties

  • names -- (array length=n_props): the names of the properties, such as "volume"

  • values -- (array length=n_props) (transfer none): the values of the properties

Returns:

TRUE if the param was set, FALSE otherwise

WpSpaPod *wp_audio_stream_get_ports_format(WpAudioStream *self)

Gets the stream ports format.

Parameters:
  • self -- the stream

Returns:

(transfer full): the stream port's format

const gchar *wp_audio_stream_get_ports_mode(WpAudioStream *self)

Gets the stream ports mode.

Parameters:
  • self -- the stream

Returns:

(transfer none): the stream port's mode

gboolean wp_audio_stream_has_monitor_ports_enabled(WpAudioStream *self)

Checks whether the monitor ports are enabled or not.

Parameters:
  • self -- the stream

Returns:

TRUE if the monitor ports are enabled, FALSE otherwise

gboolean wp_audio_stream_has_control_ports_enabled(WpAudioStream *self)

Checks whether the control ports are enabled or not.

Parameters:
  • self -- the stream

Returns:

TRUE if the control ports are enabled, FALSE otherwise

WpAudioStreamPortsState wp_audio_stream_get_ports_state(WpAudioStream *self)

Gets the state of the stream ports.

The state is WP_AUDIO_STREAM_PORTS_STATE_CONFIGURING from the moment a port configuration is requested until its ports exist or it fails, which is when the "ports-configured" or "ports-error" signal is emitted. A change of the state is notified through the "ports-state" property.

Parameters:
  • self -- the stream

Returns:

the state of the stream ports

gboolean wp_audio_stream_configure_ports(WpAudioStream *self, WpSpaPod *format, const gchar *mode, gboolean monitor, gboolean control)

Configures the stream ports.

Note that this won't re-configure the ports if they are already configured with the same format, mode, monitor and control values, in which case FALSE is returned. Only TRUE is returned when the configuration request was sent, in which case the user has to handle the 'ports-configured' and 'ports-error' signals to know if the pending configuration was successfully or not.

Parameters:
  • self -- the stream

  • format -- (transfer none): the format

  • mode -- the mode

  • monitor -- whether to enable monitor ports or not

  • control -- whether to enable control ports or not

Returns:

TRUE if the ports will be re-configured, FALSE otherwise

gboolean wp_audio_stream_is_monitorable(WpAudioStream *self, WpAudioStream *peer)

Checks whether the stream would have monitor ports if its ports were configured now in order to link it with the given peer.

Unlike wp_audio_stream_has_monitor_ports_enabled(), which reports the monitor flag of the PortConfig that was last requested, this resolves the settings, the stream's supported formats and the resulting port config mode the same way wp_audio_stream_configure_ports_with_props() does. It is therefore usable before the ports have been configured at all, which is the case while policy scripts are still selecting a link target.

Parameters:
  • self -- the stream

  • peer -- (transfer none) (nullable): the stream that self would be linked with, or NULL to ask about the default configuration

Returns:

TRUE if configuring the ports now would enable monitor ports, FALSE otherwise

gboolean wp_audio_stream_configure_ports_with_props(WpAudioStream *self, WpProperties *props)

Configures the ports given a set of properties. If no properties are given, the default configuration will be used.

Parameters:
  • self -- the stream

  • props -- (transfer full) (nullable): the properties, or NULL to use the default configuration.

Returns:

TRUE if the ports will be re-configured, FALSE otherwise

gboolean wp_audio_stream_configure_ports_with_stream(WpAudioStream *self, WpAudioStream *stream)

Configures the ports using the same configuration as another stream.

Parameters:
  • self -- the stream

  • stream -- (transfer none): the other stream

Returns:

TRUE if the ports will be re-configured, FALSE otherwise

gboolean wp_audio_stream_configure_ports_for_peer(WpAudioStream *self, WpAudioStream *peer)

Configures the ports to link them with the ports of another stream, which must have its ports configured already.

The ports take the same configuration as the other stream, like wp_audio_stream_configure_ports_with_stream() does, unless the other stream has DSP ports with unpositioned channels, such as a pro audio device, or self has the "stream.dont-remix" property set. Remixing into AUX channels puts the channels of self in no meaningful place, so in that case the DSP ports of self keep the channels they have, or those of its own best format if it has no DSP ports yet, and only the monitor and control flags are taken from the other stream.

Parameters:
  • self -- the stream

  • peer -- (transfer none): the stream to link with

Returns:

TRUE if the ports will be re-configured, FALSE otherwise

WP_TYPE_STREAM (wp_stream_get_type ())

The WpStream GType.

WP_TYPE_AUDIO_STREAM (wp_audio_stream_get_type ())

The WpAudioStream GType.

WP_TYPE_VIDEO_STREAM (wp_video_stream_get_type ())

The WpVideoStream GType.