Streams
-
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
-
enumerator WP_STREAM_KIND_UNKNOWN
-
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
-
enumerator WP_STREAM_SHAPE_UNKNOWN
-
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
-
enumerator WP_AUDIO_STREAM_PORTS_STATE_UNCONFIGURED
-
enum WpStreamFeatures
Flags to be used as WpObjectFeatures on WpStream.
Values:
-
enumerator WP_STREAM_FEATURE_ACTIVE = (1 << 0)
Activates the stream
-
enumerator WP_STREAM_FEATURE_ACTIVE = (1 << 0)
-
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.