Adjust parameters
-----------------

Audio Processors within an audio context may expose parameters which can be adjusted on the fly. The exact parameters
that are available depend on the exact processing chain requested. After an **audio context config** has been
successfully created the available parameters can be retrieved from the **parameters** attribute.

The **parameters** returned are a list of **processor parameters** objects. In most use cases there will be the
same number of groups returned as processors requested in the **audio context request** used to create the processing
context. These will also be in the same order that the processors were requested, and also the order in which any set
parameters will be applied.

Each **processor parameters** contains a number of **parameter description** objects for a single step of the
audio processing chain. A **processor parameters** also has a **name** attribute which should match the processors
requested, along with a unique id.

For example a processing context consisting of a **clarity** processor followed by a **gain** processor might have the
following parameters:


.. tabs::

  .. code-tab:: c++

    // create an audio processing context
    Iris::AudioContextRequest configRequest{.processors = {"clarity", "gain"}};
    Iris::AudioContextConfig config = Iris::createAudioContext(configRequest);

    // list parameters in each group
    for (const auto& group : config.parameters) {
      std::cout << "Parameter group " << group.name << " with id " << group.id << std::endl;
      for (const auto& description : group.parameterDescriptions) {
        std::cout << "\tParameter  " << description.name << " with id " << description.id << " default " << description.defaultValue << std::endl;
      }
    }

  .. code-tab:: py

    # create an audio processing context
    context_request = iris.sdk.AudioContextRequest()
    context_request.processors = ["clarity", "gain"]
    config = iris.sdk.create_audio_context(context_request)

    # list parameters in each group
    for group in config.parameters:
        print(f"Parameter group {group.name} with id {group.id}")
        for description in group.parameter_descriptions:
          print(f"    Parameter {description.name} with id {description.id} default {description.default_value}")

  .. code-tab:: typescript

    // create an audio processing context
    const contextRequest: AudioContextRequest = { processors = ["clarity", "gain"] };
    config = iris.sdk.createAudioContext(contextRequest)
    // list parameters in each group
    for (const group of config.parameters) {
      console.log(`Parameter group ${group.name} with id ${group.id}`);
      for (const description of group.parameterDescriptions) {
        console.log(`Parameter ${description.name} with id ${description.id} default ${description.defaultValue}`);
      }
    }

with the following output:

.. code-block:: console

    Parameter group clarity with id clarity
        Parameter  bypass with id de05fec9-2f61-e842-f695-8454b9f368ba default 0
        Parameter  postfilter with id 001b86d3-1e7c-128a-6c22-04aedbb2bc2d default 0
        Parameter  mix with id 2094d701-287d-c34f-1755-c7ee8b7d01c9 default 1
    Parameter group gain with id gain
        Parameter  bypass with id 5a7f88f0-3ec0-562d-2e41-4d283f803490 default 0
        Parameter  gain_db with id 03150a55-8a07-a1b3-d433-35151ff95f5a default 0


A **parameter description** contains a number of useful attributes such as a **display name**, the **default value** and **min / max values**.
The **id** is a unique id for this parameter, within this context.

For boolean toggle parameters any value except 0.0 is treated as true. Setting a parameter to a value outside of its min and max bounds will cause the value to be clamped.


.. warning::
    Parameter **id** attributes are generated dynamically and must be queried at runtime to be usable. Do not cache these for usage in a different context!

The **id** is used to both query and set the value for a single parameter. Parameters can be set and queried with the functions **set parameter** and **get parameter**.

As seen in the above example the **clarity** processor exposes a **mix** level that can be used to control the amount of voice isolation applied to the audio stream.


.. tabs::

  .. code-tab:: c++

    // ....
    // create context...
    // ...
    // look for the mix parameter in the clarity processor
    auto clarityMixParams = Iris::findParameterDescription(config.contextId, "clarity", "mix");
    auto clarityMixParamId = clarityMixParams[0].id;

    // get the mix level
    auto mixLevel = Iris::getParameter(config.contextId, clarityMixParamId);

    // set the mix level
    mixLevel = 0.75f;
    Iris::setParameter(config.contextId, clarityMixParamId, mixLevel);

    // ...
    // call process
    // ...

  .. code-tab:: py

    # ....
    # create context...
    # ...
    # look for the mix parameter in the clarity processor
    clarity_mix_params = iris.sdk.find_parameter_description(config.context_id, "clarity", "mix")
    clarity_mix_param_id = clarity_mix_params[0].id

    # get the mix level
    mix_level = iris.sdk.get_parameter(config.context_id, clarity_mix_param_id)

    # set the mix level
    mix_level = 0.75
    iris.sdk.set_parameter(config.context_id, clarity_mix_param_id, mix_level)

    # ...
    # call process
    # ...

  .. code-tab:: typescript

    // ....
    // create context...
    // ...
    // look for the mix parameter in the clarity processor
    const clarityMixParams = iris.findParameterDescription(config.contextId, 'clarity', 'mix');
    const clarityMixParamId = clarityMixParams[0].id

    // get the mix level
    const level = iris.getParameter(config.contextId, clarityMixParamId)

    // set the mix level
    const mixLevel = 0.75
    iris.setParameter(config.contextId, clarityMixParamId, mixLevel)

    // ...
    // call process
    // ...

.. note::
    A **parameter description** describes a parameter, including its default value, but does not reflect the actual current value.

Parameters can be set or queried at any time after an audio context is created. The **parameter groups** returned in the **audio context config** are valid for the lifetime of that context only.
Parameters can be set at any time after audio context creation and are applied at the start of the next call to **process()**.