PipeWire: Persistent Per-App Audio Routing with WirePlumber

AI-generated

PipeWire makes switching audio devices on Linux quite easy, but GUI changes are often only useful until the next reboot or reconnect. I use WirePlumber rules when I want selected applications to always use my USB DAC, HDMI display or Bluetooth headset.

On my Arch laptop I have several output devices connected depending on where I work. The internal speakers are fine for normal stuff, but I want music players on the USB DAC, games on HDMI and calls on my headset. Changing this manually in pavucontrol works, but it gets annoying fast.

WirePlumber can apply properties to every newly created audio stream. This is the current configuration model in WirePlumber 0.5 and newer. Older guides using Lua files in ~/.config/wireplumber/main.lua.d/ are for WirePlumber 0.4 and should not be copied any more.

Checking the current PipeWire devices

First I check that PipeWire and WirePlumber are running in my user session.

$ systemctl --user status pipewire wireplumber
● pipewire.service - PipeWire Multimedia Service
     Loaded: loaded
     Active: active (running)

● wireplumber.service - Multimedia Service Session Manager
     Loaded: loaded
     Active: active (running)

wpctl status shows the available sinks and currently playing streams.

$ wpctl status
PipeWire 'pipewire-0' [1.4.x, yves@arch, cookie:123456789]
 └─ Audio
     ├─ Devices:
     │      48. USB DAC
     │      63. HDMI / DisplayPort
     │      71. Bluetooth Headset
     ├─ Sinks:
     │  *   50. USB DAC Analog Stereo
     │      65. HDMI / DisplayPort 3 Output
     │      75. Bluetooth Headset Stereo
     └─ Streams:
            92. Firefox
            97. Spotify

The numeric IDs are useful for temporary testing, but they are not persistent. They change after restarting PipeWire or reconnecting a device.

For a persistent rule I need the internal node name. I can inspect a sink with its current ID:

$ wpctl inspect 50
id 50, type PipeWire:Interface:Node
    node.name = "alsa_output.usb-Generic_USB_Audio-00.analog-stereo"
    node.description = "USB DAC Analog Stereo"
    media.class = "Audio/Sink"

The important part is node.name. Keep that value somewhere while writing the rule.

For HDMI it usually looks similar to this:

alsa_output.pci-0000_03_00.1.hdmi-stereo-extra3

Bluetooth devices are provided by BlueZ and have names such as:

bluez_output.01_23_45_67_89_AB.1

Do not use the ID from wpctl status as target.object. It works only until PipeWire recreates the node. The stable node.name is what WirePlumber needs.

Finding useful application properties

WirePlumber rules can match application properties. I normally start an application, play some audio and inspect its stream.

$ wpctl status
PipeWire 'pipewire-0' [1.4.x, yves@arch, cookie:123456789]
 └─ Audio
     └─ Streams:
            92. Firefox
$ wpctl inspect 92
id 92, type PipeWire:Interface:Node
    application.name = "Firefox"
    application.process.binary = "firefox"
    media.class = "Stream/Output/Audio"
    node.name = "Firefox"

I prefer matching application.process.binary where possible. It is normally more predictable than the visible application name, especially with Electron applications or sandboxed software.

For Flatpak applications, properties can differ from the native package. Inspect the stream while it is playing instead of guessing.

Creating persistent stream rules

WirePlumber reads local configuration snippets from:

~/.config/wireplumber/wireplumber.conf.d/

I create the directory if it does not exist yet.

$ mkdir -p ~/.config/wireplumber/wireplumber.conf.d

Then I create a configuration file for my audio routes.

$ vim ~/.config/wireplumber/wireplumber.conf.d/90-per-app-audio.conf

This example sends Firefox to my USB DAC and a game started through Steam to HDMI.

node.rules = [
  {
    matches = [
      {
        media.class = "Stream/Output/Audio"
        application.process.binary = "firefox"
      }
    ]
    actions = {
      update-props = {
        target.object = "alsa_output.usb-Generic_USB_Audio-00.analog-stereo"
      }
    }
  }
  {
    matches = [
      {
        media.class = "Stream/Output/Audio"
        application.process.binary = "game"
      }
    ]
    actions = {
      update-props = {
        target.object = "alsa_output.pci-0000_03_00.1.hdmi-stereo-extra3"
      }
    }
  }
]

The first condition limits the rule to playback streams. Without media.class = "Stream/Output/Audio", a matching application could also affect unrelated PipeWire nodes.

target.object tells WirePlumber which sink should receive the stream. The rule is applied when the application creates a new playback stream, so it also works after a reboot.

For a headset I add another rule. In my case I use this for a voice application:

  {
    matches = [
      {
        media.class = "Stream/Output/Audio"
        application.process.binary = "teams-for-linux"
      }
    ]
    actions = {
      update-props = {
        target.object = "bluez_output.01_23_45_67_89_AB.1"
      }
    }
  }

Bluetooth audio can still be a bit tricky on Linux. If a headset is connected with the wrong profile, routing is not the real problem. I had similar device-level issues with a keyboard in my post about fixing Linux Bluetooth issues with the Microsoft Surface Ergonomic Keyboard.

Reloading WirePlumber and testing the rules

After changing the configuration, I restart WirePlumber.

$ systemctl --user restart wireplumber

Then I completely close and reopen the application I want to test. Existing streams keep their old properties, so just restarting WirePlumber is not always enough.

$ wpctl status
PipeWire 'pipewire-0' [1.4.x, yves@arch, cookie:123456789]
 └─ Audio
     ├─ Sinks:
     │      50. USB DAC Analog Stereo
     │      65. HDMI / DisplayPort 3 Output
     └─ Streams:
            101. Firefox

To verify the selected route, I inspect the stream:

$ wpctl inspect 101
id 101, type PipeWire:Interface:Node
    application.process.binary = "firefox"
    target.object = "alsa_output.usb-Generic_USB_Audio-00.analog-stereo"

If WirePlumber does not load the configuration, I check its user service log.

$ journalctl --user -u wireplumber -b

A syntax error in the SPA-JSON style configuration is the usual reason. Missing brackets and quotes around values are easy to overlook.

Device reconnects and default outputs

The rules work well for USB DACs and HDMI devices as long as the node.name stays the same. This normally survives reconnects because the name is based on the ALSA card path and profile.

A Bluetooth headset can be different. Its node name may change when using another codec or profile. I normally keep the headset on the same output profile if I want a fixed rule.

For everything without a dedicated rule, I set a normal default sink:

$ wpctl set-default 50

WirePlumber remembers the default node itself. The per-application rules are still useful because they override that generic choice for newly created streams.

This is also useful with gaming setups. I can keep desktop audio on my DAC while a game is routed to the display connected to my AMD GPU. For HDR games I use a separate Gamescope setup as described in HDR Gaming on Linux: Gamescope, Steam and an AMD GPU.

Do not edit files below /usr/share/wireplumber/ for local changes. Package updates overwrite them. Files in ~/.config/wireplumber/wireplumber.conf.d/ are the right place for user-specific rules.

Once the rules are in place, PipeWire audio routing becomes mostly boring again, which is exactly what I want. If you know a better way to handle changing Bluetooth profiles, let me know.