PipeWire

2022-07-12T20:38:30Z

Sirfredrick:

{{Draft|The instructions below have not been thoroughly tested and may break things.}}

[https://pipewire.org/ PipeWire] is a multimedia processing engine that aims to improve audio and video handling on Linux.

== Prerequisites ==

=== Audio Group ===

When elogind is not available, the user has to be added to the <code>audio</code> group. The user must log in for this to take effect.

<pre>
# addgroup <user> audio
</pre>

=== D-Bus ===

PipeWire requires a running [https://www.freedesktop.org/wiki/Software/dbus/ D-Bus] session. If you use a full desktop environment this will probably be started automatically, but with minimal window managers it must be done manually.

<pre>
# apk add dbus dbus-openrc dbus-x11
# rc-service dbus start
# rc-update add dbus default
</pre>

Then use <code>dbus-launch</code> whenever you start an X or Wayland session. For example:
<pre>
$ dbus-launch --exit-with-session sway
</pre>

=== XDG_RUNTIME_DIR ===

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

<pre>
$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused
</pre>

== Installation and configuration ==

<pre>
# apk add pipewire wireplumber
</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.}}

Create a custom configuration file in {{Path|/etc/pipewire/pipewire.conf}}:

<pre>
# mkdir /etc/pipewire
# cp /usr/share/pipewire/pipewire.conf /etc/pipewire/
</pre>

Add the following line to the <code>context.exec</code> section at the bottom of {{Path|/etc/pipewire/pipewire.conf}}:

<pre>
{ path = "wireplumber" args = "" }
</pre>

Enable the <code>snd_seq</code> kernel module for ALSA support.

<pre>
# modprobe snd_seq
# echo snd_seq >> /etc/modules
</pre>

=== Realtime scheduling ===

For realtime scheduling, it is recommended to use rtkit,

<pre>
# apk add rtkit
</pre>

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

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

<pre>
@audio - memlock 256
@audio - nice -11
@audio - rtprio 88
</pre>

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

=== 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.

<pre>
# apk add pipewire-pulse
</pre>

Uncomment the following line in {{Path|/etc/pipewire/pipewire.conf}}:

<pre>
{ path = "/usr/bin/pipewire" args = "-c pipewire-pulse.conf" }
</pre>

It should be automatically enabled.

=== JACK ===

If you will be using PipeWire for [https://jackaudio.org/ JACK] applications install the required package and make system wide links to the PipeWire replacement JACK libraries (I have not had success using <code>pw-jack</code>). You will not need to start a JACK server.

<pre>
# apk add pipewire-jack
# ln -sf /usr/lib/pipewire-0.3/jack/libjackserver.so.0 /usr/lib/libjackserver.so.0
# ln -sf /usr/lib/pipewire-0.3/jack/libjacknet.so.0 /usr/lib/libjacknet.so.0
# ln -sf /usr/lib/pipewire-0.3/jack/libjack.so.0 /usr/lib/libjack.so.0
</pre>

{{Note|These symlinks might be overwritten during updates.}}

=== Video ===

Video should work out-of-the-box with v4l2 devices (e.g. a lot of webcams) and [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Bluetooth headset ===

Requires <code>pipewire-spa-bluez</code> package in addition to <code>pipewire-pulse</code> daemon to be installed.

=== Automatic bluetooth profile selection ===

To automatically switch between HSP/HFP and A2DP profiles when an input stream is detected, set the bluez5.autoswitch-profile property to true:
<pre>
/etc/pipewire/media-session.d/bluez-monitor.conf

...
rules = [
{
...
actions = {
update-props = {
...
bluez5.autoswitch-profile = true
...
</pre>

=== 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:
* GNOME with <code>xdg-desktop-portal-gtk</code>
* KDE Plasma with <code>xdg-desktop-portal-kde</code> and Firefox
* Sway with <code>xdg-desktop-portal-wlr</code> and Firefox

== Usage ==

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

<pre>
$ pipewire
</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.}}

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!

<pre>
# apk add pipewire-tools
$ pw-cat -p --list-targets
</pre>

{{Note| pw-cat doesn't have --list-targets option anymore.
The version of pipewire used in Alpine 3.16 and later has the --list-targets option removed. You should now use '''pw-cli list-objects''' or '''wpctl status''' (if you use wireplumber).}}

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).

<pre>
$ pw-cat -p test.flac
</pre>

If you have a microphone test audio recording is working.

<pre>
$ 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
</pre>

Test PulseAudio clients using a media player (most use PulseAudio) and if you use JACK test that too:

<pre>
# apk add jack-example-clients
$ jack_simple_client
</pre>

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 <code>pipewire</code> command to <code>~/.xinitrc</code> or your window manager's config file.

== Troubleshooting ==

=== `pw-cat -p --list-targets` shows no targets ===

First, check whether ALSA knows about your sound card:

<pre>
aplay -l
</pre>

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:

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

== Quick Configuration ==

You might want to use pavucontrol to have a simple GUI app for controlling sound, outputs, etc, in which case:
<pre>
# apk add pavucontrol
</pre>

== See Also ==

* [https://gitlab.freedesktop.org/pipewire/pipewire PipeWire source repository]
* [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home PipeWire Wiki]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/Pipewire PipeWire on the Gentoo Wiki]

[[Category:Desktop]]
[[Category:Multimedia]]
[[Category:Sound]]

Alpine Linux - User contributions [en]

PipeWire