WirePlumber

The WirePlumber Daemon

  • Getting started
  • Installing WirePlumber
  • Running the WirePlumber daemon
  • Configuration
  • Locations of WirePlumber's files
  • Debug Logging
  • Running multiple instances

WirePlumber's Design

  • Understanding Session Management
  • Understanding WirePlumber
  • Events and Hooks

WirePlumber's Policies

  • Client Access Control
  • Linking Policy
  • Smart Filters
  • Automatic Software DSP

The WirePlumber Library

  • C API Documentation

Scripting

  • Lua API Documentation
    • Introduction
    • GObject Integration
    • Core
    • Debug Logging
    • Events & Hooks
    • Settings
    • Conf
    • Json
    • Iterator
    • WpObject
    • Object Manager
    • Object Interest
    • PipeWire Proxies
    • Streams
    • Stream Links
      • Features
      • Signals
      • StreamLink methods
        • StreamLink.get_output_stream()
        • StreamLink.get_input_stream()
        • StreamLink.get_links_count()
        • StreamLink.iterate_links()
        • StreamLink.reconfigure_ports()
      • StreamLinkManager functions
        • StreamLinkManager.get_name()
        • StreamLinkManager.link()
        • StreamLinkManager.create_link()
        • StreamLinkManager.find_link()
        • StreamLinkManager.remove_link()
        • StreamLinkManager.unlink()
        • StreamLinkManager.get_peers_count()
        • StreamLinkManager.iterate_peers()
        • StreamLinkManager.iterate_links()
    • Permissions API
    • Properties
    • Spa Device
    • Spa Pod
    • State
    • Local Modules
    • Miscellaneous
  • Existing Scripts
  • Custom Scripts

Man Pages

  • wireplumber(1)
  • wpconfig(1)
  • wpctl(1)
  • wpdot(1)
  • wpexec(1)

Resources

  • Contributing to WirePlumber
  • Testing
  • Community Resources
  • Releases
WirePlumber
  • Lua API Documentation
  • Stream Links
  • View page source
Previous Next

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; use StreamLinkManager.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

Previous Next

© Copyright 2020-2025, Collabora & contributors.

Built with Sphinx using a theme provided by Read the Docs.