# 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