WirePlumberのソースを表示

[[Category:マルチメディア]]
[[en:WirePlumber]]
{{Related articles start}}
{{Related|PipeWire}}
{{Related articles end}}

[https://pipewire.pages.freedesktop.org/wireplumber WirePlumber] は、[[PipeWire]] 用の強力なセッションおよびポリシーマネージャです。モジュール設計に基づき、管理機能を実装し、 Lua プラグインによって、高度な設定と拡張が可能です。

== インストール ==

{{Pkg|wireplumber}} パッケージを [[インストール]]してください。他の PipeWire セッションマネージャーと競合しますので、必ずアンインストールするようにしてください。

WirePlumber は [[systemd/ユーザー]] を使ってサーバーを管理し、ソケットを自動で起動します。

オプションとして、ドキュメントを確認するために {{Pkg|wireplumber-docs}} をインストールしてください。

== 設定 ==

=== 設定ファイルのレイアウト ===

[https://pipewire.pages.freedesktop.org/wireplumber/configuration.html WirePlumber の設定] は、変更された {{ic|context}} や {{ic|alsa_monitor}} などのグローバル PipeWire 風味の JSON オブジェクトで設定されていますその行動を変えるために。設定ファイルは、{{ic|~/.config/wireplumber/}} (ユーザー構成)、{{ic|/etc/wireplumber/}} (グローバル構成)、そして {{ic|/usr/share/wireplumber/}} (ストック構成) から読み取られます。

WirePlumber は、[https://pipewire.pages.freedesktop.org/wireplumber/configuration/main.html メイン設定ファイル] を読み取ることから開始します。これは、PipeWire コンテキスト、[https://docs.pipewire.org/page_spa_plugins.html SPA プラグイン]、モジュール、およびコンポーネントを設定する JSON のようなファイルです。これらのコンポーネントの中には、グローバルオブジェクトを動的に変更するために使用される [[Wikipedia:ja:Lua|Lua]] スクリプトエンジンがあります。

パッケージに同梱されているさまざまな設定ファイルがあります。

* シングルインスタンス設定ファイル{{ic|/usr/share/wireplumber/wireplumber.conf}} これはデフォルトの設定であり、他のすべての設定の機能を1つのプロセス内に含んでいます。
** すべてのメイン設定ファイルで使用されている "context" オブジェクトについては、[https://pipewire.pages.freedesktop.org/wireplumber/configuration/main.html ドキュメント] を参照。
* メイン設定ファイル {{ic|/usr/share/wireplumber/main.conf}} WirePlumber コアに必要なモジュールとコンポーネントをロードし、{{ic|''config-dir''/main.lua.d/}} から [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html Lua 設定ファイル] をロードします。[https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html] を参照してください。
** [https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html ALSAオブジェクト] と [https://pipewire.pages.freedesktop.org/wireplumber/configuration/access.html "アクセス" オブジェクト] のドキュメントを参照してください。
* [[Bluetooth]] 設定ファイル {{ic|/usr/share/wireplumber/bluetooth.conf}} コアプロセスの Bluetooth 接続を処理する WirePlumber プロセスに適しています。これは{{ic|''config-dir''/bluetooth.lua.d/}} から Lua ファイルをロードします。
** [https://pipewire.pages.freedesktop.org/wireplumber/configuration/bluetooth.html Bluetooth オブジェクトのドキュメント] を参照してください。
* ''policy'' 設定ファイルは {{ic|/usr/share/wireplumber/policy.conf}} にあります。これは、WirePlumber がノードの移動や変更を判断するためのポリシー機能をカプセル化したものです。{{ic|''config-dir''/policy.lua.d/}} から Lua ファイルを読み込みます。
** ポリシー関連オブジェクトについては、[https://pipewire.pages.freedesktop.org/wireplumber/configuration/policy.html ドキュメント] を参照してください。

{{ic|lua.d/}} ディレクトリ内の Lua 設定ファイルは、{{ic|''config-dir''/scripts/}} から Lua スクリプトも読み込みます。これらのスクリプトは Pipewire のロジック/機能の一部を実装しており、特定の状況下では変更する価値がある場合もあります。

=== 設定の変更 ===

WirePlumber を設定する推奨方法は、{{ic|/etc/wireplumber/}} または {{ic|~/.config/wireplumber/ 内の適切な {{ic|lua.d/}} ディレクトリに Lua スクリプトを追加することです。}} 考慮すべき点は次のとおりです。

* 上書きしたい既存のスクリプトがある場合は、{{ic|/usr/share/wireplumber/}} からコピーしてください。同じ名前で優先順位の低い場所にある設定ファイルは無視されます [https://pipewire.pages.freedesktop.org/wireplumber/configuration/locations.html#location-of-configuration-files]
* 新しいスクリプトを追加する場合、50 より大きな数字で始めるべきです (例:{{ic|51-my-config.lua}}) デフォルトの設定は、英数字の並び順で 50 かそれ以下で行われることがほとんどだからです。
** WirePlumber は [https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html#multi-path-merging multi-path merging] を実行するため、英数字の並び順がディレクトリの優先順位よりも優先されるため、番号の低いストックの設定が新しいスクリプトよりも先に実行されることに注意してください。
* 選択するディレクトリは、ストックの設定が行うものと一致している必要がありますが、[https://pipewire.pages.freedesktop.org/wireplumber/configuration/multi_instance.html 複数インスタンスを使用する] 場合ではない限り、厳密には重要ではありません。
* Bluetooth デバイスの ALSA プロパティは {{ic|bluetooth.lua.d/}} で設定する必要があります。Bluetooth デバイスの ALSA プロパティは {{ic|main.lua.d/}} で設定されたものでは ''ありません''。

=== ルールマッチングのためのインターフェース名の取得 ===

Lua スクリプトでは、設定するインターフェイスの [https://docs.pipewire.org/page_objects_design.html オブジェクト] のプロパティを使用して {{ic|matches}} ルールを指定する必要があります。

WirePlumber によって管理されているすべてのオブジェクトを表示するには、コマンド {{ic|wpctl status}} を使用します。ターゲットインターフェイスに割り当てられた {{ic|''ID''}} を見つけます。次に、コマンド {{ic|wpctl Inspection ''ID''}} を使用して、必要なプロパティを取得します。

たとえば、ターゲットインターフェイスが {{ic|HD Audio Controller Analog Stereo}} であり、次の出力を検討する場合:

{{hc|$ wpctl status|output=
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]
 │
 └─ ...}}

インターフェース {{ic|''ID''}} は {{ic|48}} です。

次に、inspect コマンドを使用してオブジェクトの詳細を表示し、そのオブジェクト内のすべてのプロパティをリストします。

{{hc|$ wpctl inspect 48|output=
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"
    ...
}}

Lua 構成スクリプトの {{ic|matches}} ルールで使用する {{ic|device.name}} または {{ic|node.name}} プロパティを選択します。

{{ic|device.id}} は動的であり、頻繁に変更されるため、使用は避けてください。

{{ic|matches}} ルールでは複数のプロパティが可能です。[https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html#modifying-the-default-configuration WirePlumber ALSA 設定のドキュメント] の {{ic|alsa_monitor.rules}} セクションを参照してください。

{{Note|
* このオブジェクトの {{ic|Endpoint}} クラスは {{ic|media.class}} プロパティから判断できます。
* ALSA では {{ic|node}} オブジェクトはシンクまたはソース / {{ic|device}} オブジェクトはカードに対応します。
* v0.4.9以降、ALSA ノードは PCM 名を使って {{ic|node.nick}} を生成します。これは少なくとも UCM を使っている HDA カードでは便利で、全ての出力 (アナログ、HDMI など) が一つのプロファイル上で {{ic|node}} として公開されます。
}}

{{Tip|
* コマンド {{ic|pw-top}} は、現在使用中の PipeWire {{ic|Device}} と {{ic|Node}} を表示します。
* PipeWire の同様の検査コマンドは {{ic|pw-cli info ''ID''}} です。
}}

=== デバイス/ノードのプロパティを変更する ===

デバイスやノードのプロパティ(説明やニックネームなど)を変更するには、Lua スクリプトを作成し、{{ic|~/.config/wireplumber}} に適切なパスと名前で追加する必要があります。

例えば ALSA ノードの説明を変更するには、 {{ic|~/.config/wireplumber/main.lua.d/51-alsa-rename.lua}} のようなファイルを作成して、以下のような内容を記述してください。
{{hc|head=51-alsa-rename.lua|output=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)}}

もし、Bluetooth ノードやデバイスの何かを変更したい場合は、以下のような内容で {{ic|~/.config/wireplumber/bluetooth.lua.d/51-rename.lua}} を作成するとよいでしょう。
{{hc|head=51-rename.lua|output=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)}}

Lua スクリプトのファイル名と場所は、[https://pipewire.pages.freedesktop.org/wireplumber/configuration/config_lua.html#multi-path-merging WirePlumber's マルチパスマージ] で、デフォルトの設定ファイル

(例:{{ic|/usr/share/wireplumber/main.lua.d/50-alsa-config.lua}})デバイスをロードして有効にするファイル

(例:{{ic|/usr/share/wireplumber/main.lua.d/90-enable-all.lua}})の前に実行できるよう設計されています。

デバイスやノードを選択するためのマッチングルールや、変更できるプロパティは [https://pipewire.pages.freedesktop.org/wireplumber/configuration/alsa.html ALSA 設定] と [https://pipewire.pages.freedesktop.org/wireplumber/configuration/bluetooth.html Bluetooth 設定] に記載されています。

=== デバイス/ノードの無効化 ===

WirePlumber v0.4.7 からは、プロパティ {{ic|device.disabled}} または {{ic|node.disabled}} で任意のデバイスやノードを無効にできるようになりました。

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

table.insert(alsa_monitor.rules,rule)}}

システム内の {{ic|alsa_card.*}} の名前については、[[WirePlumber#Obtain interface name for rules matching]] を参照してください。

{{Note|一般的な使用例としては、NVIDIA の HDMI オーディオ出力を無効にする場合など。}}

=== ノードの優先度の設定 ===

自動的に選択されるシンクまたはソースを変更するには、その {{ic|priority.driver}} と {{ic|priority.session}} の値を設定する必要があります。

{{hc|/etc/wireplumber/wireplumber.conf.d/52-set-priorities.conf|output=
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 出力や接続されているヘッドホンなど)がデフォルトで選択されることになります。それらのデバイスはより高い優先度を持っているため、アナログスピーカー出力ではなく、そちらが選ばれることになります。

=== 同じサウンドカード上の複数のシンクへの同時出力 ===

[[PipeWire#同じサウンドカード上の複数のシンクへの同時出力]] を参照してください。

=== 一時的なデバイスへの同時出力 ===

オンボードデバイスと外部デバイスに同時に音声を出力したい場合がありますが、外部デバイスが常に接続されているとは限りません。
これを実現するために、接続されているハードウェアに関係なく常に存在する仮想ノードを作成します。そして、外部デバイス(この例では USB ヘッドホン)を接続するたびに仮想ノードへリンクさせます。

まず、ログイン時に実行されるスクリプトを作成します(ウィンドウマネージャーの "スタートアップ" 機能を使用するのが簡単です)

{{hc|head=/usr/local/sbin/create-virtual-sink.sh|output=
#!/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) のみです。
自身のサウンドカードの識別名を確認するには、{{ic|wpctl status}} や {{ic|wpctl inspect}} を実行してください。

USB ヘッドホンが接続されたときに仮想出力へリンクするスクリプトを実行します:
{{hc|head=link-virtual-sink-headphones.sh|output=
#!/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
}}

このスクリプトは、USB ヘッドホンが接続されたときに自動実行されるように設定するのが理想的です。
[[udev]] ページに記載されている手順に従い、カスタムルールを作成してください。
(ただし、udev はスクリプト ''実行前'' にドライバをロードしないため、nohup などを使った中間スクリプトが必要になります)

また、上記スクリプトの XDG_RUNTIME_DIR の値を自身のユーザー ID に合わせて修正し、'''user1''' を自分のユーザー名に変更する必要があります。

この仮想出力には、同様の方法で任意の数のデバイスを追加できます。

デバイスの接続状態を視覚的に確認したい場合は、{{Pkg|qpwgraph}} ツールを使用すると便利です。

== ヒントとテクニック ==

=== 壊れた設定を削除 ===

WirePlumber の設定が破損している場合、すべてのユーザー設定を削除することができます:

 systemctl --user stop wireplumber.service
 rm -r ~/.local/state/wireplumber # 設定を削除
 systemctl --user start wireplumber.service

=== キーボードで音量コントロール ===

次のコマンドをボリュームキーにバインドするには、[[キーボードショートカット#Xorg]] を参照してください: {{ic|XF86AudioRaiseVolume}}、{{ic|XF86AudioLowerVolume}}、{{ic|XF86AudioMute}}、および {{ic|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

{{Tip|デフォルト以外のシンクまたはソースを使用するには、{{ic|wpctl status}} を実行して利用可能なすべてのシンクをリストし、{{ic|@DEFAULT_AUDIO_SINK@}} または {{ic|_SOURCE@}}}}

=== 音量レベルを表示 ===

デフォルトのシンクの音量レベルとミュート状態を取得するには、次の手順を実行します。

{{hc|$ wpctl get-volume @DEFAULT_AUDIO_SINK@|Volume: 0.45}}

{{Note|ミュートステータスは、シンクがミュートされている場合にのみ表示されます。}}

=== Bluetooth プロファイルの自動切り替えを無効化 ===

[[PipeWire#プロファイルの自動選択機能]] を参照してください。

=== ログアウト後も Bluetooth を実行し続ける/ヘッドレス Bluetooth ===

デフォルトでは、{{ic|/usr/share/wireplumber/bluetooth.lua.d/50-bluez-config.lua}} により [https://gitlab.freedesktop.org/pipewire/wireplumber/-/merge_requests/222/diffs?commit_id=a253aa4c4948cdd87ba222670ee17db849af85dd logind モジュール]が有効化されます。このモジュールは、セッションが終了すると Bluetooth を無効化します。この挙動は以下の設定で無効化できます:

{{hc|/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua (あるいは ~/.config/wireplumber/bluetooth.lua.d/50-bluez-config.lua)|2=
bluez_monitor.properties = {
  ["with-logind"] = false,
}
}}

{{Note|これに加えて、[[PipeWire]]/Wireplumber を実行しているユーザーに対しては[[systemd/ユーザー#systemd のユーザーインスタンスを自動起動|残留 (lingering)]] を有効にする必要があります。}}

=== オーディオスタックの統合を無効化 ===

他のオーディオソリューション (例: [[PulseAudio]]/[[JACK]]/[[ALSA]]) を使用するために [[PipeWire]]/WirePlumber にオーディオデバイスの制御を任せたくないが、それでも画面共有やビデオ用途で利用したい場合は、{{ic|wireplumber@.service}} の [[systemd#ユニットを使う|テンプレートユニット]] を利用して、異なるデフォルトプロファイルセットを有効にできます。

WirePlumber には、ビデオ関連のみを有効にし、オーディオ統合 (Bluetooth オーディオを含む) を無効にするプロファイル設定が含まれています。これを適用するには、{{ic|video-only}} テンプレート [[ユーザーユニット]] を有効にします。

{{ic|wireplumber.service}} [[ユーザーユニット]]を[[無効化]]し、{{ic|wireplumber@video-only.service}} [[ユーザーユニット]]を[[有効化]]してください。

== 参照 ==

* [https://pipewire.pages.freedesktop.org/wireplumber/ Documentation] — オフィシャル ドキュメント
* [https://www.collabora.com/news-and-blog/blog/2020/05/07/wireplumber-the-pipewire-session-manager/ WirePlumber, PipeWire session manager] - George Kiagiadakis (Collabora) による2020年5月のブログ記事で、WirePlumber の仕組みが詳しく説明されています。