loadAudioPlugin

R2026b

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

collapse all in page

Syntax

hostedPlugin = loadAudioPlugin(plugin)
hostedPlugin = loadAudioPlugin(plugin, EnableParameterAnalysis=TF)

Description

hostedPlugin = loadAudioPlugin(plugin) loads the 64-bit 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.

example

hostedPlugin = loadAudioPlugin(plugin, EnableParameterAnalysis=TF) disables the parameter analysis of the loaded plugin when you specify TF as false.

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 set the parameters and environment of the hosted plugin and use it to process audio. For information on using the hosted plugin, see externalAudioPlugin and externalAudioPluginSource.

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 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
Open Live Script

Compare the time it takes to load an audio plugin with and without automated parameter analysis. Load a VST 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');
tic;
analyzedPlugin = loadAudioPlugin(pluginPath);
toc;
Elapsed time is 0.206260 seconds.

By default, loadAudioPlugin analyzes the plugin's parameters. Load the plugin again and disable the parameter analysis by setting EnableParameterAnalyis=false.

tic;
nonAnalyzedPlugin = loadAudioPlugin(pluginPath,EnableParameterAnalysis=false);
toc;
Elapsed time is 0.023553 seconds.

To change parameters on a non-analyzed plugin, you must use the setParameter method with a normalized parameter value. For information about normalizing parameter values, see the normalizeAudioPluginParameter function.

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")

Option to enable automatic parameter analysis, specified as true or false. If you specify EnableParameterAnalysis=false, loadAudioPlugin loads plugin without analyzing its parameters, which reduces the loading time of plugins that perform complex computations in response to parameter changes. If you disable parameter analysis, you cannot change parameters by setting the properties of hostedPlugin directly. Instead, use the setParameter function to set the normalized value of a property.

Example: loadAudioPlugin("coolPlugin.dll",EnableParameterAnalysis=false)

Data Types: logical

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