Stream Links
A StreamLink connects an output Stream to an input
one. It owns the individual PipeWire links between their ports: it works out
which port pairs to connect, creates the links when it is activated, recreates
them when either stream reconfigures its ports, and destroys them when it is
deactivated or destroyed.
Stream links are created and tracked by the StreamLinkManager, which also
adopts the links it finds on the graph that WirePlumber did not make itself, so
that the peers of a stream are complete no matter who linked it.
This binds the WpStreamLink and WpStreamLinkManager C API.
Features
Feature.StreamLink.ACTIVE is the only feature a stream link has. Activating
it configures the ports of both streams, if their media type needs that, and
creates the PipeWire links; deactivating it destroys them again without
destroying the stream link, which is how the media role policy suspends and
resumes playback.
A script that asks for a link is the one that has to activate it:
StreamLinkManager.link() hands back an inactive link, and until it is
activated nothing is connected. The manager activates a link on its own only
when it made that link itself, adopting one it found on the graph.
A link that is created but never activated links nothing, but still counts as a
peer of both its streams, so a failed activation has to be followed by
StreamLinkManager.remove_link().
Signals
A StreamLink emits the signals of WpStreamLink, which are
connected with GObject.connect():
link-added(self, link)A PipeWire link between the two streams was created. link is a Link.
link-removed(self, link)One of them went away.
link-error(self, message)One of them entered the error state. This is the failure that has to be reported back to the client that owns the stream, since the client only sees its own node and not the links.
StreamLink methods
- StreamLink.get_output_stream(self)
Binds
wp_stream_link_get_output_stream()The second return value says that the link is made from the output stream's monitor ports rather than from its own ports, which is how a capture stream records what a sink is playing.
- Parameters:
self -- the stream link
- Returns:
the output stream, and whether it is linked through its monitor ports
- Return type:
Stream, boolean
- StreamLink.get_input_stream(self)
Binds
wp_stream_link_get_input_stream()- Parameters:
self -- the stream link
- Returns:
the input stream
- Return type:
Stream
- StreamLink.get_links_count(self)
Binds
wp_stream_link_get_links_count()- Parameters:
self -- the stream link
- Returns:
the number of PipeWire links between the two streams
- Return type:
integer
- StreamLink.iterate_links(self)
Binds
wp_stream_link_new_links_iterator()- Parameters:
self -- the stream link
- Returns:
the PipeWire links between the two streams
- Return type:
Iterator of Link
- StreamLink.reconfigure_ports(self)
Binds
wp_stream_link_reconfigure_ports()Configures the ports of both streams again and recreates the links. Use this when something the port configuration depends on has changed, such as a
stream.features.audio.*setting. Configuring one of the two streams directly is not equivalent: the two have to agree on one configuration, and it is the stream link that decides which one that is.Nothing happens, and false is returned, for a link that is not active yet, one whose links were only adopted from the graph, and one whose media type needs no port configuration.
- Parameters:
self -- the stream link
- Returns:
whether the ports are being reconfigured
- Return type:
boolean
StreamLinkManager functions
All of these are static; the underlying WpStreamLinkManager object is
looked up automatically.
- StreamLinkManager.get_name()
Binds
wp_stream_link_manager_get_name()- Returns:
the name of the stream link manager, or nil if none is loaded
- StreamLinkManager.link(subject, target)
Binds
wp_stream_link_manager_link()Creates a stream link between a stream that asks to be linked and the target it asked for. Which of the two is the output and which is the input follows from the direction of the subject.
The subject is recorded on the link, so that
StreamLinkManager.unlink()can later tell the links this stream asked for apart from the links other streams asked for on it. This is what a policy script should use.The returned link is not activated; activate it to establish the connection. It is destroyed automatically if either of its streams goes away.
- Parameters:
subject -- the stream that asks for the link
target -- the stream it wants to be linked to
- Returns:
the new stream link, or nil if it could not be created
- Return type:
StreamLink
- StreamLinkManager.create_link(output, input)
Binds
wp_stream_link_manager_create_link()Creates a stream link with no subject, which
StreamLinkManager.unlink()will therefore not remove. This is for links that already exist on the graph and are only being adopted; useStreamLinkManager.link()for a link the policy decides to make.- Parameters:
output -- the output stream
input -- the input stream
- Returns:
the new stream link, or nil if it could not be created
- Return type:
StreamLink
- StreamLinkManager.find_link(output, input)
Binds
wp_stream_link_manager_find_link()- Parameters:
output -- the output stream
input -- the input stream
- Returns:
the stream link between the two, or nil if there is none
- Return type:
StreamLink
- StreamLinkManager.remove_link(link)
Binds
wp_stream_link_manager_remove_link()Destroys a stream link that is not active, removing it from the manager. This is what a script that activates a link itself must do when the activation fails: a link left in the manager still counts as a peer of both its streams and makes them look linked.
The link must not be active. An active link owns the PipeWire links it created and this does not destroy them; use
StreamLinkManager.unlink()for an established link.- Parameters:
link -- the stream link to destroy
- StreamLinkManager.unlink(stream)
Binds
wp_stream_link_manager_unlink()Destroys the stream links that the given stream asked for, unlinking it from the targets it was linked to. The stream is usually also part of links that other streams asked for on it, and those are left alone: they are the other streams' to undo. Adopted links have no subject and are left alone as well.
- Parameters:
stream -- the stream to unlink
- Returns:
whether the stream had links to remove
- Return type:
boolean
- StreamLinkManager.get_peers_count(stream)
Binds
wp_stream_link_manager_get_peers_count()- Parameters:
stream -- the stream
- Returns:
the number of streams this one is linked to
- Return type:
integer
- StreamLinkManager.iterate_peers(stream)
Binds
wp_stream_link_manager_new_peers_iterator()- Parameters:
stream -- the stream
- Returns:
the streams this one is linked to
- Return type:
Iterator of Stream
- StreamLinkManager.iterate_links(stream)
Binds
wp_stream_link_manager_new_links_iterator()- Parameters:
stream -- the stream
- Returns:
every stream link the given stream takes part in, whether it asked for it or not
- Return type:
Iterator of StreamLink