[iiwusynth-devel] Proposition: Settings API

[Peter Hanappe]

Hi all,

As Josh said, the current way to change the values in the setting
structure is not a good long term solution. Also, if we design
a good API, the settings may be reused more generally as a control
interface to the synthesizer. Below you find what I've got so far.
I commited a test implementation of the settings API in the current
CVS version. You can play with it in the shell interface of iiwusynth.

Ideas are welcome!

Cheers,
Peter

--------------

Public API:

To create a synthesizer, you have to pass a 'settings' object, like
before. The settings object is opaque and has to be created with the
new_iiwu_settings() function, and it is filled with the default values.
In C:

  iiwu_settings_t* settings = new_iiwu_settings();
  iiwu_synth_t* synth = new_iiwu_synth(settings);

Still only two lines of code to get the synth running.

There are two main functions to change settings:

  iiwu_settings_setnum(settings, "midi.channels", value);
  iiwu_settings_setstr(settings, "midi.driver.name", "alsa_seq");

The first one sets a parameter with a numeric value; the second one a
parameter with a string value. Both take a string as the name of the
parameter. The parameter names use a '.' notation to group
settings. Number values are stored as 'float'. If a parameter does not
exist before calling one of the iiwu_settings_set functions, it will
be created.

Similarly you can get the value of a parameter as:

  iiwu_settings_getnum(settings, "midi.channels", &value);
  iiwu_settings_getstr(settings, "midi.driver.name", &s);


You can ask the type of a parameter with 'iiwu_settings_get_type'. For
numeric parameters, the additional API functions are:

- iiwu_settings_get_range: get [min,max] values
- iiwu_settings_get_default: get the default value
- iiwu_settings_get_hints: get some hints (cfr. hints in LADSPA API)
- iiwu_settings_is_realtime: is the parameter controllable in RT


Plugin API:

Plugins can use the following functions to register parameters:

  iiwu_settings_register_str(settings, name, value);
  iiwu_settings_register_num(settings, name, min, max, def, hints, 
callback, data);

Most of the function arguments are clear, I think. The 'callback'
arguments is a callback function that will be invoked if the parameter
has been changed after a call to 'iiwu_settings_setnum'.


Shell interface:

New commands:

  - set name value  Set the value of a controller or settings
  - get name        Get the value of a controller or settings
  - info name       Get information about a controller or settings
  - settings        Print out all settings


Implementation details:

The settings are stored in a tree structure. Parameters names are
tokenized using the '.' as a delimiter and the tokens are used to
traverse the tree structure. Each non-leaf node of the tree is
implemented as a hash table to speed up the searches.


Advantages:

- Plugins can easily export their controllers by registering them to
  the settings system.

- Users can set a parameter *before* a plugin has been loaded. When
  the plugin gets loaded, it will find the user-set parameter value.

- It's now easier to pass parameters to the various drivers. Also,
  drivers can offer more sophisticated features. For example, a
  OpenAL/DirectSound3D driver can create a number of sources that can
  be positioned in space through the settings interface.

- Using the sysex extension, as Markus proposed, any settings can be
  changed over MIDI.

- It will be easy to couple this to the OpenSoundControl protocol.

- It may be easier to integrate this with languages such as Python and
  JavaScript. In Python:

    settings = FluidSettings();
    settings.reverb.width = 100