Simplified doc-site generation
[AGL/documentation.git] / docs / 4_APIs_and_Services / 4.6_Audio_Framework / 4.6.2_Session_Manager_Configuration.md
1 ---
2 edit_link: ''
3 title: Session Manager Configuration
4 origin_url: >-
5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/wireplumber_configuration.md
6 ---
7
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 -->
9
10 # WirePlumber Configuration
11
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
14 inside those modules.
15
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.
20
21 ## `wireplumber.conf`
22
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.
26
27 The format of this file is custom and resembles a script with commands:
28
29 ```
30 # comment
31 command parameter1 parameter2 ...
32 ```
33
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:
37
38 * `add-spa-lib`
39
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.
42
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.
46
47   Example:
48   ```
49   add-spa-lib api.alsa.* alsa/libspa-alsa
50   ```
51
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).
55
56 * `load-pipewire-module`
57
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
60   daemon.
61
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`
64
65   Format:
66   ```
67   load-pipewire-module module-name some-argument some-property=value
68   ```
69   Example:
70   ```
71   load-pipewire-module libpipewire-module-client-device
72   ```
73
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
78   clients.
79
80 * `load-module`
81
82   Loads a WirePlumber module. This takes 2 arguments and an optional parameter
83   block.
84
85   Format:
86   ```
87   load-module ABI module-name {
88     "parameter": <"value">
89   }
90   ```
91
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.
95
96   The `module-name` should be the name of the `.so` file without the `.so`
97   extension.
98
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)
103   of type
104   [`a{sv}`](https://developer.gnome.org/glib/stable/gvariant-format-strings.html)
105   in the
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 `<` `>`.
111
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.
114
115   Example:
116   ```
117   load-module C libwireplumber-module-monitor {
118     "factory": <"api.alsa.enum.udev">,
119     "flags": <["use-adapter", "activate-devices"]>
120   }
121   ```
122
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.
126
127 ## Location of configuration files
128
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`.
131
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`
137
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:
141
142 ```
143 WIREPLUMBER_CONFIG_FILE=src/config/wireplumber.conf wireplumber
144 ```
145
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:
149 ```
150 WIREPLUMBER_CONFIG_DIR=src/config wireplumber
151 ```
152
153 ## Location of modules
154
155 ### WirePlumber modules
156
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
160 multiarch systems)
161
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`.
167
168 It is possible to override this directory at runtime by setting the
169 `WIREPLUMBER_MODULE_DIR` environment variable:
170 ```
171 WIREPLUMBER_MODULE_DIR=build/modules wireplumber
172 ```
173
174 ### PipeWire and SPA modules
175
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.
178
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.
182
183 # module-monitor
184
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.
189
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:
193
194 * `factory`
195
196   A string that specifies the name of the SPA factory that loads the intial
197   "device" object.
198
199   Well-known factories are:
200
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
204
205  * `flags`
206
207     An array of strings that enable specific functionality in the monitor.
208     Possible flags include:
209
210     * "use-adapter"
211
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.
215
216     * "local-nodes"
217
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
222       reasons.
223
224     * "activate-devices"
225
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.
229
230 # module-config-endpoint
231
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.
242
243 ## `*.endpoint` configuration files
244
245 These files are TOML v0.5 files. At the top-level, they must contain exactly
246 2 tables: `[match-node]` and `[endpoint]`
247
248 The `[match-node]` table contains properties that match a pipewire node that
249 exists on the graph. Possible fields of this table are:
250
251 * `priority`
252
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.
256
257   The type of this field is unsigned integer. Bigger numbers mean higher
258   priority.
259
260 * `properties`
261
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.
266
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).
271
272   When writing `.endpoint` files, a useful utility that you can use to list
273   device node properties is:
274
275   ```
276   $ wireplumber-cli device-node-props
277   ```
278
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:
282
283   ```
284   card 0: PCH [HDA Intel PCH], device 2: ALC3246 [ALC3246 Analog]
285   ```
286
287   ```
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" },
295   ```
296
297 The `[endpoint]` table contains a description of the endpoint to be created.
298 Possible fields of this table are:
299
300 * `type`
301
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`
304
305 * `direction`
306
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).
312
313 * `name`
314
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).
317
318 * `media_class`
319
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.
324
325 * `priority`
326
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`):
330
331   * Audio/Sink
332   * Audio/Source
333   * Video/Source
334
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.
338
339   If not specified, the default priority of an endpoint is equal to zero
340   (i.e. the lowest priority).
341
342 * `streams`
343
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.
348
349 ## `*.streams` configuration files
350
351 These files contain lists of streams with their names and priorities.
352 They are TOML v0.5 files.
353
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`.
357
358 The `name` of each stream is used to create the streams on new endpoints.
359
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.
362
363 # module-config-policy
364
365 This module implements demo-quality policy management that is partly driven
366 by configuration files. The configuration files that this module reads are
367 described below:
368
369 ## `*.endpoint-link`
370
371 These files contain rules to link endpoints with each other.
372 They are TOML v0.5 files.
373
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.
379
380 `.endpoint-link` files can contain 3 top-level tables:
381 * `[match-endpoint]`, required
382 * `[target-endpoint]`, optional
383 * `[endpoint-link]`, required
384
385 The `[match-endpoint]` table contains properties that match an endpoint that
386 exists on the graph. Possible fields of this table are:
387
388 * `priority`
389
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.
393
394   The type of this field is unsigned integer. Bigger numbers mean higher
395   priority.
396
397 * `direction`
398
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).
404
405 * `name`
406
407   Optional. The name of the endpoint. It is possible to use wildcards here to
408   match only parts of the name.
409
410 * `media_class`
411
412   Optional. A string that specifies the `media.class` that the endpoint
413   must have in order to match.
414
415 * `properties`
416
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.
421
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:
428
429 * `direction`, `name`, `media_class`, `properties`
430
431   All these fields are permitted and behave exactly as described above for the
432   `[match-endpoint]` table.
433
434 * `stream`
435
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`.
440
441 The `[endpoint-link]` table specifies properties of the link. Possible fields
442 of this table are:
443
444 * `keep`
445
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.