How to use the command pw-link (with examples)

The pw-link command is used to manage links between ports in PipeWire, which is a server for handling audio and video streams. It allows users to create, disconnect, and list links between audio output and input ports.

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

Code:

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

Motivation: This use case is useful for users who want to see a list of all available audio output and input ports along with their corresponding IDs.

Explanation:

• --output: This argument specifies that we want to list audio output ports.
• --input: This argument specifies that we want to list audio input ports.
• --ids: This argument indicates that we want to display the IDs of the ports.

Example output:

Output Ports:
- Output Port 1 (ID: 1)
- Output Port 2 (ID: 2)

Input Ports:
- Input Port 1 (ID: 1)
- Input Port 2 (ID: 2)

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

Code:

pw-link output_port_name input_port_name

Motivation: This use case is helpful when you want to establish a connection between an audio output port and an audio input port for streaming audio data.

Explanation:

• output_port_name: This argument specifies the name of the audio output port you want to link.
• input_port_name: This argument specifies the name of the audio input port you want to link.

Example output:

Link created between Output Port: Output Port 1 and Input Port: Input Port 1

Use case 3: Disconnect two ports

Code:

pw-link --disconnect output_port_name input_port_name

Motivation: If you want to disconnect an audio output port from an audio input port, this use case allows you to achieve that.

Explanation:

• --disconnect: This argument indicates that we want to disconnect the specified ports.
• output_port_name: This argument specifies the name of the audio output port you want to disconnect.
• input_port_name: This argument specifies the name of the audio input port you want to disconnect.

Example output:

Link disconnected between Output Port: Output Port 1 and Input Port: Input Port 1

Use case 4: List all links with their IDs

Code:

pw-link --links --ids

Motivation: This use case provides a list of all existing links between audio output and input ports along with their corresponding IDs.

Explanation:

• --links: This argument specifies that we want to list all links.
• --ids: This argument indicates that we want to display the IDs of the links.

Example output:

Links:
- Link 1 (ID: 1)
- Link 2 (ID: 2)

Use case 5: Display help

Code:

pw-link -h

Motivation: If you need assistance or want to learn more about the available options and arguments of the pw-link command, this use case allows you to display the help message.

Explanation:

• -h: This option displays the help message for the command.

Example output:

pw-link 0.3.32
Manage links between ports in PipeWire
More information: <https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Virtual-Devices>.

USAGE:
    pw-link [FLAGS] [OPTIONS] [output_port_name] [input_port_name]

FLAGS:
    -h, --help         Prints help information
        --disconnect   Disconnect two linked ports
    -i, --input        List audio input ports
        --ids          Display IDs
    -l, --links        List all links
    -o, --output       List audio output ports

OPTIONS:
        --path <path>    Connect only to specified path

ARGS:
    <output_port_name>    Output port name
    <input_port_name>     Input port name

Conclusion:

The pw-link command is a powerful tool to manage links between audio output and input ports in PipeWire. It provides several use cases, including listing ports and links, creating and disconnecting links, and displaying the help message. Understanding and utilizing these use cases will help users effectively manage their audio streaming configurations in PipeWire.