Parameters

Like most plugin APIs, the parameters need to be exposed to the host in a certain way. The JSAP plugins do this through through the parameter object. Every single JSAP is given a parameter management class (inventively called PluginManager). This object is responsible for managing all of the parameters in your plugin. It is important to use this for any user-facing paramters since it is queried by the host to interact with your plugin.

Parameters are referenced by their name, rather than an index (although listing is supported). Therefore each parameter in a plugin must have a unique name to reference it.

Accessing

this.parameters; // The ParameterManager instance

this.parameters.parameters; // The current list of parameters

this.parameters.getParameterNames(); // The list of parameter names

this.parameters.getParameterByName(name); // Return a parameter object by its name

this.parameters.getParameterObject(); // Return all the parameters as an object

this.parameters.setParameterByName(name, value); // Get a parameter by its name and set to value

this.parameters.setParametersByObject(obj); // Set multiple parameters using key->value objects

The above defines the interface for the ParameterManager interface. All of these can also be called using this rather than this.parameters, except this.parameters.parameters. For instance, this.parameters.getParameterNames() == this.getParameterNames().

PluginParameter

Every plugin parameter inherits the following interface:

PluginParameter.name; // Get the parameter name
PluginParameter.owner; // Get the plugin which owns this parameter
PluginParameter.update; // Get/Set the update function
PluginParameter.translate; // Get/Set the translate function
PluginParameter.trigger; // Get/Set the trigger function
PluginParameter.bindToAudioParam(ap); // Set the audio parameter to bind to
PluginParameter.boundAudioParam; // Get the bound audio param
PluginParameter.actionList; // Get the action history for the parameter

Binding to Audio Parameters

Each plugin can bind itself to an audio parameter. For basic functions, a direct manipulation can be used, for instance a frequency parameter for a Biaquad Filters' frequency control. Each parameter has a function called bindToAudioParam which accepts the audio parameter as an input, for instance:

var gain_param; // A NumberParameter Object
var gain_node; // A web audio API gain node
// gain_param.boundAudioParam == undefined
gain_param.bindToAudioParam(gain_node.gain);
// gain_param.boundAudioParam == gain_node.gain

When a parameter is bound to an audio parameter, every update value update is sent to the parameter. All queries of the current parameter value will update the parameter with the audio parameter value.

Translate and Update

There are times when a parameter value does not directly match an audio parameter. For instance, the Web Audio API gain node operates in linear gain values, however it may be desirable to operate in decibel values. The translate and update values can convert between the two.

Update: Converting from parameter to audio parameter Translate: Converting from audio parameter to parameter

For the decibel parameter example:

var gain_param; // A NumberParameter Object
var gain_node; // A web audio API gain node
gain_param.translate = function(v) {
    return 20.0 * Math.log10(v);
}
gain_param.update = function(v) {
    return Math.pow(10, v/20.0);
}

gain_param.update(-6); // 0.5011;
gain_param.translate(0.5011); //-6.0015;

Trigger

Each parameter has a special trigger function available, except for the ButtonParameter, where it is the onclick itself. This is called every time a plugin value is updated, enabling a callback to another function.

The trigger can be called with a custom this argument to call the parameter with a different object, otherwise it will be called with the window this.

For example, when we update the gain parameter, we could use trigger to log to the console

gain_param.trigger = function() {
    console.log(this.value);
}.bind(gain_param);
// Use the .bind to append a cutom this object

Types of Parameters

There are four parameter types designed for specific data types:

All of these parameter types inherit the SuperClass object PluginParameter which gives certain global for every parameter type.

Number Parameter

This is designed for any parameter which takes a numerical value of a range type and has the following interface:

// Inherited from PluginParameter
NumberParameter.name; // Get the parameter name
NumberParameter.owner; // Get the plugin which owns this parameter
NumberParameter.update; // Get/Set the update function
NumberParameter.translate; // Get/Set the translate function
NumberParameter.trigger; // Get/Set the trigger function
NumberParameter.bindToAudioParam(ap); // Set the audio parameter to bind to
NumberParameter.boundAudioParam; // Get the bound audio param
NumberParameter.actionList; // Get the action history for the parameter

// Unique to Number
NumberParameter.minimum; // Get the minimum accepted value (inclusive)
NumberParameter.maximum; // Get the maximum accepted value (inclusive)
NumberParameter.defaultValue; // Get the default value
NumberParameter.value; // Get/Set the parameter value
NumberParameter.stepSize; //Get/Set the accepted step size

String Parameter

This is designed for a string type and stores the input string as a value.

// Inherited from PluginParameter
StringParameter.name; // Get the parameter name
StringParameter.owner; // Get the plugin which owns this parameter
StringParameter.update; // Get/Set the update function
StringParameter.translate; // Get/Set the translate function
StringParameter.trigger; // Get/Set the trigger function
StringParameter.bindToAudioParam(ap); // Set the audio parameter to bind to
StringParameter.boundAudioParam; // Get the bound audio param
StringParameter.actionList; // Get the action history for the parameter

// Unique to Number
StringParameter.maxLength; // Get the maximum number of characters a string can hold
StringParameter.defaultValue; // Get the default string value
StringParameter.value; // Get / Set the current string

Button Parameter

This is for an action / event based interface, for click or action parameters.

// Inherited from PluginParameter
ButtonParameter.name; // Get the parameter name
ButtonParameter.owner; // Get the plugin which owns this parameter
ButtonParameter.update; // Get/Set the update function
ButtonParameter.translate; // Get/Set the translate function
ButtonParameter.trigger; // Get/Set the trigger function
ButtonParameter.bindToAudioParam(ap); // Set the audio parameter to bind to
ButtonParameter.boundAudioParam; // Get the bound audio param
ButtonParameter.actionList; // Get the action history for the parameter

// Unique to Number
ButtonParameter.onclick; // Get/Set the function to execute on button click

Switch Parameter

This is for a switch or iterative list based operators. Rather than setting a value directly, it will iterate through a range of possible integer values. For instance, it can be used for an on/off button (range of 0 to 1) or a filter type selector (1 = Low Pass, 2 = High Pass, 3 = Band Pass etc.).

// Inherited from PluginParameter
SwitchParameter.name; // Get the parameter name
SwitchParameter.owner; // Get the plugin which owns this parameter
SwitchParameter.update; // Get/Set the update function
SwitchParameter.translate; // Get/Set the translate function
SwitchParameter.trigger; // Get/Set the trigger function
SwitchParameter.bindToAudioParam(ap); // Set the audio parameter to bind to
SwitchParameter.boundAudioParam; // Get the bound audio param
SwitchParameter.actionList; // Get the action history for the parameter

// Unique to Number
SwitchParameter.defaultValue; // Get the default value
SwitchParameter.minState; // Get the lowest inclusive state value
SwitchParameter.maxState; // Get the highest inclusive state value
SwitchParameter.value; // Get/Set the current state value
SwitchParameter.increment(); // Increase the state value by one and auto-wrap
SwitchParameter.decrement(); // Decrease the state value by one and auto-wrap

Constructors

Each type of parameter has its own constructor, exposed by the this.parameter object inherited in each plugin instance. The constructors here will ensure the parameter arguments are valid, a parameter name is not already used, build the parameter and add it to the plugin parameter list.

Number Parameter

Argument Type Mandatory
name String Yes
defaultValue Number Yes
minimum Number No
maximum Number No
// Number Parameter
this.parameter.createNumberParamter(name, defaultValue, minimum, maximum)

String Parameter

Argument Type Mandatory
name String Yes
defaultValue String Yes
maxLength Number No
// Number Parameter
this.parameter.createStringParameter(name, defaultValue, maxLength)

Button Parameter

Argument Type Mandatory
name String Yes
// Number Parameter
this.parameter.createButtonParameter(name)

Switch Parameter

Argument Type Mandatory
name String Yes
defaultValue Number Yes
minState Number Yes
maxState Number Yes
// Number Parameter
this.parameter.createSwitchParameter(name, defaultValue, minState, maxState)