Audio Plugins in MATLAB

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

Additional benefits of developing your audio processing as an audio plugin include:

Rapid prototyping using the Audio Test Bench
Integration with MIDI devices
Code reuse

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.

For a review of audio plugins as defined outside the MATLAB environment, see What Are DAWs, Audio Plugins, and MIDI Controllers?

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.

See Audio Toolbox Extended Terminology for a detailed visualization of inheritance and terminology.

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.
```
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:
- 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.

View Code

The first argument of the process method has changed from ~ to plugin. The first argument of process is reserved for the audio plugin object.

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.
View Code
classdef myEchoPlugin < audioPlugin properties Gain = 1.5; end properties (Constant) %<--- PluginInterface = audioPluginInterface( ... %<--- audioPluginParameter('Gain', ... %<--- 'DisplayName','Echo Gain', ... %<--- 'Mapping',{'lin',0,3})) %<--- end %<--- methods function out = process(plugin, in) out = in*plugin.Gain; end end end

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.

View Code

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.

View Code

classdef myEchoPlugin < audioPlugin
    properties
        Gain = 1.5;
    end
    properties (Access = private)
        CircularBuffer = zeros(192001,2);
        BufferIndex = 1;
        NSamples = 0;
    end
    properties (Constant)
        PluginInterface = audioPluginInterface(...
            audioPluginParameter('Gain',...
            'DisplayName','Echo Gain',...
            'Mapping',{'lin',0,3}))
    end
    methods
        function out = process(plugin, in)
            out = zeros(size(in));                              %<---
            writeIndex = plugin.BufferIndex;                    %<---
            readIndex = writeIndex - plugin.NSamples;           %<---
            if readIndex <= 0                                   %<---
                readIndex = readIndex + 192001;                 %<---
            end                                                 %<---
                                                                %<---
            for i = 1:size(in,1)                                %<---
                plugin.CircularBuffer(writeIndex,:) = in(i,:);  %<---
                                                                %<---
                echo = plugin.CircularBuffer(readIndex,:);      %<---
                out(i,:) = in(i,:) + echo * plugin.Gain;        %<---
                                                                %<---
                writeIndex = writeIndex + 1;                    %<---
                if writeIndex > 192001                          %<---
                    writeIndex = 1;                             %<---
                end                                             %<---
                                                                %<---
                readIndex = readIndex + 1;                      %<---
                if readIndex > 192001                           %<---
                    readIndex = 1;                              %<---
                end                                             %<---
            end                                                 %<---
            plugin.BufferIndex = writeIndex;                    %<---
        end
    end
end

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.

View Code

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.

View Code

classdef myEchoPlugin < audioPlugin
    properties
        Gain = 1.5;
        Delay = 0.5;
    end
    properties (Access = private)
        CircularBuffer = zeros(192001,2);
        BufferIndex = 1;
        NSamples = 0;
    end
    properties (Constant)
        PluginInterface = audioPluginInterface(...
            audioPluginParameter('Gain',...
            'DisplayName','Echo Gain',...
            'Mapping',{'lin',0,3}),...
            audioPluginParameter('Delay',...
            'DisplayName','Echo',...
            'Label','seconds'))
    end
    methods
        function out = process(plugin, in)
            out = zeros(size(in));
            writeIndex = plugin.BufferIndex;
            readIndex = writeIndex - plugin.NSamples;
            if readIndex <= 0
                readIndex = readIndex + 192001;
            end
            
            for i = 1:size(in,1)
                plugin.CircularBuffer(writeIndex,:) = in(i,:);
                
                echo = plugin.CircularBuffer(readIndex,:);
                out(i,:) = in(i,:) + echo*plugin.Gain;
                
                writeIndex = writeIndex + 1;
                if writeIndex > 192001
                    writeIndex = 1;
                end
                
                readIndex = readIndex + 1;
                if readIndex > 192001
                    readIndex = 1;
                end
            end
            plugin.BufferIndex = writeIndex;
        end
        function set.Delay(plugin, val)
            plugin.Delay = val;
            plugin.NSamples = floor(getSampleRate(plugin)*val);
        end
        function reset(plugin)                                          %<---
            plugin.CircularBuffer = zeros(192001,2);                    %<---
            plugin.NSamples = floor(getSampleRate(plugin)*plugin.Delay);%<---
        end                                                             %<---
    end
end

Click here to open the completed plugin in MATLAB.

Design a System Object Plugin

You can map the basic plugin to a System object plugin. Note the differences between the two plugin types:

A System object plugin inherits from both the audioPlugin base class and the matlab.System base class, not just audioPlugin base class.
The primary audio processing method of a System object plugin is named stepImpl, not process.
The reset method of a System object is named resetImpl, not reset.
Both resetImpl and stepImpl must be defined as protected methods.
System objects enable alternatives to the set method. For more information, see processTunedPropertiesImpl.

System Object Plugin

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.