This is machine translation

Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Translate This Page

MathWorks Machine Translation

The automated translation of this page is provided by a general purpose third party translator tool.

MathWorks does not warrant, and disclaims all liability for, the accuracy, suitability, or fitness for purpose of the translation.

Design an Audio Plugin

Role of Audio Plugins in Audio Toolbox

The audio plugin is the suggested paradigm for developing your audio processing
algorithm in Audio Toolbox™. Once designed, the audio plugin can be validated, generated, and
deployed to a third-party digital audio workstation (DAW).

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).

Defining Audio Plugins in the MATLAB Environment

In the MATLAB environment, an audio
plugin refers to a class derived from the audioPlugin base class or the audioPluginSource base class.

Audio Toolbox documentation uses the following terminology:

A plugin is any audio plugin that derives from
the audioPlugin class or the audioPluginSource class.

A basic plugin is an audio plugin that derives
from the audioPlugin class.

A basic source plugin is an audio plugin that
derives from the audioPluginSource
class.

Audio plugins can also inherit from matlab.System. Any object that derives from matlab.System is referred to as a System
object™. Deriving from matlab.System allows
for additional functionality, including Simulink® integration. However, manipulating System objects requires a more
advanced understanding of OOP in the MATLAB environment.

Design a Basic Plugin

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.

myEchoPlugin illustrates the two minimum requirements
for audio plugin classes. They must:

Inherit from audioPlugin
class

Have a process method

The 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 process
method have two channels (columns). The number of input rows (frame size)
passed to process is determined by the environment in which
it is run. The output must have the same number of rows as the input.

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 Gain property.

The first argument of the process method has changed from
~ to plugin. The first argument of
process is reserved for the audio plugin object. If a
variable is specified as the first argument of process,
then all myEchoPlugin properties are accessible in the
process method.

Add a Plugin Parameter. Plugin parameters are the interface between plugin properties and the
plugin user. The definition of this interface is handled by audioPluginInterface,
which holds audioPluginParameter
objects. To associate a plugin property to a parameter, specify the
first argument of audioPluginParameter as a
character vector entered exactly as the property you want to associate.
The remaining arguments of 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 'Mapping'
as {'lin',0,3}, you set a linear mapping between the
Gain property 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 CircularBuffer,
BufferIndex, and NSamples
private properties. It is best practice to initialize properties to
their type and size.

Add an Echo. In the process method, 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 the 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
audioPluginParameter mapping to allow the user
to set the echo delay between 0 and 1 seconds.

Add a set method that listens for changes to the
Delay property. Use the
getSampleRate method of the audioPlugin base class to return the environment sample rate.
Approximate a delay specified in seconds as a number of samples,
NSamples. If the plugin user modifies the
Delay property, set.Delay is
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 reset method of a plugin contains instructions to
reset the plugin between uses or when the environment sample rate
changes. Because NSamples depends on the environment
sample rate, update its value in the reset
method.

Quick Start Basic Plugin

classdef myBasicPlugin < audioPlugin
% myBasicPlugin is a template basic plugin. Use this template to create% your own basic plugin.properties% Use this section to initialize properties that the end-user interacts% with.endproperties (Access = private)
% Use this section to initialize properties that the end-user does not% interact with directly.endproperties (Constant)
% This section contains instructions to build your audio plugin% interface. The end-user uses the interface to adjust tunable% parameters. Use audioPluginParameter to associate a public property% with a tunable parameter.endmethodsfunction out = process(plugin, in)
% This section contains instructions to process the input audio% signal. Use plugin.MyProperty to access a property of your% plugin.endfunction reset(plugin)
% This section contains instructions to reset the plugin between% uses or if the environment sample rate changes.endfunction set.MyProperty(plugin, val)
% This section contains instructions to execute if the% specified property is modified. Properties associated with% parameters are updated automatically. Use the set method to% execute more complicated instructions.endendend

Quick Start Basic Source Plugin

classdef myBasicSourcePlugin < audioPluginSource
% myBasicSourcePlugin is a template for a basic source plugin. Use this% template to create your own basic source plugin.properties% Use this section to initialize properties that the end-user% interacts with.endproperties (Access = private)
% Use this section to initialize properties that the end-user does% not interact with directly.endproperties (Constant)
% This section contains instructions to build your audio plugin% interface. The end-user uses the interface to adjust tunable% parameters. Use audioPluginParameter to associate a public% property with a tunable parameter.endmethodsfunction out = process(plugin)
% This section contains instructions to produce the output% audio signal. Use plugin.MyProperty to access a property of% your plugin. Use getSamplesPerFrame(plugin) to get the frame% size used by the environment.endfunction reset(plugin)
% This section contains instructions to reset the plugin% between uses, or when the environment sample rate changes.endfunction set.MyProperty(plugin, val)
% This section contains instructions to execute if the% specified property is modified. Properties associated with% parameters are updated automatically. Use the set method to% execute more complicated instructions.endendend

Quick Start System Object Plugin

classdef mySystemObjectPlugin < audioPlugin & matlab.System
% mySystemObjectPlugin is a template for System object plugins.% Use this template to create your own System object plugin.properties% Use this section to initialize properties that the end-user interacts% with.endproperties (Access = private)
% Use this section to initialize properties that the end-user does not% interact with directly.endproperties (Constant)
% This section contains instructions to build your audio plugin% interface. The end-user uses the interface to adjust tunable% parameters. Use audioPluginParameter to associate a public property% with a tunable parameter.endmethods (Access = protected)
function out = stepImpl(plugin)
% This section contains instructions to process the input audio% signal. Use plugin.MyProperty to access a property of your% plugin.endfunction resetImpl(plugin)
% This section contains instructions to reset the plugin between% uses or if the environment sample rate changes.endendmethodsfunction set.MyProperty(plugin, val)
% This section contains instructions to execute if the specified% property is modified. Properties associated with parameters are updated% automatically. Use the set method to execute more complicated% instructions.endendend

Quick Start System Object Source Plugin

classdef mySystemObjectSourcePlugin < audioPluginSource & matlab.System
% mySystemObjectPlugin is a template for System object source plugins.% Use the template to create your own System object source plugin.properties% Use this section to initialize properties that the end-user% interacts with.endproperties (Access = private)
% Use this section to initialize properties that the end-user does% not interact with directly.endproperties (Constant)
% This section contains instructions to build your audio plugin% interface. The end-user uses the interface to adjust tunable% parameters. Use audioPluginParameter to associate a public% property with a tunable parameter.endmethods (Access = protected)
function out = stepImpl(plugin)
% This section contains instructions to produce the output% audio signal. Use plugin.MyProperty to access a property of% your plugin. Use getSamplesPerFrame(plugin) to get the frame% size used by the environment.endfunction resetImpl(plugin)
% This section contains instructions to reset the plugin% between uses or if the environment sample rate changes.endendmethodsfunction set.MyProperty(plugin, val)
% This section contains instructions to execute if the% specified property is modified. Properties associated with% parameters are updated automatically. Use the set method to% execute more complicated instructions.endendend

Audio Toolbox Extended Terminology

In the MATLAB environment, an audio plugin refers to a class derived from the
audioPlugin base class or the audioPluginSource base class. Audio plugins can also
inherit from matlab.System. Any object that
derives from matlab.System is referred to as a
System
object. Deriving from matlab.System allows
for additional functionality, including Simulink integration. However, manipulating System objects requires a more
advanced understanding of OOP in the MATLAB environment.

This website uses cookies to improve your user experience, personalize content and ads, and analyze website traffic. By continuing to use this website, you consent to our use of cookies. Please see our Privacy Policy to learn more about cookies and how to change your settings.