# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# audioPluginParameter

Specify audio plugin parameters

## Syntax

``pluginParameter = audioPluginParameter(propertyName)``
``pluginParameter = audioPluginParameter(propertyName,Name,Value)``

## Description

example

````pluginParameter = audioPluginParameter(propertyName)` returns an object, `pluginParameter`, that associates an audio plugin parameter to the audio plugin property specified by `propertyName`. Use the plugin parameter object, `pluginParameter`, as an argument to an `audioPluginInterface` function in your plugin class definition.In a digital audio workstation (DAW) environment, or when using Audio Test Bench in the MATLAB® environment, plugin parameters are tunable, user-facing variables with defined ranges mapped to controls. When you modify a parameter value using a control, the associated plugin property is also modified. If the audio processing algorithm of the plugin depends on properties, the algorithm is also modified.To visualize the relationship between plugin properties, parameters, and the environment in which a plugin is run, see Implementation of Audio Plugin Parameters. ```

example

````pluginParameter = audioPluginParameter(propertyName,Name,Value)` specifies `audioPluginParameter` properties using one or more `Name,Value` pair arguments.```

## Examples

collapse all

Create a basic audio plugin class definition file. Specify a property, `Gain`, and a processing function that multiplies input by `Gain`.

```classdef myAudioPlugin < audioPlugin properties Gain = 1; end methods function out = process(plugin,in) out = in*plugin.Gain; end end end```

Add a constant property, `PluginInterface`, which is specified as an `audioPluginInterface` object.

```classdef myAudioPlugin < audioPlugin properties Gain = 1; end properties (Constant) PluginInterface = audioPluginInterface; end methods function out = process(plugin,in) out = in*plugin.Gain; end end end```

Pass `audioPluginParameter` to `audioPluginInterface`. To associate the plugin property, `Gain`, to a plugin parameter, specify the first argument of `audioPluginParameter` as the property name, `'Gain'`.

```classdef myAudioPlugin < audioPlugin properties Gain = 1; end properties (Constant) PluginInterface = audioPluginInterface(... audioPluginParameter('Gain')); end methods function out = process(plugin,in) out = in*plugin.Gain; end end end```

Create a basic plugin class definition file. Specify `'DisplayName'` as ```'Awesome Gain'```, `'Label'` as `'linear'`, and `'Mapping'` as `{'lin',0,20}`.

```classdef myAudioPlugin < audioPlugin properties Gain = 1; end properties (Constant) PluginInterface = audioPluginInterface(... audioPluginParameter('Gain',... 'DisplayName', 'Awesome Gain',... 'Label', 'linear',... 'Mapping', {'lin',0,20})); end methods function out = process(plugin,in) out = in*plugin.Gain; end end end```

The following class definition uses integer parameter mapping to define the relationship between a property and a parameter. You can use the plugin created from this class to tune the linear gain of an audio signal in integer steps from 0 to 3.

```classdef pluginWithIntegerMapping < audioPlugin properties Gain = 1; end properties (Constant) PluginInterface = audioPluginInterface( ... audioPluginParameter('Gain', ... 'Mapping', {'int',0,3})); end methods function out = process(plugin,in) out = in*plugin.Gain; end end end ```

To run the plugin, save the class definition to a local folder and then call the Audio Test Bench.

```audioTestBench(pluginWithIntegerMapping) ```

The following class definition uses power parameter mapping to define the relationship between a property and a parameter. You can use the plugin created from this class to tune the gain of an audio signal in dB.

```classdef pluginWithPowerMapping < audioPlugin properties Gain = 0; end properties (Constant) PluginInterface = audioPluginInterface( ... audioPluginParameter('Gain', ... 'Label', 'dB', ... 'Mapping', {'pow', 1/3, -140, 12})); end methods function out = process(plugin,in) dBGain = 10^(plugin.Gain/20); out = in*dBGain; end end end ```

To run the plugin, save the class definition to a local folder and then call the Audio Test Bench.

```audioTestBench(pluginWithPowerMapping) ```

The following class definition uses logarithmic parameter mapping to define the relationship between a property and a parameter. You can use the plugin created from this class to tune the center frequency of a single-band EQ filter from 100 to 10000.

```classdef pluginWithLogMapping < audioPlugin properties EQ CenterFrequency = 1000; end properties (Constant) PluginInterface = audioPluginInterface( ... audioPluginParameter('CenterFrequency', ... 'Mapping', {'log',100,10000})); end methods function plugin = pluginWithLogMapping plugin.EQ = multibandParametricEQ('NumEQBands',1, ... 'PeakGains',20, ... 'Frequencies',plugin.CenterFrequency); end function out = process(plugin,in) out = plugin.EQ(in); end function set.CenterFrequency(plugin,val) plugin.CenterFrequency = val; plugin.EQ.Frequencies = val; end function reset(plugin) plugin.EQ.SampleRate = getSampleRate(plugin); end end end ```

To run the plugin, save the class definition to a local folder and then call the Audio Test Bench.

```audioTestBench(pluginWithLogMapping) ```

The following class definition uses enumeration parameter mapping to define the relationship between a property and a parameter. You can use the plugin created from this class to block or pass through the audio signal by tuning the `PassThrough` parameter.

```classdef pluginWithLogicalEnumMapping < audioPlugin properties PassThrough = true; end properties (Constant) PluginInterface = audioPluginInterface( ... audioPluginParameter('PassThrough', ... 'Mapping', {'enum','Block signal','Pass through'})); end methods function out = process(plugin,in) if plugin.PassThrough out = in; else out = zeros(size(in)); end end end end ```

To run the plugin, save the class definition to a local folder and then call the Audio Test Bench.

```audioTestBench(pluginWithLogicalEnumMapping) ```

The following class definitions comprise a simple example of enumeration parameter mapping for properties defined by an enumeration class. You can specify the operating mode of the plugin created from this class by tuning the `Mode` parameter.

Plugin Class Definition

```classdef pluginWithEnumMapping < audioPlugin properties Mode = OperatingMode.boost; end properties (Constant) PluginInterface = audioPluginInterface(... audioPluginParameter('Mode',... 'Mapping',{'enum','+6 dB','-6 dB','silence','white noise'})); end methods function out = process(plugin,in) switch (plugin.Mode) case OperatingMode.boost out = in * 2; case OperatingMode.cut out = in / 2; case OperatingMode.mute out = zeros(size(in)); case OperatingMode.noise out = rand(size(in)) - 0.5; otherwise out = in; end end end end ```

Enumeration Class Definition

```classdef OperatingMode < int8 enumeration boost (0) cut (1) mute (2) noise (3) end end ```

To run the plugin, save the plugin and enumeration class definition files to a local folder. Then call the Audio Test Bench on the plugin class.

```audioTestBench(pluginWithEnumMapping) ```

## Input Arguments

collapse all

Name of the audio plugin property that you want to associate with a parameter, specified as a character vector. Enter the property name exactly as it is defined in the property section of your audio plugin class.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `'DisplayName','Gain','Label','dB'` specifies the display name of your parameter as `'Gain'` and the display label for parameter value units as `'dB'`.

collapse all

Display name of your parameter, specified as a comma-separated pair consisting of `'DisplayName'` and a character vector. If `'DisplayName'` is not specified, the name of the associated property is used.

The display name of your parameter is used in a digital audio workstation (DAW) environment, and when using Audio Test Bench in the MATLAB environment.

Display label for parameter value units, specified as a comma-separated pair consisting of `'Label'` and a character vector.

The display label for parameter value units is used in a digital audio workstation (DAW) environment, and when using Audio Test Bench in the MATLAB environment.

The `'Label'` name-value pair is ignored for nonnumeric parameters.

Mapping between property and parameter range, specified as the comma-separated pair consisting of `'Mapping'` and a cell array.

Parameter range mapping specifies a mapping between a property and the associated parameter range.

The first element of the cell array is a character vector specifying the kind of mapping. The valid values are `'lin'`, `'log'`, `'pow'`, `'int'`, and `'enum'`. The subsequent elements of the cell array depend on the kind of mapping. The valid mappings depend on the property data type.

Property Data TypeValid MappingsDefault
double`'lin'`, `'log'`, `'pow'`, `'int'`{`'lin'`, `0`, `1`}
logical`'enum'`{`'enum'`, `'off'`, `'on'`}
enumeration class`'enum'`enumeration names
MappingDescriptionExample
`'lin'`

Specifies a linear relationship with given minimum and maximum values.

$\left(property\text{\hspace{0.17em}}value\right)=\mathrm{min}+\left(\mathrm{max}-\mathrm{min}\right)×\left(parameter\text{\hspace{0.17em}}value\right)$

{`'lin'`, `0`, `24`} specifies a linear relationship with a minimum of 0 and maximum of 24.

Simple Example: Specify Parameter Information

`'log'`

Specifies a logarithmic relationship with given minimum and maximum values, where the control position maps to the logarithm of the property value. The minimum value must be greater than `0`.

$\left(property\text{\hspace{0.17em}}value\right)=\mathrm{min}\text{\hspace{0.17em}}×\text{\hspace{0.17em}}{\left(\mathrm{max}/\mathrm{min}\right)}^{\left(parameter\text{\hspace{0.17em}}value\right)}$

{`'log'`, `1`, `22050`} specifies a logarithmic relationship with a minimum of 1 and a maximum of 22050.

Simple Example: Logarithmic Parameter Mapping

`'pow'`

Specifies a power law relationship with given exponent, minimum, and maximum values. The property value is related to the control position raised to the exponent:

$\left(property\text{\hspace{0.17em}}value\right)=\mathrm{min}+\left(\mathrm{max}-\mathrm{min}\right)×{\left(parameter\text{\hspace{0.17em}}value\right)}^{\mathrm{exp}}$

{`'pow'`, `1/3`, `-140`, `12`} specifies a power law relationship with an exponent of 1/3, a minimum of –140, and a maximum of 12.

Simple Example: Power Parameter Mapping

`'int'`

Quantizes the control position and maps it to the range of consecutive integers with given minimum and maximum values.

$\left(property\text{\hspace{0.17em}}value\right)=floor\left(0.5+\mathrm{min}+\left(\mathrm{max}-\mathrm{min}\right)×\left(parameter\text{\hspace{0.17em}}value\right)\right)$

{`'int'`, `0`, `3`} specifies a linear, quantized relationship with a minimum of 0 and maximum of 3. The property value is mapped as an integer in the range 0 to 3.

Simple Example: Integer Parameter Mapping

`'enum' ` (logical)

Optionally provides character vectors for display on the plugin dialog box.

```{'enum','Block signal','Passthrough'}``` specifies the character vector `'Block signal'` if the parameter value is `false` and `'Passthrough'` if the parameter value is `true`.

Simple Example: Enumeration for Logical Properties Parameter Mapping

`'enum'` (enumeration class)

Optionally provides character vectors for the members of the enumeration class.

{`'enum'`, ```'+6 dB'```, `'-6 dB'`, `'silence'`, ```'white noise'```} specifies the character vectors `'+6 dB'`, ```'-6 dB'```, `'silence'`, and `'white noise'`.

Simple Example: 'enum' for Enumeration Class Parameter Mapping

For nontrivial examples of audio plugin parameter mapping, see Audio Plugin Example Gallery.

collapse all

### Implementation of Audio Plugin Parameters

Audio plugin parameters are visible and tunable in both the MATLAB and digital audio workstation (DAW) environments.

MATLAB Environment.  Use Audio Test Bench to interact with plugin parameters in the MATLAB environment.

DAW Environment.  Use `generateAudioPlugin` to deploy your audio plugin to a DAW environment. The DAW environment determines the exact layout of plugin parameters as seen by the plugin user.