Debian Codegraph @

docs/rst/daemon/configuration/migration.rst

raw
1 .. _config_migration:
2
3 Migrating configuration from 0.4
4 ================================
5
6 The configuration file format has changed in version 0.5. No automatic migration
7 of old configuration files is performed, so you will have to manually update
8 them. This document describes the changes and how to update your configuration.
9
10 wireplumber.conf
11 ----------------
12
13 In WirePlumber 0.4, there used to be a ``.conf`` file, typically
14 ``wireplumber.conf``, using the SPA-JSON format, that would list some Lua
15 scripts in the ``wireplumber.components`` section. These scripts were of type
16 ``config/lua`` and they were called by default ``main.lua``, ``policy.lua`` and
17 ``bluetooth.lua``.
18
19 Typical ``wireplumber.components`` section of a ``wireplumber.conf`` file in 0.4
20 would look like this:
21
22 .. code-block::
23
24 wireplumber.components = [
25 #{ name = <component-name>, type = <component-type> }
26 #
27 # WirePlumber components to load
28 #
29
30 # The lua scripting engine
31 { name = libwireplumber-module-lua-scripting, type = module }
32
33 # The lua configuration file(s)
34 # Other components are loaded from there
35 { name = main.lua, type = config/lua }
36 { name = policy.lua, type = config/lua }
37 { name = bluetooth.lua, type = config/lua }
38 ]
39
40 These Lua "configuration" scripts were then looked up in the standard
41 configuration directories (``/usr/share/wireplumber``, ``/etc/wireplumber`` and
42 ``~/.config/wireplumber``). The system also supported fragments of these scripts
43 to be placed in directories called ``main.lua.d``, ``policy.lua.d`` and
44 ``bluetooth.lua.d`` respectively, in the same locations.
45
46 .. attention::
47
48 Starting with WirePlumber 0.5, Lua "configuration" files are **no longer
49 supported**.
50
51 If you attempt to start it with a ``wireplumber.conf`` that still
52 lists ``config/lua`` components in its ``wireplumber.components`` section, you
53 will see the following error message on the output:
54
55 Failed to load configuration: The configuration file at '...' is likely an
56 old WirePlumber 0.4 config and is not supported anymore. Try removing it.
57
58 As the message says, to resolve this you should remove the old
59 ``wireplumber.conf`` file from the designated location. This should allow the
60 new WirePlumber to start using the default configuration that it ships with.
61
62 Lua configuration scripts
63 -------------------------
64
65 If you had custom Lua configuration scripts in the standard configuration
66 directories, such as *"main.lua.d"*, *"policy.lua.d"* or *"bluetooth.lua.d"*,
67 **you need to port them**.
68
69 Locations of files
70 ~~~~~~~~~~~~~~~~~~
71
72 The first thing you need to know is that the new files should be placed in the
73 ``~/.config/wireplumber/wireplumber.conf.d/`` directory instead of
74 ``~/.config/wireplumber/main.lua.d/`` and such ...
75
76 In addition, since the new files are in the SPA-JSON format, they should have
77 the ``.conf`` extension instead of ``.lua``.
78
79 See also :ref:`config_locations`.
80
81 Porting device/node rules
82 ~~~~~~~~~~~~~~~~~~~~~~~~~
83
84 One of the most common use-cases for these scripts was to set up properties
85 for devices and nodes using rules. Here is an example of an old rules script:
86
87 .. code-block:: lua
88 :caption: ~/.config/wireplumber/main.lua.d/51-alsa-pro-audio.lua
89
90 local rule = {
91 matches = {
92 {
93 { "device.name", "matches", "alsa_card.*" },
94 },
95 },
96 apply_properties = {
97 ["api.alsa.use-acp"] = false,
98 ["device.profile"] = "pro-audio",
99 ["api.acp.auto-profile"] = false,
100 ["api.acp.auto-port"] = false,
101 },
102 }
103
104 table.insert(alsa_monitor.rules, rule)
105
106 This equivalent of this script in the new configuration format would look like
107 this:
108
109 .. code-block::
110 :caption: ~/.config/wireplumber/wireplumber.conf.d/51-alsa-pro-audio.conf
111
112 monitor.alsa.rules = [
113 {
114 matches = [
115 {
116 device.name = "~alsa_card.*"
117 }
118 ]
119 actions = {
120 update-props = {
121 api.alsa.use-acp = false,
122 device.profile = "pro-audio"
123 api.acp.auto-profile = false
124 api.acp.auto-port = false
125 }
126 }
127 }
128 ]
129
130 Another example of Bluetooth node rules:
131
132 .. code-block:: lua
133 :caption: ~/.config/wireplumber/bluetooth.lua.d/51-headphones.lua
134
135 local rule = {
136 matches = {
137 {
138 { "node.name", "equals", "bluez_output.02_11_45_A0_B3_27.a2dp-sink" },
139 },
140 },
141 apply_properties = {
142 ["node.nick"] = "Headphones",
143 },
144 }
145
146 table.insert(bluez_monitor.rules, rule)
147
148 This equivalent of this script in the new configuration format would look like:
149
150 .. code-block::
151 :caption: ~/.config/wireplumber/wireplumber.conf.d/51-headphones.conf
152
153 monitor.bluez.rules = [
154 {
155 matches = [
156 {
157 node.name = "bluez_output.02_11_45_A0_B3_27.a2dp-sink"
158 }
159 ]
160 actions = {
161 update-props = {
162 node.nick = "Headphones"
163 }
164 }
165 }
166 ]
167
168 See also :ref:`config_modifying_configuration_rules`.
169
170 Porting properties configuration
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
173 If you had configuration scripts that were setting properties in tables such
174 as ``alsa_monitor.properties`` or ``bluez_monitor.properties``, then in many
175 cases porting to the new format can be done as follows:
176
177 .. code-block:: lua
178 :caption: ~/.config/wireplumber/bluetooth.lua.d/80-bluez-properties.lua
179
180 bluez_monitor.properties["bluez5.roles"] = "[ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]"
181 bluez_monitor.properties["bluez5.hfphsp-backend"] = "native"
182
183 .. code-block::
184 :caption: ~/.config/wireplumber/wireplumber.conf.d/80-bluez-properties.conf
185
186 monitor.bluez.properties = {
187 bluez5.roles = [ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]
188 bluez5.hfphsp-backend = "native"
189 }
190
191 See also :ref:`config_modifying_configuration_static`.
192
193 In a lot of cases, however, these properties have been promoted to become either
194 :ref:`Settings <config_modifying_configuration_settings>` or
195 :ref:`Features <config_modifying_configuration_features>`.
196 Here are some common examples:
197
198 Disabling the D-Bus device reservation API in the ALSA monitor:
199
200 * Old format:
201
202 .. code-block:: lua
203 :caption: ~/.config/wireplumber/main.lua.d/80-disable-alsa-reserve.lua
204
205 alsa_monitor.properties["alsa.reserve"] = false
206
207 * New format:
208
209 .. code-block::
210 :caption: ~/.config/wireplumber/wireplumber.conf.d/80-disable-alsa-reserve.conf
211
212 wireplumber.profiles = {
213 main = {
214 monitor.alsa.reserve-device = disabled
215 }
216 }
217
218 Disabling seat monitoring via logind in the BlueZ monitor:
219
220 * Old format:
221
222 .. code-block:: lua
223 :caption: ~/.config/wireplumber/bluetooth.lua.d/80-disable-logind.lua
224
225 bluez_monitor.properties["with-logind"] = false
226
227 * New format:
228
229 .. code-block::
230 :caption: ~/.config/wireplumber/wireplumber.conf.d/80-disable-logind.conf
231
232 wireplumber.profiles = {
233 main = {
234 monitor.bluez.seat-monitoring = disabled
235 }
236 }
237
238 See also :ref:`config_modifying_configuration_features`.
239
240 Linking policy configuration (moved to settings and renamed):
241
242 * Old format:
243
244 .. code-block:: lua
245 :caption: ~/.config/wireplumber/policy.lua.d/80-policy.lua
246
247 default_policy.policy = {
248 ["move"] = false,
249 ["follow"] = false,
250 }
251
252 * New format:
253
254 .. code-block::
255 :caption: ~/.config/wireplumber/wireplumber.conf.d/80-policy.conf
256
257 wireplumber.settings = {
258 linking.allow-moving-streams = false
259 linking.follow-default-target = false
260 }
261
262 See also :ref:`config_modifying_configuration_settings` and remember that
263 settings can also be changed at runtime via :command:`wpctl`.
264
265 Loading custom scripts
266 ~~~~~~~~~~~~~~~~~~~~~~
267
268 If you had custom Lua scripts that were loaded by the old configuration file,
269 you need to port the old ``load_script()`` commands into component descriptions.
270
271 For example, if you had a script that was loaded like this:
272
273 .. code-block:: lua
274 :caption: ~/.config/wireplumber/main.lua.d/99-my-script.lua
275
276 load_script("my-script.lua")
277
278 You should now create a new component description in the configuration file
279 and also make sure to require it in the profile:
280
281 .. code-block::
282 :caption: ~/.config/wireplumber/wireplumber.conf.d/99-my-script.conf
283
284 wireplumber.components = [
285 {
286 name = my-script.lua, type = script/lua
287 provides = custom.my-script
288 }
289 ]
290
291 wireplumber.profiles = {
292 main = {
293 custom.my-script = required
294 }
295 }
296
297 .. attention::
298
299 Another important thing to mention here is the location of custom scripts. In
300 0.4, scripts could be loaded in configuration locations such as
301 ``~/.config/wireplumber/scripts/`` and ``/etc/wireplumber/scripts/``. In 0.5,
302 the XDG base directory specification for data files is honored, so the new
303 location for custom scripts is ``~/.local/share/wireplumber/scripts/`` and
304 anything else specified in ``$XDG_DATA_HOME`` and ``$XDG_DATA_DIRS``. See
305 :ref:`daemon_file_locations` for more information.