%% Host External Audio Plugin Tutorial (Property Display Mode)
% 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')

%
% 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

%
% 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.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 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 dsp.TimeScope object. 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 = dsp.TimeScope( ...
    'SampleRate',sampleRate, ...
    '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)

%
% Copyright 2012-2018 The MathWorks, Inc.