audioPluginParameter
Specify audio plugin parameters
Syntax
Description
pluginParameter = audioPluginParameter(
returns an object, propertyName
)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(
specifies propertyName
,Name,Value
)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:
Read a frame from the file.
Feed the frame through the plugin
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'
.
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. | { 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. | { 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:
| { Example: Power Parameter Mapping |
'int' |
Quantizes the control position and maps it to the range of consecutive integers with given minimum and maximum values.
| { Example: Integer Parameter Mapping |
| Optionally provides character vectors for display on the plugin dialog box. |
Example: Enumeration for Logical Properties Parameter Mapping |
| Optionally provides character vectors for the members of the enumeration class. | { |
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 ofLayout
and spans the same rows asLayout
."right"
–– The display name is located in the column to the right ofLayout
and spans the same rows asLayout
."above"
–– The display name is located in the row aboveLayout
and spans the same columns asLayout
"below"
–– The display name is located in the row belowLayout
and spans the same columns asLayout
."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 |
---|---|---|---|
| single double |
|
|
| logical |
|
|
| enumeration with 2 values |
|
|
| enumeration |
|
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
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)