--- /dev/null
+---
+edit_link: ''
+title: Session Manager Configuration
+origin_url: >-
+ https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/wireplumber_configuration.md
+---
+
+<!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/audio-developer-guides-audio-book.yml -->
+
+# 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.
Code Review / AGL / documentation.git / blobdiff