diff --git a/src/config/media/pipewire.md b/src/config/media/pipewire.md index 2f4e29062..797fa4c05 100644 --- a/src/config/media/pipewire.md +++ b/src/config/media/pipewire.md @@ -1,39 +1,38 @@ # PipeWire -To use PipeWire, install the `pipewire` package. - -[pipewire(1)](https://man.voidlinux.org/pipewire.1) should be started as a user. -Run the pipewire command in a terminal emulator in your session. +PipeWire is a modern server for handling audio (and video) streams. It is highly +flexible and can interface with applications designed for ALSA, PulseAudio, and +JACK audio systems. It is also designed to work well with Flatpak applications +and provides a method for screenshotting and screensharing on Wayland via +[xdg-desktop-portal](../graphical-session/portals.md). + +## Prerequisites + +PipeWire requires an active [D-Bus user +session](../session-management.md#d-bus). If your desktop environment, window +manager, or Wayland compositor is configured to provide a D-Bus session bus, no +further configuration should be required. If not, the desktop environment, +window manager, or Wayland compositor may need to be launched with +[`dbus-run-session(1)`](https://man.voidlinux.org/dbus-run-session.1). + +PipeWire also requires the +[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment +variable to be defined in your environment to work properly. -``` -$ pipewire -``` +If [elogind](../session-management.md) is not enabled or in use, it is necessary +to be in the `audio` group to access audio devices and the `video` group to +access video devices. -When pipewire works as expected, use the autostarting mechanism of your desktop -environment or [startx](../graphical-session/xorg.md#startx). The `pipewire` -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 -Specification](https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html), -you can enable pipewire by symlinking the desktop files to the autostart -directory: +## Basic Setup -``` -# ln -s /usr/share/applications/pipewire.desktop /etc/xdg/autostart/pipewire.desktop -``` +To use PipeWire, install the `pipewire` package. This will also install a +PipeWire session manager, `wireplumber`. -## Session Management +### 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) -was originally provided in the Void `pipewire` package and 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. +manager, PipeWire will not function. > If you have installed an earlier version of the Void `pipewire` package, make > sure to update your system to eliminate any stale system configuration that @@ -45,29 +44,17 @@ Install the `wireplumber` package to use this session manager with PipeWire. > prior override was to disable `pipewire-media-session`, deleting the custom > configuration may be sufficient. -There are several methods for starting `wireplumber` 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 +Currently, there is only one session manager available: WirePlumber. To +configure PipeWire to use this session manager and ensure proper startup +ordering, PipeWire should be configured to launch the session manager directly. +This can be accomplished by running ``` # mkdir -p /etc/pipewire/pipewire.conf.d # ln -s /usr/share/examples/wireplumber/10-wireplumber.conf /etc/pipewire/pipewire.conf.d/ ``` -for system configurations or, for per-user configurations, running +for system-wide configuration, or ``` $ true "${XDG_CONFIG_HOME:=${HOME}/.config}" @@ -75,66 +62,106 @@ $ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d" # ln -s /usr/share/examples/wireplumber/10-wireplumber.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/" ``` -With either of these configurations, launching `pipewire` should be sufficient -to establish a working PipeWire session that uses `wireplumber` for session -management. +for per-user configuration. + +### PulseAudio interface + +The PulseAudio interface is optional but highly recommended. Most applications +cannot speak directly to PipeWire, but instead speak to PipeWire's PulseAudio +interface. + +If `pulseaudio` is installed, uninstall it and ensure `pulseaudio` is not +running. -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 +Modify the PipeWire configuration to launch `pipewire-pulse`: ``` -dbus-run-session pipewire +# mkdir -p /etc/pipewire/pipewire.conf.d +# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf /etc/pipewire/pipewire.conf.d/ ``` -## PulseAudio replacement +for system configurations, or + +``` +$ true "${XDG_CONFIG_HOME:=${HOME}/.config}" +$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d" +# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/" +``` -Before starting `pipewire-pulse`, make sure that the PulseAudio service is -[disabled](../services/index.md#disabling-services) and that no other PulseAudio -server instance is running. +for per-user configurations. -Start the PulseAudio server by running `pipewire-pulse` in a terminal emulator. +### Testing -To check if the replacement is working correctly, use -[pactl(1)](https://man.voidlinux.org/pactl.1) (provided by the -`pulseaudio-utils` package): +[pipewire(1)](https://man.voidlinux.org/pipewire.1) should be started as a your +user. To test that PipeWire works, run the `pipewire` command in a terminal +emulator in your session: ``` -$ pactl info - -[...] -Server Name: PulseAudio (on PipeWire 0.3.18) -[...] +$ pipewire ``` -Once you confirmed that `pipewire-pulse` works as expected, it's recommended to -autostart it from the same place where you start PipeWire. Alternatively, the -`pipewire` configuration can be modified to launch `pipewire-pulse` directly: +Launching `pipewire` should be sufficient to establish a working PipeWire +session that uses `wireplumber` for session management. + +The status of WirePlumber can be checked with: ``` -# mkdir -p /etc/pipewire/pipewire.conf.d -# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf /etc/pipewire/pipewire.conf.d/ +$ wpctl status +PipeWire 'pipewire-0' [0.3.74, ...] +[...] ``` -for system configurations, or +If the [PulseAudio interface](#pulseaudio-interface) was configured, use +[pactl(1)](https://man.voidlinux.org/pactl.1) (provided by the +`pulseaudio-utils` package) to ensure it is working properly: ``` -$ true "${XDG_CONFIG_HOME:=${HOME}/.config}" -$ mkdir -p "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d" -# ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf "${XDG_CONFIG_HOME}/pipewire/pipewire.conf.d/" +$ pactl info +[...] +Server Name: PulseAudio (on PipeWire 0.3.74) +[...] ``` -for per-user configurations. +### Launching Automatically + +Once `pipewire` works as expected, it can be configured to launch when starting +a graphical session. There are several ways this can be achieved: + +- **Use the autostarting mechanism of your desktop environment**: many desktop + environments have a way to configure applications and programs to start + automatically. +- **Use XDG Desktop Application Autostart**: many desktop environments also + support the [Desktop Application Autostart + Specification](https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html). + The `pipewire` package ships a [Desktop + Entry](https://specifications.freedesktop.org/desktop-entry-spec/latest/) + file for `pipewire` in `/usr/share/applications`. If your environment + supports the Desktop Application Autostart, you can start `pipewire` by + symlinking the desktop file to the autostart directory + (`/etc/xdg/autostart`). If you are using a desktop environment, window + manager, or Wayland compositor that does not support this, a tool like + [`dex(1)`](https://man.voidlinux.org/dex.1) can be used to add support for + Desktop Application Autostart. +- **Use your window manager's startup scripts**: `pipewire` can be launched + directly from your window manager or Wayland compositor's startup script. + +## Optional Setup -## Bluetooth audio +### Graphical interfaces + +`qpwgraph` and `helvum` provide a node-and-graph-style interface for connecting +applications and devices. + +If using the [PulseAudio interface](#pulseaudio-interface), PulseAudio +configuration tools like `pactl` (from `pulseaudio-utils`), `pavucontrol`, +`pavucontrol-qt`, and the applets integrated into many desktop environments can +be used to configure PipeWire. + +### Bluetooth audio For bluetooth audio to work, install the `libspa-bluetooth` package. -## ALSA integration +### ALSA integration Install `alsa-pipewire`, then enable the PipeWire ALSA device and make it the default: @@ -145,7 +172,7 @@ default: # ln -s /usr/share/alsa/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d ``` -## JACK replacement +### JACK interface Install `libjack-pipewire`. @@ -165,8 +192,38 @@ on glibc-based systems: # ldconfig ``` +then reboot. + ## Troubleshooting -The PulseAudio replacement requires the -[`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) environment -variable to work correctly. +### Common errors + +``` +[E][...] mod.rt | [ module-rt.c: 262 pw_rtkit_bus_get()] Failed to connect to system bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory +``` + +This indicates the system D-Bus is not running. +[Enable](../services/index.md#enabling-services) the `dbus` service. + +``` +[E][...] mod.rt | [ module-rt.c: 262 pw_rtkit_bus_get()] Failed to connect to session bus: D-Bus library appears to be incorrectly set up: see the manual page for dbus-uuidgen to correct this issue. (Failed to open "/var/lib/dbus/machine-id": No such file or directory; Failed to open "/etc/machine-id": No such file or directory) +``` + +This indicates the [user session D-Bus](../session-management.md#d-bus) is not +running. + +``` +[E][...] mod.protocol-native | [module-protocol-: 710 init_socket_name()] server 0x55e09658e9d0: name pipewire-0 is not an absolute path and no runtime dir found. Set one of PIPEWIRE_RUNTIME_DIR, XDG_RUNTIME_DIR or USERPROFILE in the environment +``` + +This indicates [`XDG_RUNTIME_DIR`](../session-management.html#xdg_runtime_dir) +is not set up properly. + +### Only a "dummy" output is found + +If a session manager (like `wireplumber`) is not running, [configure +it](#session-management) and restart PipeWire. + +If a session manager is running, check if your user is in the `audio` and +`video` groups. If not using `elogind`, this is necessary for PipeWire to access +devices.