Main Content

reverberator

Add reverberation to audio signal

Description

The reverberator System object™ adds reverberation to mono or stereo audio signals.

To add reverberation to your input:

  1. Create the reverberator object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Description

reverb = reverberator creates a System object, reverb, that adds artificial reverberation to an audio signal.

reverb = reverberator(Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: reverb = reverberator('PreDelay',0.5,'WetDryMix',1) creates a System object, reverb, with a 0.5 second pre-delay and a wet-to-dry mix ratio of one.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Pre-delay for reverberation in seconds, specified as a real scalar in the range [0, 1].

Pre-delay for reverberation is the time between hearing direct sound and the first early reflection. The value of PreDelay is proportional to the size of the room being modeled.

Tunable: Yes

Data Types: single | double

Lowpass filter cutoff in Hz, specified as a real positive scalar in the range 0 to (SampleRate2).

Lowpass filter cutoff is the –3 dB cutoff frequency for the single-pole lowpass filter at the front of the reverberator structure. It prevents the application of reverberation to high-frequency components of the input.

Tunable: Yes

Data Types: single | double

Density of reverb tail, specified as a real positive scalar in the range [0, 1].

Diffusion is proportional to the rate at which the reverb tail builds in density. Increasing Diffusion pushes the reflections closer together, thickening the sound. Reducing Diffusion creates more discrete echoes.

Tunable: Yes

Data Types: single | double

Decay factor of reverb tail, specified as a real positive scalar in the range [0, 1].

DecayFactor is inversely proportional to the time it takes for reflections to run out of energy. To model a large room, use a long reverb tail (low decay factor). To model a small room, use a short reverb tail (high decay factor).

Tunable: Yes

Data Types: single | double

High-frequency damping, specified as a real positive scalar in the range [0, 1].

HighFrequencyDamping is proportional to the attenuation of high frequencies in the reverberation output. Setting HighFrequencyDamping to a large value makes high-frequency reflections decay faster than low-frequency reflections.

Tunable: Yes

Data Types: single | double

Wet-dry mix, specified as a real positive scalar in the range [0, 1].

Wet-dry mix is the ratio of wet (reverberated) to dry (original) signal that your reverberator System object outputs.

Tunable: Yes

Data Types: single | double

Input sample rate in Hz, specified as a positive scalar.

Tunable: Yes

Data Types: single | double

Usage

Description

example

audioOut = reverb(audioIn) adds reverberation to the input signal, audioIn, and returns the mixed signal, audioOut. The type of reverberation is specified by the algorithm and properties of the reverberator System object, reverb.

Input Arguments

expand all

Audio input to the reverberator, specified as a column vector or two-column matrix. The columns of the matrix are treated as independent audio channels.

Data Types: single | double

Output Arguments

expand all

Audio output from the reverberator, returned as a two-column matrix.

Data Types: single | double

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

createAudioPluginClassCreate audio plugin class that implements functionality of System object
parameterTunerTune object parameters while streaming
configureMIDIConfigure MIDI connections between audio object and MIDI controller
disconnectMIDIDisconnect MIDI controls from audio object
getMIDIConnectionsGet MIDI connections of audio object
cloneCreate duplicate System object
isLockedDetermine if System object is in use
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
stepRun System object algorithm

Examples

collapse all

Use the reverberator System object™ to add artificial reverberation to an audio signal read from a file.

Create the dsp.AudioFileReader and audioDeviceWriter System objects. Use the sample rate of the reader as the sample rate of the writer.

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

Play 10 seconds of the audio signal through your device.

tic
while toc < 10
    audio = fileReader();
    deviceWriter(audio);
end
release(fileReader)

Construct a reverberator System object with default settings.

reverb = reverberator
reverb = 
  reverberator with properties:

                PreDelay: 0
        HighCutFrequency: 20000
               Diffusion: 0.5000
             DecayFactor: 0.5000
    HighFrequencyDamping: 5.0000e-04
               WetDryMix: 0.3000
              SampleRate: 44100

Construct a time scope to visualize the original audio signal and the audio signal with added artificial reverberation.

scope = timescope( ...
    'SampleRate',fileReader.SampleRate,...
    'TimeSpanOverrunAction','Scroll',...
    'TimeSpanSource','property',...
    'TimeSpan',3,...
    'BufferLength',3*fileReader.SampleRate*2, ...
    'YLimits',[-1,1],...
    'ShowGrid',true, ...
    'ShowLegend',true, ...
    'Title','Audio with Reverberation vs. Original');

Play the audio signal with artificial reverberation. Visualize the audio with reverberation and the original audio.

while ~isDone(fileReader)
    audio = fileReader();
    audioWithReverb = reverb(audio);
    deviceWriter(audioWithReverb);
    scope([audioWithReverb(:,1),audio(:,1)])
end
release(fileReader)
release(deviceWriter)
release(scope)

Create a dsp.AudioFileReader to read in audio frame-by-frame. Create an audioDeviceWriter to write audio to your sound card. Create a reverberator to process the audio data.

frameLength = 1024;
fileReader = dsp.AudioFileReader('RockDrums-44p1-stereo-11secs.mp3', ...
    'SamplesPerFrame',frameLength,'PlayCount',2);
deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);
reverb = reverberator('SampleRate',fileReader.SampleRate);

Call parameterTuner to open a UI to tune parameters of the octaveFilter while streaming.

parameterTuner(reverb)

In an audio stream loop:

  1. Read in a frame of audio from the file.

  2. Apply reverberation.

  3. Write the frame of audio to your audio device for listening.

While streaming, tune parameters of the reverberator and listen to the effect.

while ~isDone(fileReader)
    audioIn = fileReader();
    audioOut = reverb(audioIn);
    deviceWriter(audioOut);
    drawnow limitrate % required to update parameter
end

As a best practice, release your objects once done.

release(deviceWriter)
release(fileReader)
release(reverb)

Tips

The createAudioPluginClass and configureMIDI functions map tunable properties of the compressor to user-facing parameters:

PropertyRangeMappingUnit
PreDelay[0, 1]linears
HighCutFrequency[20, 20000]logHz
Diffusion[0, 1]linearnone
DecayFactor[0, 1]linearnone
HighFrequencyDamping[0, 1]linearnone
WetDryMix[0, 1]linearnone

Algorithms

expand all

The algorithm to add reverberation follows the plate-class reverberation topology described in [1] and is based on a 29,761 Hz sample rate.

The algorithm has five stages.

The description for the algorithm that follows is for a stereo input. A mono input is a simplified case.

References

[1] Dattorro, Jon. "Effect Design, Part 1: Reverberator and Other Filters." Journal of the Audio Engineering Society. Vol. 45, Issue 9, 1997, pp. 660–684.

[2] Dattorro, Jon. "Effect Design, Part 2: Delay-Line Modulation and Chorus." Journal of the Audio Engineering Society. Vol. 45, Issue 10, 1997, pp. 764–788.

Extended Capabilities

Version History

Introduced in R2016a

See Also