Lua Configuration Files

Lua configuration files are similar to the main configuration file, but they leverage the Lua language to enable advanced configuration of module arguments and allow split-file configuration.

There is only one global section that WirePlumber reads from these files: the components table. This table is equivalent to the context.components object on the main configuration file. Its purpose is to list components that WirePlumber should load on startup.

Every line on the components table should be another table that contains information about the loaded component:

{
  "component-name",
  type = "component-type",
  args = { additional arguments },
  optional = true/false,
}

component-name: Should be the name of the component to load (ex. “libwireplumber-module-mixer-api”).
component-type: Should be the type of the component. Valid component types include:
- module: A WirePlumber shared object module.
- script/lua: A WirePlumber Lua script.
- pw_module: A PipeWire shared object module (loaded on WirePlumber, not on the PipeWire daemon).
args: Is an optional table that can contain additional arguments to be passed down to the module or script. Scripts can retrieve these arguments by declaring a line that reads local config = ... at the top of the script. Modules receive these arguments as a GVariant a{sv} table.
optional: Is a boolean value that specifies whether loading of this component is optional. The default value is false. If set to true, then WirePlumber will not fail loading if the component is not found.

Split-File Configuration

When a Lua configuration file is loaded, the engine also looks for additional files in a directory that has the same name as the configuration file and a .d suffix.

A Lua directory can contain a list of Lua configuration files. Those files are loaded alphabetically by filename so that user can control the order in which Lua configuration files are executed.

Lua files in the directory are always loaded after the configuration file that is out of the directory. However, it is perfectly valid to not have any configuration file out of the directory.

Example hierarchy with files both in and out of the directory (in the order of loading):

config.lua
config.lua.d/00-functions.lua
config.lua.d/01-alsa.lua
config.lua.d/10-policy.lua
config.lua.d/99-misc.lua

Example hierarchy with files only in the directory (in the order of loading):

config.lua.d/00-functions.lua
config.lua.d/01-alsa.lua
config.lua.d/10-policy.lua
config.lua.d/99-misc.lua

Example of a file using alsa_monitor.rules in a split-file configuration:

table.insert (alsa_monitor.rules, {
  matches = {
    {
      { "device.name", "matches", "alsa_card.*" },
    },
  },
  apply_properties = {
    ["api.alsa.use-acp"] = true,
  }
})

Multi-Path Merging

WirePlumber looks for configuration files in 3 different places, as described in the Locations of files section. When a split-file configuration scheme is used, files will be merged from these different locations.

For example, consider these files exist on the filesystem:

/usr/share/wireplumber/config.lua.d/00-functions.lua
/usr/share/wireplumber/config.lua.d/01-alsa.lua
/usr/share/wireplumber/config.lua.d/10-policy.lua
/usr/share/wireplumber/config.lua.d/99-misc.lua
...
/etc/wireplumber/config.lua.d/01-alsa.lua
...
/home/user/.config/wireplumber/config.lua.d/11-policy-extras.lua

In this case, loading config.lua will result in loading these files (in this order):

/usr/share/wireplumber/config.lua.d/00-functions.lua
/etc/wireplumber/config.lua.d/01-alsa.lua
/usr/share/wireplumber/config.lua.d/10-policy.lua
/home/user/.config/wireplumber/config.lua.d/11-policy-extras.lua
/usr/share/wireplumber/config.lua.d/99-misc.lua

This is useful to keep the default configuration in /usr and override it with host-specific and user-specific parts in /etc and /home respectively.

As an exception to this rule, if the configuration path is overridden with the WIREPLUMBER_CONFIG_DIR environment variable, then configuration files will only be loaded from this path and no merging will happen.

Functions

Because of the nature of these files (they are scripts!), it is more convenient to manage the components table through functions. In the default configuration files shipped with WirePlumber, there is a file called 00-functions.lua that defines some helper functions to load components.

When loading components through these functions, duplicate calls are ignored, so it is possible to call a function to load a specific component multiple times and it will only be loaded once.

load_module(module, args)

Loads a WirePlumber shared object module.

Parameters:

module (string) – the module name, without the “libwireplumber-module-” prefix (ex specify “mixer-api” to load “libwireplumber-module-mixer-api”)
args (table) – optional module arguments table

load_optional_module(module, args)

Loads an optional WirePlumber shared object module. Optional in this case means that if the module is not present on the filesystem, it will be ignored.

Parameters:

module (string) – the module name, without the “libwireplumber-module-” prefix (ex specify “mixer-api” to load “libwireplumber-module-mixer-api”)
args (table) – optional module arguments table

load_pw_module(module)

Loads a PipeWire shared object module

Parameters:: module (string) – the module name, without the “libpipewire-module-” prefix (ex specify “adapter” to load “libpipewire-module-adapter”)

load_script(script, args)

Loads a Lua script (a functionality script, not a lua configuration file)

Parameters:

script (string) – the script’s filename (ex. “policy-node.lua”)
args (table) – optional script arguments table

load_monitor(monitor, args)

Loads a Lua monitor script. Monitors are scripts found in the monitors/ directory and their purpose is to monitor and load devices.

Parameters:

monitor (string) – the scripts’s name without the directory or the .lua extension (ex. “alsa” will load “monitors/alsa.lua”)
args (table) – optional script arguments table

load_access(access, args)

Loads a Lua access script. Access scripts are ones found in the access/ directory and their purpose is to manage application permissions.

Parameters:

access (string) – the scripts’s name without the directory or the .lua extension (ex. “flatpak” will load “access/access-flatpak.lua”)
args (table) – optional script arguments table