compressor

Dynamic range compressor

Description

The compressor System object™ performs dynamic range compression independently across each input channel. Dynamic range compression attenuates the volume of loud sounds that cross a given threshold. It uses specified attack and release times to achieve a smooth applied gain curve. Properties of the compressor System object specify the type of dynamic range compression.

To perform dynamic range compression:

Create the compressor object and set its properties.
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

dRC = compressor

dRC = compressor(thresholdValue)

dRC = compressor(thresholdValue,ratioValue)

dRC = compressor(___,Name,Value)

Description

dRC = compressor creates a System object, dRC, that performs dynamic range compression independently across each input channel over time.

dRC = compressor(thresholdValue) sets the Threshold property to thresholdValue.

dRC = compressor(thresholdValue,ratioValue) sets the Ratio property to ratioValue.

dRC = compressor(___,Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: dRC = compressor('AttackTime',0.01,'SampleRate',16000) creates a System object, dRC, with a 10 ms attack time operating at a 16 kHz sample rate.

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.

`Threshold` — Operation threshold (dB)
`–10` (default) | real scalar

Operation threshold in dB, specified as a real scalar.

Operation threshold is the level above which gain is applied to the input signal.

Tunable: Yes

Data Types: single | double

`Ratio` — Compression ratio
`5` (default) | real scalar

Compression ratio, specified as a real scalar greater than or equal to 1.

Compression ratio is the input/output ratio for signals that overshoot the operation threshold.

Assuming a hard knee characteristic and a steady-state input such that x[n] dB > Threshold, the compression ratio is defined as $R = \frac{(x [n] - T)}{(y [n] - T)}$ .

R is the compression ratio.
x[n] is the input signal in dB.
y[n] is the output signal in dB.
T is the threshold in dB.

Tunable: Yes

Data Types: single | double

`KneeWidth` — Knee width (dB)
`0` (default) | real scalar

Knee width in dB, specified as a real scalar greater than or equal to 0.

Knee width is the transition area in the compression characteristic.

For soft knee characteristics, the transition area is defined by the relation

$y = x + \frac{(\frac{1}{R} - 1) \times {(x - T + \frac{W}{2})}^{2}}{(2 \times W)}$

for the range $(2 \times | x - T |) \leq W$ .

y is the output level in dB.
x is the input level in dB.
R is the compression ratio.
T is the threshold in dB.
W is the knee width in dB.

Tunable: Yes

Data Types: single | double

`AttackTime` — Attack time (s)
`0.05` (default) | real scalar

Attack time in seconds, specified as a real scalar greater than or equal to 0.

Attack time is the time it takes the compressor gain to rise from 10% to 90% of its final value when the input goes above the threshold.

Tunable: Yes

Data Types: single | double

`ReleaseTime` — Release time (s)
`0.2` (default) | real scalar

Release time in seconds, specified as a real scalar greater than or equal to 0.

Release time is the time it takes the compressor gain to drop from 90% to 10% of its final value when the input goes below the threshold.

Tunable: Yes

Data Types: single | double

`MakeUpGainMode` — Make-up gain mode
`'Property'` (default) | `'Auto'`

Make-up gain mode, specified as 'Auto' or 'Property'.

'Auto' –– Make-up gain is applied at the output of the dynamic range compressor such that a steady-state 0 dB input has a 0 dB output.
'Property' –– Make-up gain is set to the value specified in the MakeUpGain property.

Tunable: No

Data Types: char | string

`MakeUpGain` — Make-up gain (dB)
`0` (default) | real scalar

Make-up gain in dB, specified as a real scalar.

Make-up gain compensates for gain lost during compression. It is applied at the output of the dynamic range compressor.

Tunable: Yes

Dependencies

To enable this property, set MakeUpGainMode to 'Property'.

Data Types: single | double

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

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

Tunable: Yes

Data Types: single | double

Usage

Syntax

audioOut = dRC(audioIn)

[audioOut,gain] = dRC(audioIn)

Description

example

audioOut = dRC(audioIn) performs dynamic range compression on the input signal, audioIn, and returns the compressed signal, audioOut. The type of dynamic range compression is specified by the algorithm and properties of the compressor System object, dRC.

example

[audioOut,gain] = dRC(audioIn) also returns the applied gain, in dB, at each input sample.

Input Arguments

expand all

`audioIn` — Audio input to compressor
matrix

Audio input to the compressor, specified as a matrix. The columns of the matrix are treated as independent audio channels.

Data Types: single | double

Output Arguments

expand all

`audioOut` — Audio output from compressor
matrix

Audio output from the compressor, returned as a matrix the same size as audioIn.

Data Types: single | double

`gain` — Gain applied by compressor (dB)
matrix

Gain applied by compressor, returned as a matrix the same size as audioIn.

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

Specific to compressor

`visualize`	Visualize static characteristic of dynamic range controller
`createAudioPluginClass`	Create audio plugin class that implements functionality of System 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 duplicate System object
`isLocked`	Determine if System object is in use
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object
`step`	Run System object algorithm

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

Property	Range	Mapping	Unit
`Threshold`	[–50, 0]	linear	dB
`Ratio`	[1, 50]	linear	none
`KneeWidth`	[0, 20]	linear	dB
`AttackTime`	[0, 4]	linear	seconds
`ReleaseTime`	[0, 4]	linear	seconds
`MakeUpGain` (available when you set `MakeUpGainMode` to `'Property'`)	[–10, 24]	linear	dB

Examples

collapse all

Compress Audio Signal

Open Live Script

Use dynamic range compression to attenuate the volume of loud sounds.

Set up the dsp.AudioFileReader and audioDeviceWriter System objects™.

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

Set up the compressor to have a threshold of -15 dB, a ratio of 7, and a knee width of 5 dB. Use the sample rate of your audio file reader.

dRC = compressor(-15,7, ...
    'KneeWidth',5, ...
    'SampleRate',fileReader.SampleRate);

Set up the scope to visualize the original audio signal, the compressed audio signal, and the applied compressor gain.

scope = timescope( ...
    'SampleRate',fileReader.SampleRate, ...
    'TimeSpanSource','Property','TimeSpan',1, ...
    'BufferLength',44100*4, ...
    'YLimits',[-1,1], ...
    'TimeSpanOverrunAction','Scroll', ...
    'ShowGrid',true, ...
    'LayoutDimensions',[2,1], ...
    'NumInputPorts',2, ...
    'Title', ...
    ['Original vs. Compressed Audio (top)' ...
    ' and Compressor Gain in dB (bottom)']);
scope.ActiveDisplay = 2;
scope.YLimits = [-4,0];
scope.YLabel = 'Gain (dB)';

Play the processed audio and visualize it on the scope.

while ~isDone(fileReader)
    x = fileReader();
    [y,g] = dRC(x);
    deviceWriter(y);
    scope([x(:,1),y(:,1)],g(:,1))
end

release(dRC)
release(deviceWriter)
release(scope)

Compare Dynamic Range Limiter and Compressor

Open Live Script

A dynamic range limiter is a special type of dynamic range compressor. In limiters, the level above an operational threshold is hard limited. In the simplest implementation of a limiter, the effect is equivalent to audio clipping. In compressors, the level above an operational threshold is lowered using a specified compression ratio. Using a compression ratio results in a smoother processed signal.

Compare Limiter and Compressor Applied to Sinusoid

Create a limiter System object™ and a compressor System object. Set the AttackTime and ReleaseTime properties of both objects to zero. Create an audioOscillator System object to generate a sinusoid with Frequency set to 5 and Amplitude set to 0.1.

dRL = limiter('AttackTime',0,'ReleaseTime',0);
dRC = compressor('AttackTime',0,'ReleaseTime',0);

osc = audioOscillator('Frequency',5,'Amplitude',0.1);

Create a time scope to visualize the generated sinusoid and the processed sinusoid.

scope = timescope( ...
    'SampleRate',osc.SampleRate, ...
    'TimeSpanSource','Property','TimeSpan',2, ...
    'BufferLength',osc.SampleRate*4, ...
    'TimeSpanOverrunAction','Scroll', ...
    'ShowGrid',true, ...
    'LayoutDimensions',[2 1], ...
    'NumInputPorts',2);
scope.ActiveDisplay = 1;
scope.Title = 'Original Signal vs. Limited Signal';
scope.YLimits = [-1,1]; 
scope.ActiveDisplay = 2;
scope.Title = 'Original Signal vs. Compressed Signal';
scope.YLimits = [-1,1];

In an audio stream loop, visualize the original sinusoid and the sinusoid processed by a limiter and a compressor. Increment the amplitude of the original sinusoid to illustrate the effect.

while osc.Amplitude < 0.75
    x = osc();
    
    xLimited    = dRL(x);
    xCompressed = dRC(x);
    
    scope([x xLimited],[x xCompressed]);
    
    osc.Amplitude = osc.Amplitude + 0.0002;
end
release(scope)

release(dRL)
release(dRC)
release(osc)

Compare Limiter and Compressor Applied to Audio Signal

Compare the effect of dynamic range limiters and compressors on a drum track. Create a dsp.AudioFileReader System object and a audioDeviceWriter System object to read audio from a file and write to your audio output device. To emphasize the effect of dynamic range control, set the operational threshold of the limiter and compressor to -20 dB.

dRL.Threshold = -20;
dRC.Threshold = -20;

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

Read successive frames from an audio file in a loop. Listen to and compare the effect of dynamic range limiting and dynamic range compression on an audio signal.

numFrames = 300;

fprintf('Now playing original signal...\n')

Now playing original signal...

for i = 1:numFrames
    x = fileReader();
    deviceWriter(x);
end
reset(fileReader);

fprintf('Now playing limited signal...\n')

Now playing limited signal...

for i = 1:numFrames
    x = fileReader();
    xLimited = dRL(x);
    deviceWriter(xLimited);
end
reset(fileReader);

fprintf('Now playing compressed signal...\n')

Now playing compressed signal...

for i = 1:numFrames
    x = fileReader();
    xCompressed = dRC(x);
    deviceWriter(xCompressed);
end
    
release(fileReader)
release(deviceWriter)
release(dRC)
release(dRL)

Diminish Plosives from Speech Signal

Open Live Script

Plosives are consonant sounds resulting from a sudden release of airflow. They are most pronounced in words beginning with p, d, and g sounds. Plosives can be emphasized by the recording process and are often displeasurable to hear. In this example, you minimize the plosives of a speech signal by applying highpass filtering and low-band compression.

Create a dsp.AudioFileReader object and a audioDeviceWriter object to read an audio signal from a file and write an audio signal to a device. Play the unprocessed signal. Then release the file reader and device writer.

fileReader = dsp.AudioFileReader('audioPlosives.wav');
deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);

while ~isDone(fileReader)
    audioIn = fileReader();
    deviceWriter(audioIn);
end
release(deviceWriter)
release(fileReader)

Design a highpass filter with a steep rolloff of all frequencies below 120 Hz. Use a dsp.BiquadFilter object to implement the highpass filter design. Create a crossover filter with one crossover at 250 Hz. The crossover filter enables you to separate the band of interest for processing. Create a dynamic range compressor to compress the dynamic range of plosive sounds. To apply no make-up gain, set the MakeUpGainMode to "Property" and use the default 0 dB MakeUpGain property value. Create a time scope to visualize the processed and unprocessed audio signal.

[B,A] = designVarSlopeFilter(48,120/(fileReader.SampleRate/2),"hi");
biquadFilter = dsp.BiquadFilter( ...
    "SOSMatrixSource","Input port", ...
    "ScaleValuesInputPort",false);

crossFilt = crossoverFilter( ...
    "SampleRate",fileReader.SampleRate, ...
    "NumCrossovers",1, ...
    "CrossoverFrequencies",250, ...
    "CrossoverSlopes",48);

dRCompressor = compressor( ...
    "Threshold",-35, ...
    "Ratio",10, ...
    "KneeWidth",20, ...
    "AttackTime",1e-4, ...
    "ReleaseTime",3e-1, ...
    "MakeUpGainMode","Property", ...
    "SampleRate",fileReader.SampleRate);

scope = timescope( ...
    "SampleRate",fileReader.SampleRate, ...
    "TimeSpanSource","property","TimeSpan",3, ...
    "BufferLength",fileReader.SampleRate*3*2, ...
    "YLimits",[-1 1], ...
    "ShowGrid",true, ...
    "ShowLegend",true, ...
    "ChannelNames",{'Original','Processed'});

In an audio stream loop:

Read in a frame of the audio file.
Apply highpass filtering using your biquad filter.
Split the audio signal into two bands.
Apply dynamic range compression to the lower band.
Remix the channels.
Write the processed audio signal to your audio device for listening.
Visualize the processed and unprocessed signals on a time scope.

As a best practice, release your objects once done.

while ~isDone(fileReader)
    audioIn = fileReader();
    audioIn = biquadFilter(audioIn,B,A);
    [band1,band2] = crossFilt(audioIn);
    band1compressed = dRCompressor(band1);
    audioOut = band1compressed + band2;
    deviceWriter(audioOut);
    scope([audioIn audioOut])
end

As a best practice, release your objects once done.

release(deviceWriter)
release(fileReader)
release(crossFilt)
release(dRCompressor)
release(scope)

Tune Compressor Parameters

Open Live Script

Create a dsp.AudioFileReader to read in audio frame-by-frame. Create an audioDeviceWriter to write audio to your sound card. Create a compressor to process the audio data. Call visualize to plot the static characteristic of the compressor.

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

dRC = compressor('SampleRate',fileReader.SampleRate); 
visualize(dRC)

Create a timescope to visualize the original and processed audio.

scope = timescope( ...
    'SampleRate',fileReader.SampleRate, ...
    'TimeSpanSource','property',...
    'TimeSpan',1, ...
    'BufferLength',fileReader.SampleRate*4, ...
    'YLimits',[-1,1], ...
    'TimeSpanOverrunAction','Scroll', ...
    'ShowGrid',true, ...
    'LayoutDimensions',[2,1], ...
    'NumInputPorts',2, ...
    'Title','Original vs. Compressed Audio (top) and Compressor Gain in dB (bottom)');
scope.ActiveDisplay = 2;
scope.YLimits = [-4,0];
scope.YLabel = 'Gain (dB)';

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

parameterTuner(dRC)

In an audio stream loop:

Read in a frame of audio from the file.
Apply dynamic range compression.
Write the frame of audio to your audio device for listening.
Visualize the original audio, the processed audio, and the gain applied.

While streaming, tune parameters of the dynamic range compressor and listen to the effect.

while ~isDone(fileReader)
    audioIn = fileReader();
    [audioOut,g] = dRC(audioIn);
    deviceWriter(audioOut);
    scope([audioIn(:,1),audioOut(:,1)],g(:,1));
    drawnow limitrate % required to update parameter
end

As a best practice, release your objects once done.

release(deviceWriter)
release(fileReader)
release(dRC)
release(scope)

Algorithms

expand all

The compressor System object processes a signal frame by frame and element by element.

Convert Input Signal to dB

The N-point signal, x[n], is converted to decibels:

$x_{dB} [n] = 20 \times \log_{10} | x [n] |$

Gain Computer

x_dB[n] passes through the gain computer. The gain computer uses the static characteristic properties of the dynamic range compressor to attenuate gain that is above the threshold.

If you specified a soft knee, the gain computer has the following static characteristic:

$x_{sc} (x_{dB}) = {\begin{matrix} x_{dB} & x_{dB} < (T - \frac{W}{2}) \\ x_{dB} + \frac{(\frac{1}{R} - 1) {(x_{dB} - T + \frac{W}{2})}^{2}}{2 W} & (T - \frac{W}{2}) \leq x_{dB} \leq (T + \frac{W}{2}) \\ T + \frac{(x_{dB} - T)}{R} & x_{dB} > (T + \frac{W}{2}) \end{matrix},$

where T is the threshold, R is the ratio, and W is the knee width.

If you specified a hard knee, the gain computer has the following static characteristic:

$x_{sc} (x_{dB}) = {\begin{matrix} x_{dB} & x_{dB} < T \\ T + \frac{(x_{dB} - T)}{R} & x_{dB} \geq T \end{matrix}$

The computed gain, g_c[n], is calculated as

$g_{c} [n] = x_{sc} [n] - x_{dB} [n] .$

Gain Smoothing

g_c[n] is smoothed using specified attack and release time properties:

$g_{s} [n] = {\begin{matrix} α_{A} g_{s} [n - 1] + (1 - α_{A}) g_{c} [n], & g_{c} [n] \leq g_{s} [n - 1] \\ α_{R} g_{s} [n - 1] + (1 - α_{R}) g_{c} [n], & g_{c} [n] > g_{s} [n - 1] \end{matrix}$

The attack time coefficient, α_A , is calculated as

$α_{A} = \exp (\frac{- \log (9)}{F s \times T_{A}}) .$

The release time coefficient, α_R , is calculated as

$α_{R} = \exp (\frac{- \log (9)}{F s \times T_{R}}) .$

T_A is the attack time period, specified by the AttackTime property. T_R is the release time period, specified by the ReleaseTime property. Fs is the input sampling rate, specified by the SampleRate property.

Calculate and Apply Make-up Gain

If MakeUpGainMode is set to the default 'Auto', the make-up gain is calculated as the negative of the computed gain for a 0 dB input,

$M = {- x_{sc} |}_{x_{dB} = 0} .$

Given a steady-state input of 0 dB, this configuration achieves a steady-state output of 0 dB. The make-up gain is determined by the Threshold, Ratio, and KneeWidth properties. It does not depend on the input signal.

The make-up gain, M, is added to the smoothed gain, g_s[n]:

$g_{m} [n] = g_{s} [n] + M$

Calculate and Apply Linear Gain

The calculated gain in dB, g_m[n], is translated to a linear domain:

$g_{lin} [n] = 10^{(\frac{g_{m} [n]}{20})}$

The output of the dynamic range compressor is given as

$y [n] = x [n] \times g_{lin} [n] .$

References

[1] Giannoulis, Dimitrios, Michael Massberg, and Joshua D. Reiss. "Digital Dynamic Range Compressor Design –– A Tutorial and Analysis." Journal of Audio Engineering Society. Vol. 60, Issue 6, 2012, pp. 399–408.

Documentation

compressor

Description

Creation

Syntax

Description

Properties

Threshold — Operation threshold (dB) –10 (default) | real scalar

Ratio — Compression ratio 5 (default) | real scalar

KneeWidth — Knee width (dB) 0 (default) | real scalar

AttackTime — Attack time (s) 0.05 (default) | real scalar

ReleaseTime — Release time (s) 0.2 (default) | real scalar

MakeUpGainMode — Make-up gain mode 'Property' (default) | 'Auto'

MakeUpGain — Make-up gain (dB) 0 (default) | real scalar

Dependencies

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

Usage

Syntax

Description

Input Arguments

audioIn — Audio input to compressor matrix

Output Arguments

audioOut — Audio output from compressor matrix

gain — Gain applied by compressor (dB) matrix

Object Functions

Specific to compressor

MIDI

Common to All System Objects

Examples

Compress Audio Signal

Compare Dynamic Range Limiter and Compressor

Diminish Plosives from Speech Signal

Tune Compressor Parameters

Algorithms

Convert Input Signal to dB

Gain Computer

Gain Smoothing

Calculate and Apply Make-up Gain

Calculate and Apply Linear Gain

References

Extended Capabilities

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

See Also

Topics

Audio Toolbox Documentation

Support

`Threshold` — Operation threshold (dB)
`–10` (default) | real scalar

`Ratio` — Compression ratio
`5` (default) | real scalar

`KneeWidth` — Knee width (dB)
`0` (default) | real scalar

`AttackTime` — Attack time (s)
`0.05` (default) | real scalar

`ReleaseTime` — Release time (s)
`0.2` (default) | real scalar

`MakeUpGainMode` — Make-up gain mode
`'Property'` (default) | `'Auto'`

`MakeUpGain` — Make-up gain (dB)
`0` (default) | real scalar

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

`audioIn` — Audio input to compressor
matrix

`audioOut` — Audio output from compressor
matrix

`gain` — Gain applied by compressor (dB)
matrix

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