Convert MATLAB Code to an Audio Plugin

Audio Toolbox™ supports several approaches for the development of audio processing algorithms. Two common approaches include procedural programming using MATLAB^® scripts and object-oriented programming using MATLAB classes. The audio plugin class is the suggested paradigm for developing your audio processing algorithm in Audio Toolbox. See Audio Plugins in MATLAB for a tutorial on the structure, benefits, and uses of audio plugins.

This tutorial presents an existing algorithm developed as a MATLAB script, and then walks through the steps to convert the script to an audio plugin class. Use this tutorial to understand the relationship between procedural programming and object-oriented programming. You can also use this tutorial as a template to convert any audio processing you developed as MATLAB scripts to the audio plugin paradigm.

Inspect Existing MATLAB Script

The MATLAB script has these sections:

1. Variable Initialization. Variables are initialized with known values, including the number of samples per frame (frameSize) for frame-based stream processing.

2. Object Construction.

   • Two audioOscillator System objects –– Construct to create time-varying gain control signals.

   • dsp.AudioFileReader System object –– Construct to read an audio signal from a file.

   • audioDeviceWriter System object –– Construct to write an audio signal to your default audio device.

3. Audio Stream Loop. Mixes stereo channels into a mono signal. The mono signal is used to create a new stereo signal. Each channel of the new stereo signal oscillates in applied gain between 0 and 2, with a respective 90-degree phase shift.

 View Code

Click here to open this example.

%% Section A: Variable Initialization

% Specify frequency of gain oscillation.
Frequency = 1;

% Determine sample rate of audio file (input audio signal).
fileInfo = audioinfo(...
    'RockGuitar-16-44p1-stereo-72secs.wav');
sampleRate = fileInfo.SampleRate;

% Specify size of frame to read in from audio file.
frameSize = 256;

%% Section B: Object Construction

Sine = audioOscillator(...
    'DCOffset',1,...
    'SamplesPerFrame',frameSize,...
    'Frequency',Frequency,...
    'SampleRate',sampleRate);

Cosine = audioOscillator(...
    'DCOffset',1,...
    'PhaseOffset',0.5,...
    'Frequency',Frequency,...
    'SamplesPerFrame',frameSize,...
    'SampleRate',sampleRate);

fileReader = dsp.AudioFileReader(...
    'Filename',fileInfo.Filename,...
    'SamplesPerFrame',frameSize);

deviceWriter = audioDeviceWriter(...
    'SampleRate',fileReader.SampleRate);

%% Section C: Audio Stream Loop

while ~isDone(fileReader)
    
    % Read in one frame of audio signal from file.
    in = fileReader();
    
    % Mix stereo input to mono.
    mono = 0.5*sum(in,2);
    
    % Get current frame of Sine and Cosine gain functions.
    gainLeft = Sine();
    gainRight = Cosine();
    
    % Process signal by multiplying by variable gain matrix.
    out = [mono,mono] .* [gainLeft,gainRight];
    
    % Write one frame of audio signal to device.
    deviceWriter(out);
    
end

Convert MATLAB Script to Plugin Class

This tutorial converts a MATLAB script to an audio plugin class in six steps. You begin by creating a skeleton of a basic audio plugin class, and then map sections of the MATLAB script to the audio plugin class.

For an overview of how a MATLAB script is converted to a plugin class, inspect the script to plugin visual mapping. To perform this conversion, walk through the example for explanations and step-by-step instructions.

1. Create Skeleton of Audio Plugin Class

Begin with the basic skeleton of an audio plugin class. This skeleton is not the minimum required, but a common minimum to create an interesting audio plugin. See Audio Plugins in MATLAB for the minimum requirements to create a basic audio plugin.

 View Code

classdef gainOscillator < audioPlugin
    % gainOscillator Phase-shifted stereo gain oscillation.
    %   The process method mixes stereo channels into a mono signal. The
    %   mono signal is used to create a stereo signal, with each channel
    %   oscillating in gain between zero and two, with a respective 90
    %   degree phase shift.
    
    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
    end
end

2. Map Script Variable Initialization to Plugin Properties

Properties allow a plugin to store information across sections of the plugin class definition. If a property has access set to private, the property is not accessible to the end user of a plugin. Variable initialization in a script maps to plugin properties.

• A valid plugin must allow input to the process method to have a variable frame size. Frame size is determined for each input frame in the process method of the plugin. Because frame size is used only in the process method, you do not declare it in the properties section.

• A valid audio plugin must allow input to the process method to have a variable sample rate. The reset method of a plugin is called when the environment changes the sample rate. Determine the sample rate in the reset method using the getSampleRate method inherited from the audioPlugin base class.

• The objects used by a plugin must be declared as properties to be used in multiple sections of the plugin. However, the constructor method of a plugin performs object construction.

 View Code

classdef gainOscillator < audioPlugin
    properties
        Frequency = 1;  %<---
    end
    properties(Access = private)
        Sine            %<---
        Cosine          %<---
    end
    properties (Constant)
    end
    methods
        function out = process(plugin,in)
        end
        function reset(plugin)
        end
    end
end

3. Map Script Object Construction to Plugin Constructor Method

Add a constructor method to the methods section of your audio plugin. The constructor method of a plugin has the form:

function plugin = myPluginClassName
    % Instructions to construct plugin object.
end

If your plugin uses objects, construct them when the plugin is constructed. Set nontunable properties of objects used by your plugin during construction.

In this example, you construct the Sine and Cosine objects in the constructor method of the plugin.

 View Code

classdef gainOscillator < audioPlugin
    properties
        Frequency = 1;
    end
    properties(Access = private)
        Sine
        Cosine
    end
    properties (Constant)
    end
    methods
        function plugin = gainOscillator        %<---
            plugin.Sine = audioOscillator(...   %<---
                'DCOffset',1);                  %<---
            plugin.Cosine = audioOscillator(... %<---
                'DCOffset',1,...                %<---
                'PhaseOffset',0.5);             %<---
        end                                     %<---
        function out = process(plugin,in)
        end
        function reset(plugin)
        end
    end
end

4. Add Reset Method

The reset method of a plugin is called every time a new session is started with the plugin, or when the environment changes sample rate. Use the reset method to update the SampleRate property of your Sine and Cosine objects. To query the sample rate, use the getSampleRate base class method.

 View Code

classdef gainOscillator < audioPlugin
    properties
        Frequency = 1;
    end
    properties(Access = private)
        Sine
        Cosine
    end
    properties (Constant)
    end
    methods
        function plugin = gainOscillator
            plugin.Sine = audioOscillator(...
                'DCOffset',1);
            plugin.Cosine = audioOscillator(...
                'DCOffset',1,...
                'PhaseOffset',0.5);
        end
        function out = process(plugin,in)
        end
        function reset(plugin)
            plugin.Sine.SampleRate = getSampleRate(plugin);     %<---
            plugin.Cosine.SampleRate = getSampleRate(plugin);   %<---
        end
    end
end

5. Map Script Audio Stream Loop to Plugin Process Method

The contents of the audio stream loop in a script maps to the process method of an audio plugin, with these differences:

• A valid audio plugin must accept a variable frame size, so frame size is calculated for every call to the process method. Because frame size is variable, any processing that relies on frame size must update when input frame size changes.

• The environment handles the input and output to the process method.

 View Code

classdef gainOscillator < audioPlugin
    properties
        Frequency = 1;
    end
    properties(Access = private)
        Sine
        Cosine
    end
    properties (Constant)
    end
    methods
        function plugin = gainOscillator
            plugin.Sine = audioOscillator(...
                'DCOffset',1);
            plugin.Cosine = audioOscillator(...
                'DCOffset',1,...
                'PhaseOffset',0.5);
        end
        function out = process(plugin,in)
            frameSize = size(in,1);                     %<---
            
            plugin.Sine.SamplesPerFrame = frameSize;    %<---
            plugin.Cosine.SamplesPerFrame = frameSize;  %<---
            
            mono = 0.5*sum(in,2);                       %<---
            gainLeft = step(plugin.sine);               %<---
            gainRight = step(plugin.cosine);            %<---
            out = [mono,mono].*[gainLeft,gainRight];    %<---
        end
        function reset(plugin)
            plugin.Sine.SampleRate = getSampleRate(plugin);
            plugin.Cosine.SampleRate = getSampleRate(plugin);
        end
    end
end

6. Add Plugin Interface

The plugin interface lets users view the plugin and tune its properties. Specify PluginInterface as an audioPluginInterface object that contains an audioPluginParameter object. The first argument of audioPluginParameter is the property you want to synchronize with a tunable parameter. Choose the display name, label the units, and set the parameter range. This example uses 0.1 to 10 as a reasonable range for the Frequency property. Write code so that during each call to the process method, your Sine and Cosine objects are updated with the current frequency value.

 View Code

classdef gainOscillator < audioPlugin
    properties
        Frequency = 1;
    end
    properties(Access = private)
        Sine
        Cosine
    end
    properties (Constant)
        PluginInterface = audioPluginInterface(...          %<---
            audioPluginParameter('Frequency',...            %<---
            'DisplayName','Oscillation Frequency',...       %<---
            'Label','Hz',...                                %<---
            'Mapping',{'lin',0.01,10}))                     %<---
    end
    methods
        function plugin = gainOscillator
            plugin.Sine = audioOscillator(...
                'DCOffset',1);
            plugin.Cosine = audioOscillator(...
                'DCOffset',1,...
                'PhaseOffset',0.5);
        end
        function out = process(plugin,in)
            frameSize = size(in,1);

            plugin.Sine.Frequency = plugin.Frequency;       %<---
            plugin.Cosine.Frequency = plugin.Frequency;     %<---

            plugin.Sine.SamplesPerFrame = frameSize;
            plugin.Cosine.SamplesPerFrame = frameSize;

            mono = 0.5*sum(in,2);
            gainLeft = step(plugin.Sine);
            gainRight = step(plugin.Cosine);
            out = [mono,mono].*[gainLeft,gainRight];
        end
        function reset(plugin)
            plugin.Sine.SampleRate = getSampleRate(plugin);
            plugin.Cosine.SampleRate = getSampleRate(plugin);
        end
    end
end

Once your audio plugin class definition is complete:

1. Save your plugin class definition file.

2. Validate your plugin using validateAudioPlugin.

3. Prototype it using Audio Test Bench.

4. Generate is using generateAudioPlugin.

Related Topics

• Real-Time Audio in MATLAB
• What Are DAWs, Audio Plugins, and MIDI Controllers?
• Audio Plugins in MATLAB
• Include an Audio Plugin in Simulink
• Export a MATLAB Plugin to a DAW