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

StreamKind.SUBJECT

an application stream, which asks to be linked to something

StreamKind.TARGET

a device or virtual endpoint, which others ask to be linked to

StreamKind.UNKNOWN

neither, because the node has no recognized media.class

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-added and port-removed signals 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 with Stream.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:

Properties

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.INPUT or Direction.OUTPUT

Return type:

integer

Stream.get_port_group(self)

Binds wp_stream_get_port_group()

Returns the port.group that 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.INVALID if the node is gone

Return type:

integer

Stream.get_kind(self)

Binds wp_stream_get_kind()

Parameters:

self -- the stream

Returns:

one of the StreamKind constants

Return type:

integer

Stream.get_shape(self)

Binds wp_stream_get_shape()

Parameters:

self -- the stream

Returns:

one of the StreamShape constants

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() and wp_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() and wp_stream_new_supported_enc_format_iterator()

Parameters:

self -- the stream

Returns:

the formats, as Spa Pod objects

Return type:

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() and wp_stream_has_control_port()

Check whether the given port belongs to this stream. The three kinds of port are disjoint: has_port answers 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() and wp_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() and wp_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:

Spa Pod

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.CONFIGURING lasts from the moment a port configuration is requested until its ports exist or the request fails.

Parameters:

self -- the stream

Returns:

one of the AudioStreamPortsState constants: UNCONFIGURED (the ports were never configured), CONFIGURING or CONFIGURED

Return type:

integer

AudioStream.has_monitor_ports_enabled(self)
AudioStream.has_control_ports_enabled(self)

Bind wp_audio_stream_has_monitor_ports_enabled() and wp_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_enabled will answer once the ports are configured, by resolving the settings and the stream's formats the same way the configuration does. Unlike has_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 has stream.dont-remix set, 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.