PipeWire - Arch Linux 中文维基

跳至內容

# PipeWire

出自 Arch Linux 中文维基
翻譯狀態：

- 本文（或部分內容）譯自 PipeWire，最近一次同步於 2024-02-08，若英文版本有所更改，則您可以幫助同步與翻譯更改的內容。
- 您可以在 ArchWiki 的對應頁面找到本文翻譯的原始修訂歷史。
- 本文可能與英文原文存在出入。

本文或本節需要翻譯。要貢獻翻譯，請訪問簡體中文翻譯團隊。

附註： 請提供模板的第一個位置參數以更詳細的指示。（在 Talk:PipeWire# 中討論）

相關文章

- /Examples
- 音頻系統
- WirePlumber

PipeWire 是一個新的底層多媒體框架。 它旨在以最低的延遲為音頻和視頻提供錄製和播放功能，並支持基於 PulseAudio、JACK、ALSA 和 GStreamer 的應用程式。

基於該框架的守護進程可以配置為音頻伺服器(具有 PulseAudio 和 JACK 特性)和視頻錄製伺服器。

PipeWire 還支持像 Flatpak 這樣的容器，不依賴於 `audio` 和 `video` 用戶組。 相反，它採用了類似於 Polkit的安全模式，向 Flatpak 或 Wayland 請求許可以錄製屏幕或音頻。

## 安裝

可以從官方軟體庫安裝 pipewire包 程序。 也有lib32-pipewire包 的32位庫對於 multilib 進行支持

可以選擇安裝 pipewire-docs包 來查看文檔。

Pipewire 可以作為其他音頻伺服器的直接替代品。更多詳細信息請參見#聲音。

### 會話（Session）管理

像 JACK一樣，PipeWire 內部沒有實現連接邏輯。 監視新 streams 並將其連接到適當的輸出設備或應用程式的負擔留給稱為會話管理器的外部組件。

#### WirePlumber

WirePlumber 是推薦的會話管理器，採用模塊化設計，通過 Lua 插件實現實際管理功能。

默認配置文件位於 `/usr/share/wireplumber`。推薦通過在 `/etc/wireplumber` 或 `~/.config/wireplumber` 中添加片段配置來覆蓋特定設置。[1]

WirePlumber 在 0.5 版本中將配置格式從 `.lua` 改為 `.conf`。遷移指南參見：https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html#config-migration

#### PipeWire Media Session

pipewire-media-session包 已棄用且不再推薦使用，該組件主要作為測試用例和會話管理器開發參考。

### 啟動

Pipewire 使用 systemd/用戶 來管理伺服器，並利用套接字激活在需要時自動啟動。

要在登錄時啟動 PipeWire，請啟用 `pipewire.service`, `pipewire-pulse.service` and `wireplumber.service` user units.

### GUI圖形界面

- Cable — 一款可在運行時動態修改 PipeWire 與 WirePlumber 配置的 PyQt 應用程式

  https://github.com/magillos/Cable || cableAUR

- coppwr — PipeWire 底層控制與診斷工具

  https://github.com/dimtpap/coppwr || coppwrAUR

- Helvum — 基於 GTK 的 PipeWire 接插板工具，靈感源自 JACK 的 catia。不支持連線保存

  https://gitlab.freedesktop.org/pipewire/helvum || helvum包

- qpwgraph — 基於 Qt 的 PipeWire 路由接插板，靈感源自 JACK 的 QjackCtl。支持連線保存

  https://gitlab.freedesktop.org/rncbc/qpwgraph || qpwgraph包

- pwvucontrol — PipeWire 音量控制工具，可作為 pavucontrol 替代品

  https://github.com/saivert/pwvucontrol || pwvucontrolAUR

- sonusmix — PipeWire 音頻路由工具

  https://codeberg.org/sonusmix/sonusmix || sonusmixAUR

### TUI

- pipemixer — 一個使用ncurses構建的、用於PipeWire的TUI音量控制應用程式。

  https://github.com/heather7283/pipemixer || pipemixerAUR

- wiremix — 一個用於PipeWire的簡單TUI音頻混音器。

  https://github.com/tsowell/wiremix || wiremix包

## 配置

PipeWire 軟體包在 `/usr/share/pipewire` 中提供了一組初始配置文件。不應直接編輯這些文件，因為包更新將覆蓋所做的更改。要配置 PipeWire，可以將文件從 `/usr/share/pipewire` 複製到備用系統配置目錄位置 `/etc/pipewire`或用戶目錄 `~/.config/pipewire`。具有較高優先級的目錄中的同名文件會使類似文件被忽略。 [2]

### Profiles

Pipewire 帶來了一個PulseAudio 配置以外的自定義的 "Pro Audio" 配置文件(不要與專業音頻 混淆), 可通過 pavucontrol進行選擇。其效果如下所述：https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#what-is-the-pro-audio-profile

## 用法

### 聲音

PipeWire 可以用作音頻伺服器，類似於 PulseAudio 和 JACK，它旨在通過為JACK客戶端提供PulseAudio兼容的伺服器實現和ABI兼容庫來取代PulseAudio和JACK。有關詳細信息，請參閱博客文章PipeWire Late Summer Update 2020。

首先，安裝 pipewire-audio包。然後根據音頻客戶端的類型，可能還需要執行一些額外的步驟。您可能需要為您的音頻設備安裝額外的固件，請參閱ALSA#固件。

#### ALSA 客戶端

安裝 pipewire-alsa包 (如果安裝了pulseaudio-alsa包需要刪掉它) 以使用 ALSA API 通過 PipeWire 路由所有應用程式。

#### PulseAudio 客戶端

安裝 pipewire-pulse包。它將代替 pulseaudio包 和 pulseaudio-bluetooth包。重新啟動、重新登錄或 start `pipewire-pulse.service` user unit 以查看效果。

通常，不需要進一步的操作，應用應作為用戶服務自動啟用`pipewire-pulse.socket`。要檢查替換是否正常工作，請運行以下命令並查看輸出：

    $ pactl info

    ...
    Server Name: PulseAudio (on PipeWire x.y.z)
    ...
    Default Sink: alsa_output.{bus}device}.{profile}
    Default Source: alsa_input.{bus{device}.{profile}
    ...

pactl(1) 命令由 PulseAudio 客戶端庫（libpulse包）提供，該庫會作為依賴項隨 pipewire-pulse 自動安裝。

##### 調節全局或獨立聲道音量

調節輸出聲道音量時，需通過 `pactl get-sink-volume {sink`} 指定目標設備，可使用： - 上文 Default Sink: 或下文 Name: 的值 - 默認設備占位符 @DEFAULT_SINK@ - 設備編號 Sink #（如下例中的 1）

    $ pactl list sinks | grep -B1 -A9 State:

    Sink #1
            State: RUNNING
            Name: alsa_output.pci-0000_2d_00.4.analog-surround-51
    ...
            Driver: PipeWire
    ...
            Mute: no
            Volume: front-left: 65536 / 100% / 0.00 dB,   front-right: 65536 / 100% / 0.00 dB,   rear-left: 65536 / 100% / 0.00 dB,   rear-right: 65536 / 100% / 0.00 dB,   front-center: 65536 / 100% / 0.00 dB,   lfe: 65536 / 100% / 0.00 dB
                    balance 0.00

提示：若當前有音頻播放，可通過 grep(1) 篩選 RUNNING（運行中）狀態設備，其他設備通常顯示為 SUSPENDED（已掛起）。

balance（聲道平衡）數值會自動計算。設置默認設備的整體音量：

    pactl set-sink-volume @DEFAULT_SINK@ 75%

獨立設置各聲道音量（需提供每個聲道的百分比）：

    pactl set-sink-volume @DEFAULT_SINK@ 100% 75% 100% 75% 100% 100%

Source（輸入設備）的操作方式類似。更多配置（如模塊加載）請參考上游維基： Migration from PulseAudio Pipewire-Pulse Configuration.

#### JACK 客戶端

安裝 pipewire-jack包 以獲取 JACK 支持。還有 lib32-pipewire-jack包 用於 multilib 支持。

pw-jack(1) 可以用來啟動 JACK 客戶端， 但從技術上講它不是必需的， 因為它只用作 `PIPEWIRE_REMOTE`、`PIPEWIRE_DEBUG` 和 `PIPEWIRE_LATENCY` 環境變量的包裝器。

可以通過設置 緩衝區大小/採樣率 的商（等於以秒為單位的塊延遲）來請求自定義緩衝區大小：

    PIPEWIRE_LATENCY="128/48000" application

#### 藍牙設備

如果安裝了 pipewire-pulse包 軟體包，PipeWire 將自動處理藍牙音頻設備。

##### 自動化 profile 切換

pipewire-media-session包 和 WirePlumber 都可以在檢測到輸入流時自動在 HSP/HFP 和 A2DP 配置文件之間切換。

WirePlumber 默認啟用了配置文件自動切換。每當檢測到輸入流時，它可以自動在 HSP/HFP 和 A2DP 配置文件之間切換。可以使用以下命令禁用它：

    $ wpctl settings --save bluetooth.autoswitch-to-headset-profile false

pipewire-media-session包 默認禁用，可以設置 `bluez5.autoswitch-profile` 屬性為 `true` 以啟用：

    /etc/pipewire/media-session.d/bluez-monitor.conf (or ~/.config/pipewire/media-session.d/bluez-monitor.conf)

    ...
    rules = [
        {
            ...
            actions = {
                update-props = {
                    ...
                    bluez5.autoswitch-profile = true
    ...

#### 用於命令行的 PipeWire 補丁集

qpwgraph包 可用於可視化和創建連接，以及保存和加載補丁集。 對於非 GUI 需求，以下是用於保存線集、加載線集和解除所有連接的 bash 腳本。 要保存和加載，請使用命令行參數作為文件名。

    pw-savewires

    #!/bin/bash

    if [[ "$#" -ne 1 ]]; then
    	echo
    	echo 'usage: pw-savewires filename'
    	echo
    	exit 0
    fi

    rm $1 &> /dev/null
    while IFS= read -r line; do
    	link_on=`echo $line | cut -f 4 -d '"'`
    	link_op=`echo $line | cut -f 6 -d '"'`
    	link_in=`echo $line | cut -f 8 -d '"'`
    	link_ip=`echo $line | cut -f 10 -d '"'`
    	echo "Saving: " "'"$link_on:$link_op"','"$link_in:$link_ip"'"
    	echo "'"$link_on:$link_op"','"$link_in:$link_ip"'" >> $1
    done < <(pw-cli dump short link)

    pw-loadwires

    #!/bin/python

    import sys
    import csv
    import os

    if len(sys.argv) < 2:
    	print('\n usage: pw-loadwires filename\n')
    	quit()

    with open(sys.argv[1], newline='') as csvfile:
    	pwwreader = csv.reader(csvfile, delimiter=',', quotechar='"')
    	for row in pwwreader:
    		print('Loading:  ' + row[0] + ' --> ' + row[1])
    		process = os.popen('pw-link ' + row[0] + ' ' + row[1])

    pw-dewire

    #!/bin/bash
    while read -r line; do
    	echo 'Dewiring: ' $line '...'
    	pw-link -d $line
    done < <(pw-cli dump short link {{!}} grep -Eo '^[0-9]+')

#### 與網絡上的計算機共享音頻設備

PipeWire 支持使用多種機制通過網絡共享音頻，包括：

- AES67
- RTP
- Apple Airplay (without DRM features)
- JACK (netjack2)
- Roc
- PipeWire Native RTP
- PulseAudio's network protocol
- Snapcast

PipeWire維基上有一個頁面，概述並比較了不同的網絡協議。

下文將介紹 Pulse Tunnel（Pulse 音頻隧道） 方案。PipeWire 的 PulseAudio 兼容層支持 網絡音頻串流。在網絡上的計算機之間共享音頻的一種簡單方法是使用 Avahi 守護程序進行發現。要啟用此功能，請安裝 pipewire-zeroconf包 軟體包。

確保所有要共享聲音的計算機上的 `avahi-daemon.service` 正在運行（如果使用 firewall，則要保證 UDP 埠 `5353` 已打開）。

注意：某些 GUI 卷管理器默認隱藏網卡。（例如：在 Plasma 中，必須「配置音頻音量...」並選中「顯示虛擬設備」。

要共享本地音頻設備，在主機上加載適當的模塊（確保使用本地 IP 地址）：

    $ pactl load-module module-native-protocol-tcp listen=192.168.1.10
    $ pactl load-module module-zeroconf-publish

然後在客戶端上加載發現模塊：

    $ pactl load-module module-zeroconf-discover

還可以通過創建專用配置文件自動加載模塊。

主機：

    /etc/pipewire/pipewire-pulse.conf.d/50-zeroconf-publish.conf (or ~/.config/pipewire/pipewire-pulse.conf.d/50-zeroconf-publish.conf)

    pulse.cmd = [
        { cmd = "load-module" args = "module-native-protocol-tcp listen=192.168.1.10" }
        { cmd = "load-module" args = "module-zeroconf-publish" }
    ]

客戶端:

    /etc/pipewire/pipewire-pulse.conf.d/50-zeroconf-discover.conf (or ~/.config/pipewire/pipewire-pulse.conf.d/50-zeroconf-discover.conf)

    pulse.cmd = [
        { cmd = "load-module" args = "module-zeroconf-discover" }
    ]

##### 將音頻串流到 AirPlay 接收器

可以將音頻串流到冒充 AirPlay 接收器的設備。 要啟用此功能，請加載 RAOP Discover 模塊：

    $ pactl load-module module-raop-discover

還可以通過創建專用配置文件自動加載此模塊：

    /etc/pipewire/pipewire.conf.d/raop-discover.conf (or ~/.config/pipewire/pipewire.conf.d/raop-discover.conf)

    context.modules = [
       {
           name = libpipewire-module-raop-discover
           args = { }
       }
    ]

某些揚聲器的 AirPlay 實現（例如 Sonos AirPlay 2 揚聲器）可能需要為源設備上的傳入 UDP 流量打開埠 6001 和 6002。

##### 通過 Roc 實現設備間音頻串流

Roc streaming 是一套支持前向糾錯的實時音頻網絡傳輸協議。PipeWire 默認內置對它的支持，配置十分簡便。 首先 安裝 pipewire-roc包 軟體包。

接收端 / 主機 / DAC 配置：

    ~/.config/pipewire/pipewire.conf.d/

    context.modules = [
    { name = libpipewire-module-roc-source
    args = {
    local.ip = 0.0.0.0
    roc.resampler.backend = default
    roc.resampler.profile = default
    roc.latency-tuner.backend = default
    roc.latency-tuner.profile = default
    fec.code = default
    sess.latency.msec = 100
    local.source.port = 10001
    local.repair.port = 10002
    local.control.port = 10003
    }
    }
    ]

更多參數可查閱 PipeWire 官方文檔。

注意： 該方案在搭載新版樹莓派系統的樹莓派音效卡（DAC）上運行效果極佳。

發送端 / 客戶端配置：

    ~/.config/pipewire/pipewire.conf.d/roc-sink.conf

    context.modules = [
    { name = libpipewire-module-roc-sink
    args = {
    fec.code = default
    remote.ip = <主機 IP 地址>
    remote.source.port = 10001
    remote.repair.port = 10002
    remote.control.port = 10003
    sink.props = {
    node.name = "my-roc-sink"
    node.description = "my-roc-sink"
    }
    }
    }
    ]

更多參數可查閱 PipeWire 官方文檔。

注意：`node.description` 用於設置 pulsemixer 顯示的設備名稱；`node.name` 供 pactl 工具讀取。建議兩項均進行配置。

在兩台設備上 重啟 `pipewire.service` 用戶單元。

#### 在本地 JACK 上運行 PipeWire

如果需要，PipeWire 也可以作為 JACK 客戶端在本機 JACK 守護程序之上運行。

請參閱 JACK 和 PipeWire (PipeWire wiki) 和 -JACK#jack-bridge JACK 橋(PipeWire wiki) 了解更多信息和附加配置（例如可用通道）。

要使用它，請安裝 pipewire-jack-client包 並啟動 JACK。Pipewire 應該會被自動橋接。

注意：自從 pipewire 0.3.81版本 加載 jackdbus 模塊是自動完成的，而且不再是必須的。

它可以在啟動 jack 之前像 PulseAudio 模塊一樣手動加載（在pactl(1)解釋）：`pactl load-module module-jackdbus-detect`。

#### 使用 ALSA dmix 設備作為 PipeWire 接收器

可以通過 ALSA dmix devices 將 PipeWire 伺服器（或每個用戶多個）輸出到 ALSA。這允許您使用 ALSA 作為主要音頻輸出系統，同時能夠使用非 ALSA 設備，例如藍牙耳機。

##### ALSA dmix 設置

假設您有兩張卡：`PCH` 和 `HDMI`：

    /proc/asound/cards

     0 [PCH            ]: HDA-Intel - HDA Intel PCH
                          HDA Intel PCH at 0xdff40000 irq 146
     1 [HDMI           ]: HDA-Intel - HDA ATI HDMI
                          HDA ATI HDMI at 0xdfe60000 irq 147

你的 PCM 看起來長這樣：

    /proc/asound/pcm

    00-00: ALC1220 Analog : ALC1220 Analog : playback 1 : capture 1
    00-02: ALC1220 Alt Analog : ALC1220 Alt Analog : capture 1
    01-03: HDMI 0 : HDMI 0 : playback 1
    01-07: HDMI 1 : HDMI 1 : playback 1
    01-08: HDMI 2 : HDMI 2 : playback 1
    01-09: HDMI 3 : HDMI 3 : playback 1
    01-10: HDMI 4 : HDMI 4 : playback 1
    01-11: HDMI 5 : HDMI 5 : playback 1

假設您的 ALSA 配置如下所示：

    /etc/asound.conf

    ctl.!default {
      type hw
      card PCH
    }

    pcm.!default {
      type plug
      slave.pcm "dmix:PCH,0"
    }

    pcm.dhdmi {
      type plug
      slave.pcm "dmix:HDMI,9"
    }

在此特定示例中，dmix 設備為 `dmix:PCH,0` 和 `dmix:HDMI,9`。

##### PipeWire dmix 設置

首先，通過禁用 `monitor.alsa` 來阻止 `wireplumber` 監控和添加硬體 ALSA 設備：

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

    wireplumber.profiles = {
      main = {
        monitor.alsa = disabled
      }
    }

現在，配置 `pipewire` 以使用 dmix 設備。 默認配置文件（`/usr/share/pipewire/pipewire.conf`）包含一個注釋掉了的示例，您可以將其用作模板。

將您自己的元素添加到 `context.objects` 數組中：

    /etc/pipewire/pipewire.conf.d/alsa-dmix.conf (or ~/.config/pipewire/pipewire.conf.d/alsa-dmix.conf)

    context.objects = [
        # We do not start with dmix, but with an input device.
        # Do not forget to add an input device.
        # On a friend's Laptop, I saw Zoom having a nervous
        # breakdown and endlessly crying because no input device
        # was configured! You have been warned.
        { factory = adapter
            args = {
                factory.name           = api.alsa.pcm.source
                node.name              = "alsa-mic-internal" # name of pulse device (mpv)
                node.description       = "Mic Internal" # name of pulse device (pavucontrol)
                media.class            = "Audio/Source"
                api.alsa.path          = "hw:PCH,0"
            }
        }
        # Okay, now we add our dmix PCMs
        { factory = adapter
            args = {
                factory.name           = api.alsa.pcm.sink # sink for dmix
                node.name              = "alsa-dmix-internal" # name of pulse device (mpv)
                node.description       = "PCM Internal" # name of pulse device (pavucontrol)
                media.class            = "Audio/Sink" # Sink for dmix
                api.alsa.path          = "dmix:PCH,0"
            }
        }

        { factory = adapter
            args = {
                factory.name           = api.alsa.pcm.sink # sink for dmix
                node.name              = "alsa-dmix-hdmi" # name of pulse device (mpv)
                node.description       = "PCM HDMI" # name of pulse device (pavucontrol)
                media.class            = "Audio/Sink" # Sink for dmix
                # remember this is a non-default dmix from /etc/asound.conf
                api.alsa.path          = "dmix:HDMI,9"
            }
        }
    ]

作為用戶（非 root），檢查 `wpctl status` 的輸出，並使用`wpctl set-default ID`根據您的喜好設置默認輸入（源）和輸出（接收器）設備。`ID` 是接收器/源名稱之前的數字。

現在，您可以全面測試您的配置。

#### 在設備配置之間切換

某些硬體音頻設備（例如 `snd_hda_intel`）的功能會有所不同，具體取決於設備運行的配置文件。對於 `snd_hda_intel`，HDMI 和模擬輸出有單獨的配置文件。

使用 WirePlumber 切換到 HDMI：

    $ wpctl set-profile <device-ID> 3
    $ wpctl status

    ...
    ├─ Sinks:
    │  *   53. Built-in Audio Digital Stereo (HDMI) [vol: 1.00]
    ...

使用 WirePlumber 切換到模擬：

    $ wpctl set-profile <device-ID> 1
    $ wpctl status

    ...
    ├─ Sinks:
    │  *   51. Built-in Audio Analog Stereo        [vol: 0.60]
    ...

#### 多用戶音頻共享

有時允許其他用戶連接到當前用戶的 PipeWire 實例會很實用。例如，你通過 Xephyr 登錄另一個用戶帳戶，希望 Xephyr 會話內播放的音頻從外部用戶管理的揚聲器輸出。

實現該需求的一種方式是配置外部用戶的 pipewire-pulse，使其監聽本地 TCP 連接。

在外部用戶家目錄下新建如下配置文件：

    ~/.config/pipewire/pipewire-pulse.conf.d/pulse-server.conf

    pulse.properties = {
    server.address = [
    "unix:native"
    "tcp:127.0.0.1:4713" # 此時外部用戶的 pipewire 服務會監聽 IPv4 本地迴環地址
    ]
    }

之後在內層用戶會話中設置環境變量 `PULSE_SERVER=tcp:127.0.0.1:4713`。比如以內層用戶身份啟動 Xephyr 前執行導出該變量。更多說明與其他配置方案可參閱該論壇帖子

### WebRTC 屏幕共享

大多數應用程式過去依賴 X11 來捕獲桌面（或單個應用程式），例如在網絡瀏覽器中使用 WebRTC 時（例如在 Google Hangouts 上）。 在 Wayland 上，屏幕共享機制由 XDG Desktop Portal 配合 PipeWire 實現，能夠通過細粒度的訪問控制在 Wayland 下共享內容

提示：使用以下命令測試 WebRTC 屏幕共享是否正常工作Mozilla 的 GetUserMedia WebRTC 測試頁面.
注意：xdg-desktop-portal包 1.10.0 修復了 D-Bus 接口的規範和實現之間的不匹配問題。[3] 因此，某些客戶端可能無法使用 xdg-desktop-portal 1.10.0 或更高版本。

這需要 xdg-desktop-portal包 及其後端之一被安裝。可用的後端有：

- xdg-desktop-portal-gnome包 對應 GNOME。
- xdg-desktop-portal-kde包 對應 KDE。
- xdg-desktop-portal-wlr包 對應 基於 wlroots 的 Wayland 合成器 (例如 Sway, dwl)

Firefox (84+) 默認支持此方法，而在 Chromium (73+) 上，需要通過設置啟用 WebRTC PipeWire 支持 URL `chrome://flags/#enable-webrtc-pipewire-capturer` 處的相應（實驗）標誌。

obs-studio包 (27+) 通過使用新的 PipeWire 捕獲源支持此方法。

本文或本章節的事實準確性存在爭議。

原因： 自從 該pull request 被合併後，以下有關特定應用程式/窗口共享的注釋在xdg-desktop-portal-gtk包上可能不再正確。另請參閱跟蹤此討論的情況：[4].（在 Talk:PipeWire 中討論）

請注意，唯一支持的功能是共享整個桌面，而不是特定的應用程式/窗口 -individual-windows[5]。

#### xdg-desktop-portal-wlr

為了使 `xdg-desktop-portal-wlr` 正常工作，必須在 systemd用戶會話 中設置 `XDG_CURRENT_DESKTOP` 和 `WAYLAND_DISPLAY` 環境變量。`XDG_CURRENT_DESKTOP` 必須設置為您的合成器的名稱，例如 `XDG_CURRENT_DESKTOP=sway`。`WAYLAND_DISPLAY` 由合成器自動設置。將這些環境變量引入 systemd 用戶會話的推薦方法是在啟動合成器後運行 `systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP`，例如使用合成器配置文件。有關更多詳細信息，請參閱 [6] 和 [7]。

提示：如果您有多個監視器，要選擇與 `xdg-desktop-portal-wlr` 共享監視器，請安裝 slurp包 並添加以下配置（請參閱 xdg-desktop-portal-wlr(5) § 屏幕播放选项):

    ~/.config/xdg-desktop-portal-wlr/config

    chooser_type = simple
    chooser_cmd = slurp -f %o -ro

當請求共享屏幕時，`slurp` 會向您顯示十字光標，您需要單擊要共享的屏幕。選擇後，`xdg-desktop-portal-wlr` 將允許共享該屏幕。

### 視頻

這篇文章的某些內容需要擴充。

原因：pipewire-v4l2包 (在 Talk:PipeWire 中討論)

儘管該軟體尚未準備好投入生產，但可以安全地使用。大多數依賴 GStreamer 處理視頻流的應用程式應該使用 PipeWire GStreamer 插件開箱即用，請參閱 GStreamer#PipeWire。因此，像 cheese包 這樣的應用程式已經能夠使用它來共享視頻輸入。

使用 pipewire-v4l2包，還應該可以使用 `pw-v4l2` 腳本來預加載庫 (`/lib/pipewire-0.3/v4l2/libpw-v4l2 .so`）攔截 v4l2 調用並通過管道路由視頻。

## 音頻後期處理

### Pipewire 模塊過濾鏈（module-filter-chain）

Pipewire 有一個名為過濾鏈（filter-chain）的內部模塊，可以創建節點來處理音頻輸入和輸出。有關均衡、虛擬環繞聲、LADSPA 插件和通道混合的示例，請參閱 `/usr/share/pipewire/filter-chain/`。

#### 全系統參數均衡

將配置文件複製到您的 `.config` 文件夾：

    $ mkdir -p ~/.config/pipewire/pipewire.conf.d
    $ cp /usr/share/pipewire/filter-chain/sink-eq6.conf ~/.config/pipewire/pipewire.conf.d/

然後編輯 `sink-eq6.conf` 以合併所需的參數。對於耳機，可以從 Oratory1990 的資料庫獲取，或者，如果沒有列出，則參考 AutoEQ 項目。

如果您需要前置放大器，請修改 `eq_band_1` 以在頻率 0Hz 處應用具有負增益的 `bq_highshelf` 濾波器（支持 -120 至 +20dB 的增益）：

    label = bq_highshelf
    control = { "Freq" = 0 "Q" = 1.0 "Gain" = -7.5 }

對於超過 6 個頻段，請向 `nodes` 列表和相應的 `links` 添加更多條目，將一個過濾器「:Out」連接到下一個過濾器「:In」，例如增加到 11頻段（前置放大器 + 10）：

                        { output = "eq_band_6:Out" input = "eq_band_7:In" }
                        { output = "eq_band_7:Out" input = "eq_band_8:In" }
                        { output = "eq_band_8:Out" input = "eq_band_9:In" }
                        { output = "eq_band_9:Out" input = "eq_band_10:In" }
                        { output = "eq_band_10:Out" input = "eq_band_11:In" }

重新啟動Pipewire，選擇「Equalizer Sink」作為默認聲音輸出設備； 這應該適用於所有應用程式。

### EasyEffects

EasyEffects（以前的 PulseEffects）是一個 GTK 實用程序，它為各個應用程式輸出流和麥克風輸入流提供大量音頻效果和濾波器。值得注意的效果包括輸入/​​輸出均衡器、輸出響度均衡和低音增強、輸入嘶聲消除器和降噪插件。有關效果的完整列表，請參閱 GitHub 頁面。

為了使用 EasyEffects，請安裝 easyeffects包。有關預設配置的集合，請參閱社區預設。對於算法生成的耳機 EQ 預設的集合，請參閱 AutoEq。

注意：對於 PulseEffects 舊版本，請參閱 PulseAudio#PulseEffects.

### NoiseTorch

NoiseTorch 是一種噪聲抑制的替代方法，與 noisetorchAUR 打包在一起。另外還有-git版本noisetorch-gitAUR。

啟動後，可以為所選麥克風加載模塊。可以調整語音激活閾值，應將其設置為最高級別，而不是過濾掉任何實際語音。

您可以使用 systemd 自動啟動音頻處理，請參閱 [8]。請注意，如果從 AUR 安裝，noisetorch 二進制路徑會有所不同。

### 語音噪聲抑制

安裝 noise-suppression-for-voice包 並進行下列操作之一：

- 在 `context.exec` 添加以下內容：

    /etc/pipewire/pipewire.conf (or ~/.config/pipewire/pipewire.conf)

    ...
    context.exec = [
        ...
        { path = "/usr/bin/pipewire" args = "-c /usr/share/pipewire/filter-chain/source-rnnoise.conf" }
        ...

- 參照 https://github.com/werman/noise-suppression-for-voice#pipewire.

然後將降噪後的音頻源作為音頻的默認選項。您可能需要先重啟應用才能使用新的音頻源。

### JamesDSP

JamesDSP for Linux (jamesdspAUR) 為 PipeWire 和 PulseAudio 提供開源的音效實現。JamesDSP 使用自己的效果引擎，不依賴 LADSPA 或是 Calf 之類的東西。起初它被用於安卓設備的音效處理。

### LADSPA, LV2 和 VST 插件

本文或本章節的事實準確性存在爭議。

原因： Does this section relate to using the pulseaudio daemon or the pipewire's interface for pulseaudio clients?（在 Talk:PipeWire 中討論）

您可以創建將 PulseAudio 連接到 Carla 音頻插件的輸入/輸出目標位置。

如果您想在所有可用的 LADSPA、LV2 和 VST 中選擇的話，可以使用自定義的 Pulseaudio null sink 和 Carla Jack 來應用這些插件。安裝 pipewire-pulse包、pipewire-jack包 和 carla包。首先，創建一個名為 `default_null_sink` 的 PulseAudio null sink。 .

    pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=default_null_sink channel_map=FL,FR

從 Pipewire 啟動 Carla：`pw-jack carla-rack`。在 Rack(機架) 頁面添加您想使用的插件，確保它們的類型都是 stereo(立體聲)。您可以改變插件間的順序，處理順序由上至下（最上面的會最先接收到音頻流），就跟 EasyEffects 一樣。隨後，在 Patchbay(跳線槽) 頁面將 `default_null_sink` 的左右監聽(L/R monitor)連接到 Carla 的輸入，然後將 Carla 的輸出連接到回放設備(音響、耳機、HDMI...)。將配置文件保存到一個本地位置，比如 `~/Documents/carla_sink_effects.carxp`。

您可以在多媒體應用發聲的時候測試這些效果，比如用 Firefox 看視頻。有兩種測試方式。第一種：在 Carla 的 Patchbay，斷開 Firefox 的所有連線，然後把它的左右聲道輸出連接到 `default_null_sink` 的 playback。第二種：使用 pavucontrol包 找到 Firefox 的音頻流，然後將其重定向到 `default_null_sink`（這應該會記住連接方式，在下次啟動的時候自動重定向）。

若想在啟動時應用這些設置，創建兩個 systemd 用戶服務：

    ~/.config/systemd/user/jack-carla-rack.service

    [Unit]
    Description=Load Carla Rack JACK host

    [Service]
    PassEnvironment="PIPEWIRE_LINK_PASSIVE=true"
    Type=exec
    ExecStart=/usr/bin/pw-jack carla-rack -n

    [Install]
    WantedBy=default.target

    ~/.config/systemd/user/pulseaudio-null-sink@.service

    [Unit]
    Description=Load %i Pulseaudio null sink
    Before=jack-carla-rack.service
    After=pipewire-pulse.service

    [Service]
    Type=oneshot
    ExecStart=/usr/bin/pactl load-module module-null-sink object.linger=1 media.class=Audio/Sink sink_name=%i channel_map=FL,FR
    ExecStop=/usr/bin/pactl unload-module module-null-sink
    RemainAfterExit=yes

    [Install]
    WantedBy=default.target

然後覆蓋 jack-carla-rack 服務，並在 Environment 部分寫明 Carla 配置的完整路徑。

    ~/.config/systemd/user/jack-carla-rack.service.d/override.conf

    [Service]
    Environment="CARLA_CONFIG_FILE=/home/username/Documents/carla_sink_effects.carxp"
    ExecStart=
    ExecStart=/usr/bin/pw-jack carla-rack -n $CARLA_CONFIG_FILE

最後，啟用 `pulseaudio-null-sink@default_null_sink.service` 和 `jack-carla-rack.service` 用戶單元。

注意，如果你將 `default_null_sink` 設置為了系統默認設備，所有的應用聲音都會被重定向至它，並且音量鍵也會改變它的音量而不是回放設備的。如果想控制回放設備的音量，需要把回放設備設成默認設備，然後將所需應用在 pavucontrol 裡重定向到 `default_null_sink`（PipeWire兼容層應該會記住應用的連接關係）。

## 故障排除

### 音頻

#### PipeWire 檢測不到麥克風

PipeWire 的 `alsa-monitor` 模塊默認使用 alsa-card-profiles包 檢測設備。若失效，可嘗試在 wireplumber包 中關閉 `api.alsa.use-acp` 或啟用 `api.alsa.use-ucm`：

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

    monitor.alsa.properties = {
      # 使用ALSA卡配置文件設備。它們通過UCM或配置集。
      # 來配置設備和混音器設置。
      # alsa.use-acp = true
      # 優先使用UCM配置（若可用）。可禁用此項。
      # 以跳過嘗試使用UCM配置。
      alsa.use-ucm = true
    }

如果使用的是 pipewire-media-session包:

    /etc/pipewire/media-session.d/alsa-monitor.conf (or ~/.config/pipewire/media-session.d/alsa-monitor.conf)

    ...
    rules = [
        {
            ...
            actions = {
            update-props = {
                ...
                api.alsa.use-acp = false
    ...

然後重啟 WirePlumber 並檢查可用設備：

本文或本節內容已經過時。

原因： `--list-targets` 選項在新版的 `pw-record` 中已不可用，若想列出項目請使用 `wpctl status`、`pw-cli ls` 或是 `pw-dump`。 (在Talk:PipeWire討論)

    $ pw-record --list-targets

    Available targets ("*" denotes default): 62
    	58: description="Built-in Audio" prio=1872
    	60: description="Built-in Audio" prio=2000
    *	62: description="Built-in Audio (Loopback PCM)" prio=1984

在這個 issue 中提到的另一種解決方案是手動添加麥克風。首先，確保麥克風能被 ALSA 檢測到。

    $ arecord -l

    **** List of CAPTURE Hardware Devices ****
    card card_number: card_name, device device_number: device_name
      ...

從列表裡選擇你的麥克風，運行以下命令以測試麥克風。

    $ arecord --duration=5 --format=dat --device=hw:card_number,device_number test-mic.wav # record from the mic
    $ aplay test-mic.wav # play it

如果 arecode 測試麥克風工作正常但是卻沒被 PipeWire 檢測到，試著通過配置文件手動添加這一設備。

    /etc/pipewire/pipewire.conf.d/microphone.conf (or ~/.config/pipewire/pipewire.conf.d/microphone.conf)

    context.objects = [
        { factory = adapter
            args = {
                factory.name           = api.alsa.pcm.source
                node.name              = "microphone"
                node.description       = "Undetected Microphone"
                media.class            = "Audio/Source"
                api.alsa.path          = "hw:card_number,device_number"
            }
        }
    ]

重啟 PipeWire 來重載配置。

#### 連接新設備時聲音不會自動切換

要實現自動切換到新連接的設備，請創建以下文件：

    /etc/pipewire/pipewire-pulse.conf.d/switch-on-connect.conf (或 ~/.config/pipewire/pipewire-pulse.conf.d/switch-on-connect.conf)

    pulse.cmd = [
        { cmd = "load-module" args = "module-switch-on-connect" }
    ]

然後使用 systemctl --user 重啟 `pipewire-pulse.service` 服務，並檢查 `module-switch-on-connect` 模塊是否已加載。

#### 連接到藍牙設備後沒有聲音

截至 2020-12-07，如果連接上藍牙設備卻沒有聲音，您可能需要切換默認輸出設備(sink)與/或是將 sink 輸入移動到正確的 sink 位置。使用 `pactl list sinks` 列出所有可用的 sink 並通過 `pactl set-default-sink` 將默認 sink 切換為藍牙設備。這可以使用類似這樣的腳本通過 udev 自動化。

參見這個 Reddit 討論串關於這一問題的探討。根據腳本作者所言，耳機配置(the headset profile，HSP)可能仍有問題。

#### mpv/vlc/totem 無聲音但瀏覽器和GNOME揚聲器測試正常

本文或本章節的事實準確性存在爭議。

原因： 當前行文風格不符合Wiki規範，更類似博客文章。需要重新措辭並精簡內容。子章節劃分過度，且問題原因未經證實僅為推測。（在 Talk:PipeWire 中討論）

##### 問題現象描述

驗證此問題的最佳方式是使用 `mpv` 測試已安裝編解碼器支持的視頻文件：

    $ mpv --ao=alsa 测试文件.mpv
    $ mpv --ao=pcm 测试文件.mpv
    $ mpv --ao=jack 测试文件.mpv
    $ mpv --ao=pulse 测试文件.mpv
    $ mpv --ao=openal 测试文件.mpv

若上述部分或全部測試能正常發聲，但使用 `pipewire` 選項時無聲：

    $ mpv --ao=pipewire 测试文件.mpv

則適用本解決方案。GNOME 桌面揚聲器測試和瀏覽器播放 YouTube 能正常發聲。

在 GNOME 中切換輸入、靜音/取消靜音、調節音量均無法解決問題。

`pactl list sinks` 顯示為 'SUSPENDED' 可忽略，因瀏覽器播放視頻時狀態會正常變化。

使用 `pactl info` 未發現明顯問題。

檢查相關 `systemd` 單元日誌也未發現明顯異常。

##### 問題原因

疑似 PipeWire 到硬體的音頻路徑被靜音，原作者無法通過命令行工具具體定位該問題。

##### 解決方案

安裝 pavucontrol包 軟體包。運行 `pavucontrol`，選擇相應音源，在 `mpv --ao=pipewire test.mp4` 播放時切換靜音按鈕狀態。

#### 音量過低

將 PulseAudio 替換為 PipeWire 後，聲音可能正常工作，但重啟後音量會變得異常低。

打開 `alsamixer`，使用 `F6` 選擇正確的音效卡，並確保 ALSA 音量設置為 100%。`alsactl` 會在重啟後保持此設置。

#### 提升 RLIMIT_MEMLOCK

    Dec 13 11:11:11 HOST pipewire-pulse[99999]: Failed to mlock memory 0x7f4f659d8000 32832: This is not a problem but for best performance, consider increasing RLIMIT_MEMLOCK

安裝 realtime-privileges包 並且將您的用戶加入 `realtime` 組。

此外，將 memlock 從 64kB 提升至 128kB 似乎足以解決問題。如果你是在 systemd/User 下使用 `pipewire-pulse`，向 `/etc/security/limits.d/username.conf` 添加：

    username	soft	memlock	64
    username	hard	memlock	128

#### 修改默認採樣率

默認 PipeWire 使用 48kHz 的全局採樣率。如果您想更改此值（比如您有個支持更高採樣率的 DAC），則可以設置一個更高的默認值：

    /etc/pipewire/pipewire.conf (or ~/.config/pipewire/pipewire.conf)

    ...
    context.properties = {
        ...
        default.clock.rate          = sample_rate
        ...

#### 修改允許的採樣率

只要 DAC 支持，PipeWire 可以動態更改採樣率。所選的採樣率會跟隨當前正在播放的音頻流。

    /etc/pipewire/pipewire.conf (or ~/.config/pipewire/pipewire.conf)

    ...
    context.properties = {
        ...
        default.clock.allowed-rates = [ sample_rate_1 sample_rate_2 sample_rate_3 ... ]
        ...

舉個例子： `[ 44100 48000 88200 96000 ]`.

據開發者所言，「PipeWire 支持至多 16 種不同的採樣率，並且會在允許的時候進行切換」。也就是說，在受支持的設備按照以上內容配置不會發生重採樣。在 PipeWire 0.3.61 之後，最多可以配置 32 種不同的採樣率。

##### 獲取支持的採樣率

請參照您 DAC 的硬體手冊來查看受支持的採樣率。內核驅動編碼器支持的採樣率可以通過以下命令查看：

    $ grep -E 'Codec|Audio Output|rates' /proc/asound/card*/codec#*

如果您的DAC沒有報告編解碼器信息，可以嘗試這樣獲取支持的採樣率：

    $ grep -m1 -Hn "" /proc/asound/card?/stream? | tee /dev/tty | awk -F':' '{print $1}' | xargs grep 'Rates'

注意：雖然您的DAC晶片可能報告比規格書更高的採樣率，但其中一些是為特殊模式(如USB轉I2S)設計的

##### 檢查當前使用的採樣率

要想查看當前某音效卡配置的採樣率，請運行：

    $ grep rate: /proc/asound/card?/pcm??/sub?/hw_params

    /proc/asound/card1/pcm0p/sub0/hw_params:rate: 96000 (96000/1)

在 `pcm0p` 和 `pcm0c` 中，`c` 指的是"錄製設備（capture）"而 `p`指的是"回放設備（playback）"。

命令：

    $ pw-top

也可以顯示每個音效卡和音頻流當前使用的採樣率。

提示：如果在設置default.clock.allowed-rates後DAC仍無法切換到更高採樣率，可能意味著系統無法讀取DAC支持的採樣率。這種情況下您仍可以嘗試設置default.clock.rate

#### 音質 (重採樣質量)

如果之前使用 PulseAudio 時用了 `resample-method = speex-float-10` 或是 `soxr-vhq`，可考慮將 `resample.quality` 設為 `10` 或最大值 `14`：

    /etc/pipewire/client.conf.d/resample.conf (或 ~/.config/pipewire/client.conf.d/resample.conf)

    stream.properties = {
        resample.quality = 10
    }

不要忘記重啟 `pipewire.service` 和 `pipewire-pulse.socket` 這兩個用戶單元(如果想要應用配置千萬不能把後者忘了)。

在 `10` 與 `14` 之間音質差距很小，但是 CPU 負載會差兩到三倍。同時，`4`、`10` 與 `14` 對延遲影響的差距還有待探索。在Ryzen 2600上使用 `resample.quality = 14` 進行44100→48000Hz重採樣時，`pipewire` 或 `pipewire-pulse` 進程會占用單核4%的CPU資源。

您可以在 https://src.infinitewave.ca/ 比較重採樣器(不要關注任何超過 18KHz，超過 120dB 的內容)。speex 被列為 "Xiph.org Speex"。

PipeWire 使用它自己的被稱為 Spa 的重採樣算法。與 SoX 的 `sox` 和 Speex 的 `speexenc` 一樣，PipeWire 同樣有這個重採樣器的單獨版本 `spa-resample`。使用方法如下：

    $ spa-resample -q 14 -f s24 -r 48000 输入文件16bit44100或其他格式.wav 输出文件24bit48000hz.wav

通過創建自己的 sink 並且使用其他重採樣器應該是可能的。或者你也可以使用音樂播放器的插件，比如 Qmmp 就有個 SoX 插件。

#### 外部音效卡在重連後不會激活

檢查 `~/.config/pipewire/media-session.d/default-profile` 看看有沒有默認配置是 "off" 的條目並將其移除。如果不管用，移除 `~/.config/pipewire/media-session.d/` 中的所有文件並重啟 `pipewire.service` 用戶單元。

#### 沒有聲音或 pactl info shows 執行失敗：Connection refused

這意味著應用程式無法連接到 PipeWire-Pulse 服務，請檢查 `pipewire-pulse.service` 用戶單元是否正在運行。

如果問題仍未解決，請運行 `strace -f -o /tmp/pipe.txt pactl info`，然後在 IRC（OFTC 網絡的 #pipewire 頻道）或郵件列表尋求幫助時附上 `/tmp/pipe.txt` 文件內容。

#### 藍牙音質低

若藍牙播放出現卡頓，檢查 `pipewire.service` 的 unit status，看看有沒有類似以下的錯誤：

    Feb 17 18:23:01 HOST pipewire[249297]: (bluez_input.18:54:CF:04:00:56.a2dp-sink-60) client too slow! rate:512/48000 pos:370688 status:triggered

如果出現此類錯誤，使用 `pactl list sinks` 檢查當前所選編碼器，試著把 `bluez5.codecs` 修改為 `sbc aac ldac aptx aptx_hd` 其中之一。你也可以嘗試 mSBC 支持（修復了 Sony 1000XM3 系列，比如 WH-1000XM3 和 WF-1000XM3 的麥克風）以及 SBC-XQ 編碼：

注意：像 WH-1000XM3 這樣的耳機，如果在配套應用中設置"音質模式"為"穩定連接優先"而非"音質優先"，將僅會通告 SBC/SBC-XQ 編解碼器。

在 wireplumber包 下：

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

    monitor.bluez.properties = {
      bluez5.enable-sbc-xq = true
      bluez5.enable-msbc = true
      bluez5.codecs = [ sbc sbc_xq ]
    }

使用 pipewire-media-session包 時：

    /etc/pipewire/media-session.d/bluez-monitor.conf (or ~/.config/pipewire/media-session.d/bluez-monitor.conf)

    ...
    properties = {
      ...
      bluez5.enable-msbc = true
      bluez5.enable-sbc-xq = true
      bluez5.codecs = [sbc sbc_xq]
    ...

重啟 `pipewire.service` 用戶單元來使修改生效。

#### 在播放時有可覺察的音頻延遲或是爆裂聲

這是由不活躍時的節點暫停（node suspension）造成的。

在 pipewire-media-session包 下:

創建以下配置文件覆蓋默認設置：

    /etc/wireplumber/wireplumber.conf.d/51-disable-suspension.conf (或 ~/.config/wireplumber/wireplumber.conf.d/51-disable-suspension.conf)

    monitor.alsa.rules = [
      {
        matches = [
          {
            # 匹配所有輸入設備
            node.name = "~alsa_input.*"
          },
          {
            # 匹配所有輸出設備
            node.name = "~alsa_output.*"
          }
        ]
        actions = {
          update-props = {
            session.suspend-timeout-seconds = 0
          }
        }
      }
    ]

    # 對於藍牙設備
    monitor.bluez.rules = [
      {
        matches = [
          {
            # 匹配所有藍牙輸入
            node.name = "~bluez_input.*"
          },
          {
            # 匹配所有藍牙輸出
            node.name = "~bluez_output.*"
          }
        ]
        actions = {
          update-props = {
            session.suspend-timeout-seconds = 0
          }
        }
      }
    ]

重啟 `pipewire.service` 和 `wireplumber.service` 以應用更改。

除了完全禁用節點暫停，您也可以設置掛起超時時間（單位為秒）。

部分設備會自行檢測靜音狀態並掛起。對此類設備僅禁用節點暫停可能無效，可通過添加微量噪聲使設備永不靜音：

    .../51-disable-suspension.conf

    ...
        session.suspend-timeout-seconds = 0,  # 0表示禁用掛起
        dither.method = "wannamaker3", # 添加指定類型的抖動
        dither.noise = 2, # 添加額外噪聲位
    ...

可能需要調整 `dither.noise` 和 `dither.method` 參數，使噪聲既足夠微弱又能防止靜音檢測。詳見 PipeWire documentation。

在 pipewire-media-session包 下：

編輯 `/etc/pipewire/media-session.d/*-monitor.conf` 文件（根據延遲出現的設備類型），將 `session.suspend-timeout-seconds` 屬性設為 0 禁用暫停，或嘗試其他值。

或者注釋掉 `/etc/pipewire/media-session.d/media-session.conf` 中的 `suspend-node` 行。

重啟 `pipewire.service` 和 `pipewire-pulse.service` 以應用更改，或直接重啟系統。

#### 多個流同時播放時音頻被切斷

此問題通常可以通過閱讀 `pipewire-pulse.service` 用戶單元的 journal 檢測出來。您會看到類似以下內容：

    pipewire-pulse[21740]: pulse-server 0x56009b9d5de0: [Nightly] UNDERFLOW channel:0 offset:370676 underrun:940

根據官方 PipeWire 除錯指南，在 wireplumber包 下的解決方案：

    /etc/wireplumber/wireplumber.conf.d/50-alsa-config.conf (或 ~/.config/wireplumber/wireplumber.conf.d/50-alsa-config.conf)

    monitor.alsa.rules = [
      {
        matches = [
          {
            node.name = "~alsa_output.*"
          }
        ]
        actions = {
          update-props = {
            api.alsa.period-size   = 1024    # 周期緩衝區大小
            api.alsa.headroom      = 8192    # 預留緩衝空間
          }
        }
      }
    ]

在 pipewire-media-session包 下：

    /etc/pipewire/media-session.d/alsa-monitor.conf (或 ~/.config/pipewire/media-session.d/alsa-monitor.conf

    api.alsa.headroom = 1024    # 緩衝空間設置

如果您經歷了由內核頁鎖定（page locking）與延遲調度（late scheduling）導致的音頻卡頓，請參考遊戲#調整內核參數以實現響應時間一致性。

#### 音頻失真

- 對於麥克風，試著運行 `alsamixer` 並切換到有問題的音效卡，然後使用方向鍵降低所有 "Mic Boost" 與 "Internal Mic Boost" 選項，For microphones,
- 參照#修改默認採樣率將採樣率降至 `44100` (44.1 kHz)。

#### 在待機後出現音頻問題

如果將機器從睡眠中喚醒後音頻出現缺失或是其他狀況，重新初始化 ALSA 可能有幫助：

    # alsactl init

#### USB DAC 延遲高 (比如 Schiit DACs)

修改採樣率可能有助於某些 DAC 的延遲，例如 Schiit Hel 2。[9] 使用 pipewire-media-session 的匹配規則，我們可以為設備設置屬性。[10]

將默認的配置文件 `/usr/share/pipewire/media-session.d/alsa-monitor.conf` 複製到 `/etc/pipewire/media-session.d/` 或是 `~/.config/pipewire/media-session.d/`。 隨後添加一各新的規則塊，類似下面這個：

    /etc/pipewire/media-session.d/alsa-monitor.conf (or ~/.config/pipewire/media-session.d/alsa-monitor.conf)

    ...
    rules = {
        ...
        {
            matches = [
                {
                    node.name = "alsa_output.name-of-node"
                }
            ]
            actions = {
                update-props = {
                    audio.format = "S24_3LE"
                    audio.rate = 96000
                    # Following value should be doubled until audio does not cut out or other issues stop occurring
                    api.alsa.period-size = 128
    ...

在 wireplumber包 上：

    /etc/wireplumber/wireplumber.conf.d/52-update-rate-and-format.conf (或 ~/.config/wireplumber/wireplumber.conf.d/52-update-rate-and-format.conf)

    monitor.alsa.rules = [
      {
        matches = [
          {
            node.name = "alsa_output.設備節點名稱"
          }
        ]
        actions = {
          update-props = {
            audio.format = "S24_3LE"          # 24位小端格式
            audio.rate = 96000                # 96kHz採樣率
            # 此數值應逐步加倍直至解決斷音問題
            api.alsa.period-size = 128        # 周期緩衝區大小
          }
        }
      }
    ]

`alsa_output.name-of-node` 中的 node 可以使用 `pw-top` 獲得。

你的 DAC 可能支持不同的格式或是採樣率，通過查詢 ALSA 您可以得知 DAC 支持什麼：

首先獲取 DAC 的音效卡號：

    $ aplay -l

    ...
    card 3: S2 [Schiit Hel 2], device 0: USB Audio [USB Audio]
      Subdevices: 0/1
      Subdevice #0: subdevice #0
    ...

在這個例子中是 card 3。 然後獲取所有受支持的採樣率與格式：

    $ cat /proc/asound/cardX/streamX

    ...
    Playback:
      ...
      Interface 1
        Altset 1
        Format: S16_LE
        Channels: 2
        Endpoint: 0x05 (5 OUT) (ASYNC)
        Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000
        Data packet interval: 125 us
        Bits: 16
        ...
      Interface 1
        Altset 2
        Format: S24_3LE
        Channels: 2
        Endpoint: 0x05 (5 OUT) (ASYNC)
        Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000
        Data packet interval: 125 us
        Bits: 24
        ...
      Interface 1
        Altset 3
        Format: S32_LE
        Channels: 2
        Endpoint: 0x05 (5 OUT) (ASYNC)
        Rates: 44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000
        Data packet interval: 125 us
        Bits: 32
        ...
    ...

上述輸出表明 `S16_LE, S24_3LE, S32_LE` 是受支持的格式，`44100, 48000, 88200, 96000, 176400, 192000, 352800, 384000` 是所有格式都支持的採樣率。

#### 將音量升至 30% USB DAC 才出聲

這篇文章的某些內容需要擴充。

原因：添加 pipewire-media-session包 相關指示 (在 Talk:PipeWire 中討論)

某些 USB DAC 在音量達到一定值前不會有輸出 [11]。通常這個值是 25% - 30%，而此時多半聲音已經過響，還沒法調小。解決方法是忽略硬體混音器的音量控制：將 `["api.alsa.soft-mixer"]` 設為 `true`。

在 wireplumber包 下：

    /etc/wireplumber/wireplumber.conf.d/alsa-soft-mixer.conf (或 ~/.config/wireplumber/wireplumber.conf.d/alsa-soft-mixer.conf)

    monitor.alsa.rules = [
      {
        matches = [
          {
            device.name = "~alsa_card.*"  # 匹配所有ALSA音效卡
          }
        ]
        actions = {
          update-props = {
            # 禁用硬體混音器音量控制，僅使用軟體音量調節。
            # 混音器仍會根據所選埠靜音未使用通路。
            api.alsa.soft-mixer = true
          }
        }
      }
    ]

然後重啟 pipewire。將 `alsamixer` 的主音量設定好，隨後使用root權限運行 `# alsactl store` 保存設置。您現在應該可以正常使用音量調節了。

#### 實時音頻不起作用

如果 `pipewire.service` 用戶單元的 status 出現了 `RTKit error: org.freedesktop.DBus.Error.AccessDenied`，這意味著 pipewire 守護進程的優先級不是實時。對於此問題，參見 [12]。

#### 同時輸出到同一音效卡的多個 sink

複製一份 `/usr/share/alsa-card-profile/mixer/profile-sets/default.conf` 便於更改跨版本更新持久化。以下是一個將模擬輸出和 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

接著，配置 PipeWire 的 media-session，對匹配設備使用新的音效卡配置。識別音效卡信息可以使用 `$ pw-cli dump device`。

在 wireplumber包 上：

    /etc/wireplumber/wireplumber.conf.d/51-alsa-custom.conf (或 ~/.config/wireplumber/wireplumber.conf.d/51-alsa-custom.conf)

    monitor.alsa.rules = [
      {
        matches = [
          {
            device.nick = "HDA Intel PCH"  # 匹配Intel板載音效卡
          }
        ]
        actions = {
          update-props = {
            api.alsa.use-acp = true        # 啟用ALSA卡配置文件
            api.acp.auto-profile = false   # 禁用自動配置集切換
            api.acp.auto-port = false      # 禁用自動埠切換
            device.profile-set = "multiple.conf"  # 指定配置集文件
            device.profile = "multiple"    # 使用多路輸出配置
          }
        }
      }
    ]

在 pipewire-media-session包 上：

    /etc/pipewire/media-session.d/alsa-monitor.conf (或 ~/.config/pipewire/media-session.d/alsa-monitor.conf)

    rules = [
        {
            matches = [ { alsa.card_name = "HDA Intel PCH" } ]  # 匹配Intel板載音效卡
            actions = {
                update-props = {
                    api.alsa.use-acp = true
                    device.profile-set = "multiple.conf"
                    device.profile = "multiple"
                    api.acp.auto-profile = false
                    api.acp.auto-port = false
                }
            }
        }
    ]

#### Discord 沒有提示音

這可能是由於 min.quantum 設置得過低，嘗試將其修改到 700 以上。您可以為 Discord 專門寫一個覆蓋用的配置，只需在 pipewire-pulse.conf 的 pulse.rules 部分添加如下規則：

    /etc/pipewire/pipewire-pulse.conf (or ~/.config/pipewire/pipewire-pulse.conf)

    ...
    pulse.rules = [
      ...
        {
            # Discord notification sounds fix
            matches = [ { application.process.binary = "Discord" } ]
            actions = {
                update-props = {
                    pulse.min.quantum      = 1024/48000     # 21ms
                }
            }
        }
    ...

#### FMOD 遊戲在 PipeWire 下崩潰

某些使用舊版 FMOD 音頻引擎的遊戲（譬如 Pillars of Eternity）會運行 `pulseaudio --check` 並且在 PulseAudio 的二進制文件不存在的情形下崩潰。可以通過將 `/bin/pulseaudio` 連結至 `/bin/true` 來繞過這個問題。[13]

    # ln -s /bin/true /bin/pulseaudio

注意：重新安裝 PulseAudio 需要移除此符號連結。

#### 自動切換不起作用

自動切換不起作用可能是由於 WirePlumber 狀態有問題。這條評論指出可以刪除 WirePlumber 的本地狀態並重啟守護進程看看有沒有用：

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

然後重啟 `wireplumber.service` 用戶單元。

#### 從待機狀態恢復時失去實時優先級/負載下音頻爆裂

由於 rtkit 2011 年的一個 bug，待機事件會取消 PipeWire 的實時優先級並且不會恢復。若想禁用造成問題的保護措施，編輯 `rtkit-daemon.service`：

    /etc/systemd/system/rtkit-daemon.service.d/override.conf

    [Service]
    ExecStart=
    ExecStart=/usr/lib/rtkit-daemon --no-canary

然後重啟 `rtkit-daemon.service` 和 `pipewire.service`，以及 media session 服務。

#### 在向 RAOP 設備推流時沒有聲音 (例如 Sonos)

使用 Avahi 或 systemd-resolved 設置 mDNS 域名解析。

#### KDE Plasma 中未顯示音頻設備

PipeWire 客戶端（包括桌面環境）可能依賴 XDG_RUNTIME_DIR [14] 來連接 PipeWire 守護進程。[15] 若登錄後立即出現無聲問題，可能是由於該變量被手動設置為錯誤路徑。

雖然手動重啟 PipeWire 可暫時解決，但仍可能導致其他問題（如 Chromium 無法屏幕共享並報錯 `pipewire context failed`）。`XDG_RUNTIME_DIR` 應由 pam_systemd(8) 自動設置，請檢查並移除所有初始化文件中的手動設置。

#### SDDM/LightDM 用戶登錄後設備音量未恢復

若使用 SDDM 或 LightDM 時發現登錄後音量設置未保留，需為顯示管理器的用戶屏蔽 PipeWire，因其運行的 WirePlumber 會干擾用戶會話：

    # systemctl --user -M user@ mask pipewire.socket

將 `user` 替換為 `sddm`（在SDDM上）或 `lightdm`（在LightDM上）。詳見 Debian Wiki article。

#### 終端鈴聲失效

從 PipeWire 角度，需加載 x11.bell 模塊（默認配置已包含，可見上述配置文件）。請確認已安裝 pipewire-x11-bell包 包。窗口管理器也可能影響終端鈴聲，例如 xfwm 需在終端設置中啟用"聲音提示"。重啟服務測試：

    $ systemctl --user restart pipewire

可通過以下命令測試鈴聲：

    $ echo $'\a'

### 視頻

#### OBS 等程序即使請求了窗口/屏幕卻仍舊什麼都不顯示

如果您確定自己已經安裝了 xdg-desktop-portal包 以及 xdg-desktop-portal-gtk包 和 xdg-desktop-portal-kde包 兩者之一，請檢查守護程序的運行狀態。

在 OBS 中，如果一切工作正常，您應該會在 `stdout` 看到如下輸出：

    ...
    info: [pipewire] desktop selected, setting up screencast
    info: [pipewire] created stream 0x5632d7456850
    info: [pipewire] playing stream…

對於多顯示器配置，slurp包 可以用於捕獲所有屏幕。

## 參閱

- Wiki——Freedesktop GitLab 上的 PipeWire Wiki
- Pipewire Update Blog Post——一篇 2018 年 1 月的描述當時 PipeWire 狀態的博文
- PipeWire Late Summer Update 2020——2020 年 9 月的一篇博文

分類：​

- 多媒體
- 使用「模板:過時」標記的頁面或章節

隱藏分類：​

- 使用「模板:Translateme」標記的頁面或章節
- 使用「模板:準確性」標記的頁面或章節

PipeWire
新增話題