Understanding the 'pw-link' Command for PipeWire (with examples)

The pw-link command is a crucial utility for managing connections between audio and video ports in PipeWire, a server for handling audio and video streams on Linux systems. It empowers users to list available ports, create or disconnect links between them, and gain helpful insights into the system’s audio routing configuration. PipeWire is designed to be a more flexible and modern alternative to PulseAudio and JACK, allowing for better handling of both consumer and professional audio workloads. The pw-link tool specifically focuses on helping users easily connect and manage these audio and video links.

Use case 1: Listing all audio output and input ports with their IDs

Code:

pw-link --output --input --ids

Motivation:

This command is essential for users who want to understand the topology of their audio system. When dealing with complex audio setups that include multiple audio devices, understanding which audio outputs (like speakers or headphones) and inputs (like microphones) are recognized by the system is critical. By listing these with their IDs, users can more easily decide which ports to link or troubleshoot if certain devices are not behaving as expected.

Explanation:

• --output: This flag tells pw-link to list all available output ports. Outputs refer to devices where audio is sent to, such as speakers or recording devices.
• --input: This option specifies that pw-link should list all input ports, which act as audio sources like microphones.
• --ids: Including this parameter will append unique identifiers to each port, aiding in precise identification and management of ports, particularly in complex setups with multiple similar devices.

Example Output:

0: alsa_output.pci-0000_00_1b.0.analog-stereo
1: alsa_input.usb-Logitech_USB_Headset-00.analog-stereo

Use case 2: Creating a link between an output and an input port

Code:

pw-link output_port_name input_port_name

Motivation:

Creating links between output and input ports is fundamental when setting up audio routing in a system. You might want to direct audio from a specific application to a particular recording device for streaming or recording purposes. Connecting specific output to input allows for tailored routing, enabling users to conduct activities like podcasting, live streaming, or configuring audio for multimedia production workflows.

Explanation:

• output_port_name: This argument specifies the name of the output port you want to link. It represents the starting point of the audio signal that you wish to route.
• input_port_name: This is the designated destination for the audio signal. By linking it to an output, you’re effectively telling PipeWire to direct audio from the source device/application into this specific input.

Example Output:

Link created between output alsa_output.pci-0000_00_1b.0.analog-stereo and input alsa_input.usb-Logitech_USB_Headset-00.analog-stereo

Use case 3: Disconnecting two ports

Code:

pw-link --disconnect output_port_name input_port_name

Motivation:

Sometimes, audio routing needs to be altered or stopped entirely. Whether because a device is no longer in use, or you want to reconfigure your setup, disconnecting linked ports allows for flexible and dynamic management of audio routes. It’s particularly useful in troubleshooting scenarios or when discontinuing specific audio paths within a live setup.

Explanation:

• --disconnect: This option directs pw-link to terminate the connection between the specified ports.
• output_port_name: Denotes the output port that has been previously linked.
• input_port_name: Specifies the input port currently linked to the output port.

Example Output:

Disconnected link between output alsa_output.pci-0000_00_1b.0.analog-stereo and input alsa_input.usb-Logitech_USB_Headset-00.analog-stereo

Use case 4: Listing all links with their IDs

Code:

pw-link --links --ids

Motivation:

By listing all links with their IDs, users can quickly view all the existing connections between various ports. This is invaluable when managing multiple audio links, as it allows for a clear snapshot of which outputs are connected to which inputs. It can serve as a powerful troubleshooting tool, aiding in identifying any incorrect or unintended connections within a system’s audio ecosystem.

Explanation:

• --links: This flag instructs pw-link to display all current links between ports.
• --ids: When used along with --links, this lists links along with their unique identifiers, making it easier to manage and reference specific connections.

Example Output:

0: Link between output alsa_output.pci-0000_00_1b.0.analog-stereo and input alsa_input.usb-Logitech_USB_Headset-00.analog-stereo

Use case 5: Displaying help

Code:

pw-link -h

Motivation:

Every command-line utility should come with a help option that guides users through its functionality. The -h option provides a quick reference for users to understand the available flags and usage patterns of the pw-link command. This is particularly beneficial for new or occasional users who need a reminder of the command’s capabilities without searching through external documentation.

Explanation:

• -h: The help flag displays a simple textual guide on the usage and options available in pw-link. It typically outlines basic command syntax, options, and their descriptions.

Example Output:

Usage: pw-link [options]
Manage links between ports in PipeWire

Options:
  --output        List output nodes
  --input         List input nodes
  ...

Conclusion

The pw-link command serves as an essential tool for managing audio connections using PipeWire. From listing available ports, linking inputs and outputs, to easily displaying configured links, it provides a suite of functionalities to deal with complex audio setups. This empowers both casual users and audio professionals to tailor and manage their sound architectures with enhanced flexibility.