diff --git a/doc/dox/overview.dox b/doc/dox/overview.dox index 24ed4aaa5..c19518b0c 100644 --- a/doc/dox/overview.dox +++ b/doc/dox/overview.dox @@ -71,7 +71,7 @@ and the remaining two channels as stereo output. \image html Routing-Remap.drawio.svg Most of these settings need configuration files, there is no GUI yet. -To unlock the full power of PipeWire, you will have to dive into the deeper areas of Lake Audio! +To unlock the full power of PipeWire, you will have to dive into the deeper areas of Lake Config! # What do I need? @@ -85,9 +85,133 @@ PipeWire, as well as WirePlumber, run in *userspace,* so interfacing with them w happens in *user context* with the `--user` flag, for example `systemctl --user status pipewire.service` or `journalctl --user -fu wireplumber.service`. -**WirePlumber** provides [Session Management](https://pipewire.pages.freedesktop.org/wireplumber/design/understanding_session_management.html): It enables new devices when they appear on ALSA, creates and configures nodes, +The session manager is normally **WirePlumber** – it describes its work on [Session Management](https://pipewire.pages.freedesktop.org/wireplumber/design/understanding_session_management.html): +It enables new devices when they appear on ALSA, creates and configures nodes, create links between nodes to route sound from an application to a consumer, etc. +## PipeWire Tools + +PipeWire alone includes a \ref page_programs "considerable number of programs". +This is just a short selection of tools that you will need more often. + +- [qpwgraph](https://gitlab.freedesktop.org/rncbc/qpwgraph) gives a quick visual overview over the current system configuration with nodes and links between them. + It also allows creating and deleting links on the fly. +- `pw-dump` dumps the whole configuration as JSON, which is extremely helpful for debugging. +- `pw-cli` allows to query and configure PipeWire, for example setting a sound card profile (like Stereo, Pro Audio, 7.1 Surround) with + the command `pw-cli s Profile CARD_ID "{index: PROFILE_ID, save: true}"`. You can also do it in the interactive mode of `pw-cli`. **Important:** In interactive mode, do *not* use quotes around JSON data. +- `wpctl` interfaces with WirePlumber, for example `wpctl status` shows an ASCII representation of the nodes, sources, sinks, and routing. + +# Configuration Basics + +This section gives a short configuration overview, for the complete reference see the \ref page_config "Configuration" reference. + +Both PipeWire and WirePlumber have a set of config files for configuring different *sections* like `node.rules`. +They use the same “SPA JSON” format. +Configuration files are loaded from different files/directories and then merged based on their priority. +For example, settings from `$HOME/.config/pipewire/pipewire.conf` have priority over those in `/etc/pipewire/pipewire.conf`, +and all settings in config files in `$HOME/.config/pipewire/pipewire.conf.d/` have least priority. + + +## PipeWire Server Configuration + +The **PipeWire server configuration** configures the PipeWire instance, defines which modules PipeWire should load, adds device rules, etc. + +- Location: `pipewire/pipewire.conf` +- Docs: \ref page_man_pipewire_conf_5 "pipewire.conf" +- Configures: `context.exec`, `context.modules`, `context.properties`, `context.spa-libs`, `device.rules`, `node.rules` + +## PipeWire Client Configuration + +The **PipeWire client configuration** contains configuration for PipeWire and ALSA clients. +For example, if VLC uses the PipeWire or ALSA backend, its runtime behaviour can be modified with a rule in `stream.rules` +which defines to always route `vlc` sound output to Bluetooth earbuds and `pw-play` to a stereo headset. + +- Location: `pipewire/client.conf`, for example `~/.config/pipewire/client.conf.d/` +- Docs: \ref page_man_pipewire-client_conf_5 "client.conf" +- Docs: \ref page_man_pipewire-props_7 "PipeWire object property reference" (also contains WirePlumber related options!) +- Configures: `alsa.properties`, `alsa.rules`, `stream.properties`, `stream.rules` + +## PulseAudio, JACK, and other Configuration + +The **PulseAudio/JACK configuration** contains configuration for PipeWire’s PulseAudio and JACK servers. + +- Docs: \ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf" +- Docs: \ref page_man_pipewire-jack_conf_5 "jack.conf" + +## WirePlumber Configuration + +The **WirePlumber configuration** configures general WirePlumber aspects (should it even bring up ALSA devices +or save/restore user settings configured with e.g. `pavucontrol`) and also ALSA/Bluetooth monitor aspects +(choosing a default profile like Stereo or 7.1, setting device priorities that affect default routing, setting device properties, etc.). + +- Location: `wireplumber.conf`, e.g. `~/.config/wireplumber/wireplumber.conf.d/` +- Docs: [WirePlumber daemon configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html) +- Docs: [ALSA configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/alsa.html) and more +- Configures: `context`, `device`, `linking`, `wireplumber`, `monitor` (like `monitor.alsa.properties`, `monitor.alsa.rules`), `node` (like `node.software-dsp`),`support`, `policy` + + + +Rules in config file can define default outputs for specific nodes (e.g. VLC sound always goes to the 7.1 sound card). +[ArchLinux: WirePlumber](https://wiki.archlinux.org/title/WirePlumber) gives a short introduction to using them. + +## Writing Rules and Examples + +Rules often need IDs of nodes or other components. +One way to find them is by using the `pwdump` tool and then searching in the JSON output with `pwdump | less`. +It can also print specific types only, for example `pwdump Node | less`. + +Rules can use regular expression when strings start with `~`, for example `"~alsa.*"`. +This is explained in [PipeWire: Working with rules](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/modifying_configuration.html#working-with-rules). + +```text +# Goes to e.g. ~/.config/wireplumber/wireplumber.conf.d/wireplumber-default-device.conf +# Restart wireplumber.service so it loads the rules: +# systemctl restart --user wireplumber.service +# This sample rule increases the priority of the stereo output on a Raspberry Pi, +# so it is used by default. +monitor.alsa.rules = [ + { + matches = [ + { + # An exact match could be the following name: + # node.name = "alsa_output.platform-fe00b840.mailbox.stereo-fallback" + # Instead, let’s use a regular expression to keep the configuration portable: + node.name = "~alsa_output.platform-.*.mailbox.stereo-fallback" + } + ] + actions = { + update-props = { + priority.driver = 3000 + priority.session = 3000 + } + } + } +] + +``` + +```text +# Goes to ~/.config/pipewire/client.conf.d/default-pw-play-output.conf +# Restart wireplumber.service so it loads the rules +# This sample rule uses a specific sound card for playback with pw-play. +# If it does not exist, WirePlumber takes the next suitable one. +stream.rules = [ + { + matches = [ + { + application.name = "pw-play" + } + ] + actions = { + update-props = { + target.object = "alsa_output.usb-PreSonus_Audio_AudioBox_USB-01.pro-output-0" + } + } + } +] + +``` + # Concepts ## The PipeWire Server