%% Add Reverberation Using Freeverb Algorithm 
% This example shows how to apply reverberation to audio by using the
% Freeverb reverberation algorithm. The reverberation can be tuned using a
% user interface (UI) in MATLAB or through a MIDI controller. This example
% illustrates MATLAB(R) and Simulink(R) implementations.

% Copyright 2014-2019 The MathWorks, Inc.

%% Introduction 
% Reverberators are used to add the effect of multiple decaying echoes, or
% reverbs, to audio signals. A common use of reverberation is to simulate
% music played in a closed room. Most digital audio workstations (DAWs)
% have options to add such effects to the sound track.
%
% In this example, you add reverberation to audio through the Freeverb
% algorithm. Freeverb is a popular implementation of the Schroeder
% reverberator. A high-level model of the Freeverb algorithm is shown
% below:
%
% <<../FreeverbExample.png>>

%% Example Architecture
% The reverberator is implemented in the System object
% <matlab:edit('audioexample.FreeverbReverberator')
% |audioexample.FreeverbReverberator|>. The object has five properties that
% can be tuned while the simulation is running: |RoomSize|, |StereoWidth|,
% |WetDryMix|, |Balance|, and |Volume|. |RoomSize| affects the feedback
% gain of the comb filters. |StereoWidth| and |WetDryMix| both take part in
% the mixing stage that happens after filtering is complete. The default
% values of the |StereoSpread|, |CombDelayLength|, and |AllpassDelayLength|
% properties are taken from the Freeverb specifications.

%% MATLAB Simulation
% To use the reverberator on an audio signal, run
% |audioFreeverbReverberationExampleApp|.
%
%   audioFreeverbReverberationExampleApp
%
% The |audioFreeverbReverberationExampleApp| command first sets up the
% audio source and player. It then iteratively calls the
% |audioexample.FreeverbReverberator| System object with the audio input,
% providing addition of reverberation in a streaming fashion. The output of
% the object is played back so you can hear the effect added to the audio.
%
% The simulation opens a UI to interact with
% |audioexample.FreeverbReverberator| while the simulation is running. The
% UI allows you to tune parameters and the results are reflected in the
% simulation instantly. For example, moving the slider *Room size* to the
% left while the simulation is running decreases the reflectivity of the
% walls of the room being simulated.
% 
% There are also three buttons on the UI - the *Reset* button will reset
% the states of the comb and allpass sections in reverberator to their
% initial values and the *Pause Simulation* button will hold the simulation
% until you click on it again. The simulation may be terminated by either
% closing the UI or by clicking on the *Stop simulation* button. If you
% have a MIDI controller, it is possible to synchronize it with the UI. You
% can do this by choosing a MIDI control in the dialog that is opened when
% you right-click on the sliders or buttons and select "Synchronize" from
% the context menu. The chosen MIDI control then works in accordance with
% the slider or button so that operating one control is tracked by the
% other.
%
% <<../FreeverbExample02.png>>
%
% If you see a lot of queue underrun warnings, you will need to adjust the
% buffer and queue size of audio player used in
% |audioFreeverbReverberationExampleApp|. More information on this can be
% found at the documentation page for |audioDeviceWriter|. The audio source
% in this example is an audio file, but you can replace it with an audio
% input device (through |audioDeviceReader|) to add reverberation to live
% audio. For ways to reduce latency while not having any
% overruns/underruns, you can follow the example
% <docid:audio_examples#mw_3fc4c53d-b968-4013-8839-95b6cc04051f Measure
% Audio Latency>.

%% Using a Generated MEX File
% Using MATLAB Coder(TM), you can generate a MEX file for the main
% processing algorithm by executing the |HelperFreeverbCodeGeneration|
% command. You can use the generated MEX file by executing the
% |audioFreeverbReverberationExampleApp| command with |true| as an argument.
%
%   audioFreeverbReverberationExampleApp(true)

%% Simulink Version
% |audiofreeverbreverberation| is a Simulink model that implements the same
% Freeverb reverberation example highlighted in the previous sections.
%
open_system('audiofreeverbreverberation')

%%
% In this model, the addition of reverberation is modeled using the
% <matlab:edit('audioexample.FreeverbReverberator')
% |audioexample.FreeverbReverberator|> System object used inside a MATLAB
% System block. Using the MATLAB System block saves you the effort of
% reimplementing a MATLAB algorithm in Simulink. You can open the UI to
% tune Freeverb parameters by clicking the 'Launch Parameter Tuning UI'
% link on the model.
%
% The model generates code when it is simulated. Therefore, it must be
% executed from a folder with write permissions.

%% Acknowledgement
% The algorithm in this example is based on the public domain 'Freeverb'
% model written by Jezar at Dreampoint (June 2000).

%% Reference
% Smith, J.O. "Freeverb", in "Physical Audio Signal Processing",
% https://ccrma.stanford.edu/~jos/pasp/Freeverb.html, online book, 2010
% edition, accessed April 24, 2014.
