normalizeAudioPluginParameter

R2026b

Convert audio plugin property values to normalized values

Since R2026b

collapse all in page

    Syntax

    normValue = normalizeAudioPluginParameter(paramValue,mapMethod,minValue,maxValue)
    normValue = normalizeAudioPluginParameter(paramValue,"pow",exponent,minValue,maxValue)
    normValue = normalizeAudioPluginParameter(paramValue,"enum",enumList)
    normValue = normalizeAudioPluginParameter(paramValue,audioParam)

    Description

    normValue = normalizeAudioPluginParameter(paramValue,mapMethod,minValue,maxValue) returns the normalized value for a parameter with a linear, logarithmic, or integer mapping.

    example

    normValue = normalizeAudioPluginParameter(paramValue,"pow",exponent,minValue,maxValue) returns the normalized value for a parameter with a power mapping.

    normValue = normalizeAudioPluginParameter(paramValue,"enum",enumList) returns the normalized value for a parameter with an enumeration mapping.

    normValue = normalizeAudioPluginParameter(paramValue,audioParam) returns the normalized value for a parameter using the mapping from an existing plugin parameter object.

    example

    Examples

    collapse all

    Open Live Script

    Audio plugin parameters must be normalized to the range [0,1] in VST and AU formats. The normalizeAudioPluginParameter function creates normalized values based on a parameter mapping method and range.

    Many plugins use a dry-wet parameter ranging from 0 (100% dry) to 100 (100% wet). Use a linear map from 0 to 100 to normalize the value 50.

    normValue = normalizeAudioPluginParameter(50,"lin",0,100)
    normValue = 
0.5000

    Parameters that control frequency often use a nonlinear map. Use a logarithmic map from 50 Hz to 1600 Hz to normalize the values 50 Hz, 100 Hz, 200 Hz, 400 hz, 800 Hz, and 1600 Hz (that is, five octaves).

    normValues = normalizeAudioPluginParameter([50,100,200,400,800,1600],"log",50,1600)
    normValues = 1×6

         0    0.2000    0.4000    0.6000    0.8000    1.0000

    Parameters in dB often use a power map. Use a square root map from –80 dB to 20 dB to normalize the values –60 dB, –40 dB, –20 dB, 0 dB, and 20 dB.

    normValues = normalizeAudioPluginParameter([-60,-40,-20,0,20],"pow",1/2,-80,20)
    normValues = 1×5

    0.0400    0.1600    0.3600    0.6400    1.0000

    Discrete and categorical parameters must also be normalized. Use integer mapping to normalize a filter order of 4 from the range 1 to 16. 

    normValue = normalizeAudioPluginParameter(4,"int",1,16)
    normValue = 
0.2000

    Use an enumeration map to normalize the option "Instrument" for an input level parameter with options Mic, Instrument, and Line.

    normValue = normalizeAudioPluginParameter("Instrument","enum",["Mic","Instrument","Line"])
    normValue = 
0.5000
    Open Live Script

    Use the map of an existing audioPluginParameter object to normalize parameter values.

    existingPluginObject = audiopluginexample.VolumeController;
existingGainParam = existingPluginObject.PluginInterface.Parameters.Gain;
normValues = normalizeAudioPluginParameter([-60,-40,-20,0,20],existingGainParam)
    normValues = 1×5

    0.1837    0.3265    0.5102    0.7347    1.0000
    Open Live Script

    When you load an audio plugin into MATLAB® without enabling parameter analysis, you can only set plugin parameters using normalized values. Use the normalizeAudioPluginParameter function to create normalized values using a known mapping.

    Load a VST plugin by specifying its full path and disable parameter analysis. If you are using a Mac, replace the .dll file extension with .vst. 

    pluginPath = fullfile(matlabroot,'toolbox','audio','samples','ParametricEqualizer.dll');
hostedPlugin = loadAudioPlugin(pluginPath,EnableParameterAnalysis=false);

    Set the Low Center Frequency parameter to the normalized values of 0.0, 0.5, and 1.0 and observe the DisplayValue field.

    hostedPlugin.setParameter("Low Center Frequency",0.0);
[~,paramInfo] = hostedPlugin.getParameter("Low Center Frequency")
    paramInfo = struct with fields:
     DisplayName: 'Low Center Frequency'
    DisplayValue: '20.000'
           Label: 'Hz'


    hostedPlugin.setParameter("Low Center Frequency",0.5);
[~,paramInfo] = hostedPlugin.getParameter("Low Center Frequency")
    paramInfo = struct with fields:
     DisplayName: 'Low Center Frequency'
    DisplayValue: '632.456'
           Label: 'Hz'


    hostedPlugin.setParameter("Low Center Frequency",1.0);
[~,paramInfo] = hostedPlugin.getParameter("Low Center Frequency")
    paramInfo = struct with fields:
     DisplayName: 'Low Center Frequency'
    DisplayValue: '20000.000'
           Label: 'Hz'

    The Low Center Frequency parameter has the range 20–20,000 Hz and a normalized midpoint of 632.456 Hz, suggesting a logarithmic map between frequency in Hz and the normalized value. Confirm this relationship using normalizeAudioPluginParameter with a logarithmic map.

    normValue = normalizeAudioPluginParameter(632.456,"log",20,20000)
    normValue = 
0.5000

    Use normalizeAudioPluginParameter to set the Low Center Frequency parameter to 1000 Hz.

    normValue = normalizeAudioPluginParameter(1000,"log",20,20000);
hostedPlugin.setParameter("Low Center Frequency", normValue);
[paramValue,paramInfo] = hostedPlugin.getParameter("Low Center Frequency")
    paramValue = 
0.5663

    paramInfo = struct with fields:
     DisplayName: 'Low Center Frequency'
    DisplayValue: '1000.000'
           Label: 'Hz'

    Input Arguments

    collapse all

    Parameter value to normalize, specified as a numeric value for linear, logarithmic, and power mappings, integer for integer mapping, or string for mapping with enumeration.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | string | character vector

    Method of parameter mapping, specified as one of the values listed in this table.

    ValueDescriptionInput data type

    "lin"

    Use a linear mapping. Provide a minimum and maximum value.

    		paramValue must be numeric.

    "log"

    Use a logarithmic mapping. Provide a minimum and maximum value.

    		paramValue must be numeric and nonnegative.

    "int"

    Use an integer mapping. Provide a minimum and maximum value.

    		paramValue must be an integer.

    "pow"

    Use a power mapping. Provide an exponent, minimum value, and maximum value.

    		paramValue must be numeric.

    "enum"

    Use an enumeration mapping. Provide an ordered list of enumerative states.

    		paramValue must be a string or character vector.

    Data Types: string | character vector

    Exponent of power mapping, specified as a positive scalar. Specify this argument when mapMethod is "pow".

    Data Types: single | double

    Minimum value for numeric mappings, specified as a scalar. Specify this argument when mapMethod is "lin","log","int" or "pow".

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

    Maximum value for numeric mappings, specified as a scalar. Specify this argument when mapMethod is "lin","log","int" or "pow".

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

    Ordered list of enumerative states, specified as a vector of strings. Specify this argument when mapMethod is "enum".

    Data Types: string vector

    Audio parameter with existing mapping, specified as a pluginParameter object created by the audioPluginParameter function. paramValue must be the same data type as the existing mapping.

    Output Arguments

    collapse all

    Normalized parameter value in the range [0,1].

    Version History

    Introduced in R2026b

    See Also

    | | |

    Topics