reverberator

Add reverberation to audio signal

expand all in page

Description

ThereverberatorSystem object™ adds reverberation to mono or stereo audio signals.

To add reverberation to your input:

Create thereverberatorobject and set its properties.
Call the object with arguments, as if it were a function.

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

Creation

Syntax

reverb = reverberator

reverb = reverberator(Name,Value)

Description

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

reverb = reverberator(Name,Value)sets each propertyNameto the specifiedValue. 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 arenontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and thereleasefunction unlocks them.

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

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

`PreDelay`—Pre-delay for reverberation (s)
`0`(default) |real positive scalar

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

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

可调:Yes

Data Types:single|double

`HighCutFrequency`—Lowpass filter cutoff (Hz)
`20000`(default) |real positive scalar

Lowpass filter cutoff in Hz, specified as a real positive scalar in the range 0 to $(\frac{S a m p l e R a t e}{2})$ .

Lowpass filter cutoffis 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.

可调:Yes

Data Types:single|double

`Diffusion`—Density of reverb tail
`0.5`(default) |real scalar

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

Diffusionis proportional to the rate at which the reverb tail builds in density. IncreasingDiffusionpushes the reflections closer together, thickening the sound. ReducingDiffusioncreates more discrete echoes.

可调:Yes

Data Types:single|double

`DecayFactor`—Decay factor of reverb tail
`0.5`(default) |real scalar

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

DecayFactoris 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).

可调:Yes

Data Types:single|double

`HighFrequencyDamping`—High-frequency damping
`0.0005`(default) |real scalar

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

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

可调:Yes

Data Types:single|double

`WetDryMix`—Wet-dry mix
`0.3`(default) |real scalar

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

Wet-dry mixis the ratio of wet (reverberated) to dry (original) signal that yourreverberatorSystem object outputs.

可调:Yes

Data Types:single|double

`SampleRate`—Input sample rate (Hz)
`44100`(default) |positive scalar

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

可调:Yes

Data Types:single|double

Usage

Syntax

audioOut = reverb(audioIn)

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

`audioIn`—Audio input to reverberator
column vector|N-by-2 matrix

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

`audioOut`— Audio output from reverberator
N-by-2 matrix

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 namedobj, use this syntax:

release(obj)

expand all

Specific to reverberator

`createAudioPluginClass`	Create audio plugin class that implements functionality ofSystem object
`parameterTuner`	Tune object parameters while streaming

MIDI

`configureMIDI`	Configure MIDI connections between audio object and MIDI controller
`disconnectMIDI`	Disconnect MIDI controls from audio object
`getMIDIConnections`	Get MIDI connections of audio object

Common to All System Objects

`clone`	Create duplicateSystem object
`isLocked`	Determine ifSystem objectis in use
`release`	Release resources and allow changes toSystem objectproperty values and input characteristics
`reset`	Reset internal states ofSystem object
`step`	RunSystem objectalgorithm

Examples

collapse all

Add Reverberation to Audio Signal

Open Live Script

Use thereverberatorSystem object™ to add artificial reverberation to an audio signal read from a file.

Create thedsp。AudioFileReaderandaudioDeviceWriterSystem 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.

ticwhiletoc < 10 audio = fileReader(); deviceWriter(audio);endrelease(fileReader)

Construct areverberatorSystem object with default settings.

reverb = reverberator

混响=反射器的属性:预延迟:0HighCutFrequency: 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)])endrelease(fileReader) release(deviceWriter) release(scope)

Tune Reverberator Parameters

Open Live Script

Create adsp。AudioFileReaderto read in audio frame-by-frame. Create anaudioDeviceWriterto write audio to your sound card. Create areverberatorto 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);

CallparameterTunerto open a UI to tune parameters of theoctaveFilterwhile streaming.

parameterTuner(reverb)

In an audio stream loop:

Read in a frame of audio from the file.
Apply reverberation.
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); drawnowlimitrate% required to update parameterend

As a best practice, release your objects once done.

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

Tips

ThecreateAudioPluginClassandconfigureMIDIfunctions map tunable properties of thecompressorto user-facing parameters:

Property	Range	Mapping	Unit
`PreDelay`	[0, 1]	linear	s
`HighCutFrequency`	[20, 20000]	log	Hz
`Diffusion`	[0, 1]	linear	none
`DecayFactor`	[0, 1]	linear	none
`HighFrequencyDamping`	[0, 1]	linear	none
`WetDryMix`	[0, 1]	linear	none

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.

Stereo-to-Mono

A stereo signal is converted to a mono signal: $x [n] = 0.5 \times (x_{R} [n] + x_{L} [n])$ .

Preconditioning

A delay followed by a lowpass filter preconditions the mono signal.

The pre-delay output is determined as $x_{p} [n] = x [n - k]$ ,那里的PreDelayproperty determines the value ofk.
The signal is fed through a single-pole lowpass filter with transfer function

$L P (z) = \frac{1 - α}{1 - α z^{- 1}},$

where

$α = \exp (- 2 π \times \frac{f_{c}}{f_{s}}) .$
- f_cis the cutoff frequency specified by theHighCutFrequencyproperty.
- f_sis the sampling frequency specified by theSampleRateproperty.

Decorrelation

The signal is decorrelated by passing through a series of four allpass filters.

The allpass filters are of the form

$A P (z) = \frac{β + z^{- k}}{1 + β z^{- k}},$

whereβis the coefficient specified by theDiffusionproperty andkis the delay as follows:

ForAP₁,k= 142.
ForAP₂,k= 107.
ForAP₃,k= 379.
ForAP₄,k= 277.

Tank

The signal is fed into the tank, where it circulates to simulate the decay of a reverberation tail.

The following description tracks the signal as it progresses through the top of the tank. The signal progression through the bottom of the tank follows the same pattern, with different delay specifications.

The new signal enters the top of the tank and is added to the circulated signal from the bottom of the tank.
The signal passes through a modulated allpass filter:

$M o d u l a t e d A P_{1} (z) = \frac{- β + z^{- k}}{1 - β z^{- k}}$
- βis the coefficient specified by theDiffusionproperty.
- kis the variable delay specified by a 1 Hz sinusoid withamplitude = (8/29761)*SampleRate. To account for fractional delay resulting from the modulatingk, allpass interpolation is used[2].
The signal is delayed again, and then passes through a lowpass filter:

$L P_{2} (z) = \frac{1 - φ}{1 - φ z^{- 1}}$
- φis the coefficient specified by theHighFrequencyDampingproperty.
The signal is multiplied by a gain specified by theDecayFactorproperty. The signal then passes through an allpass filter:

$A P_{5} (z) = \frac{β + z^{- k}}{1 + β z^{- k}} .$
- βis the coefficient specified by theDiffusionproperty.
- kis set to1800for the top of the tank and2656for the bottom of the tank.
The signal is delayed again and then circulated to the bottom half of the tank for the next iteration.

A similar pattern is executed in parallel for the bottom half of the tank. The output of the tank is calculated as the signed sum of delay lines picked off at various points from the tank. The summed output is multiplied by0.6.

Wet/Dry Mix

The wet (processed) signal is then added to the dry (original) signal:

$y_{R} [n] = (1 - κ) x_{R} [n] + κ x_{3 R} [n],$

$y_{L} [n] = (1 - κ) x_{L} [n] + κ x_{3 L} [n],$

where theWetDryMixproperty determinesκ.

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

System Objects in MATLAB Code Generation(MATLAB Coder)

Version History

Introduced in R2016a

reverberator

Description

Creation

Syntax

Description

Properties

PreDelay—Pre-delay for reverberation (s)0(default) |real positive scalar

HighCutFrequency—Lowpass filter cutoff (Hz)20000(default) |real positive scalar

Diffusion—Density of reverb tail0.5(default) |real scalar

DecayFactor—Decay factor of reverb tail0.5(default) |real scalar

HighFrequencyDamping—High-frequency damping0.0005(default) |real scalar

WetDryMix—Wet-dry mix0.3(default) |real scalar

SampleRate—Input sample rate (Hz)44100(default) |positive scalar

Usage

Syntax

Description

Input Arguments

audioIn—Audio input to reverberatorcolumn vector|N-by-2 matrix

Output Arguments

audioOut— Audio output from reverberatorN-by-2 matrix

Object Functions

Specific to reverberator

MIDI

Common to All System Objects

Examples

Add Reverberation to Audio Signal

Tune Reverberator Parameters

Tips

Algorithms

Stereo-to-Mono

Preconditioning

Decorrelation

Tank

Wet/Dry Mix

References

Extended Capabilities

C/C++ Code GenerationGenerate C and C++ code using MATLAB® Coder™.

Version History

See Also

`PreDelay`—Pre-delay for reverberation (s)
`0`(default) |real positive scalar

`HighCutFrequency`—Lowpass filter cutoff (Hz)
`20000`(default) |real positive scalar

`Diffusion`—Density of reverb tail
`0.5`(default) |real scalar

`DecayFactor`—Decay factor of reverb tail
`0.5`(default) |real scalar

`HighFrequencyDamping`—High-frequency damping
`0.0005`(default) |real scalar

`WetDryMix`—Wet-dry mix
`0.3`(default) |real scalar

`SampleRate`—Input sample rate (Hz)
`44100`(default) |positive scalar

`audioIn`—Audio input to reverberator
column vector|N-by-2 matrix

`audioOut`— Audio output from reverberator
N-by-2 matrix

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.