| 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 |
] |