Debian Codegraph @

docs/rst/daemon/configuration/conf_file.rst

raw
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.