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:

// 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;
  }
}

# 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}")

// 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:

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.

// ....
// 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
// ...

# ....
# 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
# ...

// ....
// 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().