Streams
A Stream is a logical group of ports on a node that share a direction and a
media type. Scripts never construct streams: the stream manager creates one per
port group as soon as a node appears on the graph, and destroys it with the
node. Streams are obtained from an ObjectManager
or, in the linking hooks, from event:get_subject ().
This binds the WpStream C API. There are two concrete
kinds, AudioStream and VideoStream, and an Interest can ask for either the base type or one of them:
om = ObjectManager {
Interest { type = "AudioStream",
Constraint { "media.class", "=", "Stream/Output/Audio" },
},
}
Constants
Three tables name the enumerations that the stream methods return.
StreamKind tells apart the two roles a stream plays in the linking policy:
Constant |
Meaning |
|---|---|
|
an application stream, which asks to be linked to something |
|
a device or virtual endpoint, which others ask to be linked to |
|
neither, because the node has no recognized
|
StreamShape is the finer classification the kind is derived from, taken
from the node's media.class: StreamShape.SINK, StreamShape.SOURCE,
StreamShape.INPUT, StreamShape.OUTPUT and StreamShape.UNKNOWN. Sinks
and sources are targets; inputs and outputs are subjects.
Direction is the direction of the stream's ports: Direction.INPUT or
Direction.OUTPUT. Note that a sink and a stream that plays into it are both
Direction.INPUT; the direction says which way data flows through the ports,
not which end of a link the stream is.
Features
Feature.Stream.ACTIVE is the only feature a stream has. It is activated by
the stream manager and means that the stream knows its ports and the formats
its node supports. A stream that is not active answers 0 to every port and
format query.
Signals
A Stream emits the signals of WpStream, which are connected
with GObject.connect():
port-added(self, port)A port joined the stream. port is a Port.
port-removed(self, port)A port left the stream.
ports-changed(self)The set of ports settled after a change. This is emitted once per change, after the
port-addedandport-removedsignals of that change, and is the right place to react to the stream's new shape.params-changed(self, id)The Props or PropInfo param of the stream changed. id is the name of the param that changed, either
"Props"or"PropInfo". The new param objects can be retrieved withStream.iterate_params().
An AudioStream emits two more, which report the outcome of a port
configuration this stream asked for:
ports-configured(self)The node applied the PortConfig that was requested.
ports-error(self, message)The node refused it.
Stream methods
- Stream.get_node(self)
Binds
wp_stream_get_node()- Parameters:
self -- the stream
- Returns:
the node this stream belongs to
- Return type:
Node, see PipeWire Proxies
- Stream.get_properties(self)
Binds
wp_stream_get_properties()Returns the stream's properties. These are a copy of the node's properties taken when the stream was created, so they do not follow later changes on the node. The keys set in the node's
stream.props.<port-group>property replace the node ones, so the node value of such a key can only be read from the node itself.- Parameters:
self -- the stream
- Returns:
the stream properties
- Return type:
- Stream.get_property(self, key)
Binds
wp_stream_object_get_property()- Parameters:
self -- the stream
key (string) -- the property name
- Returns:
the value of the property, or nil if it does not exist
- Return type:
string
- Stream.get_direction(self)
Binds
wp_stream_get_direction()- Parameters:
self -- the stream
- Returns:
Direction.INPUTorDirection.OUTPUT- Return type:
integer
- Stream.get_port_group(self)
Binds
wp_stream_get_port_group()Returns the
port.groupthat this stream's ports carry, which is what separates the streams of a node that has more than one.- Parameters:
self -- the stream
- Returns:
the port group, or nil
- Stream.get_creation_time(self)
Binds
wp_stream_get_creation_time()Returns the time the stream was created, in microseconds. The linking policy uses this to tell which of two streams is the newer one.
- Parameters:
self -- the stream
- Returns:
the creation time in microseconds
- Return type:
integer
- Stream.get_node_bound_id(self)
Binds
wp_stream_get_node_bound_id()Returns the global id of the stream's node, which is the id that clients and the metadata refer to.
- Parameters:
self -- the stream
- Returns:
the node's bound id, or
Id.INVALIDif the node is gone- Return type:
integer
- Stream.get_kind(self)
Binds
wp_stream_get_kind()- Parameters:
self -- the stream
- Returns:
one of the
StreamKindconstants- Return type:
integer
- Stream.get_shape(self)
Binds
wp_stream_get_shape()- Parameters:
self -- the stream
- Returns:
one of the
StreamShapeconstants- Return type:
integer
- Stream.is_compatible(self, other)
Binds
wp_stream_is_compatible()Checks whether the two streams have a format in common, which is the precondition for linking them. The second return value says that the only common format is an encoded one, in which case the link has to be made in passthrough mode.
- Parameters:
self -- the stream
other -- the other stream
- Returns:
whether the streams are compatible, and whether only an encoded format is common to both
- Return type:
boolean, boolean
- Stream.is_exclusive(self)
Binds
wp_stream_is_exclusive()Returns whether the stream accepts only one peer at a time. A video input stream always is, because video cannot be mixed; an audio stream is only when its ports are configured in passthrough mode, where there is nothing in the graph that could mix them.
- Parameters:
self -- the stream
- Returns:
whether the stream is exclusive
- Return type:
boolean
- Stream.get_supported_raw_format_count(self)
- Stream.get_supported_enc_format_count(self)
Bind
wp_stream_get_supported_raw_format_count()andwp_stream_get_supported_enc_format_count()Return how many raw, respectively encoded, formats the node reported in EnumFormat for this stream.
- Parameters:
self -- the stream
- Returns:
the number of formats
- Return type:
integer
- Stream.iterate_supported_raw_formats(self)
- Stream.iterate_supported_enc_formats(self)
Bind
wp_stream_new_supported_raw_format_iterator()andwp_stream_new_supported_enc_format_iterator()
- Stream.has_port(self, port_id)
- Stream.has_monitor_port(self, port_id)
- Stream.has_control_port(self, port_id)
Bind
wp_stream_has_port(),wp_stream_has_monitor_port()andwp_stream_has_control_port()Check whether the given port belongs to this stream. The three kinds of port are disjoint:
has_portanswers only for the ports that carry the stream's own data, not for its monitor or control ports.- Parameters:
self -- the stream
port_id (integer) -- the global id of the port
- Returns:
whether the stream has that port
- Return type:
boolean
- Stream.get_ports_count(self)
- Stream.get_monitor_ports_count(self)
- Stream.get_control_ports_count(self)
Bind
wp_stream_get_ports_count(),wp_stream_get_monitor_ports_count()andwp_stream_get_control_ports_count()- Parameters:
self -- the stream
- Returns:
the number of ports of that kind
- Return type:
integer
- Stream.iterate_ports(self)
- Stream.iterate_monitor_ports(self)
- Stream.iterate_control_ports(self)
Bind
wp_stream_new_ports_iterator(),wp_stream_new_monitor_ports_iterator()andwp_stream_new_control_ports_iterator()- Parameters:
self -- the stream
- Returns:
the ports of that kind
- Return type:
Iterator of Port
- Stream.iterate_params(self, param_name)
Binds
wp_stream_enum_params_sync()- Parameters:
self -- the stream
param_name (string) -- the param name to enumerate, either "Props" or "PropInfo"
- Returns:
the cached param objects of the stream, which are the ones of its port group, or all of them if the stream has no port group
- Return type:
Iterator; the iteration items are Spa Pod objects
- Stream.set_props_param(self, props)
Binds
wp_stream_set_props_param_array()Sets the Props param of the stream's node, with the stream's port group, if any, so that the node only applies the props to this stream.
stream:set_props_param { volume = Pod.Float (1.0), mute = Pod.Boolean (false), }
- Parameters:
self -- the stream
props (table) -- the Spa Pod values of the props, indexed by their names
- Returns:
whether the param was set
- Return type:
boolean
AudioStream methods
An AudioStream has everything above, plus the port configuration API. Ports
are configured through PortConfig on the node, which decides the port layout
(one mono port per channel in DSP mode, or the negotiated format on a single
port otherwise) and whether monitor and control ports exist.
Configuring ports is asynchronous. The methods below return true when a request
was sent, in which case ports-configured or ports-error follows, and
false when the ports already have the requested configuration and nothing needs
to be done.
Scripts do not normally call these directly: a StreamLink configures both of its streams when it is activated, and that is the only place that can decide which of the two configurations the pair should agree on.
- AudioStream.get_ports_format(self)
Binds
wp_audio_stream_get_ports_format()- Parameters:
self -- the stream
- Returns:
the format of the last requested PortConfig, or nil
- Return type:
- AudioStream.get_ports_mode(self)
Binds
wp_audio_stream_get_ports_mode()- Parameters:
self -- the stream
- Returns:
the mode of the last requested PortConfig (
"none","dsp","convert"or"passthrough"), or nil- Return type:
string
- AudioStream.get_ports_state(self)
Binds
wp_audio_stream_get_ports_state()AudioStreamPortsState.CONFIGURINGlasts from the moment a port configuration is requested until its ports exist or the request fails.- Parameters:
self -- the stream
- Returns:
one of the
AudioStreamPortsStateconstants:UNCONFIGURED(the ports were never configured),CONFIGURINGorCONFIGURED- Return type:
integer
- AudioStream.has_monitor_ports_enabled(self)
- AudioStream.has_control_ports_enabled(self)
Bind
wp_audio_stream_has_monitor_ports_enabled()andwp_audio_stream_has_control_ports_enabled()Return the monitor, respectively control, flag of the PortConfig that was last requested.
- Parameters:
self -- the stream
- Returns:
whether those ports were asked for
- Return type:
boolean
- AudioStream.is_monitorable(self, peer)
Binds
wp_audio_stream_is_monitorable()Answers what
has_monitor_ports_enabledwill answer once the ports are configured, by resolving the settings and the stream's formats the same way the configuration does. Unlikehas_monitor_ports_enabled, it is usable before anything has been configured, which is the case while the policy is still choosing a target.- Parameters:
self -- the stream
peer -- (optional) the stream this one would be linked with, or nil to ask about the default configuration
- Returns:
whether configuring the ports now would enable monitor ports
- Return type:
boolean
- AudioStream.configure_ports(self, format, mode, monitor, control)
Binds
wp_audio_stream_configure_ports()- Parameters:
self -- the stream
format -- the format to configure, as a Spa Pod
mode (string) -- the port config mode
monitor (boolean) -- whether to create monitor ports
control (boolean) -- whether to create control ports
- Returns:
whether a configuration request was sent
- Return type:
boolean
- AudioStream.configure_ports_with_props(self, props)
Binds
wp_audio_stream_configure_ports_with_props()Configures the ports from a set of properties, falling back to the settings and the node's own properties for everything the given properties do not say.
- Parameters:
self -- the stream
props -- (optional) a table or Properties object, or nil for the default configuration
- Returns:
whether a configuration request was sent
- Return type:
boolean
- AudioStream.configure_ports_with_stream(self, other)
Binds
wp_audio_stream_configure_ports_with_stream()Configures the ports with the same configuration that other has, so that the two streams can be linked.
- Parameters:
self -- the stream
other -- the stream to copy the configuration from
- Returns:
whether a configuration request was sent
- Return type:
boolean
- AudioStream.configure_ports_for_peer(self, peer)
Binds
wp_audio_stream_configure_ports_for_peer()Configures the ports so that the stream can be linked with peer. This copies the configuration of peer like
configure_ports_with_stream, unless peer has unpositioned (AUX) DSP ports or this stream hasstream.dont-remixset, in which case the stream keeps its own channels.- Parameters:
self -- the stream
peer -- the stream to link with, with its ports configured
- Returns:
whether a configuration request was sent
- Return type:
boolean
VideoStream methods
VideoStream adds nothing to Stream. Video ports are not configured by
WirePlumber, so there is no equivalent of the AudioStream methods above,
and iterate_supported_enc_formats is always empty.