loadAudioPlugin

Load VST, VST3, and AU plugins into MATLAB environment

collapse all in page

Syntax

hostedPlugin = loadAudioPlugin(pluginpath)

Description

example

hostedPlugin = loadAudioPlugin(pluginpath) loads the 64-bit VST, VST3, or AU audio plugin specified by pluginpath. On Windows®, you can load VST and VST3 plugins. On macOS, you can load AU, VST, and VST3 plugins.

Your hosted plugin has two display modes: Parameters and Properties. The default display mode is Properties.

  • Parameters –– Interact with normalized parameter values of the hosted plugin using set and get functions.

  • Properties –– Interact with heuristically interpreted parameters with real-world values. You can use standard dot notation to set and get the values while using this mode.

You can specify the display mode of the hosted plugin using standard dot notation, for example:

hostedPlugin.DisplayMode = 'Parameters';

See Host External Audio Plugins for a discussion of display modes and a walkthrough of both modes of interaction.

You can interact with and exercise the hosted plugin using the following functions.

Process Audio

  • audioOut = process(hostedPlugin,audioIn)

    Returns an audio signal processed according to the algorithm and parameters of the hosted plugin. For source plugins, call process without an audio input.

Set and Get Normalized Parameter Values

  • value = getParameter(hostedPlugin,parameter)

    Returns the normalized value of the specified hosted plugin parameter. Normalized values are in the range [0,1]. You can specify a parameter by its name or by its index. To specify the name, use a character vector.

  • setParameter(hostedPlugin,parameter,newValue)

    Sets the normalized value of the specified hosted plugin parameter to newValue. Normalized values are in the range [0,1].

Get High-Level Information About the Hosted Plugin

  • dispParameter(hostedPlugin)

    Displays all parameters and associated indices, values, displayed values, and display labels of the hosted plugin.

  • pluginInfo = info(hostedPlugin)

    Returns a structure containing information about the hosted plugin.

Set the Environment in Which the Plugin Is Run

  • frameSize = getSamplesPerFrame(hostedPlugin)

    Returns the frame size that the hosted plugin returns in subsequent calls to its processing function (source plugins only).

  • setSamplesPerFrame(hostedPlugin,frameSize)

    Sets the frame size that the hosted plugin must return in subsequent calls to its processing function (source plugins only).

  • setSampleRate(hostedPlugin,sampleRate)

    Sets the sample rate of the hosted plugin.

  • sampleRate = getSampleRate(hostedPlugin)

    Returns the sample rate in Hz at which the plugin is being run.

Examples

collapse all

Open Live Script

Use loadAudioPlugin to host a VST external plugin and a VST external source plugin in MATLAB®.

Use the fullfile command to determine the full path to the oscillator VST plugin and parametric equalizer VST plugin included with Audio Toolbox™. If you are using a Mac, replace the .dll file extension with .vst.

oscPluginPath = ...
    fullfile(matlabroot,'toolbox/audio/samples/oscillator.dll');
EQPluginPath = ...
    fullfile(matlabroot,'toolbox/audio/samples/ParametricEqualizer.dll');

Create external plugin objects by calling loadAudioPlugin for each of the plugin paths.

hostedSourcePlugin = loadAudioPlugin(oscPluginPath);
hostedPlugin = loadAudioPlugin(EQPluginPath);

Hosted plugins derive from either the externalAudioPlugin or externalAudioSourcePlugin class. Because oscillator.dll is a source audio plugin, the hosted object derives from externalAudioSourcePlugin. Use class() to verify the classes of the hosted plugins.

class(hostedPlugin)
ans = 
'externalAudioPlugin'

class(hostedSourcePlugin)
ans = 
'externalAudioPluginSource'

Call the hosted plugins to display basic information about them. This information includes the format, the plugin name, the number of channels in and out, and the tunable properties of the plugin. Source plugins also display the frame size of the plugin.

hostedSourcePlugin
hostedSourcePlugin = 
  VST plugin 'oscillator'  source, 1 out, 256 samples

    Frequency: 100 Hz
    Amplitude: 1 AU
     DCOffset: 0 AU

hostedPlugin
hostedPlugin = 
  VST plugin 'ParametricEQ'  2 in, 2 out

              LowPeakGain: 0 dB
       LowCenterFrequency: 100 Hz
               LowQFactor: 2
           MediumPeakGain: 0 dB
    MediumCenterFrequency: 1000 Hz
            MediumQFactor: 2
             HighPeakGain: 0 dB
      HighCenterFrequency: 10000 Hz
              HighQFactor: 2
Open Live Script

Load a VST audio plugin into MATLAB™ by specifying its full path. If you are using a Mac, replace the .dll file extension with .vst.

pluginPath = fullfile(matlabroot,'toolbox','audio','samples','ParametricEqualizer.dll');
hostedPlugin = loadAudioPlugin(pluginPath);

Create input and output objects for an audio stream loop that reads from a file and writes to your audio device. Set the sample rate of the hosted plugin to the sample rate of the input to the plugin.

fileReader = dsp.AudioFileReader('FunkyDrums-44p1-stereo-25secs.mp3');
deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);
setSampleRate(hostedPlugin,fileReader.SampleRate);

Set the MediumPeakGain property to -20 dB.

hostedPlugin.MediumPeakGain = -20;

Use the hosted plugin to process the audio file in an audio stream loop. Sweep the medium peak gain upward in the loop to hear the effect.

while hostedPlugin.MediumPeakGain < 19
    hostedPlugin.MediumPeakGain = hostedPlugin.MediumPeakGain + 0.04;
    x = fileReader();
    y = process(hostedPlugin,x);
    deviceWriter(y);
end

release(fileReader)
release(deviceWriter)
Open Live Script

Load a VST audio source plugin into MATLAB™ by specifying its full path. If you are using a Mac, replace the .dll file extension with .vst.

pluginPath = fullfile(matlabroot,'toolbox','audio','samples','oscillator.dll');
hostedSourcePlugin = loadAudioPlugin(pluginPath);

Set the Amplitude property to 0.5. Set the Frequency property to 16 kHz.

hostedSourcePlugin.Amplitude = 0.5;
hostedSourcePlugin.Frequency = 16000;

Set the sample rate at which to run the plugin. Create an output object to write to your audio device.

setSampleRate(hostedSourcePlugin,44100);
deviceWriter = audioDeviceWriter('SampleRate',44100);

Use the hosted source plugin to output an audio stream. The processing in the audio stream loop ramps the frequency parameter down and then up.

k = 1;
for i = 1:1000
    hostedSourcePlugin.Frequency = hostedSourcePlugin.Frequency - 30*k;
    y = process(hostedSourcePlugin);
    deviceWriter(y);
    if (hostedSourcePlugin.Frequency - 30 <= 0.1) || (hostedSourcePlugin.Frequency + 30 >= 20e3)
        k = -1*k;
    end
end

release(deviceWriter)

Input Arguments

collapse all

Location of the external plugin, specified as a character vector. Use the full path to specify the audio plugin you want to host in MATLAB®. If the plugin is located in the current folder, specify it by its name.

Example: loadAudioPlugin('coolPlugin.dll')

Example: loadAudioPlugin('C:\Program Files\VSTPlugins\coolPlugin.dll')

Plugin Path for Mac

For macOS, the plugin locations are predetermined depending on if the plugin was saved system wide or for a particular user.

This table shows the system-wide paths.

Plugin TypePath
VST2

/Library/Audio/Plug-Ins/VST/coolPlugin.vst

VST3

/Library/Audio/Plug-Ins/VST3/coolPlugin.vst3

AU

/Library/Audio/Plug-Ins/Components/coolPlugin.component

This table shows the user-specific paths.

Plugin TypePath
VST2

~/Library/Audio/Plug-Ins/VST/coolPlugin.vst

VST3

~/Library/Audio/Plug-Ins/VST3/coolPlugin.vst3

AU

~/Library/Audio/Plug-Ins/Components/coolPlugin.component

Output Arguments

collapse all

Object of an external plugin, derived from the externalAudioPlugin or externalAudioSourcePlugin class. You can interact with the hosted plugin as a DAW would, with the additional functionality of the MATLAB environment.

Limitations

The loadAudioPlugin function supports 64-bit plugins only. You cannot load 32-bit plugins using the loadAudioPlugin function.

See Also

| | | | |

Topics

Introduced in R2016b

Audio Toolbox Documentation

Support