WirePlumber

WirePlumber 是一个功能强大的 PipeWire 会话和策略管理器。它基于模块化设计，通过实现实际管理功能的 Lua 插件，具有高度的可配置性和可扩展性。

安装

安装 wireplumber 软件包。任何冲突的 PipeWire 会话管理器都将被卸载。

WirePlumber 使用 systemd 用户单元来管理服务器。

配置

配置文件布局

WirePlumber 的配置由全局的 PipeWire 风格 JSON 对象组成，例如 context 和 alsa_monitor，可以通过修改这些对象来改变其行为。配置文件依次从 ~/.config/wireplumber/（用户配置）、/etc/wireplumber/（全局配置）以及 /usr/share/wireplumber/（默认配置）读取。

WirePlumber 启动时首先读取主配置文件。这是一个类 JSON 文件，用于设置 PipeWire 上下文、SPA 插件、模块和组件。

位于 /usr/share/wireplumber/wireplumber.conf 的单实例配置文件是默认配置，它在单个进程中包含了所有其他配置的功能。请参阅关于 ALSA 对象、“access”对象和蓝牙对象的文档。

修改配置

配置 WirePlumber 的推荐方法是在 /etc/wireplumber/ 或 ~/.config/wireplumber/ 的相应 wireplumber.conf.d/ 目录中添加一个 SPA-JSON 文件。

用户配置文件的优先级高于系统文件。名称相同但位于低优先级位置的配置文件将被忽略。在每个配置目录中，单个文件按字母数字顺序打开。详情请参阅文档。

获取用于规则匹配的接口名称

在配置中，您需要使用要配置的接口对象的属性来指定 matches 规则。

使用命令 wpctl status 显示所有由 WirePlumber 管理的对象。找到分配给目标接口的 ID。然后使用命令 wpctl inspect ID 来获取所需的属性。

例如，如果您的目标接口是 HD Audio Controller Analog Stereo，请参考以下输出

$ wpctl status

PipeWire 'pipewire-0' [0.3.56, user@hostname, cookie:1163266174]

Audio
 ├─ Devices:
 │      42. HD Audio Controller                 [alsa]
 │     105. USB PnP Audio Device                [alsa]
 │
 ├─ Sinks:
 │  *   48. HD Audio Controller Analog Stereo   [vol: 0.50]
 │
 ├─ ...
 │
 ├─ Sources:
 │  *  101. USB PnP Audio Device Mono           [vol: 0.74]
 │
 └─ ...

该接口的 ID 为 48。

然后使用 inspect 命令查看对象的详细信息并列出该对象的所有属性

$ wpctl inspect 48

id 48, type PipeWire:Interface:Node
    ...
    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"
    ...
  * 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"
    ...

选择一个唯一且稳定的属性用于 matches 规则。推荐使用 device.name 或 node.name 属性。

避免使用 device.id，因为它是动态的，可能会在不同会话之间发生变化。

支持正则表达式和多属性 matches；详情请参阅官方文档中的 Working with rules 章节。

注

对大多数用户而言最重要的两种对象类型
- Device（设备）对象相当于 ALSA Card（ALSA 声卡）。
- Node（节点）对象相当于 ALSA Device（ALSA 设备）。
PipeWire 虚拟设备的流类由 media.class 属性指示。请参阅 WirePlumber 链接策略介绍中的分类逻辑。
WirePlumber 使用 PCM 名称来填充 node.nick 属性。在使用了 UCM 的 HDA 声卡上，即使它们共享一个配置文件，这也能让不同的输出（模拟、HDMI 等）作为具有描述性昵称的独立 Nodes 呈现。

提示

如果您在寻找接口时遇到困难，可以使用 PipeWire 命令 pw-top 来查看当前活动的 devices 和 nodes 列表。
PipeWire 中类似的检查命令是 pw-cli info ID。

更改设备/节点属性

要更改设备或节点属性（例如其描述或昵称），您必须创建一个 SPA-JSON 文件，并将其添加到 /etc/wireplumber/ 或 ~/.config/wireplumber/ 的正确路径和文件名下。

例如，要更改 ALSA 节点的描述，您可以创建如下文件

/etc/wireplumber/wireplumber.conf.d/device-rename.conf (or ~/.config/wireplumber/wireplumber.conf.d/device-rename.conf)

monitor.alsa.rules = [
  {
    matches = [
      {
        node.name = "alsa_output.pci-0000_00_1f.3.output_analog-stereo"
      }
    ]
    actions = {
      update-props = {
        node.description = "Laptop"
      }
    }
  }
]

如果您想更改蓝牙节点或设备上的内容，可以创建如下文件

/etc/wireplumber/wireplumber.conf.d/bluez-rename.conf (or ~/.config/wireplumber/wireplumber.conf.d/bluez-rename.conf)

monitor.bluez.rules = [
  {
    matches = [
      {
        node.name = "bluez_output.02_11_45_A0_B3_27.a2dp-sink"
      }
    ]
    actions = {
      update-props = {
        node.nick = "Headphones"
      }
    }
  }
]

您可以更改的属性以及选择设备或节点的匹配规则在 ALSA 配置和蓝牙配置中有详细文档。

禁用设备/节点

任何设备或节点都可以通过为设备设置 device.disabled 属性或为节点设置 node.disabled 属性来禁用

/etc/wireplumber/wireplumber.conf.d/alsa-disable.conf (or ~/.config/wireplumber/wireplumber.conf.d/alsa-disable.conf)

monitor.alsa.rules = [
  {
    matches = [
      {
        device.name = "alsa_card.pci-0000_08_00.4"
      }
    ]
    actions = {
      update-props = {
         device.disabled = true
      }
    }
  }
]

按照 #获取用于规则匹配的接口名称找到设备或节点的唯一标识符。在本例中，匹配是基于 device.name 完成的，但也可以基于任何其他标识属性（如 node.nick）完成。

注意请记住，如果您匹配的是节点属性而非设备属性，则必须使用 node.disabled 而不是 device.disabled。

一个常见的用例是禁用显卡的 HDMI 音频输出。这种方法也可以通过使用类似 node.nick 的方式匹配特定节点，从而仅禁用特定显示器的 HDMI 音频，因为这可能会根据插入的设备而变化。

设置节点优先级

要更改自动选择哪个接收端（sink）或源（source），您需要设置其 priority.driver 和 priority.session 值

/etc/wireplumber/wireplumber.conf.d/set-priorities.conf

monitor.alsa.rules = [
  {
    matches = [
      {
        node.name = "alsa_output.usb-Generic_USB_Audio-00.HiFi__Speaker__sink"
      }
    ]
    actions = {
      update-props = {
        priority.driver = 100
        priority.session = 100
      }
    }
  }
]

本例将 Asus B650E-F 主板上板载音频的扬声器输出接收端的优先级设置为 100（从原值 1000 降低）。因此，其他输出接收端（如板载音频设备的 S/PDIF 输出或插入的耳机）由于优先级更高，将被默认选择，而不是模拟扬声器输出。

同时输出到同一声卡上的多个 sink

参阅 PipeWire#同时输出到同一声卡的多个接收端。

同时输出到瞬时设备

您可能希望同时向板载设备和外部设备输出声音——即使外部设备并非一直插入。为了实现这一点，我们创建一个始终存在的虚拟节点，无论插入了什么硬件。然后，在瞬时硬件（本例中为 USB 耳机）插入时，将其链接到该虚拟节点。

首先，创建一个在登录时运行的脚本；这通常通过窗口管理器的“启动/Startup”功能最容易实现。

/usr/local/sbin/create-virtual-sink.sh

#!/bin/bash

# Create a new sink called Simultaneous Output
pw-cli create-node adapter '{ factory.name=support.null-audio-sink node.name="Simultaneous Output" node.description="Simultaneous Output" media.class=Audio/Sink object.linger=true audio.position=[FL FR] }'

# Connect the normal permanent sound card output to the new sink
pw-link "Simultaneous Output:monitor_FL" alsa_output.pci-0000_05_04.0.analog-stereo:playback_FL
pw-link "Simultaneous Output:monitor_FR" alsa_output.pci-0000_05_04.0.analog-stereo:playback_FR

# Switch the default output to the new virtual sink
wpctl set-default `wpctl status | grep "\. Simultaneous Output" | egrep '^ │( )*[0-9]*' -o | cut -c6-55 | egrep -o '[0-9]*'`

在上述示例中，最初唯一的输出设备是我们的“常规”板载声卡 (alsa_output.pci-0000_05_04.0.analog-stereo)。您可以通过运行 wpctl status 和 wpctl inspect 找到您声卡的标识符。

当您的 USB 耳机插入时，运行以下脚本将其链接到虚拟接收端

link-virtual-sink-headphones.sh

#!/bin/bash
# link the virtual sync to your headphones should run when detected by UDEV

# wait a second for the drivers to load
sleep 1s

# link the headphones to your virtual sink
sudo -u user1 env XDG_RUNTIME_DIR=/run/user/1000 pw-link "Simultaneous Output:monitor_FL" alsa_output.usb-Kingston_HyperX_Cloud_Flight_S_000000000001-00.analog-stereo:playback_FL
sudo -u user1 env XDG_RUNTIME_DIR=/run/user/1000 pw-link "Simultaneous Output:monitor_FR" alsa_output.usb-Kingston_HyperX_Cloud_Flight_S_000000000001-00.analog-stereo:playback_FR

# finish and return the code for success
exit 0

理想情况下，您会在耳机插入时自动运行此脚本。udev 页面上的指令描述了如何为此创建自定义规则。（但请注意，您不能直接运行此脚本——因为 udev 在运行任何指定脚本之后才会加载驱动程序。因此，您需要一个中间脚本，并使用 nohup 技巧或类似方法）。您还需要修改上述脚本，使 XDG_RUNTIME_DIR 与您的用户 ID 数字匹配，并且需要将 user1 替换为您的用户名。

您可以以同样的方式将任意数量的设备添加到此虚拟接收端。

如果您在跟踪设备连接情况时遇到困难，qpwgraph 工具非常适合以可视化方式呈现设备之间的连接情况。

技巧与提示

删除损坏的设置

如果 WirePlumber 的设置损坏，可以删除所有用户设置。停止 wireplumber.service 用户单元，并使用以下命令删除设置

$ rm -r ~/.local/state/wireplumber

然后，您可以重新启动 wireplumber.service 用户单元。

键盘音量控制

参阅键盘快捷键#Xorg 以将以下命令绑定到您的音量键：XF86AudioRaiseVolume, XF86AudioLowerVolume, XF86AudioMute 和 XF86AudioMicMute。

调高音量，上限为 150%

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

减小音量

$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-

静音/取消静音音量

$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle

静音/取消静音麦克风

$ wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle

提示要使用默认以外的接收端或源，请运行 wpctl status 列出所有可用接收端，并使用接收端或源的数字代替 @DEFAULT_AUDIO_SINK@ 或 _SOURCE@。

显示音量等级

获取默认接收端的音量等级和静音状态

$ wpctl get-volume @DEFAULT_AUDIO_SINK@

Volume: 0.45

注意只有在接收端静音时，静音状态才可见。

禁用蓝牙配置文件自动切换

参阅 PipeWire#自动配置文件选择。

注销后保持蓝牙运行 / 无头蓝牙

注意您还需要为运行 PipeWire/Wireplumber 的用户启用 lingering（驻留）。

自 0.4.8 版本起，必须禁用 support.logind 要求才能进行 bluez 席位监控（seat-monitoring）。

~/.config/wireplumber/wireplumber.conf.d/disable-logind.conf

wireplumber.profiles = {
  main = {
    monitor.bluez.seat-monitoring = disabled
  }
}

禁用音频栈集成

如果您不希望 PipeWire/Wireplumber 接管您的音频设备（因为您选择了其他音频解决方案，例如 PulseAudio/JACK/ALSA），但仍希望它可用于屏幕共享/视频目的，您可以利用 wireplumber@.service 模板单元来启用一组不同的默认配置文件。Wireplumber 提供了一个配置文件，通过启用 video-only 模板用户单元，仅启用视频部分并禁用音频集成（包括蓝牙音频）。

禁用 wireplumber.service 用户单元并启用 wireplumber@video-only.service 用户单元。

调整当前未播放音频的应用音量

某些应用程序（例如启动器）播放声音的时间太短，无法使用图形界面混音器调整音量。WirePlumber 将每个应用程序和每个节点的音量及静音状态存储在文本文件 $HOME/.local/state/wireplumber/stream-properties 中。可以通过手动编辑此文件来更改这些设置。编辑时请确保 WirePlumber 未在运行，否则它可能会覆盖更改。

故障排除

由于 WirePlumber 仅用于管理 PipeWire 会话，WirePlumber 相关的修复方案可以在 PipeWire#故障排除中找到。

参见

文档 — 官方文档
WirePlumber, the PipeWire session manager — George Kiagiadakis (Collabora) 2020年5月的博客文章，详细介绍了 WirePlumber 的工作原理