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.

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

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

   classdef myEchoPlugin < audioPlugin
       properties                             %<---
           Gain = 1.5;                        %<---
       end                                    %<---
       methods
           function out = process(plugin, in) %<---
               out = in*plugin.Gain;          %<---
           end
       end
   end

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

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

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

   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 = in*plugin.Gain;
           end
       end
   end

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

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

   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 Delay',...      %<---
               '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                                                     %<---
       end
   end

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

classdef myEchoSystemObjectPlugin < audioPlugin & matlab.System
    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 (Access = protected)
        function out = stepImpl(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 resetImpl(plugin)
            plugin.CircularBuffer = zeros(192001,2);
            plugin.NSamples = floor(getSampleRate(plugin) * plugin.Delay);
        end
    end
    methods
        function set.Delay(plugin, val)
            plugin.Delay = val;
            plugin.NSamples = floor(getSampleRate(plugin) * val);
        end
    end
end

Click here to open the file.

Quick Start Basic Plugin

 Template

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.
    end
    properties (Access = private)
        % Use this section to initialize properties that the end-user does not
        % interact with directly.
    end
    properties (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.
    end
    methods
        function out = process(plugin, in)
            % This section contains instructions to process the input audio
            % signal. Use plugin.MyProperty to access a property of your
            % plugin.
        end
        function reset(plugin)
            % This section contains instructions to reset the plugin between
            % uses or if the environment sample rate changes.
        end
        function 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.
        end
    end
end

 Annotated Example

This basic plugin enables the user to tune a damped applied gain. Click here to open the file.

Quick Start Basic Source Plugin

 Template

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.
    end
    properties (Access = private)
        % Use this section to initialize properties that the end-user does
        % not interact with directly.
    end
    properties (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.
    end
    methods
        function 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.
        end
        function reset(plugin)
            % This section contains instructions to reset the plugin
            % between uses, or when the environment sample rate changes.
        end
        function 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.
        end
    end
end

 Annotated Example

This basic source plugin enables the user to tune the damped gain of a noise signal. Click here to open the file.

Quick Start System Object Plugin

 Template

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.
    end
    properties (Access = private)
        % Use this section to initialize properties that the end-user does not
        % interact with directly.
    end
    properties (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.
    end
    methods (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.
        end
        function resetImpl(plugin)
            % This section contains instructions to reset the plugin between
            % uses or if the environment sample rate changes.
        end  
    end
    methods
        function 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.
        end
    end
end

 Annotated Example

This System object plugin enables the user to tune a damped applied gain. Click here to open the file.

Quick Start System Object Source Plugin

 Template

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.
    end
    properties (Access = private)
        % Use this section to initialize properties that the end-user does
        % not interact with directly.
    end
    properties (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.
    end
    methods (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.
        end
        function resetImpl(plugin)
            % This section contains instructions to reset the plugin
            % between uses or if the environment sample rate changes.
        end
    end
    methods
        function 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.
        end
    end
end

 Annotated Example

This System object source plugin enables the user to tune the damped gain of a noise signal. Click here to open the file.

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.