Main Content

loadAudioPlugin

Load VST, VST 3, and AU plugins into MATLAB environment

collapse all in page

Syntax

hostedPlugin = loadAudioPlugin(plugin)

Description

hostedPlugin = loadAudioPlugin(plugin) loads the 64-bit VST, VST 3, or AU audio plugin specified by plugin. On Windows®, you can load VST and VST 3 plugins. On macOS, you can load AU, AUv3, VST, and VST 3 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.

example

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)

To load an AUv3 plugin into MATLAB®, you need the plugin component IDs.

Use the auval macOS command which lists all of the AUv3 plugins that are registered with the operating system, and use grep to search for the Echo plugin. Use the system function to run this command.

[~,out] = system("auval -a | grep Echo")
out =

    'aufx 4pvz Math  -  MathWorks: Echo
     '

Use the component IDs shown in the auval output to load the plugin into MATLAB.

hostedPlugin = loadAudioPlugin("AudioUnit: aufx 4pvz Math")
hostedPlugin = 

  AudioUnit plugin 'Echo'  2 in, 2 out

          Gain: 0.5
      Feedback: 0.35
     BaseDelay: 0.5
    Wet_dryMix: 0.5

Input Arguments

collapse all

External plugin to load, specified as a string or character vector containing the file name of the plugin. If the external plugin is not in the current folder, specify the full or relative path to the plugin file.

Example: loadAudioPlugin("coolPlugin.dll")

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

For AUv3 plugins on macOS, specify the plugin as a string or character vector containing the AUv3 component IDs in the format "AudioUnit:TYPE SUBT MANU". TYPE, SUBT, and MANU are the four-character component IDs of the AUv3 plugin returned by the auval command in the macOS command line. For an example that shows how to load an AUv3 plugin using its component IDs, see Host AUv3 Plugin on macOS.

Example: loadAudioPlugin("AudioUnit:aufx 4pvx Math")

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.

  • Saving an external plugin as a MAT-file and then loading it preserves the external settings and parameters of the plugin but does not preserve its internal state or memory. Do not save and load your plugins when you are processing audio.

Version History

Introduced in R2016b

expand all

See Also

| | | | |

Topics