WirePlumber

From ArchWiki

Related articles

WirePlumber is a powerful session and policy manager for PipeWire. Based on a modular design, with Lua plugins that implement the actual management functionality, it is highly configurable and extendable.

Installation

Install the wireplumber package. It will conflict with other PipeWire Session Managers and make sure they are uninstalled.

WirePlumber uses systemd user units to manage the server.

Configuration

Tango-view-refresh-red.pngThis article or section is out of date.Tango-view-refresh-red.png

Reason: WirePlumber's configuration format is changing.[1] (Discuss in ArchWiki talk:Requests#Update for new WirePlumber configuration format)

Configuration file layout

WirePlumber's configuration is comprised of global PipeWire-flavored JSON objects such as context and alsa_monitor that are modified to change its behavior. The configuration files are read from ~/.config/wireplumber/ (user configuration), /etc/wireplumber/ (global configuration), and then /usr/share/wireplumber/ (stock configuration).

WirePlumber starts by reading the main configuration file. This is a JSON-like file that sets up the PipeWire context, SPA plugins, modules, and components. Among these components is the Lua scripting engine, which is used to dynamically modify the global objects.

There are different main configuration files that ship with the package:

  • The single-instance configuration file, at /usr/share/wireplumber/wireplumber.conf. This is the default configuration, which includes the functionality of all the other configurations within one process.
  • The main configuration file, at /usr/share/wireplumber/main.conf. This loads the modules and components necessary for the WirePlumber core, and loads Lua configuration files from config-dir/main.lua.d/. [2]
  • The Bluetooth configuration file, at /usr/share/wireplumber/bluetooth.conf. This is suitable for a WirePlumber process that is handling Bluetooth connectivity for the core process. This loads Lua files from config-dir/bluetooth.lua.d/.
  • The policy configuration file, at /usr/share/wireplumber/policy.conf. This encapsulates policy functionality, which is how WirePlumber makes decisions about moving and making changes to nodes. This loads Lua files from config-dir/policy.lua.d/

The Lua configuration files in the lua.d/ directories also load Lua scripts from config-dir/scripts/. These scripts implement some of the logic/functionality of Pipewire, and could also be worth modifying under certain circumstances.

Modifying the configuration

The recommended way to configure WirePlumber is to add a Lua script to the appropriate lua.d/ directory within /etc/wireplumber/ or ~/.config/wireplumber/. Some things to consider are:

  • If there is an existing script you want to override, copy it from /usr/share/wireplumber/ to the destination while keeping its name the same. Configuration files with the same name but in a lower priority location will be ignored. [3]
  • Otherwise, if you are adding a new script, you should start it with a number bigger than 50 (e.g. 51-my-config.lua), as the default configuration is mostly done at or below 50 in the alphanumeric ordering.
    • Note that WirePlumber performs multi-path merging, meaning that a lower numbered stock config will run before your new script, as alphanumeric ordering takes precedence over directory priorities.
  • The directory you choose should be consistent with what the stock configuration does, but it does not strictly matter unless you are using multiple instances.
  • ALSA properties for Bluetooth devices must be configured in bluetooth.lua.d/. An ALSA property for a Bluetooth device set in main.lua.d/ is not applied.

Obtain interface name for rules matching

In the Lua scripts, you need to specify matches rules with a property from PipeWire objects of the target interface you want to configure.

Use the command wpctl status to show all objects managed by WirePlumber. Find the ID of you desired interface.

Consider following example output: 

$ wpctl status
PipeWire 'pipewire-0' [0.3.56, user@hostname, cookie:1163266174]
 └─ Clients:
        32. pipewire-pulse                      [0.3.56, user@hostname, pid:895]
        33. WirePlumber                         [0.3.56, user@hostname, pid:894]
        ...
Audio
 ├─ Devices:
 │      42. HD Audio Controller                 [alsa]
 │     105. USB PnP Audio Device                [alsa]
 │
 ├─ Sinks:
 │  *   48. HD Audio Controller Analog Stereo   [vol: 0.50]
 │      53. EasyEffects Sink                    [vol: 1.00]
 │
 ├─ ...
 │
 ├─ Sources:
 │      54. EasyEffects Source                  [vol: 1.00]
 │  *  101. USB PnP Audio Device Mono           [vol: 0.74]
 │
 └─ ...

Video
 └─ ...

Settings
 └─ Default Configured Node Names:
         0. Audio/Sink    alsa_output.pci-0000_08_00.4.analog-stereo
         1. Audio/Source  alsa_input.usb-0c76_USB_PnP_Audio_Device-00.mono-fallback

the ID of desired interface: HD Audio Controller Analog Stereo is 48.

Then use command wpctl inspect ID to view object detail, listed all properties in that object: 

$ wpctl inspect 48
id 48, type PipeWire:Interface:Node
    ...
  * client.id = "34"
    device.api = "alsa"
    device.class = "sound"
  * device.id = "42"
    device.profile.description = "Analog Stereo"
    device.profile.name = "analog-stereo"
  * factory.id = "18"
    factory.mode = "merge"
    factory.name = "api.alsa.pcm.sink"
    library.name = "audioconvert/libspa-audioconvert"
  * media.class = "Audio/Sink"
  * node.description = "HD Audio Controller Analog Stereo"
    ...
  * node.name = "alsa_output.pci-0000_08_00.4.analog-stereo"
  * node.nick = "ALC1220 Analog"
    ...
  * object.path = "alsa:pcm:1:front:1:playback"
  * object.serial = "49"
    ...

Choose device.name or node.name or node.nick property, to use with the matches rules in the Lua configuration script.

Avoid using device.id, it is dynamic and changes often.

Note:
  • wpctl inspect outputs the object type on the first line, i.e. type PipeWire:Interface:Node means that the object type is Node.
  • Node objects are sinks or sources in the PipeWire graph, and Device objects correspond to the ALSA card.
  • You can determine the Endpoint class of this object from the media.class property.
  • Since WirePlumber v0.4.9, ALSA nodes use the PCM name to populate node.nick, which is useful at least on HDA cards using UCM, where all outputs (analog, HDMI, etc.) are exposed as Node on a single profile.
Tip:
  • The command pw-top shows the PipeWire Device and Node currently in use.
  • Results from wpctl inspect ID are the same as the properties field from the pw-cli dump ID command.

Changing a device/node property

To change a device or node property, such as its description or nick, you must create a Lua script and add it into /etc/wireplumber/ or ~/.config/wireplumber/ under the proper path and name.

For instance, to change the description of an ALSA node, you would create a file such as: 

/etc/wireplumber/main.lua.d/51-device-rename.lua (or ~/.config/wireplumber/main.lua.d/51-device-rename.lua)
rule = {
  matches = {
    {
      { "node.name", "equals", "alsa_output.pci-0000_00_1f.3.output_analog-stereo" },
    },
  },
  apply_properties = {
    ["node.description"] = "Laptop",
  },
}

table.insert(alsa_monitor.rules, rule)

If instead you wish to change something on a Bluetooth node or device, you could create a file such as: 

/etc/wireplumber/bluetooth.lua.d/51-device-rename.lua (or ~/.config/wireplumber/bluetooth.lua.d/51-device-rename.lua)
rule = {
  matches = {
    {
      { "node.name", "equals", "bluez_output.02_11_45_A0_B3_27.a2dp-sink" },
    },
  },
  apply_properties = {
    ["node.nick"] = "Headphones",
  },
}

table.insert(bluez_monitor.rules, rule)

The properties that you can change as well as the matching rules to select devices or nodes are documented at ALSA configuration and Bluetooth configuration.

Disable a device/node

Since WirePlumber v0.4.7, users could now disable any devices or nodes by property device.disabled or node.disabled: 

/etc/wireplumber/main.lua.d/51-alsa-disable.lua (or ~/.config/wireplumber/main.lua.d/51-alsa-disable.lua)
rule = {
  matches = {
    {
      { "device.name", "equals", "alsa_card.pci-0000_08_00.4" },
    },
  },
  apply_properties = {
    ["device.disabled"] = true,
  },
}

table.insert(alsa_monitor.rules,rule)

For the name of alsa_card.* in your system, see #Obtain interface name for rules matching.

Note: Common use-case, for example, is to disable NVIDIA's HDMI audio output.

Simultaneous output to multiple sinks on the same sound card

Create a copy of /usr/share/alsa-card-profile/mixer/profile-sets/default.conf so that changes persist across updates. Here we define a profile joining the two default mappings for Analog and HDMI. 

/usr/share/alsa-card-profile/mixer/profile-sets/multiple.conf
[General]
auto-profiles = no

[Mapping analog-stereo]
device-strings = front:%f
channel-map = left,right
paths-output = analog-output analog-output-lineout analog-output-speaker analog-output-headphones analog-output-headphones-2
paths-input = analog-input-front-mic analog-input-rear-mic analog-input-internal-mic analog-input-dock-mic analog-input analog-input-mic analog-input-linein analog-input-aux analog-input-video analog-input-tvtuner analog-input-fm analog-input-mic-line analog-input-headphone-mic analog-input-headset-mic
priority = 15

[Mapping hdmi-stereo]
description = Digital Stereo (HDMI)
device-strings = hdmi:%f
paths-output = hdmi-output-0
channel-map = left,right
priority = 9
direction = output

[Profile multiple]
description = Analog Stereo Duplex + Digital Stereo (HDMI) Output
output-mappings = analog-stereo hdmi-stereo
input-mappings = analog-stereo

Now we configure Wireplumber to use the new card-profile for matching devices. For identifying information see #Obtain interface name for rules matching. We apply the configuration by creating a Lua script such as the following: 

/etc/wireplumber/main.lua.d/51-alsa-custom.lua (or ~/.config/wireplumber/main.lua.d/51-alsa-custom.lua)
rule = {
  matches = {
    {
      { "device.nick", "matches", "HDA Intel PCH" },
    },
  },
  apply_properties = {
    ["api.alsa.use-acp"] = true,
    ["api.acp.auto-profile"] = false,
    ["api.acp.auto-port"] = false,
    ["device.profile-set"] = "multiple.conf",
    ["device.profile"] = "multiple",
  },
}
table.insert(alsa_monitor.rules,rule)

Tips and tricks

Keyboard volume control

See Keyboard shortcuts#Xorg to bind the following commands to your volume keys: XF86AudioRaiseVolume, XF86AudioLowerVolume, XF86AudioMute and XF86AudioMicMute.

To raise the volume, with a limit of 150%: 

$ wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5%+

To lower the volume: 

$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-

To mute/unmute the volume: 

$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle

To mute/unmute the microphone: 

$ wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle
Tip: To use sinks or sources other than the default ones, run wpctl status to list all available sinks, and use sink or source numbers in place of @DEFAULT_AUDIO_SINK@ or _SOURCE@.

Show volume level

To get the volume level and mute status of the default sink: 

$ wpctl get-volume @DEFAULT_AUDIO_SINK@
Volume: 0.45
Note: The mute status is only visible when the sink is muted.

Keep Bluetooth running after logout / Headless Bluetooth

By default /usr/share/wireplumber/bluetooth.lua.d/50-bluez-config.lua enables the "logind-monitor" which disables bluetooth whenever the session is terminated.

You have two options to override this: In /etc/wireplumber/ to apply this for a system-instance of wireplumber (or multiple users), or in ~/.config/wireplumber/ for a specific user. If you're unsure, use the one in your home directory. 

$ mkdir -p ~/.config/wireplumber/bluetooth.lua.d/

~/.config/wireplumber/bluetooth.lua.d/50-bluez-config.lua
bluez_monitor.properties = {
  ["with-logind"] = false,
}
Note: You also need to enable lingering for the user running PipeWire/Wireplumber.

See also

Retrieved from "https://wiki.archlinux.org/index.php?title=WirePlumber&oldid=779078"