diff --git a/src/config/media/pipewire.md b/src/config/media/pipewire.md index f44158896..b0279a6c3 100644 --- a/src/config/media/pipewire.md +++ b/src/config/media/pipewire.md @@ -11,10 +11,7 @@ $ pipewire When pipewire works as expected, use the autostarting mechanism of your desktop environment or [startx](../graphical-session/xorg.md#startx). The `pipewire` -package provides `pipewire` and `pipewire-pulse` system services, but they are -not recommended for a typical setup. - -The `pipewire` package ships [Desktop +package ships [Desktop Entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/) files for `pipewire` and `pipewire-pulse` in `/usr/share/applications`. If your environment supports the [Desktop Application Autostart @@ -26,6 +23,94 @@ directory: # ln -s /usr/share/applications/pipewire.desktop /etc/xdg/autostart/pipewire.desktop ``` +## Session Management + +In PipeWire, a session manager assumes responsibility for interconnecting media +sources and sinks as well as enforcing routing policy. Without a session +manager, PipeWire will not function. The reference +[`pipewire-media-session`](https://gitlab.freedesktop.org/pipewire/media-session) +package was originally provided and, in Void, configured to run by default to +satisfy this requirement. However, `pipewire-media-session` is deprecated and +the authors recommend using +[WirePlumber](https://pipewire.pages.freedesktop.org/wireplumber/) in its place. +Install the `wireplumber` package to use this session manager with PipeWire. + +The standard Void configuration, which causes `pipewire` to launch +`pipewire-media-session` automatically, must be overridden to use `wireplumber`. +The only change necessary is to comment out the `pipewire-media-session` +invocation in the `context.exec` section, which can be done with a single `sed` +substitution. To make this configuration change visible to all users, place the +new configuration file in `/etc/pipewire`: + +``` +# mkdir -p /etc/pipewire +# sed '/path.*=.*pipewire-media-session/s/{/#{/' \ + /usr/share/pipewire/pipewire.conf > /etc/pipewire/pipewire.conf +``` + +Alternatively, place the new configuration file in the expected location for a +single user: + +``` +$ : "${XDG_CONFIG_HOME:=${HOME}/.config}" +$ mkdir -p "${XDG_CONFIG_HOME}/pipewire" +$ sed '/path.*=.*pipewire-media-session/s/{/#{/' \ + /usr/share/pipewire/pipewire.conf > "${XDG_CONFIG_HOME}/pipewire/pipewire.conf" +``` + +> A custom `pipewire.conf` in either `/etc/pipewire` or +> `${XDG_CONFIG_HOME}/pipewire` will prevent entirely the use of the default +> system configuration. Users who override the default configuration to enable +> `wireplumber` are encouraged to monitor the default configuration and +> reconcile any changes with each `pipewire` update. + +Now, configure `wireplumber` to start alongside `pipewire`. If your window +manager or desktop environment auto-start mechanism is used to start +`pipewire`, it is recommended to use the same mechanism for starting +`wireplumber`. The `wireplumber` package includes a `wireplumber.desktop` +Desktop Entry file that may be useful in this situation. + +> Be aware that `wireplumber` must launch *after* the `pipewire` executable. +> The Desktop Application Autostart Specification makes no provision for +> ordering of services started via Desktop Entry files. When relying on these +> files to launch `pipewire` and `wireplumber`, consult the documentation for +> your window manager or desktop environment to determine whether proper +> ordering of services can be achieved. + +If proper ordering of separate `pipewire` and `wireplumber` services is +infeasible, it is possible to configure `pipewire` to launch the session +manager directly. This can be accomplished by running + +``` +# mkdir -p /etc/pipewire/pipewire.conf.d +# echo 'context.exec = [ { path = "/usr/bin/wireplumber" args = "" } ]' \ + > /etc/pipewire/pipewire.conf.d/10-wireplumber.conf +``` + +for system configurations or, for per-user configurations, running + +``` +$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d +$ echo 'context.exec = [ { path = "/usr/bin/wireplumber" args = "" } ]' \ + > "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/10-wireplumber.conf" +``` + +With either of these configurations, launching `pipewire` should be sufficient +to establish a working PipeWire session that uses `wireplumber` for session +management. + +In its default configuration, WirePlumber requires an active [D-Bus +session](../session-management.md#d-bus). If your desktop environment or window +manager is configured to provide a D-Bus session as well as launch `pipewire` +and `wireplumber`, no further configuration should be required. Users wishing +to launch `pipewire` on its own, *e.g.*, in a `.xinitrc` script, may find it +necessary to configure `pipewire` to launch `wireplumber` directly and wrap the +`pipewire` invocation as + +``` +dbus-run-session pipewire +``` + ## PulseAudio replacement Before starting `pipewire-pulse`, make sure that the PulseAudio service is