| 1 |
.. _config_conf_file: |
| 2 |
|
| 3 |
The configuration file |
| 4 |
====================== |
| 5 |
|
| 6 |
WirePlumber's configuration file is by default ``wireplumber.conf`` and resides |
| 7 |
in one of the WirePlumber specific |
| 8 |
:ref:`configuration file search locations <config_locations>`. |
| 9 |
|
| 10 |
The default configuration file can be changed on the command line by passing |
| 11 |
the ``--config-file`` or ``-c`` option: |
| 12 |
|
| 13 |
.. code-block:: bash |
| 14 |
|
| 15 |
$ wireplumber --config-file=custom.conf |
| 16 |
|
| 17 |
.. important:: |
| 18 |
|
| 19 |
Starting with WirePlumber 0.5, this is the only file that WirePlumber reads |
| 20 |
to load configuration (together with its fragments - see below). In the past, |
| 21 |
WirePlumber also used to read Lua configuration files that were referenced |
| 22 |
from ``wireplumber.conf`` and all the heavy lifting was done in Lua. This is |
| 23 |
no longer the case, and the **Lua configuration files are no longer supported.** |
| 24 |
See :ref:`config_migration`. |
| 25 |
|
| 26 |
Note that Lua is still the scripting language for WirePlumber, but it is only |
| 27 |
used for actual scripting and not for configuration. |
| 28 |
|
| 29 |
The SPA-JSON Format |
| 30 |
------------------- |
| 31 |
|
| 32 |
The format of this configuration file is a variant of JSON that is also |
| 33 |
used in PipeWire configuration files (also known as SPA-JSON). The file consists |
| 34 |
of a global JSON object that is not explicitly typed, and a list of sections |
| 35 |
which are essentially key-value pairs of that global JSON object. Each section |
| 36 |
is usually a JSON object, but it can also be a JSON array. |
| 37 |
|
| 38 |
SPA-JSON is a superset of standard JSON, so any valid JSON file is also a valid |
| 39 |
SPA-JSON file. However, it is more permissive than standard JSON. First of all, |
| 40 |
it allows strings to be typed without quotes (``"``), and it also allows the |
| 41 |
character ``=`` as a separator between keys and values in addition to the |
| 42 |
standard ``:``. This can make it look similar to INI files or other custom |
| 43 |
configuration formats that people are familiar with, which makes it easier for |
| 44 |
users to read and edit. |
| 45 |
|
| 46 |
Other deviations from standard JSON include allowing comments (lines starting |
| 47 |
with ``#`` are treated as comments) and allowing the separator characters |
| 48 |
(``:``, ``=``, ``,``) to appear in excess or abundance. That means that you can |
| 49 |
write ``key = value`` or ``key: value`` or ``key value`` and it will be |
| 50 |
interpreted the same way. You may also write ``[val1, val2, val3]`` or |
| 51 |
``[val1, val2, val3, ]`` or ``[val1 val2 val3]`` and it will be interpreted |
| 52 |
the same way. This is allowed because the SPA-JSON parser in fact ignores all |
| 53 |
the separator characters (the real separator is the space character). |
| 54 |
|
| 55 |
Examples of valid SPA-JSON files: |
| 56 |
|
| 57 |
.. code-block:: |
| 58 |
|
| 59 |
# This is the most common syntax |
| 60 |
section1 = { |
| 61 |
string-key = value1 |
| 62 |
number-key = 123 |
| 63 |
boolean-key = true |
| 64 |
} |
| 65 |
section2 = [ |
| 66 |
val1, val2, val3 |
| 67 |
] |
| 68 |
|
| 69 |
.. code-block:: |
| 70 |
|
| 71 |
# Mixed syntax |
| 72 |
section1 { |
| 73 |
"string-key" = "value1" |
| 74 |
number-key: 123 |
| 75 |
boolean-key true |
| 76 |
} |
| 77 |
section2 = [ |
| 78 |
val1, val2 val3, |
| 79 |
] |
| 80 |
|
| 81 |
.. code-block:: |
| 82 |
|
| 83 |
# Standard JSON (albeit this comment line) |
| 84 |
"section1": { |
| 85 |
"string-key": "value1", |
| 86 |
"number-key": 123, |
| 87 |
"boolean-key": true |
| 88 |
} |
| 89 |
"section2": [ |
| 90 |
"val1", "val2", "val3" |
| 91 |
] |
| 92 |
|
| 93 |
.. _config_conf_file_fragments: |
| 94 |
|
| 95 |
Fragments |
| 96 |
--------- |
| 97 |
|
| 98 |
Just like PipeWire, WirePlumber supports configuration fragments. This means |
| 99 |
that the main configuration file can be split into multiple files, and all of |
| 100 |
them will be loaded and merged together. This is mostly useful to allow users |
| 101 |
to customize their configuration without having to modify the main file. |
| 102 |
|
| 103 |
When loading the configuration file, WirePlumber will also look for |
| 104 |
additional files in the directory that has the same name as the configuration |
| 105 |
file suffixed with ``.d`` and will load all of them as well. For example, |
| 106 |
loading ``wireplumber.conf`` will also load any ``.conf`` files under |
| 107 |
``wireplumber.conf.d/``. This directory is searched in all the configuration |
| 108 |
search locations and the fragments are loaded from *all* of them, starting |
| 109 |
from the most system-wide locations and moving towards the most user-specific |
| 110 |
locations, in alphanumerical order within each location (see also |
| 111 |
:ref:`config_locations_fragments`). |
| 112 |
|
| 113 |
When a JSON object appears in multiple files, the properties of the objects are |
| 114 |
merged together. When a JSON array appears in multiple files, the arrays are |
| 115 |
concatenated together. When merging objects, if specific properties appear in |
| 116 |
many of those objects, the last one to be parsed always overwrites previous |
| 117 |
ones, unless the value is also an object or array; if it is, then the value is |
| 118 |
recursively merged using the same rules. |
| 119 |
|
| 120 |
Sections |
| 121 |
-------- |
| 122 |
|
| 123 |
WirePlumber reads the following standard sections from the configuration |
| 124 |
file: |
| 125 |
|
| 126 |
* *wireplumber.components* |
| 127 |
|
| 128 |
This section is an array that lists components that can be loaded by |
| 129 |
WirePlumber. For more information, see :ref:`config_components_and_profiles`. |
| 130 |
|
| 131 |
* *wireplumber.components.rules* |
| 132 |
|
| 133 |
This section is an array containing rules that can be used to modify entries |
| 134 |
of the *wireplumber.components* array. This is useful to inject changes |
| 135 |
to the components list without having to modify the main configuration file. |
| 136 |
|
| 137 |
* *wireplumber.profiles* |
| 138 |
|
| 139 |
This section is an object that defines profiles that can be loaded by |
| 140 |
WirePlumber. For more information, see :ref:`config_components_and_profiles`. |
| 141 |
|
| 142 |
* *wireplumber.settings* |
| 143 |
|
| 144 |
This section is an object that defines settings that can be used to |
| 145 |
alter WirePlumber's behavior. For more information, see :ref:`config_settings`. |
| 146 |
|
| 147 |
* *wireplumber.settings.schema* |
| 148 |
|
| 149 |
This section is an object that defines the schema for the settings that |
| 150 |
can be listed in *wireplumber.settings*. This is used to validate the |
| 151 |
settings when they are modified at runtime. For more information, see |
| 152 |
:ref:`config_configuration_option_types`. |
| 153 |
|
| 154 |
In addition, there are many sections that are specific to certain components, |
| 155 |
mostly hardware monitors, such as *monitor.alsa.properties*, |
| 156 |
*monitor.alsa.rules*, etc. These are documented further on, in the respective |
| 157 |
sections of this documentation that describe the configuration options of |
| 158 |
these components. |
| 159 |
|
| 160 |
Finally, WirePlumber also reads the following sections, which are parsed |
| 161 |
by libpipewire to configure the PipeWire context: |
| 162 |
|
| 163 |
* *context.properties* |
| 164 |
|
| 165 |
Used to define properties to configure the PipeWire context and some modules. |
| 166 |
|
| 167 |
* *context.spa-libs* |
| 168 |
|
| 169 |
Used to find SPA factory names. It maps a SPA factory name regular expression |
| 170 |
to a library name that should contain that factory. The object property names |
| 171 |
are the regular expressions, and the object property values are the actual |
| 172 |
library names: |
| 173 |
|
| 174 |
.. code-block:: |
| 175 |
|
| 176 |
<factory-name regex> = <library-name> |
| 177 |
|
| 178 |
For example: |
| 179 |
|
| 180 |
.. code-block:: |
| 181 |
|
| 182 |
context.spa-libs = { |
| 183 |
api.alsa.* = alsa/libspa-alsa |
| 184 |
audio.convert.* = audioconvert/libspa-audioconvert |
| 185 |
} |
| 186 |
|
| 187 |
In this example, we instruct wireplumber to lookup any *api.alsa.** factory |
| 188 |
in the *libspa-alsa* library, and any *audio.convert.** factory |
| 189 |
in the *libspa-audioconvert* library. |
| 190 |
|
| 191 |
.. note:: |
| 192 |
|
| 193 |
The default configuration file already contains a list of well-known |
| 194 |
factory names and their corresponding libraries. You should only |
| 195 |
need to add entries to this section if you are using custom SPA plugins. |
| 196 |
|
| 197 |
* *context.modules* |
| 198 |
|
| 199 |
Used to load PipeWire modules. This does not affect the PipeWire daemon by any |
| 200 |
means. It exists simply to allow loading *libpipewire* modules inside |
| 201 |
WirePlumber. This is usually useful to load PipeWire protocol extensions, |
| 202 |
so that you can export custom objects to PipeWire and other clients. |
| 203 |
|
| 204 |
.. note:: |
| 205 |
|
| 206 |
PipeWire modules can also be loaded as :ref:`components <config_components_and_profiles>`, |
| 207 |
which may be preferable since it allows you to load them conditionally |
| 208 |
based on the profile and component dependencies. |
| 209 |
|
| 210 |
.. admonition:: Remember |
| 211 |
|
| 212 |
Modules listed in *context.modules* are always loaded before attempting a |
| 213 |
connection to the PipeWire daemon, while modules listed in |
| 214 |
*wireplumber.components* are always loaded after the connection is |
| 215 |
established. It is important to load the PipeWire protocol-native module |
| 216 |
and any extensions (such as module-metadata) in the *context.modules* |
| 217 |
section, so that the connection can be done properly. |
| 218 |
|
| 219 |
Each module is described by a JSON object containing the module's *name*, |
| 220 |
its arguments (*args*) and a combination of *flags*, which can be ``ifexists`` |
| 221 |
and ``nofail``. |
| 222 |
|
| 223 |
.. code-block:: |
| 224 |
|
| 225 |
{ |
| 226 |
name = <module-name> |
| 227 |
[ args = { <key> = <value> ... } ] |
| 228 |
[ flags = [ [ ifexists ] [ nofail ] ] |
| 229 |
} |
| 230 |
|
| 231 |
For example: |
| 232 |
|
| 233 |
.. code-block:: |
| 234 |
|
| 235 |
context.modules = [ |
| 236 |
{ name = libpipewire-module-adapter } |
| 237 |
{ |
| 238 |
name = libpipewire-module-metadata, |
| 239 |
flags = [ ifexists ] |
| 240 |
} |
| 241 |
] |
| 242 |
|
| 243 |
The above example loads both PipeWire adapter and metadata modules. The |
| 244 |
metadata module will be ignored if not found because of its ``ifexists`` flag. |