pw-link

List all audio output and input ports with their IDs

$ pw-link [[-oiI|--output --input --id]]

$ pw-link [output_port_name] [input_port_name]

$ pw-link [[-d|--disconnect]] [output_port_name] [input_port_name]

$ pw-link [[-lI|--links --id]]

$ pw-link [[-h|--help]]

pw-link [OPTIONS] [SOURCE_ID/NAME] [SINK_ID/NAME]
pw-link -l [OPTIONS]
pw-link -d LINK_ID

-l, --list
    List all available PipeWire nodes and their ports.

-i, --input <ID/NAME>
    Specify the input port for a connection.

-o, --output <ID/NAME>
    Specify the output port for a connection.

-p, --passive
    Create a passive link. Passive links do not cause the source node to activate the sink node.

-d, --disconnect <ID>
    Disconnect a specific link by its ID.

-m, --monitor
    Monitor link changes in real-time, printing events as they occur.

-P, --playback <ID/NAME>
    Alias for --output, typically used for playback streams.

-R, --record <ID/NAME>
    Alias for --input, typically used for record streams.

-L, --linger
    Keep the link active after pw-link exits, even if the parent terminal is closed.

--help
    Show help message and exit.

--version
    Show version information and exit.

SOURCE_ID/NAME
    The ID or name of the source node or port (output) for a connection.

SINK_ID/NAME
    The ID or name of the sink node or port (input) for a connection.

pw-link is a command-line utility used to manage links between nodes and ports within the PipeWire multimedia server. PipeWire is a low-latency multimedia graph server designed to handle audio and video streams efficiently on Linux systems, aiming to unify functionalities previously covered by PulseAudio and JACK Audio Connection Kit.

The primary function of pw-link is to establish and remove connections, allowing audio or video data to flow from an output port of one node to an input port of another. This is crucial for routing signals between applications, hardware devices, and virtual processors within the PipeWire ecosystem. For instance, you can use pw-link to connect the output of a music player to the input of a recording application, or route microphone input to a specific conferencing tool.

It operates by identifying nodes and ports using their unique numeric IDs or names. Users typically first list available nodes and ports with pw-link -l or pw-cli ls to identify the desired connection points, and then use pw-link with source and sink IDs to create the link. This provides a powerful, scriptable way to configure complex audio/video routing setups.

pw-link requires the PipeWire daemon to be running. Node and port IDs are dynamic and can change between PipeWire daemon restarts or system reboots, making scripts using hardcoded IDs potentially brittle. It is recommended to use node/port names where possible, or combine with pw-cli ls to dynamically resolve IDs. Understanding PipeWire's graph model is beneficial for effective use.

Before creating a link, you often need to identify the numeric IDs or names of the desired source (output) and sink (input) ports. This can be done using pw-link -l, which lists all active nodes and their associated ports, or pw-cli ls for a more detailed overview of all PipeWire objects.

By default, pw-link creates active links. An active link ensures that the source node activates the sink node when data is present. A passive link (created with -p or --passive) does not cause the source node to activate the sink. Passive links are useful when the sink node is already active for other reasons or managed externally.

pw-link is an integral part of the PipeWire project, initiated by Wim Taymans (Red Hat) around 2017. PipeWire was developed to provide a modern, secure, and performant multimedia framework for Linux, addressing limitations found in existing systems like JACK and PulseAudio. pw-link specifically emerged as the command-line tool to manage the fundamental concept of "links" within PipeWire's graph architecture, enabling dynamic audio/video routing capabilities essential for both desktop and professional audio/video workflows. Its design reflects the need for a programmatic way to control media streams without reliance on graphical tools.

pipewire(1), pw-cli(1), pw-dot(1), pactl(1), jackd(1)