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