Settings

The Settings API gives scripts access to WirePlumber's runtime settings. Unlike static configuration, settings can be changed while WirePlumber is running — from wpctl settings, or by any client writing to the sm-settings metadata — and scripts can subscribe to be notified when they change.

Every setting must be declared in the wireplumber.settings.schema section of the configuration, which defines its type, default value and (for numbers) its valid range. See Well-known settings for the list of settings that ship with WirePlumber and Modifying configuration for how to change them.

This binds the WpSettings C API. All the functions are static; the underlying WpSettings object is looked up automatically.

Reading settings

Settings.get(name)

Binds wp_settings_get()

Returns the current value of a setting as raw JSON. The typed accessors below are usually more convenient.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting, or nil if it does not exist
Return type:: Json, see Json

Settings.get_boolean(name)

Returns the value of a boolean setting. If the setting does not exist or is not a boolean, false is returned.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: boolean

Settings.get_int(name)

Returns the value of an integer setting, or 0 if it does not exist or is not an integer.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: integer

Settings.get_float(name)

Returns the value of a float setting, or 0 if it does not exist or is not a float.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: number

Settings.get_string(name)

Returns the value of a string setting, or nil if it does not exist or is not a string.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: string

Settings.get_array(name)

Returns the value of an array setting as a Lua table. If the setting does not exist or is not an array, an empty table is returned.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: table

Settings.get_object(name)

Returns the value of a JSON object setting as a Lua table. If the setting does not exist or is not an object, an empty table is returned.

Parameters:: name (string) -- the name of the setting
Returns:: the value of the setting
Return type:: table

Settings.get_saved(name)

Binds wp_settings_get_saved()

Returns the value of the setting as it was persisted to the state file, if it has been saved. This may differ from the current value.

Parameters:: name (string) -- the name of the setting
Returns:: the saved value of the setting, or nil if it has not been saved
Return type:: Json, see Json

Settings.iterate()

Binds wp_settings_new_iterator()

Iterates over all the settings. Intended to be used in a for loop; the iteration yields the setting name and its value on each step.

for name, value in Settings.iterate () do
  log:info (name .. " = " .. value:to_string ())
end

Changing settings

Note

Scripts do not normally need to change settings; this is what wpctl settings and other clients do. These functions exist for scripts that implement such a control interface.

Settings.set(name, value)

Binds wp_settings_set()

Changes the current value of a setting. The change is not persistent unless Settings.save() is also called.

Parameters:

name (string) -- the name of the setting
value (Json) -- the new value

Returns:

true if the setting was changed, false otherwise

Return type:

boolean

Settings.reset(name)

Binds wp_settings_reset()

Resets a setting to the default value declared in the schema.

Parameters:: name (string) -- the name of the setting
Returns:: true on success, false otherwise
Return type:: boolean

Settings.save(name)

Binds wp_settings_save()

Persists the current value of a setting, so that it is restored the next time WirePlumber starts.

Parameters:: name (string) -- the name of the setting
Returns:: true on success, false otherwise
Return type:: boolean

Settings.delete(name)

Binds wp_settings_delete()

Deletes the persisted value of a setting. The current value is not changed.

Parameters:: name (string) -- the name of the setting
Returns:: true on success, false otherwise
Return type:: boolean

Settings.reset_all()

Binds wp_settings_reset_all()

Resets all settings to their default values.

Settings.save_all()

Binds wp_settings_save_all()

Persists the current value of all settings.

Settings.delete_all()

Binds wp_settings_delete_all()

Deletes the persisted values of all settings.

Reacting to changes

Settings.subscribe(pattern, callback)

Binds wp_settings_subscribe_closure()

Calls callback whenever a setting whose name matches pattern changes.

This is the idiomatic way for a script to respond to a setting: read the value once at load time, and then again from the callback. Scripts commonly use this to register or remove an event hook, so that the hook only exists while the setting is enabled — see Enabling and disabling hooks at runtime.

Settings.subscribe ("linking.allow-moving-streams", function ()
  handleMoveSetting (Settings.get_boolean ("linking.allow-moving-streams"))
end)

Parameters:

pattern (string) -- a glob-style pattern matching setting names; use "*" to subscribe to all settings
callback (function) -- the function to call when a matching setting changes

Returns:

an id that can be passed to Settings.unsubscribe()

Return type:

integer

Settings.unsubscribe(id)

Binds wp_settings_unsubscribe()

Cancels a subscription previously created with Settings.subscribe().

Parameters:: id (integer) -- the subscription id
Returns:: true if the subscription was found and removed
Return type:: boolean