diff options
| -rw-r--r-- | docs/audio-book.yml | 8 | ||||
| -rw-r--r-- | docs/audio/pipewire.md | 108 | ||||
| -rw-r--r-- | docs/audio/wireplumber_configuration.md | 441 |
3 files changed, 491 insertions, 66 deletions
diff --git a/docs/audio-book.yml b/docs/audio-book.yml index f7e3a53..e11002c 100644 --- a/docs/audio-book.yml +++ b/docs/audio-book.yml @@ -8,7 +8,9 @@ books: author: "AGL" version: master chapters: - - url: audio/bluez-alsa.md - name: bluez-alsa - url: audio/pipewire.md - name: pipewire
\ No newline at end of file + name: Overview + - url: audio/wireplumber_configuration.md + name: Session Manager Configuration + - url: audio/bluez-alsa.md + name: Bluetooth diff --git a/docs/audio/pipewire.md b/docs/audio/pipewire.md index 02b2024..626bdd3 100644 --- a/docs/audio/pipewire.md +++ b/docs/audio/pipewire.md @@ -1,4 +1,4 @@ -# Audio System +# PipeWire Audio System Overview ## Overview @@ -12,67 +12,44 @@ using the *libpipewire* library as a front-end to that socket. ## Configuration -Currently in AGL Happy Halibut (8.0.0) there are limited configuration options -for the PipeWire audio stack. In a future release it is expected that a new -configuration mechanism will be available, with more flexibility, -comprehensibility and options. +The Audio System's configuration is mainly done in the session manager. +The session manager is the service that dictates policy, therefore this is +the place to configure options such as device properties, device priorities +and application linking policy. + +An extensive listing of configuration options for the session manager, +WirePlumber, is available in the next chapter, +[Session Manager Configuration](./wireplumber_configuration.md) + +### wireplumber-cli + +WirePlumber supports runtime configuration of devices, through the +`wireplumber-cli` tool. This tool supports the following sub-commands: + +* `wireplumber-cli ls-endpoints`: + This lists all the known audio endpoints, including devices and applications + that are streaming. In front of the devices, there is a `*` (star) character + on the "default" device, i.e. the device that is chosen by default to link + applications to. The volume and mute status of the devices is also shown. +* `wireplumber-cli set-default [id]`: + Changes the default endpoint of a specific category (capture or playback, + determined automatically by the endpoint's type) + and sets it to be the endpoint with the specified `[id]`. The id is the + number shown in front of each endpoint's name in `ls-endpoints`. +* `wireplumber-cli set-volume [id] [vol]`: + Sets the volume of `[id]` to `[vol]`. `[vol]` must be a floating point + number between 0.0 (0%) and 1.0 (100%). +* `wireplumber-cli device-node-props`: + Lists all the properties of the device nodes, useful for writing `.endpoint` + configuration files, as discussed in the _Session Management Configuration_ + chapter. + +Due to a system limitation, before running this tool on the command line, +you need to export the `XDG_RUNTIME_DIR` environment variable, like this: -### wireplumber.conf - -The most useful configuration options for the audio stack can be found -in **/etc/wireplumber/wireplumber.conf**. - -Through this file it is possible to configure: - -* The default playback and capture devices: -``` - "default-playback-device": <"hw:0,0">, - "default-capture-device": <"hw:0,0">, -``` - -You may change these lines to reflect the configuration of your board. The ALSA -device strings that you use there **must** start with *hw:* and **must** use -exactly 2 integer numbers, one for the device and one for the subdevice. Other -strings are not understood as of the time of writing of this document. - -* The streams that are available for applications to use: -``` -load-module C libwireplumber-module-mixer { - "streams": <["Master", "Multimedia", "Navigation", "Communication", "Emergency"]> -} -... -load-module C libwireplumber-module-pw-alsa-udev { - "streams": <["Multimedia", "Navigation", "Communication", "Emergency"]> -} ``` - -You may modify these arrays to include the streams that you would like to be -available on your system. These strings are matched against the strings that -the applications declare as their *role*. - -*Note*: the *Master* stream on the mixer is a special stream that enables the -master volume control. Removing it will remove the ability to have a master -volume and may break applications that expect it to be available. This stream -should not be listed in the configuration for *libwireplumber-module-pw-alsa-udev* - -*Note*: the stream names should be aligned everywhere they appear in this -configuration file. Listing different streams in different places may result in -undefined behaviour. - -* The priorities of the roles: +export XDG_RUNTIME_DIR=/run/user/1001 ``` - "role-priorities": <{ - "Multimedia": 1, - "Communication": 5, - "Navigation": 8, - "Emergency": 10 - }> -``` - -A stream with a higher priority will always take over the audio output, pausing -any other lower priority streams in the meantime. - -Currently there is no way of configuring other policy options. ### pipewire.conf @@ -91,7 +68,7 @@ and it is beyond the scope of this document to describe it all. For playback and capture, applications should use *struct pw_stream* and its associated methods. There are usage examples for it in the PipeWire -[source code](https://github.com/PipeWire/pipewire). +[source code](https://gitlab.freedesktop.org/pipewire/pipewire). ### Native API - GStreamer (Recommended) @@ -138,7 +115,9 @@ the ALSA API will likely block. ### Audiomixer service -See the separate audiomixer service documentation. +See the separate +[agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) +documentation. ## Runtime mechanics @@ -162,12 +141,15 @@ it... The PipeWire and WirePlumber daemons can be configured to be more verbose by editing **/etc/pipewire/environment** -* Set G_MESSAGES_DEBUG=all to enable WirePlumber's debug output. -* Set PIPEWIRE_DEBUG=n (n=1-5) to enable PipeWire's debug output. +* Set `G_MESSAGES_DEBUG=all` to enable WirePlumber's debug output. +* Set `PIPEWIRE_DEBUG=n` (n=1-5) to enable PipeWire's debug output. All messages will be available in the systemd journal, inspectable with journalctl. +`PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the +most verbose and 1 the least verbose. + ### AGL applications & services (AppFW) For AGL applications and services that are installed by the app framework, diff --git a/docs/audio/wireplumber_configuration.md b/docs/audio/wireplumber_configuration.md new file mode 100644 index 0000000..4be1824 --- /dev/null +++ b/docs/audio/wireplumber_configuration.md @@ -0,0 +1,441 @@ +# WirePlumber Configuration + +WirePlumber is a heavily modular daemon. By itself, it doesn't do anything +except load the configured modules. All the rest of the logic is implemented +inside those modules. + +Modular design ensures that it is possible to swap the implementation of +specific functionality without having to re-implement the rest of it, allowing +flexibility on target-sensitive parts, such as policy management and +making use of non-standard hardware. + +## `wireplumber.conf` + +This is WirePlumber's main configuration file. It is read at startup, before +connecting to the PipeWire daemon. Its purpose is to list all the modules +that need to be loaded by WirePlumber. + +The format of this file is custom and resembles a script with commands: + +``` +# comment +command parameter1 parameter2 ... +``` + +Lines are executed in the order they appear and each of them executes an +action defined by the command. Lines starting with `#` are treated as comments +and ignored. Possible commands are: + +* `add-spa-lib` + + Associates SPA plugin names with the names of the SPA modules that they + can be loaded from. This takes 2 parameters: a name pattern and a library name. + + This actually does not load the SPA plugin, it only calls `pw_core_add_spa_lib` + with the 2 paramteres given as arguments. As a consequence, it is safe to + call this even if the SPA module is not actually installed on the system. + + Example: + ``` + add-spa-lib api.alsa.* alsa/libspa-alsa + ``` + + In this example, we let `libpipewire` know that any SPA plugin whose name + starts with `api.alsa.` can be loaded from the SPA module + `alsa/libspa-alsa.so` (relative to the standard SPA modules directory). + +* `load-pipewire-module` + + Loads a `libpipewire` module. This is similar to the `load-module` commands + that would appear on `pipewire.conf`, the configuration file of the PipeWire + daemon. + + This takes at least 1 parameter, the module name, and optionally any module + arguments, in the format that they would be given in `pipewire.conf` + + Format: + ``` + load-pipewire-module module-name some-argument some-property=value + ``` + Example: + ``` + load-pipewire-module libpipewire-module-client-device + ``` + + This command does not affect the PipeWire daemon by any means. It exists + simply to allow loading `libpipewire` modules in the pipewire core that + runs inside WirePlumber. This is usually useful to load pipewire protocol + extensions, so that you can export custom objects to PipeWire and other + clients. + +* `load-module` + + Loads a WirePlumber module. This takes 2 arguments and an optional parameter + block. + + Format: + ``` + load-module ABI module-name { + "parameter": <"value"> + } + ``` + + The `ABI` parameter specifies the binary interface that WirePlumber shall use + to load this module. Currently, the only supported ABI is `C`. It exists to + allow future expansion, writing modules in other languages. + + The `module-name` should be the name of the `.so` file without the `.so` + extension. + + Optionally, if the `load-module` line ends with a `{`, the next lines up to + and including the next matching `}` are treated as a parameter block. + This block essentially is a + [GVariant](https://developer.gnome.org/glib/stable/glib-GVariant.html) + of type + [`a{sv}`](https://developer.gnome.org/glib/stable/gvariant-format-strings.html) + in the + [GVariant Text Format](https://developer.gnome.org/glib/stable/gvariant-text.html). + As a rule of thumb, parameter names in this block must always be strings + enclosed in double quotes, the separation between names and values is done + with the `:` character and values, regardless of their inner type, must always + be enclosed in `<` `>`. + + Note that starting the parameter block on the next line is an error. The + starting brace (`{`) must always be on the `load-module` line. + + Example: + ``` + load-module C libwireplumber-module-monitor { + "factory": <"api.alsa.enum.udev">, + "flags": <["use-adapter", "activate-devices"]> + } + ``` + + Parameters are module-dependent. They are passed as a GVariant in the + module's initialization function and it is up to the module to interpret + their meaning. WirePlumber does not have any reserved parameters. + +## Location of configuration files + +WirePlumber's default location of its configuration files is determined at +compile time by the build system. Typically, it ends up being `/etc/wireplumber`. + +In more detail, this is controlled by the `--sysconfdir` meson option. When +this is set to an absolute path, such as `/etc`, the location of the +configuration files is set to be `$sysconfdir/wireplumber`. When this is set +to a relative path, such as `etc`, then the installation prefix (`--prefix`) +is prepended to the path: `$prefix/$sysconfdir/wireplumber` + +WirePlumber expects its `wireplumber.conf` to reside in that directory. +It is possible to override that at runtime by setting the +`WIREPLUMBER_CONFIG_FILE` environment variable: + +``` +WIREPLUMBER_CONFIG_FILE=src/config/wireplumber.conf wireplumber +``` + +It is also possible to override the whole configuration directory, so that +all other configuration files are being read from a different location as well, +by setting the `WIREPLUMBER_CONFIG_DIR` environment variable: +``` +WIREPLUMBER_CONFIG_DIR=src/config wireplumber +``` + +## Location of modules + +### WirePlumber modules + +Like with configuration files, WirePlumber's default location of its modules is +determined at compile time by the build system. Typically, it ends up being +`/usr/lib/wireplumber-0.1` (or `/usr/lib/<arch-triplet>/wireplumber-0.1` on +multiarch systems) + +In more detail, this is controlled by the `--libdir` meson option. When +this is set to an absolute path, such as `/lib`, the location of the +modules is set to be `$libdir/wireplumber-$abi_version`. When this is set +to a relative path, such as `lib`, then the installation prefix (`--prefix`) +is prepended to the path: `$prefix/$libdir/wireplumber-$abi_version`. + +It is possible to override this directory at runtime by setting the +`WIREPLUMBER_MODULE_DIR` environment variable: +``` +WIREPLUMBER_MODULE_DIR=build/modules wireplumber +``` + +### PipeWire and SPA modules + +PipeWire and SPA modules are not loaded from the same location as WirePlumber's +modules. They are loaded from the location that PipeWire loads them. + +It is also possible to override these locations by using environment variables: +`SPA_PLUGIN_DIR` and `PIPEWIRE_MODULE_DIR`. For more details, refer to +PipeWire's documentation. + +# module-monitor + +This module internally loads a SPA "device" object which enumerates all the +devices of a certain subsystem. Then it listens for "node" objects that are +being created by this device and exports them to PipeWire, after adjusting +their properties to provide enough context. + +`module-monitor` does not read any configuration files, however, it supports +configuration through parameters defined in the main `wireplumber.conf`. +Possible parameters are: + +* `factory` + + A string that specifies the name of the SPA factory that loads the intial + "device" object. + + Well-known factories are: + + * "api.alsa.enum.udev" - Discovers ALSA devices via udev + * "api.v4l2.enum.udev" - Discovers V4L2 devices via udev + * "api.bluez5.enum.dbus" - Discovers bluetooth devices by calling bluez5 API via D-Bus + + * `flags` + + An array of strings that enable specific functionality in the monitor. + Possible flags include: + + * "use-adapter" + + Instructs the monitor to wrap all the created nodes in an "adapter" + SPA node, which provides automatic port splitting/merging and format/rate + conversion. This should be always enabled for audio device nodes. + + * "local-nodes" + + Instructs the monitor to run all the created nodes locally in in the + WirePlumber process, instead of the default behavior which is to create + the nodes in the PipeWire process. This is useful for bluetooth nodes, + which should run outside of the main PipeWire process for performance + reasons. + + * "activate-devices" + + Instructs the monitor to automatically set the device profile to "On", + so that the nodes are created. If not specified, the profile must be + set externally by the user before any nodes appear. + +# module-config-endpoint + +This module creates endpoints when WirePlumber detects new nodes in the +pipewire graph. Nodes themselves can be created in two ways: +Device modes are being created by "monitors" that watch a specific subsystem +(udev, bluez, etc...) for devices. Client nodes are being created by client +applications that try to stream to/from pipewire. As soon as a node is created, +the `module-config-endpoint` iterates through all the `.endpoint` configuration +files, in the order that is determined by the `match-node.priority` field, +and tries to match the node to the node description in the `[match-node]` table. +Upon a successful match, a new endpoint that follows the description in the +`[endpoint]` table is created. + +## `*.endpoint` configuration files + +These files are TOML v0.5 files. At the top-level, they must contain exactly +2 tables: `[match-node]` and `[endpoint]` + +The `[match-node]` table contains properties that match a pipewire node that +exists on the graph. Possible fields of this table are: + +* `priority` + + Specifies the order in which the `.endpoint` files are being searched for a + match with a node. If a node matches the description of more than one + `.endpoint` file, the one with the highest priority wins. + + The type of this field is unsigned integer. Bigger numbers mean higher + priority. + +* `properties` + + This is a TOML array of tables, where each table must contain two fields: + `name` and `value`, both being strings. Each table describes a match against + one of the pipewire properties of the node. For a successful node match, all + the described properties must match with the node. + + The value of the `name` field must match exactly the name of the pipewire + property, while the value of the `value` field can contain '*' (wildcard) + and '?' (joker), adhering to the rules of the + [GLib g_pattern_match() function](https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html). + + When writing `.endpoint` files, a useful utility that you can use to list + device node properties is: + + ``` + $ wireplumber-cli device-node-props + ``` + + Another way to figure out some of these properties *for ALSA nodes* is + by parsing the aplay/arecord output. For example, this line from `aplay -l` + is interpreted as follows: + + ``` + card 0: PCH [HDA Intel PCH], device 2: ALC3246 [ALC3246 Analog] + ``` + + ``` + { name = "api.alsa.path", value = "hw:0,2" }, + { name = "api.alsa.card", value = "0" }, + { name = "api.alsa.card.id", value = "PCH" }, + { name = "api.alsa.card.name", value = "HDA Intel PCH" }, + { name = "api.alsa.pcm.device", value = "2" }, + { name = "api.alsa.pcm.id", value = "ALC3246" }, + { name = "api.alsa.pcm.name", value = "ALC3246 Analog" }, + ``` + +The `[endpoint]` table contains a description of the endpoint to be created. +Possible fields of this table are: + +* `type` + + Required. Specifies the factory to be used for construction. + The only well-known factory at the moment of writing is: `pw-audio-softdsp-endpoint` + +* `direction` + + Required. Can be set to either `"sink"` or `"source"`. Specifies the + direction of the media flow of this endpoint. A `source` is an endpoint that + produces data (i.e. an audio capture device or a playback application) and + a `sink` is an endpoint that consumes data (audio playback device or + capture application). + +* `name` + + Optional. The name of the newly created endpoint. If not specified, + the endpoint is named after the node (from the `node.name` property of the node). + +* `media_class` + + Optional. A string that specifies an override for the `media.class` property + of the node. It can be used in special circumstances to declare that an + endpoint is dealing with a different type of data. This is only useful in + combination with a policy implementation that is aware of this media class. + +* `priority` + + Optional. An unsigned integer that specifies the order in which endpoints are + chosen to be the default of a specific device group. Possible device groups + are (determined by the endpoint's `media.class`): + + * Audio/Sink + * Audio/Source + * Video/Source + + Every time a new device endpoint is created, wireplumber picks the "default" + of the group that it belongs to, based on this priority number: the endpoint + with the biggest priority number wins. + + If not specified, the default priority of an endpoint is equal to zero + (i.e. the lowest priority). + +* `streams` + + Optional. Specifies the name of a `.streams` file that contains the + descriptions of the streams to create for this endpoint. This currently + specific to the implementation of the `pw-audio-softdsp-endpoint` and might + change in the future. + +## `*.streams` configuration files + +These files contain lists of streams with their names and priorities. +They are TOML v0.5 files. + +Each `.streams` file must contain exactly one top-level array of tables, +called `streams`. Every table must contain exactly two fields: +`name` and `priority`. + +The `name` of each stream is used to create the streams on new endpoints. + +The `priority` of each stream is being interpreted by the policy module to +apply restrictions on which app can use the stream at a given time. + +# module-config-policy + +This module implements demo-quality policy management that is partly driven +by configuration files. The configuration files that this module reads are +described below: + +## `*.endpoint-link` + +These files contain rules to link endpoints with each other. +They are TOML v0.5 files. + +Endpoints are normally created by another module, such +as `module-config-endpoint` which is described above. +As soon as an endpoint is created, the `module-config-policy` uses the +information gathered from the `.endpoint-link` files in order to create a +link to another endpoint. + +`.endpoint-link` files can contain 3 top-level tables: +* `[match-endpoint]`, required +* `[target-endpoint]`, optional +* `[endpoint-link]`, required + +The `[match-endpoint]` table contains properties that match an endpoint that +exists on the graph. Possible fields of this table are: + +* `priority` + + Specifies the order in which the `.endpoint-link` files are being searched + for a match with an endpoint. If an endpoint matches the description of more + than one `.endpoint-link` file, the one with the highest priority wins. + + The type of this field is unsigned integer. Bigger numbers mean higher + priority. + +* `direction` + + Required. Can be set to either `"sink"` or `"source"`. Specifies the + direction of the media flow of this endpoint. A `source` is an endpoint that + produces data (i.e. an audio capture device or a playback application) and + a `sink` is an endpoint that consumes data (audio playback device or + capture application). + +* `name` + + Optional. The name of the endpoint. It is possible to use wildcards here to + match only parts of the name. + +* `media_class` + + Optional. A string that specifies the `media.class` that the endpoint + must have in order to match. + +* `properties` + + This is a TOML array of tables, where each table must contain two fields: + `name` and `value`, both being strings. Each table describes a match against + one of the pipewire properties of the endpoint. For a successful endpoint + match, all the described properties must match with the endpoint. + +The `[target-endpoint]` table contains properties that match an endpoint that +exists on the graph. The purpose of this table is to match a second endpoint +that the original matching endpoint from `[match-endpoint]` will be linked to. +If not specified, `module-config-policy` will look for the session "default" +endpoint for the type of media that the matching endpoint produces or consumes +and will use that as a target. Possible fields of this table are: + +* `direction`, `name`, `media_class`, `properties` + + All these fields are permitted and behave exactly as described above for the + `[match-endpoint]` table. + +* `stream` + + This field specifies a stream name that the link will use on the target + endpoint. If it is not specified, the stream name is acquired from the + `media.role` property of the matching endpoint. If specified, the value of + this field overrides the `media.role`. + +The `[endpoint-link]` table specifies properties of the link. Possible fields +of this table are: + +* `keep` + + A boolean field. If set to true, the link is always kept active and ignores + policy rules regarding corking or stream priority. This link will also not + affect the rules for other links. For example, if a keep=true link is + activating a high priority stream, lower priority streams can still work on + the same target endpoint for links with keep=false. |