audioPluginParameter

Specify audio plugin parameters

Syntax

pluginParameter = audioPluginParameter(propertyName)

pluginParameter = audioPluginParameter(propertyName,Name,Value)

Description

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.

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

Examples

Associate Property with Parameter

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

Specify Parameter Information

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

Integer Parameter Mapping

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)

Power Parameter Mapping

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)

Logarithmic Parameter Mapping

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)

Enumeration for Logical Properties Parameter Mapping

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

'enum' for Enumeration Class Parameter Mapping

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

propertyName — Name of audio plugin property

character vector | string

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

Mapping — Mapping between property and parameter range

cell array

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 Type	Valid Mappings	Default
double	'lin', 'log', 'pow', 'int'	{'lin', 0, 1}
logical	'enum'	{'enum', 'off', 'on'}
enumeration class	'enum'	enumeration names

Mapping	Description	Example
'lin'	Specifies a linear relationship with given minimum and maximum values. $$\left(propertyvalue\right)=\min +(\max -\min )\times \left(parametervalue\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(propertyvalue\right)=\min \times {(\max /\min )}^{(parametervalue)}$$	{'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(propertyvalue\right)=\min +(\max -\min )\times {\left(parametervalue\right)}^{\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(propertyvalue\right)=\mathrm{floor}\left(0.5+\min +(\max -\min )\times \left(parametervalue\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. 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'. Example: 'enum' for Enumeration Class Parameter Mapping

Graphical User Interface

Layout — Grid cells occupied by parameter control

[row, column] (single-cell specification) | [upper, left; lower, right] (multi-cell specification)

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

DisplayName — Display name of parameter

associated property name (default) | character vector | string

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

DisplayNameLocation — Location of display name

"left" | "right" | "above" | "below" | "none"

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

EditBoxLocation — Location of edit box

"left" | "right" | "above" | "below" | "none"

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

Label — Display label for parameter value units

' ' (default) | character vector | 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

Style — Visual control for plugin parameter

'hslider' | 'vslider' | 'rotaryknob' | 'checkbox' | 'vrocker' | 'vtoggle' | 'dropdown'

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

Style	Description
'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:

Mapping	Property Class	Default Style	Additional Valid Styles
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

Filmstrip — Name of PNG, GIF, or JPG graphics file

character vector | 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

FilmstripFrameSize — Size of individual frames (pixels)

[width, height]

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.

More About

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