Debian Codegraph @

docs/rst/daemon/configuration/modifying_configuration.rst

raw
1 .. _config_modifying_configuration:
2
3 Modifying configuration
4 =======================
5
6 WirePlumber is a heavily modular daemon that depends on its configuration
7 file to operate. If you were to start WirePlumber with an empty configuration
8 file, it would fail to start. This is why the default configuration file is
9 installed in the system-wide application data directory, which prevents it from
10 being modified by the user.
11
12 It is technically possible, if you wish, to copy the default configuration
13 file in one of the other :ref:`configuration search locations <config_locations>`
14 and modify it. However, this is **not recommended**, as it may lead to issues
15 when upgrading WirePlumber.
16
17 In the :ref:`Configuration file <config_conf_file>` section, we saw that
18 configuration files support fragments, which allow you to override or extend the
19 default configuration. This is the recommended way to modify the configuration.
20
21 Working with fragments
22 ----------------------
23
24 The easiest way to add :ref:`fragments <config_conf_file_fragments>` to
25 modify the default configuration is to create a directory called
26 ``~/.config/wireplumber/wireplumber.conf.d`` and place your fragments there.
27
28 All fragment files need to have the ``.conf`` extension and must be valid
29 SPA-JSON files. The fragments are loaded in alphanumerical order, so you can
30 control the order in which they are loaded by naming them accordingly. It is
31 recommended to use a numeric prefix for the file names, e.g.
32 ``10-my-fragment.conf``, ``20-my-other-fragment.conf``, etc., so that you can
33 easily control the order in which they are loaded.
34
35 .. _config_modifying_configuration_features:
36
37 Customizing the loaded features
38 -------------------------------
39
40 As seen in the :ref:`Components & Profiles <config_components_and_profiles>`
41 section, the list of components that are loaded can be customized by enabling or
42 disabling :ref:`well-known features <config_features>` in the profile that is
43 in use by WirePlumber.
44
45 The default profile of WirePlumber is called ``main``, so a fragment that
46 enables or disables a specific feature in the default configuration should look
47 like this:
48
49 .. code-block::
50
51 wireplumber.profiles = {
52 main = {
53 some.feature.name = disabled
54 some.other.feature.name = required
55 }
56 }
57
58 Remember that features can be ``required``, ``optional`` or ``disabled``. See
59 the :ref:`Components & Profiles <config_components_and_profiles>` for details.
60
61 .. _config_modifying_configuration_settings:
62
63 Modifying dynamic options ("settings")
64 --------------------------------------
65
66 As seen in the :ref:`Configuration option types <config_configuration_option_types>`
67 section, WirePlumber components can be partly configured with dynamic options
68 (referred to as "settings"). These settings can either be modified permanently
69 in the configuration file, or they can be modified at runtime using the
70 ``wpctl`` command-line tool.
71
72 To modify a setting in the configuration file, you can use a fragment like this:
73
74 .. code-block::
75
76 wireplumber.settings = {
77 some.setting.name = value
78 }
79
80 For example, setting the ``device.routes.default-sink-volume`` setting to
81 ``0.5`` can be done like this:
82
83 .. code-block::
84
85 wireplumber.settings = {
86 device.routes.default-sink-volume = 0.5
87 }
88
89 .. note::
90
91 Since the configuration file is only read at startup, this will only take
92 effect after restarting WirePlumber.
93
94 If you would prefer to change the setting at runtime, you can use ``wpctl`` as
95 follows:
96
97 .. code-block:: bash
98
99 $ wpctl settings device.routes.default-sink-volume 0.5
100 Updated setting 'device.routes.default-sink-volume' to: 0.5
101
102 The above command changes the setting immediately, but for the current
103 WirePlumber instance only. If you want the setting to be applied every time
104 WirePlumber is started, you may also use the ``--save`` option:
105
106 .. code-block:: bash
107
108 $ wpctl settings --save device.routes.default-sink-volume 0.5
109 Updated and saved setting 'device.routes.default-sink-volume' to: 0.5
110
111 This will save the setting persistently in WirePlumber's state storage.
112 Even though it is not in the configuration file, this saved value will be
113 applied automatically when WirePlumber is started.
114
115 .. attention::
116
117 When a setting's value is saved, it will override the value from the
118 configuration file. Changing the value in the configuration file will
119 have no effect until the saved value is removed. Use the ``--delete``
120 switch in ``wpctl`` to remove a saved value (see below).
121
122 With ``wpctl``, it is also possible to restore a setting to its default value
123 (taken from the schema), by using the ``--reset`` option. For example, to reset
124 the ``device.routes.default-sink-volume`` setting, the following command can be
125 used:
126
127 .. code-block:: bash
128
129 $ wpctl settings --reset device.routes.default-sink-volume
130 Reset setting 'device.routes.default-sink-volume' successfully
131 $ wpctl settings device.routes.default-sink-volume
132 Value: 0.064 (Saved: 0.5)
133
134 Note that the ``--reset`` option will only reset the setting to its default
135 value, but it will not remove the saved value from the state file. If you want
136 to remove the saved value, you can use the ``--delete`` option:
137
138 .. code-block:: bash
139
140 $ wpctl settings --delete device.routes.default-sink-volume
141 Deleted setting 'device.routes.default-sink-volume' successfully
142 $ wpctl settings device.routes.default-sink-volume
143 Value: 0.064
144
145 A list of all the available settings can be found in the :ref:`config_settings`
146 section.
147
148 .. _config_modifying_configuration_static:
149
150 Modifying static options
151 ------------------------
152
153 Static options always live in their own section of the configuration file.
154 Sections can be of two types: either a JSON object or a JSON array.
155
156 When dealing with a **JSON object**, you can add or modify a key-value pair by
157 creating a fragment like this:
158
159 .. code-block::
160
161 wireplumber.some-section = {
162 some.option = new_value
163 }
164
165 This is similar to what we have seen also above for modifying profile features
166 and settings (because both are JSON objects).
167
168 When dealing with a **JSON array**, any values that you define in a fragment
169 will be appended to the array. For example, to add a new rule to the
170 ``monitor.alsa.rules`` array, you can create a fragment like this:
171
172 .. code-block::
173
174 monitor.alsa.rules = [
175 {
176 matches = [
177 {
178 device.name = "~alsa_card.*"
179 }
180 ]
181 actions = {
182 update-props = {
183 api.alsa.use-ucm = false
184 }
185 }
186 }
187 ]
188
189 This will add a new rule to the ``monitor.alsa.rules`` array, which will
190 be evaluated **after** all other rules that were parsed before. This is where
191 the order in which fragments are loaded actually matters.
192
193 If you don't want to append a new rule, but rather override the entire array
194 with a new one, you can do so by using the ``override.`` prefix on the array
195 name:
196
197 .. code-block::
198
199 override.monitor.alsa.rules = [
200 {
201 matches = [
202 {
203 device.name = "~alsa_card.*"
204 }
205 ]
206 actions = {
207 update-props = {
208 api.alsa.use-ucm = false
209 }
210 }
211 }
212 ]
213
214 This will now replace the entire ``monitor.alsa.rules`` array with this new one.
215
216 .. attention::
217
218 If you want to remove a rule from the array, you will need to override the
219 whole array with a new one that does not contain the rule you want to remove.
220 There is no way to remove a specific element from an array using fragments.
221
222 Another thing worth remembering here is that this behavior of appending values
223 to arrays also works in arrays that are nested inside other arrays or objects.
224 For example, consider this fragment:
225
226 .. code-block::
227
228 monitor.bluez.properties = {
229 bluez5.codecs = [ sbc_xq aac ldac ]
230 }
231
232 If this is the first time that the ``bluez5.codecs`` array is being defined, it
233 will be created with the given values. If it already exists, the given values
234 will be appended to the existing array. If you want to make sure that this
235 fragment will override the existing array, you need to use the ``override.``
236 prefix on the array name:
237
238 .. code-block::
239
240 monitor.bluez.properties = {
241 override.bluez5.codecs = [ sbc_xq aac ldac ]
242 }
243
244 The ``override.`` prefix may also be used in JSON object keys, to override the
245 entire object with a new one. For example, to override the entire
246 ``monitor.bluez.properties`` object, you can use a fragment like this:
247
248 .. code-block::
249
250 override.monitor.bluez.properties = {
251 bluez5.codecs = [ sbc_xq aac ldac ]
252 }
253
254 Here, the entire ``monitor.bluez.properties`` object will be replaced with the
255 new one, and all previous key-value pairs configured will be discarded. This
256 also means that the ``bluez5.codecs`` array will be replaced with the new one
257 and does not require the ``override.`` prefix.
258
259 .. note::
260
261 Even though WirePlumber uses PipeWire's syntax for configuration files, the
262 ``override.`` prefix is a WirePlumber extension and does not work in
263 PipeWire.
264
265 .. _config_modifying_configuration_rules:
266
267 Working with rules
268 ------------------
269
270 Some of the static option sections in the configuration file are used to define
271 rules that are evaluated by WirePlumber at runtime. These rules are typically
272 used to match objects and perform actions on them. For example, the
273 ``monitor.alsa.rules`` section is used to define rules that are evaluated by
274 the ALSA monitor to match ALSA devices and update their properties.
275
276 The syntax of these rules is the same as the syntax of
277 `PipeWire's rules <https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire#rules>`_.
278
279 A rule is always a JSON object with two keys: ``matches`` and ``actions``. The
280 ``matches`` key is used to define the conditions that need to be met for the
281 rule to be evaluated as true, and the ``actions`` key is used to define the
282 actions that are performed when the rule is evaluated as true.
283
284 The ``matches`` key is always a JSON array of objects, where each object
285 defines a condition that needs to be met. Each condition is a list of key-value
286 pairs, where the key is the name of the property that is being matched, and the
287 value is the value that the property needs to have. Within a condition, all
288 the key-value pairs are combined with a logical AND, and all the conditions in
289 the ``matches`` array are combined with a logical OR.
290
291 The ``actions`` key is always a JSON object, where each key-value pair defines
292 an action that is performed when the rule is evaluated as true. The action
293 name is specific to the rule and is defined by the rule's documentation, but
294 most frequently you will see the ``update-props`` action, which is used to
295 update the properties of the matched object.
296
297 For example:
298
299 .. code-block::
300
301 some.theoretical.rules = [
302 {
303 matches = [
304 {
305 object.name = "my_object"
306 object.profile.name = "my_profile"
307 }
308 {
309 object.name = "other_object"
310 }
311 ]
312 actions = {
313 update-props = {
314 object.tag = "matched_by_my_rule"
315 }
316 }
317 }
318 ]
319
320 This rule is equivalent to the following expression:
321
322 .. code-block:: python
323
324 if (properties["object.name"] == "my_object" and properties["object.profile.name"] == "my_profile") or (properties["object.name"] == "other_object"):
325 properties["object.tag"] = "matched_by_my_rule"
326
327 In the ``matches`` array, it is also possible to use regular expressions to match
328 property values. For example, to match all nodes with a name that starts with
329 ``my_``, you can use the following condition:
330
331 .. code-block::
332
333 matches = [
334 {
335 node.name = "~my_.*"
336 }
337 ]
338
339 The ``~`` character signifies that the value is a regular expression. The exact
340 syntax of the regular expressions is the POSIX extended regex syntax, as
341 described in the `regex (7)` man page.
342
343 In addition to regular expressions, you may also use the ``!`` character to
344 negate a condition. For example, to match all nodes with a name that does not
345 start with ``my_``, you can use the following condition:
346
347 .. code-block::
348
349 matches = [
350 {
351 node.name = "!~my_.*"
352 }
353 ]
354
355 The ``!`` character can be used with or without a regular expression. For
356 example, to match all nodes with a name that is not equal to ``my_node``,
357 you can use the following condition:
358
359 .. code-block::
360
361 matches = [
362 {
363 node.name = "!my_node"
364 }
365 ]