audioEnvelopeFollower

R2026b

Track amplitude envelope of audio signal

Since R2026b

Description

The audioEnvelopeFollower object estimates the envelope of an input signal over time.

To generate the estimated envelope:

1. Create the audioEnvelopeFollower 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

Syntax

aEF = audioEnvelopeFollower

aEF = audioEnvelopeFollower(PropertyName=Value)

Description

aEF = audioEnvelopeFollower creates an audio envelope follower System object™, aEF, with default property values.

aEF = audioEnvelopeFollower(PropertyName=Value) sets properties using one or more name-value arguments. Unspecified properties have default values.

For example, aEF = audioEnvelopeFollower(AttackTime=0.05,ReleaseTime=0.1) creates an audio envelope follower System object, aEF, with an attack time of 0.05 seconds and a release time of 0.1 seconds.

Properties

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.

InputMode — Input signal preprocessing mode

"rms" (default) | "peak" | "bypass"

Input signal preprocessing mode, specified as one of these:

• "rms" — The object squares the input signal before estimating the squared envelope. This mode tracks the root-mean-square (RMS) amplitude.

• "peak" — The object takes the absolute value of the input signal before estimating the envelope. This mode tracks peak amplitude.

• "bypass" — The input signal passes directly for envelope estimation without preprocessing.

For more information, see Algorithms.

Data Types: char

AttackTime — Attack time in seconds

0.125 (default) | nonnegative scalar

Attack time in seconds, specified as a nonnegative scalar.

This property represents the time for the envelope to rise toward higher amplitude levels.

• A smaller attack time causes the envelope to respond more quickly to increases in signal amplitude.

• A value of 0 causes the envelope to instantly track upward changes.

To use the parameterTuner function, this parameter must not be greater than 4 seconds.

Tunable: Yes

Data Types: single | double

ReleaseTime — Release time in seconds

0.125 (default) | nonnegative scalar

Release time in seconds, specified as a nonnegative scalar.

This property represents the time for the envelope to fall toward lower amplitude levels.

• A smaller release time causes the envelope to respond more quickly to decreases in signal amplitude.

• A value of 0 causes the envelope to instantly track downward changes.

To use the parameterTuner function, this parameter must not be greater than 4 seconds.

Tunable: Yes

Data Types: single | double

HoldTime — Hold time in seconds

0 (default) | nonnegative scalar

Hold time in seconds, specified as a nonnegative scalar.

This property represents the time for the object to hold the envelope at its current level before beginning the release.

• When the input signal drops below the current envelope level, the envelope maintains its current value for the duration of HoldTime before beginning to decay according to ReleaseTime.

• A value of 0 causes the envelope to instantly respond to downward changes according to ReleaseTime.

To use the parameterTuner function, this parameter must not be greater than 4 seconds.

Tunable: Yes

Data Types: single | double

SampleRate — Input sample rate in Hz

44100 (default) | positive scalar

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

The sample rate determines the mapping between the AttackTime, ReleaseTime, and HoldTime properties and the filter coefficients used to detect the envelope.

Tunable: Yes

Data Types: single | double

Usage

Syntax

env = aEF(audioIn)

Description

env = aEF(audioIn) generates an envelope, env, for the input audio signal, audioIn.

Input Arguments

audioIn — Input audio signal

column vector | matrix

Input audio signal, specified as a column vector or a matrix with one column per channel.

Data Types: single | double

Output Arguments

env — Envelope

column vector | matrix

Envelope, returned as a column vector or a matrix with as many columns as channels.

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)

Specific to audioEnvelopeFollower

parameterTuner

Tune object parameters while streaming

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Track Envelope of Audio Signal

Create an audioEnvelopeFollower System object with default parameters.

aEFd = audioEnvelopeFollower

aEFd = 
  audioEnvelopeFollower with properties:

      InputMode: 'rms'
     AttackTime: 0.1250
    ReleaseTime: 0.1250
       HoldTime: 0
     SampleRate: 44100

Process an audio signal from a file through the audioEnvelopeFollower System object. Plot the audio signal and its envelope follower.

[x,Fs] = audioread("Ambiance-16-44p1-mono-12secs.wav");
t = (0:numel(x)-1)/Fs;

y1 = aEFd(x);

plot(t,x,t,y1,".--")
xlim([0 t(end)])
xlabel("Time (s)")
ylabel("Amplitude (V)")
legend(["Audio Input" "Envelope Follower (Default)"],Location="northeast")

To enhance the envelope follower, adjust the properties of the audioEnvelopeFollower System object. Set the attack time to 10 ms, the release time to 50 ms, and the hold time to 5 ms.

aEFe = audioEnvelopeFollower(SampleRate=Fs, ...
    AttackTime=10e-3,ReleaseTime=50e-3,HoldTime=5e-3)

aEFe = 
  audioEnvelopeFollower with properties:

      InputMode: 'rms'
     AttackTime: 0.0100
    ReleaseTime: 0.0500
       HoldTime: 0.0050
     SampleRate: 44100

Process the audio signal through the adjusted envelope follower. Plot the signal and its tracked envelope. The adjusted envelope follower tracks the oscillating amplitudes.

y2 = aEFe(x);

cla
plot(t,x,t,y2,".--")
xlim([0 t(end)])
legend(["Audio Input" "Envelope Follower (Adjusted)"],Location="northeast")

Envelope Follower of Multichannel Signal

Create an audio enveloper follower at a sample rate of 48000 Hz that tracks the peak amplitude. Set the attack time and hold time to 10 ms.

Fs  = 48e3;
ef = audioEnvelopeFollower(SampleRate=Fs, ...
    AttackTime=10e-3,HoldTime=10e-3,InputMode="peak")

ef = 
  audioEnvelopeFollower with properties:

      InputMode: 'peak'
     AttackTime: 0.0100
    ReleaseTime: 0.1250
       HoldTime: 0.0100
     SampleRate: 48000

Generate a two-channel signal that comprises:

• A sine-modulated signal, where the amplitude oscillates between 0.5 and 2.5 V. The carrier frequency is 220 Hz.

• A square-modulated signal with a 25% duty cycle. The carrier frequency is 55 Hz.

t = (0:2*Fs-1)'/Fs;
C1 = (1.5+sin(2*pi*t)) .* sin(2*pi*220*t);
C2 = (1+square(2*pi*2*t,25))/2 .* sin(2*pi*55*t);
x = [C1 C2];

Estimate the envelope follower from the two-channel input signal. For each channel, plot the input signal and its envelope follower.

y = ef(x);

tiledlayout("vertical")
for c = 1:size(x,2)
    nexttile
    plot(t,x(:,c),"k",t,y(:,c),".-");
    grid on
    xlabel("Time (s)");
    ylabel("Amplitude (V)");
    title("Channel " + c);
    legend(["Input" "Envelope"],Location="southeast");
end

Multi-Threshold Compressor Using Audio Envelope Follower

Use the envelope of an audio signal to calculate compression gain values using multiple thresholds and ratios.

Load an audio signal and convert it to mono.

[x,fs] = audioread("RockDrums-48-stereo-11secs.mp3");
x = mean(x,2);

Create an audioEnvelopeFollower System object™ with an attack time of 5 ms, a hold time of 10 ms, and a release time of 20 ms. Specify the sample rate as the sample rate of the audio signal.

ae = audioEnvelopeFollower( ...
    AttackTime=0.005, ...
    HoldTime=0.01,...
    ReleaseTime=0.02, ...
    SampleRate=fs);

Get the RMS envelope of the signal using the envelope follower. Convert the envelope to decibels.

xEnv = ae(x);
xEnvdB = 20*log10(max(xEnv,eps));

Specify two compressor thresholds and ratios: –20 dB and 4:1, and –10 dB and 8:1, respectively.

thresh1 = -20;
thresh2 = -10;
ratio1 = 4;
ratio2 = 8;

Calculate the negative gain applied by the compressor. When the signal exceeds –20 dB, apply gain using a 4:1 ratio.

targetdB1 = xEnvdB;
above_thresh1 = targetdB1 > thresh1;
targetdB1(above_thresh1) = thresh1 + (xEnvdB(above_thresh1) - thresh1) / ratio1;
G1 = targetdB1 - xEnvdB;

If the signal exceeds –10 dB after the initial gain, apply additional compression using the 8:1 ratio.

targetdB2 = targetdB1;
above_thresh2 = targetdB2 > thresh2;
targetdB2(above_thresh2) = thresh2 + (targetdB2(above_thresh2) - thresh2) / ratio2;
G2 = targetdB2 - targetdB1;

Add the gain signals and convert to linear amplitude. Compress the input signal using the calculated gain.

G = G1 + G2;
Glinear = 10.^(G/20);
xComp = x .* Glinear;

Plot the first channel of the input signal and the compressed signal. Additionally plot the gain applied to the input signal. Restrict the x-axis to show two transients.

t = (1:length(x))/fs;
tiledlayout(2,1,TileSpacing="compact")
nexttile
plot(t, [x xComp])
xlim([11.15,11.35])
xlabel('Time (s)')
ylabel('Amplitude')
title('Original and Compressed Signals')
nexttile
plot(t,G)
xlim([11.15,11.35])
xlabel('Time (s)')
ylabel('Gain (dB)')
title('Gain Signal')

Algorithms

Assume an input signal x[n] and its envelope y[n] with these parameters:

• F_s is the sample rate.

• t_a is the attack time.

• t_r is the release time.

• t_h is the hold time.

The attack and release times correspond to the time in seconds that y[n] takes to go to 1 – e^–1 (~63.2%) of its final value. The release time count, t_c, is the time elapsed since x is less than y. Then, the attack-time coefficient α_a and the release-time coefficient α_r are these:

• α_a = e^{–1/(F_st_a)}

• α_r = e^{–1/(F_st_r)}

Depending on the input signal preprocessing mode, the table lists the preprocessed input x_p[n], preprocessed envelope y_p[n], and envelope y[n].

Preprocessing Mode	Preprocessed Input	Preprocessed Envelope	Envelope
Root mean square (RMS)	xp[n] = (x[n])2	$$y_{\text{p}}[n]=\{\begin{array}{c}{\alpha }_{\text{a}}{y}_{\text{p}}[n-1]+(1-{\alpha }_{\text{a}})x_{\text{p}}[n],x_{\text{p}}[n]>y_{\text{p}}[n-1]\\ y_{\text{p}}[n-1],x_{\text{p}}[n]\le y_{\text{p}}[n-1]\wedge t_{\text{c}}\le t_{\text{h}}\\ {\alpha }_{\text{r}}{y}_{\text{p}}[n-1]+(1-{\alpha }_{\text{r}})x_{\text{p}}[n],x_{\text{p}}[n]\le y_{\text{p}}[n-1]\wedge t_{\text{c}}>t_{\text{h}}\end{array}$$	y[n] = √(yp[n])
Peak	xp[n] = |x[n]|		y[n] = yp[n]
Bypass	xp[n] = x[n]		y[n] = yp[n]

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 R2026b