Alpine Linux - User contributions [en]

PipeWire

2024-03-14T22:30:26Z

Leg: /* XFCE Audio Mixer Plugin */

{{TOC right}}

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

=== Device access ===

PipeWire needs proper permissions to access devices. If you do not use [[Elogind|elogind]], your user should be in <code>audio</code> (to access audio devices) and <code>video</code> (to access webcam devices) groups:

{{Cmd|<nowiki># addgroup <user> audio
# addgroup <user> video</nowiki>}}

{{Warning|Membership of the <code>video</code> group will also grant unrestricted access to video devices, which is often a security issue. See issue {{issue|15409}} for further details.
}}

See [https://wiki.archlinux.org/title/Users_and_groups#Pre-systemd_groups pre-systemd groups] for more info.
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 [[#Disable_D-Bus_support|configuration files]] to disable D-Bus support.

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

=== Environment ===

Ensure that [[XDG_RUNTIME_DIR]] is configured correctly. If this is not set, pipewire will create a directory in your home folder instead, called {{Path|~/pulse}}, 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>

Under [[Sway]], in order for <code>xdg-desktop-portal-wlr</code> to work it may also be necessary to set <code>XDG_CURRENT_DESKTOP</code> and <code>XDG_SESSION_DESKTOP</code> to <code>sway</code>

== Installation ==

Install the {{Pkg|pipewire}} package.

{{Cmd|# apk add pipewire}}

=== Session Manager ===

PipeWire delegates plumbing work to session manager. There is only one option: '''[https://gitlab.freedesktop.org/pipewire/wireplumber WirePlumber]'''. It has modular design and supports Lua plugins. '''This is the default pipewire session manager.

{{Cmd|# apk add wireplumber}}

=== PulseAudio compatibility ===

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

=== JACK compatibility ===

Install {{Pkg|pipewire-jack}} package, which provides ABI-compatible libraries for JACK applications.

=== ALSA support ===

Install {{Pkg|pipewire-alsa}} package.

== Configuration ==

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

{{Cmd|<nowiki># cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc</nowiki>}}

=== Disable D-Bus support ===

Edit the following configuration parameters:

{{Cat|/etc/pipewire/pipewire.conf|<nowiki>context.properties = {
...
support.dbus = false
}</nowiki>}}

{{Cat|/etc/wireplumber/wireplumber.conf|<nowiki>context.properties = {
...
support.dbus = false
}</nowiki>}}

{{Cat|/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua|<nowiki>bluez_monitor.properties = {
...
["with-logind"] = false,
}</nowiki>}}

{{Cat|/etc/wireplumber/main.lua.d/50-alsa-config.lua|<nowiki>alsa_monitor.properties = {
...
["alsa.reserve"] = false,
}</nowiki>}}

{{Cat|/etc/wireplumber/main.lua.d/50-default-access-config.lua|<nowiki>default_access.properties = {
...
["enable-flatpak-portal"] = false,
}</nowiki>}}

=== Realtime scheduling ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}}. Add your user to the <code>rtkit</code> group.

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

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

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 [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Bluetooth audio ===

* Enable PulseAudio support as described above
* Install bluetooth service packages: <code>bluez bluez-openrc pipewire-spa-bluez</code>
* Optional: install GUI manager for bluetooth <code>blueman</code>
* Enable and start bluetooth service: <code>rc-update add bluetooth; rc-service bluetooth start</code>
* Restart PipeWire
* Use commandline program <code>bluetoothctl</code> or GUI program <code>blueman-manager</code> 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 [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, see [[Sway]] for details

== Running ==

{{Tip|You can also use <code>superd</code> to manage <code>pipewire</code> and its related services.}}

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

{{Cmd|$ /usr/libexec/pipewire-launcher}}

A D-Bus session service must be running unless dbus support is disabled.

=== Auto launching ===
You can add {{Path|/usr/libexec/pipewire-launcher}} to your {{Path|~/.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:
{{Cmd|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 ===
{{Cmd|$ wpctl status}}

=== pw-cat playback ===

Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile]{{insecure url|Server refuses HTTPS connections}} (e.g. flac, opus, ogg, wav). Use <code>pw-cat</code> utility from {{Pkg|pipewire-tools}}:

{{Cmd|$ 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.

{{Cmd|$ 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 <code>jack_simple_client</code> from {{Pkg|jack-simple-clients}}:

{{Cmd|$ jack_simple_client}}

You should hear a sustained beep.

== Troubleshooting ==

=== `wpctl status` shows no targets ===

First, check whether ALSA knows about your sound card:

{{Cmd|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:

{{Cmd|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 <code>dbus-run-session</code> as outlined [[#Running|above]]. Alternatively, [[#D-Bus|disable D-Bus support]].

=== Bluetooth connect failed: br-connection-profile-unavailable ===

Ensure that a [[#Session_Manager|Session Manager]] is running.

=== Play/Pause buttons not working on bluetooth headphones ===

Check {{Path|/var/log/messages}}. If you see something like this:

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

Then bluez is trying to register the headphones buttons as an input devices, but <code>uinput</code> is not loaded. Try <code>modprobe uinput</code>. 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 {{Pkg|pavucontrol}} or {{Pkg|pavucontrol-qt}} to have a simple GUI app for controlling sound, outputs, etc.

== PipeWire Graph Qt GUI Interface ==

'''{{Pkg|qpwgraph}}''' is a graph manager dedicated to PipeWire.

== XFCE Audio Mixer Plugin ==

to help the XFCE audio mixer plugin find the volume to control:

{{Cmd|doas apk add gst-plugin-pipewire}}

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

PipeWire

2024-03-14T22:29:22Z

Leg: Add instructions for XFCE

{{TOC right}}

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

=== Device access ===

PipeWire needs proper permissions to access devices. If you do not use [[Elogind|elogind]], your user should be in <code>audio</code> (to access audio devices) and <code>video</code> (to access webcam devices) groups:

{{Cmd|<nowiki># addgroup <user> audio
# addgroup <user> video</nowiki>}}

{{Warning|Membership of the <code>video</code> group will also grant unrestricted access to video devices, which is often a security issue. See issue {{issue|15409}} for further details.
}}

See [https://wiki.archlinux.org/title/Users_and_groups#Pre-systemd_groups pre-systemd groups] for more info.
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 [[#Disable_D-Bus_support|configuration files]] to disable D-Bus support.

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

=== Environment ===

Ensure that [[XDG_RUNTIME_DIR]] is configured correctly. If this is not set, pipewire will create a directory in your home folder instead, called {{Path|~/pulse}}, 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>

Under [[Sway]], in order for <code>xdg-desktop-portal-wlr</code> to work it may also be necessary to set <code>XDG_CURRENT_DESKTOP</code> and <code>XDG_SESSION_DESKTOP</code> to <code>sway</code>

== Installation ==

Install the {{Pkg|pipewire}} package.

{{Cmd|# apk add pipewire}}

=== Session Manager ===

PipeWire delegates plumbing work to session manager. There is only one option: '''[https://gitlab.freedesktop.org/pipewire/wireplumber WirePlumber]'''. It has modular design and supports Lua plugins. '''This is the default pipewire session manager.

{{Cmd|# apk add wireplumber}}

=== PulseAudio compatibility ===

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

=== JACK compatibility ===

Install {{Pkg|pipewire-jack}} package, which provides ABI-compatible libraries for JACK applications.

=== ALSA support ===

Install {{Pkg|pipewire-alsa}} package.

== Configuration ==

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

{{Cmd|<nowiki># cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc</nowiki>}}

=== Disable D-Bus support ===

Edit the following configuration parameters:

{{Cat|/etc/pipewire/pipewire.conf|<nowiki>context.properties = {
...
support.dbus = false
}</nowiki>}}

{{Cat|/etc/wireplumber/wireplumber.conf|<nowiki>context.properties = {
...
support.dbus = false
}</nowiki>}}

{{Cat|/etc/wireplumber/bluetooth.lua.d/50-bluez-config.lua|<nowiki>bluez_monitor.properties = {
...
["with-logind"] = false,
}</nowiki>}}

{{Cat|/etc/wireplumber/main.lua.d/50-alsa-config.lua|<nowiki>alsa_monitor.properties = {
...
["alsa.reserve"] = false,
}</nowiki>}}

{{Cat|/etc/wireplumber/main.lua.d/50-default-access-config.lua|<nowiki>default_access.properties = {
...
["enable-flatpak-portal"] = false,
}</nowiki>}}

=== Realtime scheduling ===

For realtime scheduling, it is recommended to use {{Pkg|rtkit}}. Add your user to the <code>rtkit</code> group.

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

<pre>
@pipewire - memlock 4194304
@pipewire - nice -19
@pipewire - rtprio 95
</pre>

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 [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Bluetooth audio ===

* Enable PulseAudio support as described above
* Install bluetooth service packages: <code>bluez bluez-openrc pipewire-spa-bluez</code>
* Optional: install GUI manager for bluetooth <code>blueman</code>
* Enable and start bluetooth service: <code>rc-update add bluetooth; rc-service bluetooth start</code>
* Restart PipeWire
* Use commandline program <code>bluetoothctl</code> or GUI program <code>blueman-manager</code> 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 [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, see [[Sway]] for details

== Running ==

{{Tip|You can also use <code>superd</code> to manage <code>pipewire</code> and its related services.}}

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

{{Cmd|$ /usr/libexec/pipewire-launcher}}

A D-Bus session service must be running unless dbus support is disabled.

=== Auto launching ===
You can add {{Path|/usr/libexec/pipewire-launcher}} to your {{Path|~/.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:
{{Cmd|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 ===
{{Cmd|$ wpctl status}}

=== pw-cat playback ===

Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile]{{insecure url|Server refuses HTTPS connections}} (e.g. flac, opus, ogg, wav). Use <code>pw-cat</code> utility from {{Pkg|pipewire-tools}}:

{{Cmd|$ 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.

{{Cmd|$ 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 <code>jack_simple_client</code> from {{Pkg|jack-simple-clients}}:

{{Cmd|$ jack_simple_client}}

You should hear a sustained beep.

== Troubleshooting ==

=== `wpctl status` shows no targets ===

First, check whether ALSA knows about your sound card:

{{Cmd|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:

{{Cmd|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 <code>dbus-run-session</code> as outlined [[#Running|above]]. Alternatively, [[#D-Bus|disable D-Bus support]].

=== Bluetooth connect failed: br-connection-profile-unavailable ===

Ensure that a [[#Session_Manager|Session Manager]] is running.

=== Play/Pause buttons not working on bluetooth headphones ===

Check {{Path|/var/log/messages}}. If you see something like this:

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

Then bluez is trying to register the headphones buttons as an input devices, but <code>uinput</code> is not loaded. Try <code>modprobe uinput</code>. 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 {{Pkg|pavucontrol}} or {{Pkg|pavucontrol-qt}} to have a simple GUI app for controlling sound, outputs, etc.

== PipeWire Graph Qt GUI Interface ==

'''{{Pkg|qpwgraph}}''' is a graph manager dedicated to PipeWire.

== XFCE Audio Mixer Plugin ==

to help the XFCE audio mixer plugin find the volume to control:

doas apk add gst-plugin-pipewire

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