3 title: Session Manager Configuration
5 https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/wireplumber_configuration.md
8 <!-- 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 -->
10 # WirePlumber Configuration
12 WirePlumber is a heavily modular daemon. By itself, it doesn't do anything
13 except load the configured modules. All the rest of the logic is implemented
16 Modular design ensures that it is possible to swap the implementation of
17 specific functionality without having to re-implement the rest of it, allowing
18 flexibility on target-sensitive parts, such as policy management and
19 making use of non-standard hardware.
23 This is WirePlumber's main configuration file. It is read at startup, before
24 connecting to the PipeWire daemon. Its purpose is to list all the modules
25 that need to be loaded by WirePlumber.
27 The format of this file is custom and resembles a script with commands:
31 command parameter1 parameter2 ...
34 Lines are executed in the order they appear and each of them executes an
35 action defined by the command. Lines starting with `#` are treated as comments
36 and ignored. Possible commands are:
40 Associates SPA plugin names with the names of the SPA modules that they
41 can be loaded from. This takes 2 parameters: a name pattern and a library name.
43 This actually does not load the SPA plugin, it only calls `pw_core_add_spa_lib`
44 with the 2 paramteres given as arguments. As a consequence, it is safe to
45 call this even if the SPA module is not actually installed on the system.
49 add-spa-lib api.alsa.* alsa/libspa-alsa
52 In this example, we let `libpipewire` know that any SPA plugin whose name
53 starts with `api.alsa.` can be loaded from the SPA module
54 `alsa/libspa-alsa.so` (relative to the standard SPA modules directory).
56 * `load-pipewire-module`
58 Loads a `libpipewire` module. This is similar to the `load-module` commands
59 that would appear on `pipewire.conf`, the configuration file of the PipeWire
62 This takes at least 1 parameter, the module name, and optionally any module
63 arguments, in the format that they would be given in `pipewire.conf`
67 load-pipewire-module module-name some-argument some-property=value
71 load-pipewire-module libpipewire-module-client-device
74 This command does not affect the PipeWire daemon by any means. It exists
75 simply to allow loading `libpipewire` modules in the pipewire core that
76 runs inside WirePlumber. This is usually useful to load pipewire protocol
77 extensions, so that you can export custom objects to PipeWire and other
82 Loads a WirePlumber module. This takes 2 arguments and an optional parameter
87 load-module ABI module-name {
88 "parameter": <"value">
92 The `ABI` parameter specifies the binary interface that WirePlumber shall use
93 to load this module. Currently, the only supported ABI is `C`. It exists to
94 allow future expansion, writing modules in other languages.
96 The `module-name` should be the name of the `.so` file without the `.so`
99 Optionally, if the `load-module` line ends with a `{`, the next lines up to
100 and including the next matching `}` are treated as a parameter block.
101 This block essentially is a
102 [GVariant](https://developer.gnome.org/glib/stable/glib-GVariant.html)
104 [`a{sv}`](https://developer.gnome.org/glib/stable/gvariant-format-strings.html)
106 [GVariant Text Format](https://developer.gnome.org/glib/stable/gvariant-text.html).
107 As a rule of thumb, parameter names in this block must always be strings
108 enclosed in double quotes, the separation between names and values is done
109 with the `:` character and values, regardless of their inner type, must always
110 be enclosed in `<` `>`.
112 Note that starting the parameter block on the next line is an error. The
113 starting brace (`{`) must always be on the `load-module` line.
117 load-module C libwireplumber-module-monitor {
118 "factory": <"api.alsa.enum.udev">,
119 "flags": <["use-adapter", "activate-devices"]>
123 Parameters are module-dependent. They are passed as a GVariant in the
124 module's initialization function and it is up to the module to interpret
125 their meaning. WirePlumber does not have any reserved parameters.
127 ## Location of configuration files
129 WirePlumber's default location of its configuration files is determined at
130 compile time by the build system. Typically, it ends up being `/etc/wireplumber`.
132 In more detail, this is controlled by the `--sysconfdir` meson option. When
133 this is set to an absolute path, such as `/etc`, the location of the
134 configuration files is set to be `$sysconfdir/wireplumber`. When this is set
135 to a relative path, such as `etc`, then the installation prefix (`--prefix`)
136 is prepended to the path: `$prefix/$sysconfdir/wireplumber`
138 WirePlumber expects its `wireplumber.conf` to reside in that directory.
139 It is possible to override that at runtime by setting the
140 `WIREPLUMBER_CONFIG_FILE` environment variable:
143 WIREPLUMBER_CONFIG_FILE=src/config/wireplumber.conf wireplumber
146 It is also possible to override the whole configuration directory, so that
147 all other configuration files are being read from a different location as well,
148 by setting the `WIREPLUMBER_CONFIG_DIR` environment variable:
150 WIREPLUMBER_CONFIG_DIR=src/config wireplumber
153 ## Location of modules
155 ### WirePlumber modules
157 Like with configuration files, WirePlumber's default location of its modules is
158 determined at compile time by the build system. Typically, it ends up being
159 `/usr/lib/wireplumber-0.1` (or `/usr/lib/<arch-triplet>/wireplumber-0.1` on
162 In more detail, this is controlled by the `--libdir` meson option. When
163 this is set to an absolute path, such as `/lib`, the location of the
164 modules is set to be `$libdir/wireplumber-$abi_version`. When this is set
165 to a relative path, such as `lib`, then the installation prefix (`--prefix`)
166 is prepended to the path: `$prefix/$libdir/wireplumber-$abi_version`.
168 It is possible to override this directory at runtime by setting the
169 `WIREPLUMBER_MODULE_DIR` environment variable:
171 WIREPLUMBER_MODULE_DIR=build/modules wireplumber
174 ### PipeWire and SPA modules
176 PipeWire and SPA modules are not loaded from the same location as WirePlumber's
177 modules. They are loaded from the location that PipeWire loads them.
179 It is also possible to override these locations by using environment variables:
180 `SPA_PLUGIN_DIR` and `PIPEWIRE_MODULE_DIR`. For more details, refer to
181 PipeWire's documentation.
185 This module internally loads a SPA "device" object which enumerates all the
186 devices of a certain subsystem. Then it listens for "node" objects that are
187 being created by this device and exports them to PipeWire, after adjusting
188 their properties to provide enough context.
190 `module-monitor` does not read any configuration files, however, it supports
191 configuration through parameters defined in the main `wireplumber.conf`.
192 Possible parameters are:
196 A string that specifies the name of the SPA factory that loads the intial
199 Well-known factories are:
201 * "api.alsa.enum.udev" - Discovers ALSA devices via udev
202 * "api.v4l2.enum.udev" - Discovers V4L2 devices via udev
203 * "api.bluez5.enum.dbus" - Discovers bluetooth devices by calling bluez5 API via D-Bus
207 An array of strings that enable specific functionality in the monitor.
208 Possible flags include:
212 Instructs the monitor to wrap all the created nodes in an "adapter"
213 SPA node, which provides automatic port splitting/merging and format/rate
214 conversion. This should be always enabled for audio device nodes.
218 Instructs the monitor to run all the created nodes locally in in the
219 WirePlumber process, instead of the default behavior which is to create
220 the nodes in the PipeWire process. This is useful for bluetooth nodes,
221 which should run outside of the main PipeWire process for performance
226 Instructs the monitor to automatically set the device profile to "On",
227 so that the nodes are created. If not specified, the profile must be
228 set externally by the user before any nodes appear.
230 # module-config-endpoint
232 This module creates endpoints when WirePlumber detects new nodes in the
233 pipewire graph. Nodes themselves can be created in two ways:
234 Device modes are being created by "monitors" that watch a specific subsystem
235 (udev, bluez, etc...) for devices. Client nodes are being created by client
236 applications that try to stream to/from pipewire. As soon as a node is created,
237 the `module-config-endpoint` iterates through all the `.endpoint` configuration
238 files, in the order that is determined by the `match-node.priority` field,
239 and tries to match the node to the node description in the `[match-node]` table.
240 Upon a successful match, a new endpoint that follows the description in the
241 `[endpoint]` table is created.
243 ## `*.endpoint` configuration files
245 These files are TOML v0.5 files. At the top-level, they must contain exactly
246 2 tables: `[match-node]` and `[endpoint]`
248 The `[match-node]` table contains properties that match a pipewire node that
249 exists on the graph. Possible fields of this table are:
253 Specifies the order in which the `.endpoint` files are being searched for a
254 match with a node. If a node matches the description of more than one
255 `.endpoint` file, the one with the highest priority wins.
257 The type of this field is unsigned integer. Bigger numbers mean higher
262 This is a TOML array of tables, where each table must contain two fields:
263 `name` and `value`, both being strings. Each table describes a match against
264 one of the pipewire properties of the node. For a successful node match, all
265 the described properties must match with the node.
267 The value of the `name` field must match exactly the name of the pipewire
268 property, while the value of the `value` field can contain '*' (wildcard)
269 and '?' (joker), adhering to the rules of the
270 [GLib g_pattern_match() function](https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html).
272 When writing `.endpoint` files, a useful utility that you can use to list
273 device node properties is:
276 $ wireplumber-cli device-node-props
279 Another way to figure out some of these properties *for ALSA nodes* is
280 by parsing the aplay/arecord output. For example, this line from `aplay -l`
281 is interpreted as follows:
284 card 0: PCH [HDA Intel PCH], device 2: ALC3246 [ALC3246 Analog]
288 { name = "api.alsa.path", value = "hw:0,2" },
289 { name = "api.alsa.card", value = "0" },
290 { name = "api.alsa.card.id", value = "PCH" },
291 { name = "api.alsa.card.name", value = "HDA Intel PCH" },
292 { name = "api.alsa.pcm.device", value = "2" },
293 { name = "api.alsa.pcm.id", value = "ALC3246" },
294 { name = "api.alsa.pcm.name", value = "ALC3246 Analog" },
297 The `[endpoint]` table contains a description of the endpoint to be created.
298 Possible fields of this table are:
302 Required. Specifies the factory to be used for construction.
303 The only well-known factory at the moment of writing is: `pw-audio-softdsp-endpoint`
307 Required. Can be set to either `"sink"` or `"source"`. Specifies the
308 direction of the media flow of this endpoint. A `source` is an endpoint that
309 produces data (i.e. an audio capture device or a playback application) and
310 a `sink` is an endpoint that consumes data (audio playback device or
311 capture application).
315 Optional. The name of the newly created endpoint. If not specified,
316 the endpoint is named after the node (from the `node.name` property of the node).
320 Optional. A string that specifies an override for the `media.class` property
321 of the node. It can be used in special circumstances to declare that an
322 endpoint is dealing with a different type of data. This is only useful in
323 combination with a policy implementation that is aware of this media class.
327 Optional. An unsigned integer that specifies the order in which endpoints are
328 chosen to be the default of a specific device group. Possible device groups
329 are (determined by the endpoint's `media.class`):
335 Every time a new device endpoint is created, wireplumber picks the "default"
336 of the group that it belongs to, based on this priority number: the endpoint
337 with the biggest priority number wins.
339 If not specified, the default priority of an endpoint is equal to zero
340 (i.e. the lowest priority).
344 Optional. Specifies the name of a `.streams` file that contains the
345 descriptions of the streams to create for this endpoint. This currently
346 specific to the implementation of the `pw-audio-softdsp-endpoint` and might
347 change in the future.
349 ## `*.streams` configuration files
351 These files contain lists of streams with their names and priorities.
352 They are TOML v0.5 files.
354 Each `.streams` file must contain exactly one top-level array of tables,
355 called `streams`. Every table must contain exactly two fields:
356 `name` and `priority`.
358 The `name` of each stream is used to create the streams on new endpoints.
360 The `priority` of each stream is being interpreted by the policy module to
361 apply restrictions on which app can use the stream at a given time.
363 # module-config-policy
365 This module implements demo-quality policy management that is partly driven
366 by configuration files. The configuration files that this module reads are
371 These files contain rules to link endpoints with each other.
372 They are TOML v0.5 files.
374 Endpoints are normally created by another module, such
375 as `module-config-endpoint` which is described above.
376 As soon as an endpoint is created, the `module-config-policy` uses the
377 information gathered from the `.endpoint-link` files in order to create a
378 link to another endpoint.
380 `.endpoint-link` files can contain 3 top-level tables:
381 * `[match-endpoint]`, required
382 * `[target-endpoint]`, optional
383 * `[endpoint-link]`, required
385 The `[match-endpoint]` table contains properties that match an endpoint that
386 exists on the graph. Possible fields of this table are:
390 Specifies the order in which the `.endpoint-link` files are being searched
391 for a match with an endpoint. If an endpoint matches the description of more
392 than one `.endpoint-link` file, the one with the highest priority wins.
394 The type of this field is unsigned integer. Bigger numbers mean higher
399 Required. Can be set to either `"sink"` or `"source"`. Specifies the
400 direction of the media flow of this endpoint. A `source` is an endpoint that
401 produces data (i.e. an audio capture device or a playback application) and
402 a `sink` is an endpoint that consumes data (audio playback device or
403 capture application).
407 Optional. The name of the endpoint. It is possible to use wildcards here to
408 match only parts of the name.
412 Optional. A string that specifies the `media.class` that the endpoint
413 must have in order to match.
417 This is a TOML array of tables, where each table must contain two fields:
418 `name` and `value`, both being strings. Each table describes a match against
419 one of the pipewire properties of the endpoint. For a successful endpoint
420 match, all the described properties must match with the endpoint.
422 The `[target-endpoint]` table contains properties that match an endpoint that
423 exists on the graph. The purpose of this table is to match a second endpoint
424 that the original matching endpoint from `[match-endpoint]` will be linked to.
425 If not specified, `module-config-policy` will look for the session "default"
426 endpoint for the type of media that the matching endpoint produces or consumes
427 and will use that as a target. Possible fields of this table are:
429 * `direction`, `name`, `media_class`, `properties`
431 All these fields are permitted and behave exactly as described above for the
432 `[match-endpoint]` table.
436 This field specifies a stream name that the link will use on the target
437 endpoint. If it is not specified, the stream name is acquired from the
438 `media.role` property of the matching endpoint. If specified, the value of
439 this field overrides the `media.role`.
441 The `[endpoint-link]` table specifies properties of the link. Possible fields
446 A boolean field. If set to true, the link is always kept active and ignores
447 policy rules regarding corking or stream priority. This link will also not
448 affect the rules for other links. For example, if a keep=true link is
449 activating a high priority stream, lower priority streams can still work on
450 the same target endpoint for links with keep=false.