# 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 `audioPluginInterface` in your plugin class definition.In a digital audio workstation (DAW) environment, or when using Audio Test Bench or `parameterTuner` in the MATLAB® environment, plugin parameters are tunable, user-facing values 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,4}, ... 'Layout',[1,1], ... 'Style','vslider'), ... audioPluginGridLayout('RowHeight',[400,20])); 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}, ... 'Style','rotary', ... 'Layout',[1,1]), ... audioPluginGridLayout); 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'}, ... 'Layout',[1,1], ... 'Style','vtoggle', ... 'DisplayNameLocation','none'), ... audioPluginGridLayout); 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 create an audio I/O stream loop.

First, create objects to read from a file and write to your device.

```fileReader = dsp.AudioFileReader('Engine-16-44p1-stereo-20sec.wav'); deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);```

Create a plugin object and set the sample rate to the sample rate of the file.

```passThrough = pluginWithLogicalEnumMapping; setSampleRate(passThrough,fileReader.SampleRate)```

Open a `parameterTuner` so that you can toggle the logical parameter of the plugin while stream processing.

`parameterTuner(passThrough)`

While the file contains unread data:

1. Read a frame from the file.

2. Feed the frame through the plugin

3. Write the processed audio to your device.

While the audio stream runs, toggle the `PassThrough` parameter and listen to the effect.

```while ~isDone(fileReader) audioIn = fileReader(); audioOut = process(passThrough,audioIn); deviceWriter(audioOut); drawnow limitrate end```

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 or string. Enter the property name exactly as it is defined in the property section of your audio plugin class.

Data Types: `char` | `string`

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

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

Mappings

collapse all

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.

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 22,050.

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.

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)=\mathrm{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, 3].

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

`'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'```.

Graphical User Interface

collapse all

Grid cells occupied by parameter control, specified as a comma-separated pair consisting of `'Layout'` and a two-element row vector or 2-by-2 matrix. To use a single cell, specify [row, column] of the cell. To span multiple cells, specify the upper left and lower right cells as [upper, left; lower, right].

Example: `'Layout',[2,3]`

Example: `'Layout',[2,3;3,6]`

#### Dependencies

To enable this name-value pair, pass an `audioPluginGridLayout` object to `audioPluginInterface`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

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

Data Types: `char` | `string`

Location of `DisplayName` relative to `Layout`, specified as `"left"`, `"right"`, `"above"`, `"below"`, or `"none"`.

• `"left"` –– The display name is located in the column to the left of `Layout` and spans the same rows as `Layout`.

• `"right"` –– The display name is located in the column to the right of `Layout` and spans the same rows as `Layout`.

• `"above"` –– The display name is located in the row above `Layout` and spans the same columns as `Layout`

• `"below"` –– The display name is located in the row below `Layout` and spans the same columns as `Layout`.

• `"none"` –– `DisplayName` is suppressed.

The `DisplayName` of the parameter does not occupy the same grid cells as the control for the parameter.

Example: `DisplayNameLocation="left"`

#### Dependencies

To enable this name-value argument, pass an `audioPluginGridLayout` object to `audioPluginInterface`.

Data Types: `char` | `string`

Location of edit box for the parameter relative to the control, specified as `"left"`, `"right"`, `"above"`, `"below"`, or `"none"`.

• `"left"` –– The edit box is located to the left of the control.

• `"right"` –– The edit box is located to the right of the control.

• `"above"` –– The edit box is located above the control.

• `"below"` –– The edit box is located below the control.

• `"none"` –– The edit box is suppressed.

The edit box exists so that users can directly enter a numeric value if the control `Style` is `"hslider"`, `"vslider"`, or `"rotaryknob"`.

The edit box occupies the same grid cells as the control for the parameter, which are the cells specified by `Layout`.

Example: `EditBoxLocation="right"`

#### Dependencies

To enable this name-value argument, pass an `audioPluginGridLayout` object to `audioPluginInterface`.

This argument only applies if `Style` is `"hslider"`, `"vslider"`, or `"rotaryknob"`.

Data Types: `char` | `string`

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

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

Data Types: `char` | `string`

Visual control for plugin parameter, specified as a comma-separated pair consisting of `'Style'` and a string or character vector:

StyleDescription
`'hslider'`

Horizontal slider

`'vslider'`

Vertical slider

`'rotaryknob'`

Rotary knob

`'checkbox'`

Check box

`'vrocker'`

Vertical rocker switch

`'vtoggle'`

Vertical toggle switch

`'dropdown'`

Dropdown

Default and valid styles depends on the plugin parameter `Mapping` and corresponding property class:

`lin`

`log`

`pow`

`int`

single

double

`hslider`

`vslider`

`rotaryknob`

`enum`

logical

`checkbox`

`dropdown`

`vrocker`

`vtoggle`

`enum`

enumeration with 2 values

`vrocker`

`dropdown`

`vtoggle`

`enum`

enumeration

`dropdown`

#### Dependencies

To enable this name-value pair, pass an `audioPluginGridLayout` object to `audioPluginInterface`.

Data Types: `char` | `string`

Name of PNG, GIF, or JPG graphics file, specified as the comma-separated pair consisting of `'Filmstrip'` and a character vector or string. The graphics file contains a sequence of images of controls.

Filmstrips enable you to replace default control graphics with your own custom images. Filmstrips support all control `Style` values except for dropdowns. A filmstrip is a single image created by concatenating smaller images called frames. Each frame is an image of a control in a particular position. For example, a filmstrip for a switch contains two frames: one depicting the "off" state and another depicting the "on" state. Frames can be concatenated vertically or horizontally. Suppose that the switch frames are 50 pixels wide by 100 pixels high. Then vertical concatenation produces a 50-by-200 pixel filmstrip image, with the top frame used for the switch "off" state. Horizontal concatenation produces a 100-by-100 pixel image, with the left frame used for the switch "off" state. Filmstrips for sliders and knobs typically contain many more frames. The top/left frame corresponds to the minimum control position, and the bottom/right frame corresponds to the maximum control position. The relative control position determines which frame is displayed for a given parameter value.

#### Dependencies

To enable this name-value pair, pass an `audioPluginGridLayout` object to `audioPluginInterface` and specify `'FilmstripFrameSize'`.

Data Types: `char` | `string`

Size of individual frames in the film strip in pixels, specified as the comma-separated pair consisting of `'FilmstripFrameSize'` and a two-element row vector of integers that specify [width, height].

#### Dependencies

To enable this name-value pair, pass an `audioPluginGridLayout` object to `audioPluginInterface` and specify a `'Filmstrip'`.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

To learn how to design a graphic user interface, see Design User Interface for Audio Plugin.

collapse all

### Implementation of Audio Plugin Parameters

Audio plugin parameters are visible and tunable in both the MATLAB and digital audio workstation (DAW) environments. The different environments and corresponding renderings of the audio plugin parameters are outlined here. For an example describing how your class definition maps to the UI, see Design User Interface for Audio Plugin.

MATLAB Environment Using Audio Test Bench.  Use Audio Test Bench to interact with plugin parameters in the MATLAB environment in a complete GUI-based workflow. Using the Audio Test Bench, you can specify audio input and output, analyze your plugin using time- and frequency-domain scopes, connect to MIDI controls, and validate and generate your plugin. The Audio Test Bench honors the graphical user interface you specified in `audioPluginParameter`, `audioPluginGridLayout`, and `audioPluginInterface` (except for filmstrips).

MATLAB Environment Using `parameterTuner`.  Use `parameterTuner` to interact with plugin parameters in the MATLAB environment while developing, analyzing, or using your plugin in a programmatic workflow. The `parameterTuner` honors the graphical user interface you specified in `audioPluginParameter`, `audioPluginGridLayout`, and `audioPluginInterface` (except for filmstrips).

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.

## Version History

Introduced in R2016a