PipeWire
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.
PipeWire 的主要功能:
- 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.
安装
内核
Needed media-video/wireplumber options:
Device Drivers ---> <*> Sound card support Search for <code>CONFIG_SOUND</code> to find this item. ---> <*> Advanced Linux Sound Architecture Search for <code>CONFIG_SND</code> to find this item. ---> -*- Sound Proc FS Support [*] Verbose procfs contents Search for <code>CONFIG_VERBOSE_PROCFS</code> to find this item.
USE 标记
To use PipeWire as a sound server, specify the sound-server USE flag on media-video/pipewire[1].
Then, if using PipeWire as a replacement for the PulseAudio sound server:
- Ensure media-sound/pulseaudio-daemon is not installed. This is necessary to avoid issues resulting from running more than one sound server.
- Ensure media-libs/libpulse is installed, which will allow PipeWire to emulate a PulseAudio sound server. Not many applications currently support PipeWire's native API.
- Ensure the pulseaudio USE flag is still set globally.
PipeWire requires the presence of a D-Bus session bus and an XDG-compliant environment. Both requirements should be met by a desktop profile; on such systems, starting PipeWire is as simple as running the pipewire binary. On other profiles, if using OpenRC, permissions requirements might also need the elogind USE flag on the media-video/wireplumber package, together with elogind itself.
To enable direct screencasting support on applications offering it, specify the screencast USE flag on the relevant packages. Otherwise, screencasting support may also be provided through the PulseAudio or JACK compatibility layers.
USE flags for media-video/pipewire Multimedia processing graphs
+man
|
Build and install man pages |
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 |
elogind
|
Enable session tracking via sys-auth/elogind |
extra
|
Build pw-cat/pw-play/pw-record |
ffmpeg
|
Enable ffmpeg/libav-based audio/video codec support |
flatpak
|
Enable Flatpak support |
gsettings
|
Use gsettings (dev-libs/glib) to read/save used modules (useful for e.g. media-sound/paprefs |
gstreamer
|
Add support for media-libs/gstreamer (Streaming media) |
ieee1394
|
Enable FireWire/iLink IEEE1394 support (dv, camera, ...) |
jack-client
|
Install a plugin for running PipeWire as a JACK client |
jack-sdk
|
Use PipeWire as JACK replacement |
liblc3
|
Allow loading LC3 plugins via media-sound/liblc3 |
lv2
|
Allow loading LV2 plugins via media-libs/lv2 |
modemmanager
|
Combined with USE=bluetooth, allows PipeWire to perform telephony on mobile devices. |
pipewire-alsa
|
Replace PulseAudio's ALSA plugin with PipeWire's plugin |
readline
|
Enable support for libreadline, a GNU line-editing library that almost everyone wants |
roc
|
Enable roc support for real-time audio streaming over the network, using media-libs/roc-toolkit. See https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Network#roc |
selinux
|
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur |
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) |
v4l
|
Enable support for video4linux (using linux-headers or userspace libv4l libraries) |
zeroconf
|
Support for DNS Service Discovery (DNS-SD) |
Emerge
Once the USE flags have been specified, rebuild the 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
Typically, the WirePlumber session manager should also be installed. WirePlumber is a replacement for pipewire-media-session; refer to this article for an introduction and the details. The media-video/wireplumber package provides the wireplumber.service systemd service and the wireplumber binary used by gentoo-pipewire-launcher.
root #
emerge --ask media-video/wireplumber
配置
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 system-level configuration is usually best left unmodified.
Audio Groups
PipeWire's default configuration tries to use realtime scheduling to increase audio thread priorities. It's recommended that users are in the pipewire group. If the user doesn't have the necessary permissions for this, the configuration will try to use RTKit instead, so the package may need to be installed. This behavior is defined under the context.modules
portion of PipeWire's configuration.
root #
usermod -aG pipewire larry
root #
emerge --ask sys-auth/rtkit
For the best experience with fast user switching, it is recommended that you remove your user from the audio group unless you rely on the audio group for device access control or ACLs:
root #
usermod -rG audio larry
PipeWire also recognizes multiple environment variables that allow these settings to be changed, per-user, or for individual commands.
No additional configuration is required to use PipeWire as video server; this functionality is enabled by default.
File locations
If configuration is required, PipeWire's configuration files are located at:
- ~/.config/pipewire/pipewire.conf - PipeWire 用户配置
- /etc/pipewire/pipewire.conf - PipeWire 系统配置
- /usr/share/pipewire/pipewire.conf - PipeWire 配置示例
The PipeWire configuration files do not exist by default, they must be created by copying the sample configuration.
root #
cp /usr/share/pipewire/pipewire.conf /etc/pipewire/pipewire.conf
user $
cp /usr/share/pipewire/pipewire.conf ~/.config/pipewire/pipewire.conf
Configuration fragments
Since 0.3.45 fragments of the config file can be copied to a file (with a .conf extension) in the following directories[2]:
- /usr/share/pipewire/pipewire.conf.d/
- /etc/pipewire/pipewire.conf.d/
- ~/.config/pipewire/pipewire.conf.d/
context.properties
The following configuration options are applied under context.properties
in PipeWire's configuration
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.
context.properties = {
default.clock.rate = 192000
default.clock.allowed-rates = [ 192000 48000 44100 ] # Up to 16 can be specified
}
Setting
default.clock.allowed-rates
to contain rates the output device supports eliminates the need to resample.[3]
This not enabled by default because of kernel driver bugs in kernels before 5.16
Sound Server Configuration
SDDM users should make sure to start it up via the proper service or XDG_RUNTIME_DIR may not be set up correctly.
systemd
PipeWire provides socket and service files when built with the systemd
USE flag.
If the PulseAudio user service is enabled, disable it; this is safe to do even if the user service was not in use.
user $
systemctl --user disable --now pulseaudio.socket pulseaudio.service
While PipeWire does not appear to utilize the ~/.config/pulse/ directory beyond the cookie file, it may be a good idea to rename or delete it.
Enable the wireplumber
service and the pipewire-pulse
socket; enabling the pipewire-pulse
socket will cause the pipewire-pulse
service to be started if required. That service will in turn start the pipewire
service.
user $
systemctl --user enable --now pipewire-pulse.socket wireplumber.service
Socket activation means the pipewire
service will only be started when required, which is usually sufficient. However, the pipewire
service can be always started when the user logs in by enabling pipewire.service:
user $
systemctl --user enable --now pipewire.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 and doesn't change the existing ones, i.e. non-PipeWire clients continue using the same libraries and services they were using previously.
OpenRC
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.
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.
Prerequisites
- XDG_RUNTIME_DIR
This variable is usually set automatically by systemd-logind, elogind or seatd. Systems that don't use any of these seat management daemons will need to set XDG_RUNTIME_DIR manually, e.g. in ~/.bash_profile, ~/.zprofile, etc.:
# Ensure XDG_RUNTIME_DIR is set
if test -z "$XDG_RUNTIME_DIR"; then
export XDG_RUNTIME_DIR=$(mktemp -d /tmp/$(id -u)-runtime-dir.XXX)
fi
- DBUS_SESSION_BUS_ADDRESS
This variable is usually set automatically by desktop environments such as GNOME or KDE. Note that a D-Bus session bus is not what is typically being provided by the system D-Bus service, which is instead providing a system bus for things like hardware events, etc.
When running a window manager, such as i3, bspwm or Sway, the WM needs to be started with dbus-launch, which will set DBUS_SESSION_BUS_ADDRESS for the session. For example, if starting X via startx, the final line of ~/.xinitrc could be:
exec dbus-launch --exit-with-session bspwm
Note that use of exec in this context means that no subsequent commands in that file will be executed, as the shell process interpreting the file will be replaced by the dbus-launch process. Any commands needing to be run from within the new session should be added to the WM's configuration/setup file, e.g. ~/.config/bspwm/bspwmrc.
More generally, dbus-launch can be run directly from the command line:
user $
dbus-launch --exit-with-session sway
gentoo-pipewire-launcher
The gentoo-pipewire-launcher script starts:
- a PipeWire server;
- a WirePlumber session manager, required to make use of PipeWire servers;
- a pipewire-pulse PipeWire server, required for PulseAudio compatibility.
Before doing so, the script terminates any existing PipeWire or WirePlumber instances. For further details, refer to the comments in the script.
gentoo-pipewire-launcher should be started in an environment which has the DBUS_SESSION_BUS_ADDRESS environment variable set appropriately, i.e. within the context of the program started by dbus-launch or dbus-run-session.
gentoo-pipewire-launcher supports logging, via ${XDG_CONFIG_HOME}/gentoo-pipewire-launcher.conf. The variables GENTOO_PIPEWIRE_LOG, GENTOO_PIPEWIRE_PULSE_LOG, and GENTOO_WIREPLUMBER_LOG can be used to specify the absolute path of a file to which logs should be written.
GUI environments (Desktop Environments and Window Managers)
Gentoo's PipeWire package installs the /etc/xdg/autostart/pipewire.desktop autostart file. However, not all GUI environments make use of autostart files: Plasma, GNOME, XFCE and Cinnamon do, but various window managers (such as Fluxbox) do not. Environments which make use of autostart files must not start PipeWire via ~/.xprofile; environments not making use of autostart files must start PipeWire by calling gentoo-pipewire-launcher from either the environment's startup file (see below), or ~/.xprofile (creating that file if necessary):
gentoo-pipewire-launcher &
Wayland / Sway / Window Managers
The XDG autostart approach should work for Wayland as well as X, but it is not clear whether .xprofile is necessarily sourced when starting a Wayland session.
For Sway, edit ~/.config/sway/config to add:
exec gentoo-pipewire-launcher &
For dwm, edit ~/.dwm/dwmrc to add:
gentoo-pipewire-launcher &
More generally, when using a window manager, a call to gentoo-pipewire-launcher needs to be added to the WM's configuration/setup file, e.g.:
exec gentoo-pipewire-launcher &
Restarting PipeWire and WirePlumber
To restart PipeWire and WirePlumber under OpenRC, e.g. to pick up configuration changes, run gentoo-pipewire-launcher with the restart argument to have it first shut down the existing instances from within the relevant D-Bus session:
user $
nohup gentoo-pipewire-launcher restart &
Using nohup allows the terminal to be closed without terminating gentoo-pipewire-launcher. Where output is directed might depend on the implementation of nohup; depending on the shell, nohup might be a builtin or an external command (e.g. nohup(1)), so check the shell's documentation.
Note that due to this wireplumber bug, nohup may not work, so you may need to use an alternative. In Bash, for instance, you can omit nohup, and then run disown right afterwards:
user $
gentoo-pipewire-launcher restart &
user $
disown
Verifying PulseAudio server emulation
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.
Usage
Controlling the volume
Pipewire volume can be controlled using Pulseaudio tools like pactl (media-libs/libpulse). It can also be controlled without depending on Pulseaudio:
Using wpctl (media-video/wireplumber). Example: to increase volume by 2%:
user $
wpctl set-volume @DEFAULT_AUDIO_SINK@ 2%+
Or using pw-cli (media-video/pipewire):[4]
1. Find the stream node id:
user $
pw-cli ls Node
2. Change the needed properties (To introspect the properties of a node, run pw-cli e <node-id> Props). Example: to unmute and set volume to 0.3:
user $
pw-cli s <node-id> Props '{ mute: false, channelVolumes: [ 0.3, 0.3 ] }'
Checking the sample rate
pw-metadata can be used to check the current sample rate, along with other configuration:
user $
pw-metadata -n settings
Found "settings" metadata 31 update: id:0 key:'log.level' value:'2' type:'' update: id:0 key:'clock.rate' value:'192000' type:'' update: id:0 key:'clock.allowed-rates' value:'[ 192000, 48000, 44100 ]' type:'' update: id:0 key:'clock.quantum' value:'1024' type:'' update: id:0 key:'clock.min-quantum' value:'32' type:'' update: id:0 key:'clock.max-quantum' value:'2048' type:'' update: id:0 key:'clock.force-quantum' value:'0' type:'' update: id:0 key:'clock.force-rate' value:'0' type:''
PulseAudio Server
If Pipewire is being used as a PulseAudio backend, the sample rate and bit depth, or Default Sample Specification
, can be checked with:
user $
pactl info
Server String: /run/user/1000/pulse/native Library Protocol Version: 35 Server Protocol Version: 35 Is Local: yes Client Index: 213 Tile Size: 65472 User Name: larry Host Name: gentoo Server Name: PulseAudio (on PipeWire 0.3.71) Server Version: 15.0.0 Default Sample Specification: float32le 2ch 192000Hz Default Channel Map: front-left,front-right Default Sink: alsa_output.usb-Generic_USB_Audio-00.pro-output-2 Default Source: alsa_input.usb-Focusrite_Scarlett_Solo_USB-00.pro-input-0
Setting the Sample Rate at Runtime
pw-metadata -n settings 0 clock.rate can be used to adjust the clock rate at runtime:
user $
pw-metadata -n settings 0 clock.rate 384000
Found "settings" metadata 31 set property: id:0 key:clock.rate value:384000 type:(null)
Results can be verified with pw-metadata -n settings, and this procedure can be used for other config values.
GUI patchbays
Any of the patchbays are great to use:
media-sound/helvum is a GTK-based pipewire patchbay. Simple and easy to use.
media-sound/qpwgraph is a QT-based pipewire patchbay. Can save layout. Monitor-streams are not joint with original objects, since sometimes not intuitive. Yet simple and easy to use.
coppwr advertise itself as low-level pipewire patchbay. Seems to be very interesting to use. If you used helvum or qpwgraph, this can be relatively easy to use. Currently there's only flatpak package for gentoo. To install, get Flatpak installed, then:
user $
flatpak install io.github.dimtpap.coppwr
If you are using KDE's volume applet and if you get a lot of useless objects like
Plasma PA*
which do not disappear after closing the menu at any of the patchbays, then just open and close a few times the menu for volume. Usually it removes all of such at an attempt.Streaming audio through RTP at network using pipewire native module
Check next documentation for that. Start the listener, then start broadcaster. At config for listener change 0.0.0.0 to source ip-address, for broadcaster config change to destination ip-address too.
Then use any patchbay to sink prefered audio stream to a new sink called localhost.localdomain with your names. Do the same for listener: use previously mentioned tools for streaming to prefered device.
If you got error code 69 at restarting pipewire, it seems config is bad. If error code is 70, it seems that it tried to create RTP connection and failed. Check whether ip-addresses and ports at configs are right.
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
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.
Stuttering recordings in applications like media-sound/ardour might be resolved using a WirePlumber script:
table.insert(alsa_monitor.rules, {
matches = {
{
-- replace device as described below
{ "node.name", "equals", "device" },
},
},
apply_properties = {
-- If 64 doesn't work, try bigger values that are a power of 2 (128, 256, 512, 1024, 2048, etc.)
["api.alsa.headroom"] = 64,
},
})
user $
wpctl status
user $
wpctl inspect <number> | grep node.name
* node.name = "alsa_output.usb-Lenovo_ThinkPad.analog-stereo"
. Replace device
in the script with the device from the output (in this example it would be alsa_output.usb-Lenovo_ThinkPad.analog-stereo
). The problem should be resolved after restarting PipeWire. If the issue is not resolved, more information can be found here or here.
Troubleshooting
Screensharing doesn't work with Chrome
Change "WebRTC PipeWire support" to "Enabled" from chrome://flags.
CS:GO (and other games using the Valve's Source engine)
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[5][6]:
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 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:
# 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
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:
...
modules = {
...
default = [
...
bluez5 # bluetooth support
...
]
...
Then run:
user $
systemctl --user restart pipewire-pulse.service
Restarting PipeWire after crash (with OpenRC)
When PipeWire crashes, all sound devices disappear. Three processes need to be created:
- pipewire
- wireplumber
- pipewire -c pipewire-pulse.conf
Do not run these directly. Instead, start them with:
user $
/usr/bin/gentoo-pipewire-launcher &
from the environment with a running D-Bus session bus (e.g. the desktop). An environment with a D-Bus session bus will have the DBUS_SESSION_BUS_ADDRESS variable set; if it is not set, refer to the OpenRC section for how to ensure a D-Bus session bus is running for the environment.
Crackling and stuttering
Crackling and stuttering might be reduced or eliminated by setting default.clock.min-quantum appropriately in pipewire.conf[7]:
default.clock.min-quantum = 2048
See also
- PulseAudio — a multi-platform, open source, sound server that provides a number of features on top of the low-level audio interface ALSA
- ALSA — 介绍了使用 ALSA(Advanced Linux Sound Architecture) 设置声卡的方法。
- Technical notes on the packaging of PipeWire
External resources
- https://bootlin.com/blog/an-introduction-to-pipewire/ - An introduction to PipeWire [June 2022]
- https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ - The PipeWire FAQ
- https://venam.nixers.net/blog/unix/2021/06/23/pipewire-under-the-hood.html - A blog explaining PipeWire from a unique perspective.
- https://lwn.net/Articles/847412/ - PipeWire: The Linux audio/video bus (LWN).
References
- ↑ https://www.gentoo.org/support/news-items/2022-07-29-pipewire-sound-server.html
- ↑ https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire#configuration-file-pipewireconf
- ↑ PipeWire's Issue 1523
- ↑ https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Migrate-PulseAudio#sink-inputsource-output-volumemute
- ↑ https://csgoguru.com/improve-your-csgo-sound-settings/
- ↑ https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/401
- ↑ Post on Gentoo forums. Retrieved on 2024-03-13.