PipeWire: Difference between revisions

Revision as of 18:55, 7 November 2022

This material is work-in-progress ...

The instructions below have not been thoroughly tested and may break things.
(Last edited by Ermine on 7 Nov 2022.)

PipeWire is a multimedia processing engine that aims to improve audio and video handling on Linux.

Prerequisites

Device access

PipeWire needs proper permissions to access devices. If you do not use elogind, your user should be in audio and video groups:

# addgroup <user> audio
# addgroup <user> video

D-Bus

PipeWire requires a running D-Bus session for some of its functionality.

For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary. Edit context.properties section in configuration files to disable D-Bus integration:

/etc/pipewire/pipewire.conf

support.dbus = false

/etc/wireplumber/wireplumber.conf

support.dbus = false

XDG_RUNTIME_DIR

If you are not using a Desktop Manager, ensure that your XDG_RUNTIME_DIR is set to a user-writable location. By default for pulseaudio this is /run/user/1000/ or /tmp. If this is not set, pipewire will create a directory in your home folder instead, called ~/pulse, and on attempting to run Pavucontrol or pactl, you will get the following error:

$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused

Installation and configuration

Install PipeWire:

# apk add pipewire

Session Manager

PipeWire delegates plumbing work to session manager. There are two options available:

WirePlumber. It has modular design and supports Lua plugins. This is recommended session manager. If you do not know which session manager you need, use WirePlumber.
pipewire-media-session. It is much more simpler and covers only basic use cases. It was used for testing purposes. Now it does not make much sense since WirePlumber is available.

PulseAudio compatibility

Install pipewire-pulse package, which provides a daemon so PulseAudio applications could use PipeWire as backend.

JACK compatibility

Install pipewire-jack package, which provides ABI-compatible libraries for JACK applications.

ALSA support

Install pipewire-alsa package.

Configuration

PipeWire and WirePlumber store their default configuration in /usr/share/pipewire and /usr/share/wireplumber respectively. If you want to edit the configuration, you need to move it to /etc:

# cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc

Realtime scheduling

For realtime scheduling, it is recommended to use rtkit,

# apk add rtkit

and then add your user to the `rtkit` group.

Alternatively, ensure your user has the right ulimit permissions. You generally need (limits.conf format):

@audio - memlock 256
@audio - nice -11
@audio - rtprio 88

This allows a member of the audio group to have the right permissions for PipeWire to use realtime scheduling without rtkit.

Video

Video should work out-of-the-box with v4l2 devices (e.g. a lot of webcams) and GStreamer applications.

Bluetooth audio

Enable PulseAudio support as described above
Install bluetooth service packages: bluez bluez-openrc pipewire-spa-bluez
Optional: install GUI manager for bluetooth blueman
Enable and start bluetooth service: rc-update add bluetooth; rc-service bluetooth start
Restart PipeWire
Use commandline program bluetoothctl or GUI program blueman-manager to scan and pair bluetooth audio devices.
Use pavucontrol to adjust volume and manually select high definition bluetooth codecs.

Screen sharing on Wayland

You will need the right xdg-desktop-portal backend for your desktop environment. Screen sharing is known to work on:

GNOME with xdg-desktop-portal-gtk
KDE Plasma with xdg-desktop-portal-kde and Firefox
Sway with xdg-desktop-portal-wlr and Firefox, see Sway for details

Running

Note: pipewire-launcher script is provided by Alpine Linux, not by upstream. Please report issues to Alpine Linux maintainers first.

Start the PipeWire media server. You'll probably get quite a few errors but just ignore them for now.

$ /usr/libexec/pipewire-launcher

If you do not have D-Bus session bus running (e.g. you are in tty or you are using minimalistic DE or window manager which does not launch D-Bus session) and you did not disable D-Bus in PipeWire configuration, use dbus-launch:

$ dbus-launch /usr/libexec/pipewire-launch

Note: PipeWire doesn't auto-start a session manager anymore. In 3.14 and earlier, the PipeWire default config was edited in packaging to auto-start pipewire-media-session as the default session manager. Since we now have wireplumber available as an alternative session manager, this has been changed in favor of a launch wrapper for pipewire at /usr/libexec/pipewire-launcher. When executed, this will launch pipewire, pipewire-media-session or wireplumber, and pipewire-pulse, depending on what modules are available. If you were launching /usr/bin/pipewire and the session manager manually before, please use the new launcher wrapper instead. WirePlumber can now also be used as a proper alternative for pipewire-media-session.

Testing

In a different terminal window check the default output device. I don't yet know how this default can be changed for all applications, so you'd better hope it's right!

WirePlumber

$ wpctl status

pw-cat playback

Test sound is working using an audio file in a format supported by libsndfile (e.g. flac, opus, ogg, wav).

# apk add pipewire-tools
$ pw-cat -p test.flac

pw-cat recording

If you have a microphone test audio recording is working.

$ pw-cat -r --list-targets
$ pw-cat -r recording.flac
(Speak for a while then stop it with Ctrl+c)
$ pw-cat -p recording.flac

PulseAudio

Test PulseAudio clients using a media player, as most use PulseAudio.

JACK

Use jack_simple_client:

# apk add jack-example-clients
$ jack_simple_client

You should hear a sustained beep.

If you are happy everything is working, make PipeWire start automatically when your X or Wayland session starts. For example, you could add the /usr/libexec/pipewire-launcher command to ~/.xinitrc or your window manager's config file.

Troubleshooting

`wpctl status` shows no targets

First, check whether ALSA knows about your sound card:

aplay -l

If sound devices are found, the issue is with your pipewire configuration. Consider double-checking the instructions above.

Otherwise, your sound card may not be supported in the version of the Linux Kernel you're running. You should search online for fixes relating to your current kernel version and the codec of your sound card. You can find each of these with:

uname -r
cat /proc/asound/card0/codec* | grep Codec

Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY

This means D-Bus session bus is not started and GUI is not active (i.e. you are in a tty). Use dbus-launch as outlined above. Alternatively, disable D-Bus support.

Quick Configuration

You might want to use pavucontrol to have a simple GUI app for controlling sound, outputs, etc, in which case:

# apk add pavucontrol

@@ Line 5: / Line 5: @@
 == Prerequisites ==
-=== Audio Group ===
+=== Device access ===
-When elogind is not available, the user has to be added to the <code>audio</code> group. The user must re-log-in in for this to take effect.
+PipeWire needs proper permissions to access devices. If you do not use [[Elogind|elogind]], your user should be in <code>audio</code> and <code>video</code> groups:
 <pre>
 # addgroup <user> audio
+# addgroup <user> video
 </pre>
 === D-Bus ===
-PipeWire requires a running [https://www.freedesktop.org/wiki/Software/dbus/ D-Bus] session for some of its functionality. If you use a full desktop environment this will probably be started automatically, but with minimal window managers it must be done manually.
+PipeWire requires a running [[D-Bus]] session for some of its functionality.
+For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary. Edit <code>context.properties</code> section in [[#Configuration|configuration files]] to disable D-Bus integration:
+''/etc/pipewire/pipewire.conf''
 <pre>
-# apk add dbus dbus-openrc
+support.dbus = false
-# rc-service dbus start
-# rc-update add dbus default
 </pre>
-Then use <code>dbus-run-session</code> whenever you start an X or Wayland session. For example:
+''/etc/wireplumber/wireplumber.conf''
 <pre>
-$ dbus-run-session -- sway
+support.dbus = false
 </pre>
-{{Note|Alternatively, it can be used <code>dbus-launch</code> (which is included in the dbus-x11 package) to start the dbus daemon independently to the graphic server}}
-For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary.
 === XDG_RUNTIME_DIR ===
@@ Line 44: / Line 42: @@
 == Installation and configuration ==
+Install PipeWire:
 <pre>
-# apk add pipewire wireplumber
+# apk add pipewire
 </pre>
-{{Note|Using [https://gitlab.freedesktop.org/pipewire/wireplumber WirePlumber] rather than the pipewire-media-session (which comes with pipewire) is [https://gitlab.freedesktop.org/pipewire/media-session/-/blob/master/README.md recommended] but not required.}}
+=== Session Manager ===
+PipeWire delegates plumbing work to session manager. There are two options available:
+* '''[https://gitlab.freedesktop.org/pipewire/wireplumber WirePlumber]'''. It has modular design and supports Lua plugins. '''This is recommended session manager. If you do not know which session manager you need, use WirePlumber.'''
+* '''[https://gitlab.freedesktop.org/pipewire/media-session pipewire-media-session]'''. It is much more simpler and covers only basic use cases. It was used for testing purposes. Now it does not make much sense since WirePlumber is available.
+=== PulseAudio compatibility ===
+Install <code>pipewire-pulse</code> package, which provides a daemon so PulseAudio applications could use PipeWire as backend.
+=== JACK compatibility ===
+Install <code>pipewire-jack</code> package, which provides ABI-compatible libraries for JACK applications.
+=== ALSA support ===
+Install <code>pipewire-alsa</code> package.
+== Configuration ==
+PipeWire and WirePlumber store their default configuration in <code>/usr/share/pipewire</code> and <code>/usr/share/wireplumber</code> respectively. If you want to edit the configuration, you need to move it to <code>/etc</code>:
+<pre>
+# cp -a /usr/share/pipewire /etc
+# cp -a /usr/share/wireplumber /etc
+</pre>
 === Realtime scheduling ===
@@ Line 69: / Line 88: @@
 This allows a member of the audio group to have the right permissions for PipeWire to use realtime scheduling without rtkit.
-=== ALSA ===
-<pre>
-# apk add pipewire-alsa
-</pre>
-ALSA support works out of the box if you have the pipewire-alsa package. You may need the <code>snd_seq</code> kernel module.
-=== PulseAudio ===
-PipeWire can run a [https://www.freedesktop.org/wiki/Software/PulseAudio/ PulseAudio] daemon which should allow all existing PulseAudio applications to be used with the PipeWire backend. You need to have <code>pipewire-pulse</code> installed.
-=== JACK ===
-If you will be using PipeWire for [https://jackaudio.org/ JACK] applications install the required package (pipewire-jack). Things should work with just that.
 === Video ===
@@ Line 100: / Line 103: @@
 * Use pavucontrol to adjust volume and manually select high definition bluetooth codecs.
-== Screen sharing on Wayland ==
+=== Screen sharing on Wayland ===
 You will need the right [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] backend for your desktop environment. Screen sharing is known to work on:
@@ Line 107: / Line 110: @@
 * Sway with <code>xdg-desktop-portal-wlr</code> and Firefox, see [[Sway]] for details
-== Usage ==
+== Running ==
+{{Note|<code>pipewire-launcher</code> script is provided by Alpine Linux, not by upstream. Please report issues to Alpine Linux maintainers first.}}
 Start the PipeWire media server. You'll probably get quite a few errors but just ignore them for now.
@@ Line 113: / Line 118: @@
 <pre>
 $ /usr/libexec/pipewire-launcher
+</pre>
+If you do not have D-Bus session bus running (e.g. you are in tty or you are using minimalistic DE or window manager which does not launch D-Bus session) and you did not disable D-Bus in PipeWire configuration, use <code>dbus-launch</code>:
+<pre>
+$ dbus-launch /usr/libexec/pipewire-launch
 </pre>
 {{Note| PipeWire doesn't auto-start a session manager anymore.
 In 3.14 and earlier, the PipeWire default config was edited in packaging to auto-start pipewire-media-session as the default session manager. Since we now have wireplumber available as an alternative session manager, this has been changed in favor of a launch wrapper for pipewire at /usr/libexec/pipewire-launcher. When executed, this will launch pipewire, pipewire-media-session or wireplumber, and pipewire-pulse, depending on what modules are available. If you were launching /usr/bin/pipewire and the session manager manually before, please use the new launcher wrapper instead. WirePlumber can now also be used as a proper alternative for pipewire-media-session.}}
+== Testing ==
 In a different terminal window check the default output device. I don't yet know how this default can be changed for all applications, so you'd better hope it's right!
-wireplumber:
+=== WirePlumber ===
 <pre>
 $ wpctl status
 </pre>
+=== pw-cat playback ===
 Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile] (e.g. flac, opus, ogg, wav).
@@ Line 132: / Line 146: @@
 </pre>
+=== pw-cat recording ===
 If you have a microphone test audio recording is working.
@@ Line 141: / Line 156: @@
 </pre>
-Test PulseAudio clients using a media player (most use PulseAudio) and if you use JACK test that too:
+=== PulseAudio ===
+Test PulseAudio clients using a media player, as most use PulseAudio.
+=== JACK ===
+Use <code>jack_simple_client</code>:
 <pre>
@@ Line 170: / Line 189: @@
 cat /proc/asound/card0/codec* | grep Codec
 </pre>
+=== Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY ===
+This means D-Bus session bus is not started and GUI is not active (i.e. you are in a tty). Use <code>dbus-launch</code> as outlined [[#Running|above]]. Alternatively, [[#D-Bus|disable D-Bus support]].
 == Quick Configuration ==