The audio plugin is the suggested paradigm for developing your audio processing algorithm in Audio System Toolbox™. Once designed, the audio plugin can be validated, generated, and deployed to a third-party digital audio workstation (DAW).
Additional benefits of developing your audio processing as an audio plugin include:
Rapid prototyping using the Audio Test Bench
Integration with MIDI devices
Some understanding of object-oriented programming (OOP) in the MATLAB® environment is required to optimize your use of the audio plugin paradigm. If you are unfamiliar with these concepts, see Why Use Object-Oriented Design (MATLAB).
For a review of audio plugins as defined outside the MATLAB environment, see What Are DAWs, Audio Plugins, and MIDI Controllers?
In the MATLAB environment,
an audio plugin refers to a class derived from the
class or the
audioPluginSource base class.
Audio System Toolbox documentation uses the following terminology:
A plugin is any audio plugin
that derives from the
audioPlugin class or the
A basic plugin is an audio
plugin that derives from the
A basic source plugin is an
audio plugin that derives from the
Audio plugins can also inherit from
Any object that derives from
matlab.System is referred
to as a System
object™. Deriving from
for additional functionality, including Simulink® integration.
However, manipulating System objects requires a more advanced understanding
of OOP in the MATLAB environment.
See Audio System Toolbox Extended Terminology for a detailed visualization of inheritance and terminology.
In this example, you create a simple plugin, and then gradually increase complexity. Your final plugin uses a circular buffer to add an echo effect to an input audio signal. For additional considerations for generating a plugin, see Export a MATLAB Plugin to a DAW.
Define a Basic Plugin Class. Begin with a simple plugin that copies input to output without modification.
classdef myEchoPlugin < audioPlugin methods function out = process(~, in) out = in; end end end
myEchoPlugin illustrates the two minimum
requirements for audio plugin classes. They must:
process method contains the primary
frame-based audio processing algorithm. It is called in an audio stream
loop to process an audio signal over time.
By default, both the input to and output from the
have two channels (columns). The number of input rows (frame size)
process is determined by the environment
in which it is run. The output must have the same number of rows as
Add a Plugin Property. A property can store information
in an object. Add a property,
Gain, to your class
definition. Modify your
process method to multiply
the input by the value specified by the
The first argument of the
has changed from
The first argument of
process is reserved for the
audio plugin object. If a variable is specified as the first argument
process, then all
are accessible in the
Add a Plugin Parameter. Plugin parameters are the
interface between plugin properties and the plugin user. The definition
of this interface is handled by
To associate a plugin property to a parameter, specify the first argument
audioPluginParameter as a character vector
entered exactly as the property you want to associate. The remaining
audioPluginParameter specify optional
additional parameter attributes.
In this example, you specify a mapping between the value of
the parameter and its associated property, as well as the parameter
display name as it appears on a plugin dialog box. By specifying
you set a linear mapping between the
and the associated user-facing parameter, with an allowable range
for the property between 0 and 3.
Add Private Properties. Add properties to store
a circular buffer, a buffer index, and the N-sample delay of your
echo. Because the plugin user does not need to see them, make
NSamples private properties. It is best practice
to initialize properties to their type and size.
Add an Echo. In the
write to and read from your circular buffer to create an output that
consists of your input and a gain-adjusted echo. The first line of
process method initializes the output to the
size of the input. It is best practice to initialize your output to
avoid errors when generating plugins.
Make the Echo Delay Tunable. To allow the user
to modify the
NSamples delay of the echo, define
a public property,
Delay, and associate it with
a parameter. Use the default
to allow the user to set the echo delay between 0 and 1 seconds.
set method that listens for changes
Delay property. Use the
audioPlugin base class to return the environment
sample rate. Approximate a delay specified in seconds as a number
NSamples. If the plugin user modifies
called and the delay in samples (
NSamples) is calculated.
If the environment sample rate is above 192,000 Hz, the plugin does
not perform as expected.
Add a Reset Function. The
of a plugin contains instructions to reset the plugin between uses
or when the environment sample rate changes. Because
on the environment sample rate, update its value in the
You can map the basic plugin to a System object plugin. Note the differences between the two plugin types:
object plugin inherits from both the
class and the
matlab.System base class, not just
The primary audio processing method of a System
The reset method of a System
object is named
be defined as protected methods.
System objects enable alternatives to the
For more information, see
In the MATLAB environment, an audio plugin refers to a
class derived from the
audioPlugin base class or
audioPluginSource base class. Audio plugins can
also inherit from
matlab.System. Any object that
matlab.System is referred to as a System
matlab.System allows for additional
functionality, including Simulink integration. However, manipulating
System objects requires a more advanced understanding of OOP in the MATLAB environment.