PipeWire

This material is work-in-progress ... The instructions below have not been thoroughly tested and may break things. (Last edited by Psykose on 17 Feb 2023.)

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

Make sure to re-login for these changes to take effect.

D-Bus

PipeWire optionally requires a running D-Bus system and/or session bus for some of its functionality.

For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary. Edit configuration files to disable D-Bus support.

You can start a dbus session like this: dbus-run-session -- sh(replacing sh with your shell or a window manager), or, export $(dbus-launch). This is distinct from running dbus system-wide: rc-service dbus start, which is a prerequisite to run a user dbus session.

If you start session-wide dbus instance, make sure to start PipeWire in that same session.

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

Under Sway, in order for xdg-desktop-portal-wlr to work it may also be necessary to set XDG_CURRENT_DESKTOP and XDG_SESSION_DESKTOP to sway

Installation

Install the pipewire package.

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 the recommended session manager. If you do not know which session manager you need, use WirePlumber.
  Package: 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.
  Package: pipewire-media-session

Note: This page assumes that you are using WirePlumber.

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

Disable D-Bus support

Edit the following configuration parameters:

/etc/pipewire/pipewire.conf

context.properties = {
    ... 
    support.dbus = false
}

/etc/wireplumber/wireplumber.conf

context.properties = {
    ... 
    support.dbus = false
}

/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua

bluez_monitor.properties = {
  ...
  ["with-logind"] = false,
}

/etc/wireplumber/main.lua.d/50-alsa-config.lua

alsa_monitor.properties = {
  ...
  ["alsa.reserve"] = false,
}

/etc/wireplumber/main.lua.d/50-default-access-config.lua

default_access.properties = {
  ...
  ["enable-flatpak-portal"] = false,
}

Realtime scheduling

For realtime scheduling, it is recommended to use rtkit. Add your user to the rtkit group.

Alternatively, ensure your user has the right ulimit permissions. Since pipewire 0.3.66, you can add yourself to the pipewire group. You generally need (e.g. in /etc/security/limits.conf):

@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95

This allows a member of the pipewire group to have the right permissions for PipeWire to use realtime scheduling without rtkit. This same snippet comes with pipewire since 0.3.66, so if you have a PAM login session and add yourself to the pipewire group, you don't have to do anything else.

Note that the above limits.conf will only work if your session is using PAM.

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

Tip: You can also use superd to manage pipewire and its related services.

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-launcher

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.

Auto launching

You can add /usr/libexec/pipewire-launcher to your .xinitrc.

If you do not use GUI by default and have D-Bus enabled in configuration, add the following stanza to your shell configuration file:

export $(dbus-launch)
/usr/libexec/pipewire-launcher

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). Use pw-cat utility from 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 from jack-simple-clients:

$ jack_simple_client

You should hear a sustained beep.

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-run-session as outlined above. Alternatively, disable D-Bus support.

Bluetooth connect failed: br-connection-profile-unavailable

Ensure that a Session Manager is running.

Play/Pause buttons not working on bluetooth headphones

Check /var/log/messages. If you see something like this:

bluetoothd[3463]: profiles/audio/avctp.c:uinput_create() Can't open input device: No such file or directory (2)
bluetoothd[3463]: profiles/audio/avctp.c:init_uinput() AVRCP: failed to init uinput for WH-1000XM5

Then bluez is trying to register the headphones buttons as an input devices, but uinput is not loaded. Try modprobe uinput. If this works, see Architecture#Module_Loading for instructions on how to make sure this module is loaded automatically on each startup.

Quick Configuration

You might want to use pavucontrol to have a simple GUI app for controlling sound, outputs, etc.

See Also

• PipeWire source repository
• PipeWire Wiki
• PipeWire on the ArchWiki
• PipeWire on the Gentoo Wiki