Main Content

Host External Audio Plugins

You can host VST, VST3, and AU plugins in MATLAB® by using the loadAudioPlugin function from Audio Toolbox™.

After you load an external audio plugin, you process audio through its main audio-processing algorithm.

Audio Toolbox enables three ways to interact with the hosted audio plugin:

The following tutorials–one version for property display mode and one version for parameter display mode–walk you through the process of hosting an externally authored VST plugin and interacting with the plugin at the MATLAB command line. You host a plugin from the suite of ReaPlugs VST plugins distributed by Cockos Incorporated. To download the ReaPlugs VST FX Suite for your system, follow the instructions on the REAPER website. A 64-bit Windows platform is used in this tutorial. The loadAudioPlugin function cannot load 32-bit plugins.

Property Display Mode (Default)

Setting the display mode to property enables you to interact with the hosted plugin object using standard dot notation. For example:

hostedObject.Gain = 5; % dB
Property is the default display mode of hosted plugins.

Numeric parameters are mapped through a heuristic interpretation of the normalized parameter values and the corresponding display values. The property display mode is simple and intuitive. However, due to the Heuristic Mapping of normalized parameter values to real-world property values, the property display mode may break down for some plugins. In this case, you should use the parameter display mode.

Host External Audio Plugin Tutorial (Property Display Mode)

Open Live Script

The following tutorial walks through the steps of loading and configuring an external audio plugin in property display mode.

1. Load External Audio Plugin

Use the loadAudioPlugin function to host the ReaDelay VST plugin. If the plugin is in your current folder, you can specify just the file name. Otherwise, you must specify the full path. In this example, the plugin is in the current folder. By default, the display mode is set to property.

hostedPlugin = loadAudioPlugin('readelay-standalone.dll')
hostedPlugin = 
  VST plugin 'ReaDelay (ReaPlugs Edition)'  2 in, 2 out

               Wet: 0 dB
               Dry: 0 dB
        x1_Enabled: 'ON'
       x1_Length_4: 0 ms
       x1_Length_5: 4 8N
       x1_Feedback: -Inf dB
        x1_Lowpass: 20000 Hz
         x1_Hipass: 0 Hz
     x1_Resolution: 24 bits
    x1_StereoWidth: 1
         x1_Volume: 0 dB
            x1_Pan: 0 %

The first line displays the plugin type, plugin display name, and the number of input and output channels for the main audio-processing algorithm of the plugin. If you are hosting a source plugin, the number of output channels and the default samples per frame are displayed.

By default, all properties are displayed.

2. Tune Hosted Plugin Property Values

You can interact with the properties of the hosted plugin using dot notation. If you go above or below the allowed range of the property, an error message will state the valid boundaries.

hostedPlugin.x1_Hipass = 120;
highPassSetting = hostedPlugin.x1_Hipass
highPassSetting = 120

You can use tab-completion to get a list of possible values for enumerated properties.

3. Use Hosted Plugin to Process Audio

To process an audio signal with the hosted plugin, use process.

audioIn = [1,1];
audioOut = process(hostedPlugin,audioIn);

Audio plugins are designed for variable-frame-based processing, meaning that you can call process with successive audio input frames of different lengths. The hosted plugin saves the internal states required for continuous processing. To process an audio signal read from a file and then written to your audio output device, place your hosted plugin in an audio stream loop. Use dsp.AudioFileWriter and audioDeviceWriter objects as the input and output to your audio stream loop, respectively. Set the sample rate of the hosted plugin to the sample rate of the audio file by using setSampleRate.

fileReader = dsp.AudioFileReader('Counting-16-44p1-mono-15secs.wav');
sampleRate = fileReader.SampleRate;

deviceWriter = audioDeviceWriter('SampleRate',sampleRate);
setSampleRate(hostedPlugin,sampleRate);

while ~isDone(fileReader)
    audioIn = fileReader();
    
    % The hosted plugin requires a stereo input.
    stereoAudioIn = [audioIn,audioIn];
    
    x = process(hostedPlugin,stereoAudioIn);
    
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

You can modify properties in the audio stream loop. To control the Wet property of your plugin in an audio stream loop, create an audioOscillator System object™. Use the fileReader, deviceWriter, and hostedPlugin objects you created previously to process the audio.

osc = audioOscillator('sine', ...
    'Frequency',10, ...
    'Amplitude',20, ...
    'DCOffset',-20, ...
    'SamplesPerFrame',fileReader.SamplesPerFrame, ...
    'SampleRate',sampleRate);

while ~isDone(fileReader)
    audioIn = fileReader();
    
    controlSignal = osc();
    hostedPlugin.Wet = controlSignal(1);
    
    stereoAudioIn = [audioIn,audioIn];
    x = process(hostedPlugin,stereoAudioIn);
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

4. Analyze Hosted Plugin

You can use the Audio Toolbox measurement and visualization tools to display behavior information about your hosted plugin. To display the input and output of your hosted audio plugin, create a time scope. Create a loudnessMeter object and use the 'EBU Mode' visualization to monitor loudness output by the hosted plugin. Use the fileReader, deviceWriter, osc, and hostedPlugin objects you created previously to process the audio.

scope = timescope('SampleRate',sampleRate, ...
    'TimeSpanSource','property', ...
    'TimeSpanOverrunAction','scroll', ...
    'TimeSpan',5, ...
    'BufferLength',5*2*sampleRate, ...
    'YLimits',[-1 1]);

loudMtr = loudnessMeter('SampleRate',sampleRate);
visualize(loudMtr)

while ~isDone(fileReader)
    audioIn = fileReader();
    
    controlSignal = osc();
    hostedPlugin.Wet = controlSignal(1);
    
    stereoAudioIn = [audioIn,audioIn];
    x = process(hostedPlugin,stereoAudioIn);
    
    loudMtr(x);
    scope([x(:,1),audioIn(:,1)])
    
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

Parameter Display Mode

Setting the display mode to parameter enables you to interact with the hosted plugin in the most basic way possible: by setting and getting normalized parameter values. You can use the information optionally returned by getParameter to interpret normalized values as real-world values, such as decibels and Hertz.

Host External Audio Plugin Tutorial (Parameter Mode)

Open Live Script

The following tutorial walks through the steps of loading and configuring an external audio plugin in parameter display mode.

1. Load External Audio Plugin

Use the loadAudioPlugin function to host the ReaDelay VST plugin. If the plugin is in your current folder, you can specify just the file name. Otherwise, you must specify the full path. In this example, the plugin is in the current folder.

hostedPlugin = loadAudioPlugin('readelay-standalone.dll');

By default, the display mode is set to property. Set the DisplayMode property to Parameters for low-level interaction with the hosted plugin.

hostedPlugin.DisplayMode = 'Parameters'
hostedPlugin = 
  VST plugin 'ReaDelay (ReaPlugs Edition)'  2 in, 2 out

          Parameter    Value    Display
        ________________________________
     1          Wet:   1.0000   +0.0 dB
     2          Dry:   1.0000   +0.0 dB
     3   1: Enabled:   1.0000     ON   
     4    1: Length:   0.0000    0.0 ms
     5    1: Length:   0.0156   4.00 8N
   7 parameters not displayed. See all 12 params.

The first line displays the plugin type, plugin display name, and the number of input and output channels for the main audio processing algorithm of the plugin. If you are hosting a source plugin, the number of output channels and the default samples per frame are displayed.

By default, only the first five parameters are displayed. To display all parameters of the hosted plugin, click See all 12 params.

The table provides the parameter index, parameter name, normalized parameter value, displayed parameter value, and the displayed parameter value label.

The normalized parameter value is always in the range [0,1] and generally corresponds to the position of a user interface (UI) widget in a DAW or the position of a MIDI control on a MIDI control surface. The parameter display value is related to the normalized parameter value by an unknown mapping internal to the plugin and typically reflects the value used internally by the plugin for processing.

2. Set and Get Hosted Plugin Parameter Values

You can use getParameter and setParameter to interact with the parameters of the hosted plugin. Using getParameter and setParameter is the programmatic equivalent of moving widgets in a UI or controls on a MIDI control surface. A typical DAW UI provides the parameter name, a visual representation of the normalized parameter value, the displayed parameter value, and the displayed parameter value label.

For example, the Wet parameter of readelay-standalone.dll has a normalized parameter value of 1 and a display parameter value of +0.0. The Wet parameter might be displayed in a DAW as follows:

With Audio Toolbox, you can use getParameter to return the normalized parameter value and additional information about a single hosted plugin parameter. You can specify which parameter to get by the parameter index.

parameterIndex = 1;
[normParamValue,paramInfo] = getParameter(hostedPlugin,parameterIndex)
normParamValue = 1

paramInfo = struct with fields:
     DisplayName: 'Wet'
    DisplayValue: '+0.0'
           Label: 'dB'

You can use setParameter to set a normalized parameter value of your hosted plugin. You can specify which parameter to set by its parameter index.

normParamValue = 0.5;
setParameter(hostedPlugin,parameterIndex,normParamValue)

Setting the normalized parameter value to 0.5 is equivalent to setting the indicator to the center of a slider in a DAW.

To verify the new normalized parameter value for Wet, use getParameter.

parameterIndex = 1;
[normParamValue,paramInfo] = getParameter(hostedPlugin,parameterIndex);

The DisplayValue for the Wet parameter updates from +0.0 to -6.0 because you set the corresponding normalized parameter value. The relationship between the displayed value and the normalized value is determined by an unknown mapping that is internal to the hosted plugin.

3. Use Hosted Plugin to Process Audio

To process an audio signal with the hosted plugin, use process.

audioIn = [1,1];
audioOut = process(hostedPlugin,audioIn);

Audio plugins are designed for variable-frame-based processing, meaning that you can call process with successive audio input frames of different lengths. The hosted plugin saves the internal states required for continuous processing. To process an audio signal read from a file and then written to your audio output device, place your hosted plugin in an audio stream loop. Use dsp.AudioFileReader and audioDeviceWriter objects as the input and output to your audio stream loop, respectively. Set the sample rate of the hosted plugin to the sample rate of the audio file by using setSampleRate.

fileReader = dsp.AudioFileReader('Counting-16-44p1-mono-15secs.wav');
sampleRate = fileReader.SampleRate;

deviceWriter = audioDeviceWriter('SampleRate',sampleRate);
setSampleRate(hostedPlugin,sampleRate);

while ~isDone(fileReader)
    audioIn = fileReader();
    
    % The hosted plugin requires a stereo input.
    stereoAudioIn = [audioIn,audioIn];
    
    x = process(hostedPlugin,stereoAudioIn);
    
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

You can modify parameters in the audio stream loop. To control the Wet parameter of your plugin in an audio stream loop, create an audioOscillator System object™. Use the fileReader, deviceWriter, and hostedPlugin objects you created previously to process the audio.

osc = audioOscillator('sine', ...
    'Frequency',10, ...
    'Amplitude',0.5, ...
    'DCOffset',0.5, ...
    'SamplesPerFrame',fileReader.SamplesPerFrame, ...
    'SampleRate',sampleRate);

while ~isDone(fileReader)
    audioIn = fileReader();
    
    controlSignal = osc();
    setParameter(hostedPlugin,1,controlSignal(1));
    
    stereoAudioIn = [audioIn,audioIn];
    x = process(hostedPlugin,stereoAudioIn);
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

4. Analyze Hosted Plugin

You can use the Audio Toolbox measurement and visualization tools to display behavior information about your hosted plugin. To display the input and output of your hosted audio plugin, create a time scope. Create a loudnessMeter object and use the 'EBU Mode' visualization to monitor loudness output by the hosted plugin. Use the fileReader, deviceWriter, osc, and hostedPlugin objects you created previously to process the audio.

scope = timescope('SampleRate',sampleRate, ...
    'TimeSpanSource','property', ...
    'TimeSpanOverrunAction','scroll', ...
    'TimeSpan',5, ...
    'BufferLength',5*2*sampleRate, ...
    'YLimits',[-1 1]);

loudMtr = loudnessMeter('SampleRate',sampleRate);
visualize(loudMtr)

while ~isDone(fileReader)
    audioIn = fileReader();
    
    controlSignal = osc();
    setParameter(hostedPlugin,1,controlSignal(1));
    
    stereoAudioIn = [audioIn,audioIn];
    x = process(hostedPlugin,stereoAudioIn);
    
    loudMtr(x);
    scope([x(:,1),audioIn(:,1)])
    
    deviceWriter(x);
end

release(fileReader)
release(deviceWriter)

Graphical Interaction

You can also interact with an externally authored audio plugin graphically using the Audio Test Bench. The Audio Test Bench mimics the default graphical user interface common to most digital audio workstations.

Heuristic Mapping

Investigate Parameter/Property Mapping

Open Script

Parameter display values are related to normalized parameter values by unknown mapping rules internal to the plugin. You can investigate the relationship between the normalized parameter values and the displayed values by creating a sweeping function. You can use the sweeping function to map parameter values to their displayed output.

The properties display mode of hosted plugins uses a similar approach to enable you to interact directly with the real-world (displayed) values, instead of the normalized parameter values.

Save the displayParameterMapping function in your current folder. This function performs a simplified version of the parameter sweeping used to create the property display mode for hosted plugins.

function displayParameterMapping(hPlugin,prmIndx)
x = 0:0.001:1; % Normalized parameter range

[~,prmInfo] = getParameter(hPlugin,prmIndx);
if isnan(str2double(prmInfo.DisplayValue))
    % Non-Numeric Displays - prints normalized parameter range associated
    % with string
    setParameter(hPlugin,prmIndx,0);
    [~,prmInfo] = getParameter(hPlugin,prmIndx);
    txtOld = prmInfo.DisplayValue;
    oldIndx = 1;
    
    for i = 2:numel(x)
        setParameter(hPlugin,prmIndx,x(i))
        [~,prmInfo] = getParameter(hPlugin,prmIndx);
        txtNew = prmInfo.DisplayValue;
        if ~strcmp(txtNew,txtOld)
            fprintf('%s: %g - %g\n',txtOld, x(oldIndx),x(i-1));
            oldIndx = i;
            txtOld = txtNew;
        end
    end
    fprintf('%s: %g - %g\n',txtOld, x(oldIndx),x(i));
else
    % Numeric Displays - plots normalized parameter value against displayed
    % parameter value
    y = zeros(numel(x),1);
    for i = 1:numel(x)
        setParameter(hPlugin,prmIndx,x(i))
        [~,prmInfo] = getParameter(hPlugin,prmIndx);
        y(i) = str2double(prmInfo.DisplayValue);
    end
    if any(isnan(y))
        warning('NaN detected in numeric display.')
    end
    plot(x,y)
    xlabel('Normalized Parameter Value')
    ylabel(['Displayed Parameter Value (',prmInfo.Label,')'])
    title(prmInfo.DisplayName)   
end

end

Load the readelay-standalone.dll plugin into MATLAB®. Call the displayParameterMapping function with the hosted plugin and a parameter index.

hostedPlugin = loadAudioPlugin('readelay-standalone.dll');
displayParameterMapping(hostedPlugin,1);

If you use the displayParameterMapping function with a nonnumeric parameter, the relationship displays in the Command Window:

displayParameterMapping(hostedPlugin,3)

OFF: 0 - 0.499
ON: 0.5 - 1

See Also

Functions

Classes

Related Topics