PipeWire

From Gentoo Wiki
(Redirected from Wireplumber)
Jump to:navigation Jump to:search
Warning
As of mid 2022, PipeWire is still in active development. Some things may still not be fully integrated, tested, or implemented, and there may be large changes. It can work well for some, though the experience is not guaranteed to be perfect, free of issues, or bugs.
Important
This article currently describes the state-of-affairs in the testing branch (~arch), rather than stable. This will change in future, once the pace of development slows down a bit.

PipeWire is a low-latency, graph-based, processing engine and server, for interfacing with audio and video devices. It can be used to support use-cases currently handled by ALSA, PulseAudio, and/or JACK, and aims to improve handling of audio and video under Linux.

Some key features of PipeWire include:

  • Minimal latency capture/playback of audio and video.
  • Real-time multimedia processing.
  • Multi-process architecture allowing multimedia content sharing between applications.
  • Seamless support for PulseAudio, JACK, ALSA, and GStreamer.
  • Applications sandboxing support with Flatpak, with a security model that facilitates interacting containerized applications.


PipeWire currently ships a PipeWire daemon, an example session manager, tools to introspect and use the PipeWire Daemon, a library to develop PipeWire applications and plugins, and the SPA (Simple Plugin API) used by both the PipeWire daemon and the PipeWire library.

Installation

Kernel

CONFIG_SND_PROC_FS and CONFIG_SND_VERBOSE_PROCFS are needed for newer versions of media-video/wireplumber to work.

KERNEL
Device Drivers  --->
    <*> Sound card support  --->
        <*> Advanced Linux Sound Architecture  --->
            [*]   Sound Proc FS Support
            [*]     Verbose procfs contents

USE flags

Note
The sound server feature of PipeWire is governed by the USE=sound-server local USE flag, on the media-video/pipewire package.
Tip
The use of PipeWire by applications natively is governed by the USE=screencast USE flag, on each package that has optional PipeWire support. Of course pipewire support may also be provided through the pulseaudio or JACK compatibility layer.

USE flags for media-video/pipewire Multimedia processing graphs

X Enable audible bell for X11
bluetooth Enable Bluetooth Support
dbus Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc)
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
echo-cancel Enable WebRTC-based echo canceller via media-libs/webrtc-audio-processing
extra Build pw-cat/pw-play/pw-record
gstreamer Add support for media-libs/gstreamer (Streaming media)
jack-client Install a plugin for running PipeWire as a JACK client
jack-sdk Use PipeWire as JACK replacement
lv2 Allow loading LV2 plugins via media-libs/lv2
pipewire-alsa Replace PulseAudio's ALSA plugin with PipeWire's plugin
sound-server Provide sound server using ALSA and bluetooth devices
ssl Enable raop-sink support (needs dev-libs/openssl)
system-service Install systemd unit files for running as a system service. Not recommended.
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
v4l Enable support for video4linux (using linux-headers or userspace libv4l libraries)
zeroconf Support for DNS Service Discovery (DNS-SD)

Emerge

Note
Set the sound-server USE flag to enable sound server functionality.

Set the screencast USE flag on the ebuilds for which PipeWire support is desired, and media-video/pipewire will be pulled in as a dependency. Alternatively, set the screencast USE flag in make.conf.

After changing USE flags, rebuild affected packages:

root #emerge --ask --verbose --changed-use --update --deep @world

Alternatively, PipeWire may be emerged independently, though the previous method is usually what is required:

root #emerge --ask media-video/pipewire

Configuration

Note
PipeWire is still in heavy development - configuration paths, options and defaults can change from one minor release to another - if things on the system do not align with documentation, double check or at least make a backup before making changes.
Tip
Detailed, non Gentoo-specific, configuration documentation can be found at the project's official wiki.

Typically, things work reasonably well out of the box, and PipeWire's global configuration is usually best left unmodified.

Global PipeWire configuration can be changed by editing the /etc/pipewire/pipewire.conf file, and ~/.config/pipewire/pipewire.conf may be used for per-user configuration.

PipeWire also recognizes multiple environment variables that allow these settings to be changed, per-user, or for individual commands.

PipeWire video server

No additional configuration is required to use PipeWire as video server, this function is enabled by default.

The rest of this document describes how to deal with PipeWire sound server.

PipeWire sound server

To use PipeWire as a sound server, enable USE=sound-server USE flag and install as directed in the Emerge section.

The following sections describe further configuration, though often, no more configuration will be necessary.

In principle, existing PulseAudio or JACK tools can be used to interact with PipeWire when it is set up to behave as a JACK and/or PulseAudio server, but currently only parts of the respective APIs have been implemented. See the replacing PulseAudio section.

Service

systemd

PipeWire provides socket and service files when built with the systemd USE flag. The following systemctl command enables systemd's socket activation of PipeWire for the current user:

user $systemctl --user enable --now pipewire.socket

The socket activation only starts the service when required, which is usually sufficient. Alternatively the user service can be always started when the user logs in by replacing pipewire.socket with pipewire.service:

user $systemctl --user enable --now pipewire.service

Starting with 0.3.39, PipeWire also requires media-video/wireplumber to run properly:

user $systemctl --user enable --now wireplumber.service

In these cases, the --now flag is optional but probably safe to use as starting PipeWire with default configuration merely allows using new interfaces but does not change the existing ones i.e. non-PipeWire clients continue using the same libraries and services they were using previously. To also replace PulseAudio and/or JACK, follow the instructions in the relevant section.

OpenRC with elogind (any of Gentoo's desktop profiles)

PipeWire relies on a working D-Bus user daemon with an XDG compliant environment. Both requirements should be automatically met when a desktop profile is used, thanks to their elogind integration. On such systems, starting PipeWire is as simple as running the pipewire binary.

There is no truly standardized way (outside of systemd) to load PipeWire when starting a graphical shell, and users need to choose the correct approach based on how their graphical environment is started. The following table lists some ways to launch PipeWire when logging into a graphical environment:

Important
In all cases where systemd user services are not being used, PipeWire must be started before anything that might try to connect to any sound input or output, such as a volume monitoring applet. Additionally, consider disabling PA autospawn as described in man pulse-client.conf.
Note
Older versions of PipeWire (<0.3.39) worked by calling pipewire directly, but this is no longer recommended/correct.
Starting PipeWire with various non-systemd setups
Setup Instructions Content to add Notes
Display manager (SDDM, LightDM, GDM, etc) Gentoo's PipeWire package now installs the needed autostart files to /etc/xdg/autostart/pipewire.desktop, so no action should be required! Alternatively, edit the ~/.xprofile file. N/A if using XDG option.
FILE ~/.xprofile
gentoo-pipewire-launcher &
Note
The XDG approach should work for Wayland as well as X, but .xprofile may not be sourced when starting a Wayland session (unclear).
Sway Edit ~/.config/sway/config file.
FILE ~/.config/sway/config
exec gentoo-pipewire-launcher
Either elogind or seatd must be in use, otherwise start sway with:
user $dbus-launch --exit-with-session sway

Remember to set the XDG_RUNTIME_DIR, following what the ebuild prints out after installation.

Login without session management

Ensure there is a viable D-Bus session active:

FILE ~/.xinitrc
if command -v dbus-launch >/dev/null && test -z "${DBUS_SESSION_BUS_ADDRESS}"; then
       eval $(dbus-launch --sh-syntax --exit-with-session)
fi

Check that XDG_RUNTIME_DIR is set. This is usually managed by either systemd-logind, its fork elogind for OpenRC and similar init systems, or seatd - an alternative free-standing implementation of logind. In addition to running one of the 3 logind variants, a PAM module must also be loaded to let the daemon interact with users logging in and out of the system.

On systems without any such logind implementation and the required PAM module, the user must create the required directory and set the environment variable manually:

# Ensure XDG_RUNTIME_DIR is set
unset XDG_RUNTIME_DIR
export XDG_RUNTIME_DIR=$(mktemp -d /tmp/$(id -u)-runtime-dir.XXX)

The PipeWire executable must also be called:

FILE ~/.xinitrc
/usr/bin/gentoo-pipewire-launcher

Setting sample rates

PipeWire uses a global sample rate in the audio processing pipeline. All signals are converted to this sample rate and then converted to the sample rate of the device.

To change the sample rate, uncomment and change this line:

FILE pipewire.conf
default.clock.rate = 48000

It is also possible to dynamically force a sample rate at runtime see here

Avoid resampling

Since 0.3.33, it is possible to specify up to 16 alternative sample rates. Use the following config option to specify the sample rates:

FILE pipewire.conf
default.clock.allowed-rates = [48000 44100 96000]

Note that this not enabled by default because of kernel driver bugs.

According to the PipeWire developer, with the above configuration, no resampling is done when the graph is at a rate which both the client and the device can support.

Replacing PulseAudio

Note
Unless using ALSA or JACK, the PulseAudio libraries (the new media-libs/libpulse package, see bug #536780) will still need to be installed, but PipeWire will use these to emulate a PulseAudio server (PulseAudio's daemon will not be running in such a configuration). Not many applications support PipeWire's native API so the most common setup is to use PipeWire's PulseAudio-server emulation and use PulseAudio's API in applications (e.g. USE=pulseaudio still set in make.conf.

When PipeWire sound server is enabled via USE=sound-server, it will also provide a PulseAudio server for applications built using media-libs/libpulse client libraries.

To prevent a problem caused by running more than one sound server daemon, PipeWire ebuild will prevent simultaneously installing media-video/pipewire with USE=sound-server and any of PulseAudio daemon packages (media-sound/pulseaudio with USE=daemon, or media-sound/pulseaudio-daemon)

So, to use PipeWire instead of PulseAudio for the sound server, enable the USE=sound-server USE flag on media-video/pipewire, and disable the USE=daemon USE flag on media-sound/pulseaudio:

FILE /etc/portage/package.use
media-video/pipewire sound-server
media-sound/pulseaudio -daemon

Then do a world upgrade:

root #emerge -a -uvDU @world

Troubleshooting

Package conflict

Related package conflict should be automatically resolved by uninstalling PulseAudio daemon when emerge is called to update the @world set. If that does not happen, disable the USE=daemon USE flag for media-sound/pulseaudio in /etc/portage/package.use:

FILE /etc/portage/package.use
media-sound/pulseaudio -daemon

Then do an upgrade:

root #emerge -a -uvDU @world

Uninstalling PulseAudio daemon would also automatically disable pulseaudio daemon autospawn function in libpulse.

Disabling autospawn

Warning
The following is not needed anymore because pulseaudio daemon is no longer installed simultaneously with pipewire[sound-server] for ~arch users.

To be extra sure, one can disable autospawn explicitly:

  1. Turn it off in /etc/pulse/client.conf set autospawn = no. Remove any ; at the beginning of the line. This is already disabled with pulseaudio 16.1 or later.
  2. On OpenRC system, also check if /etc/pulse/client.conf.d/enable-autospawn.conf exists and set autospawn = no there.
  3. Disable daemon via configuration by editing /etc/pulse/daemon.conf and change 'daemonize' to daemonize = no. Remove any ; at the beginning of the line.

Alternatively, if media-sound/pulseaudio-daemon is installed, simply depclean (emerge --ask --depclean --verbose media-sound/pulseaudio-daemon) it.

systemd

Note
These instructions must be executed as and for each user that needs PipeWire!

First disable PulseAudio's user service (safe to do even if user service was not in use) and then enable the PipeWire and PipeWire-Pulse sockets:

user $systemctl --user disable --now pulseaudio.socket pulseaudio.service
user $systemctl --user enable --now pipewire.socket pipewire-pulse.socket wireplumber.service
Note
While PipeWire does not appear to utilize it beyond the cookie file, it may be a good idea to delete or rename the directory of existing PulseAudio user configuration that's usually found under the ~/.config/pulse/ directory.
Note
The following is not needed anymore because pulseaudio daemon is no longer installed simultaneously with pipewire[sound-server] for ~arch users.

Optionally, mask PulseAudio user service and socket, but it should be noted that this will not help much if PulseAudio configuration permits autostart (as is default):

user $systemctl --user mask pulseaudio.socket pulseaudio.service
Important
A reboot is strongly advised for the change to take effect. Of course this can be avoided but due to PulseAudio usually being configured to autostart and often surviving logouts, this feat of stubbornness is left as an exercise to particularly skilled readers.

OpenRC

Note
PipeWire versions 0.3.28 and greater now store the .conf files in /usr/share/pipewire/ directory. To create the PipeWire directory in /etc, type in the following command as root:


root #cp -r /usr/share/pipewire/ /etc/

To have PipeWire to act as a PulseAudio user daemon/server, no action is required on XDG-compliant desktops. If using a manual start solution, be sure to call gentoo-pipewire-launcher in scripts.

Verifying that it worked

Make sure prior that $ gentoo-pipewire-launcher & has been launched either manually or as script stated in the previous sections.

To check whether PipeWire is now acting as the PulseAudio user daemon/server, use this pactl command in a Bash compatible shell:

user $LANG=C pactl info | grep "Server Name"
Server Name: PulseAudio (on PipeWire 0.3.39)

Adding multi user support

The default configuration only allows the current user (who started pipewire-pulse) to play audio.

For multi-user support, the TCP interface is needed:

user $cp -r /usr/share/pipewire/ /etc/
user $$EDITOR /etc/pipewire/pipewire-pulse.conf

Locate server.address = [ section and uncomment one of the available TCP options.

Replacing JACK

To have JACK clients routed through PipeWire, currently the only method supported by Gentoo is to run them via pw-jack which uses LD_PRELOAD to redirect clients from JACK's original libraries to PipeWire's alternatives:

user $pw-jack qsynth
Important
Existing JACK users are likely to have realtime capability set up but new users are advised to raise the RLIMIT_MEMLOCK value from Gentoo's default of 64 kilobytes to 256 kilobytes on all PipeWire users that want to use its JACK emulation. For instructions on how to achieve that please see the subsection on that below (also listed in the table of contents for this page). Failure to do this will likely cause at least occasional buffer underuns (xruns) as a single page fault is likely to spend half to the entire length of a buffer just in kernel time to resolve.

It should be noted that either due to PipeWire incompleteness or Gentoo configuration shortcomings, not every client will work. Some may even ungracefully exit due to missing symbols. It will likely also require re-configuration of JACK clients, because they will attempt to use their old configuration files, if such exist.

Alternatively it should be possible to have PipeWire connect to a real jackd and act as a gateway for non-JACK applications but, unless there already is a working JACK setup, this is not recommended for the overall worse user experience with JACK.

Troubleshooting

CS:GO (and other games using the Valve's Source engine)

Note
It appears that this issue has been resolved by a patch by Valve in early 2021. If the issue is no longer present without any fixes applied, then please delete this subsection entirely.

The default sound buffer length is 0.025. This can sometimes be too low causing cracking audio; for now the workaround is to increase the size of the application's audio buffer from within CS:GO[1][2]:

snd_mixahead is the length of the sound buffer in seconds, so 0.05 is 50ms (0.10, edited: 25ms is the default). This is essentially the audio delay, so reducing it gives better synchronization. Not all hardware can handle a buffer setting this low though, so if there are any crackling or pops at 0.05, increase this setting by 0.01 until the crackling/pops disappear.

Increasing RLIMIT_MEMLOCK for PulseAudio clients (systemd specific)

Note
While the general issue of insufficient lockable memory limit is common among Gentoo and, indeed, most Desktop GNU/Linux distributions, this subsection chiefly addresses an additional resource limit on systemd units. Readers not using systemd's user services should follow instructions on JACK clients instead.

In case if messages such as this are observed:

user $systemctl --user status pipewire-pulse.service
...
.. pipewire-pulse[pid]: Failed to mlock memory [address] 32816: This is not a problem but for best performance, consider increasing RLIMIT_MEMLOCK
...

The amount of memory that pipewire-pulse process can lock can be adjusted via:

user $systemctl edit --user pipewire-pulse.service

and add in the blank space in the upper section of the editor window (not forgetting to save the file afterwards, of course):

...
### Anything between here and the comment below will become the new contents of the file

[Service]
LimitMEMLOCK=256K

### Lines below this comment will be discarded
...
Important
systemd is case sensitive and does not recognize the SI abbreviation for kilo, so be sure to use the capital letter K or will print a warning about illegal value and not apply the override!

If the system is shared between multiple users, this has to be done for each user (or the created override file has to be copied over with appropriate permissions).

Finally, to have the override applied, reload the configuration and then restart the service:

user $systemctl --user daemon-reload
user $systemctl --user restart pipewire-pulse.service

The current unit default is set to LimitMEMLOCK=131072 (same as 128K) by the Gentoo package which as of PipeWire 0.3.21 appears to allow for 1 PulseAudio client (subsequent clients will receive buffers backed by unlocked memory). Increasing the number to 256K as seen above should allow for 3 clients with buffers locked to memory at the same time.

While this is just a conjecture, it seems very likely that the LimitMEMLOCK which sets the per-unit hard limit (and implicitly also the LimitMEMLOCKSoft to the same value) must be within the bounds set on the user in question, which is 64 kilobytes for users without realtime capability. To actually have the default 128K or any other value above 64 kilobytes applied, set a new limit for non-system accounts:

FILE /etc/security/limits.d/50-custom.conf
# This raises the lockable memory upper limit of every process running under a non-system account (except for nobody) from default 64 to 256 kilobytes (in increments of page size); default (soft limit) remains at 64 kilobytes
1000:65533      hard    memlock 256

The new limits are only in effect on new logins, therefore the user must log out and back in. This is usually enough but if pipewire-pulse.service survived the logout, then it must be manually restarted as described previously in this subsection.

Increasing RLIMIT_MEMLOCK for JACK clients (and PulseAudio clients with OpenRC)

Unlike the case of PulseAudio clients, for which the user service does memory locking of buffers, JACK clients do it themselves. In the likely event that the clients report being unable to lock memory, in addition to the hard limit (max permitted value) described in previous sub-section on PulseAudio RLIMIT_MEMLOCK, the soft limit (the default value) must also be raised:

FILE /etc/security/limits.d/50-custom.conf
# This both raises the max and sets the default lockable memory limit of every process running under a non-system account (except for nobody) from default 64 to 256 kilobytes (in increments of page size)
1000:65533      -    memlock 256

Bluetooth

Important
PipeWire should already be enabling the bluez5 module when built with the pulseaudio USE flag. Please check if it's being set system-wide as PulseAudio API for clients is not going anywhere in a hurry.

By default, Bluetooth support is disabled to avoid clashes with PulseAudio's Bluetooth stack since currently the main use case is as an addition to not a replacement for PA. Uncomment PipeWire's bluez5 module for Bluetooth devices to be listed:

FILE /etc/pipewire/media-session.d/media-session.conf
...
modules = {
    ...
    default = [
        ...
        bluez5          # bluetooth support
        ...
    ]
    ...

Then run:

user $systemctl --user restart pipewire-pulse.service

See also

External resources

References