Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this 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.

(propertyvalue)=min+(maxmin)×(parametervalue)

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

(propertyvalue)=min×(max/min)(parametervalue)

{'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:

(propertyvalue)=min+(maxmin)×(parametervalue)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.

(propertyvalue)=floor(0.5+min+(maxmin)×(parametervalue))

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

More About

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.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Introduced in R2016a

Was this topic helpful?