PipeWire: Difference between revisions

Latest revision as of 11:09, 25 February 2025

PipeWire is a multimedia processing engine that aims to improve audio and video handling on Linux. Pipewire can act as a replacement for both PulseAudio and ALSA servers.

Prerequisites

PipeWire requires a running D-Bus system and/or session bus for most of its functionality. If you start session-wide dbus instance, make sure to start PipeWire in that same session.

PipeWire needs proper permissions to access devices. If elogind is used, no further configuration is required. Otherwise, the user should be in audio (to access audio devices) and video (to access webcam devices) groups. Make sure to re-login for these changes to take effect:

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

Warning: Membership of the video group will also grant unrestricted access to video devices, which is often a security issue. See issue #15409 for further details.

Installation

The following packages i.e pipewire and wireplumber a session manager are the minimum required packages for getting pipewire to work.

# apk add pipewire wireplumber

Pulseaudio interface

The package pipewire-pulse allows pulseaudio applications to use PipeWire as audio server in the backend.

# apk add pipewire-pulse

JACK compatibility

Since Pipewire replaces JACK, Install pipewire-jack package, so it provides ABI-compatible libraries for JACK applications.

# apk add pipewire-jack

ALSA support

Install pipewire-alsa package to provide support for Alsa applications.

# apk add pipewire-alsa

GUI tools

pavucontrol or pavucontrol-qt package provides a simple GUI app for controlling sound, outputs, etc. To use pavucontrol tool install pipewire-pulse as the tool still needs Pulseaudio Interface. The XFCE Audio mixer can also be used to help control volume by installing the package xfce4-mixer which is currently in available in testing repository.

qpwgraph' is a graph manager dedicated to PipeWire with Qt GUI Interface.

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

pipewire-launcher

Start the PipeWire media server using the pipewire-launcher script provided by Alpine Linux. You'll probably get quite a few errors but just ignore them for now.

$ /usr/libexec/pipewire-launcher

If .xinitrc is used, add /usr/libexec/pipewire-launcher to your ~/.xinitrc.

If you do not use GUI by default, add the following stanza to your shell configuration file:

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

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

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

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.

Video

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

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 /etc/security/limits.conf will only work if your session is using PAM.

Disable D-Bus support

Warning: This section is no longer supported since Alpine 3.19 as Using lua for configuration files is no longer supported in version 0.5.

For certain configurations (e.g. only audio playback and recording) D-Bus setup is not necessary and it can be disabled as follows.

Edit the following configuration parameters:

Contents of /etc/pipewire/pipewire.conf

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

Contents of /etc/wireplumber/wireplumber.conf

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

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

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

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

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

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

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

Testing

Use the wpctl utility from WirePlumber to test the working of pipewire:

$ 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-play /usr/share/sounds/alsa/Front_Center.wav

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 using the aplay utility from alsa-utils package:

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*

Modern devices might require sof-firmware, which is the case if you get sof firmware file is missing errors in dmesg.

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.

Connection failure: Connection refused

When using Wayland, ensure that XDG_RUNTIME_DIR is configured correctly. 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

Bluetooth connect failed: br-connection-profile-unavailable

Ensure that 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.