Compressor

Tier: Primitives | ComponentType: 13 | Params: 7

Full dynamics processor with envelope follower, soft-knee gain computer, and makeup gain.

Overview

The Compressor implements a complete dynamics processing chain: level detection (peak or RMS), envelope following with independent attack/release, a soft-knee gain computer, and makeup gain. The ratio parameter supports the full range from expansion (ratio < 1) through compression to limiting (ratio approaches infinity).

The soft knee provides a gradual onset of compression that avoids the "pumping" artifacts of a hard knee. The gain computer operates in the dB domain for perceptually linear behavior.

File Locations

	Path
Header	Sources/FolioDSP/include/FolioDSP/Primitives/Compressor.h
Implementation	Sources/FolioDSP/src/Primitives/Compressor.cpp
Tests	Tests/FolioDSPTests/CompressorTests.swift
Bridge	Sources/FolioDSPBridge/src/FolioDSPBridge.mm (CompressorBridge)

Parameters

Index	Name	Description	Min	Max	Default Min	Default Max	Default	Unit
0	Threshold	Level above which compression begins	-80.0	0.0	-60.0	0.0	-20.0	dB
1	Ratio	Compression ratio (< 1 = expansion, > 1 = compression)	0.1	100.0	1.0	20.0	4.0	:1
2	Attack	Time to respond to rising levels	0.01	500.0	0.1	100.0	10.0	ms
3	Release	Time for gain to recover	1.0	5000.0	10.0	1000.0	100.0	ms
4	Knee	Soft knee width (0 = hard knee)	0.0	60.0	0.0	30.0	6.0	dB
5	Makeup Gain	Output gain compensation	0.0	60.0	0.0	30.0	0.0	dB
6	Detection	Detection mode: 0=peak, 1=RMS	0.0	1.0	0.0	1.0	0.0

Processing Algorithm

1. Level Detection

Peak: \(L = |x|\)

RMS: \(L = \sqrt{\frac{1}{512}\sum x^2}\) (512-sample window)

2. Convert to dB

\[L_{\text{dB}} = 20 \log_{10}(L)\]

3. Envelope Following

\[e \mathrel{+}= (1 - \alpha)(L_{\text{dB}} - e)\]

with separate \(\alpha\) for attack (rising) and release (falling).

4. Gain Computer (Soft Knee)

\[\text{overshoot} = e - T\]

Hard knee (knee < 0.01 dB):

\[G_{\text{dB}} = \text{overshoot} \cdot (1/R - 1), \quad \text{overshoot} > 0\]

Soft knee:

\[G_{\text{dB}} = \begin{cases} 0 & \text{overshoot} < -K/2 \\ \left(\frac{\text{overshoot} + K/2}{K}\right)^2 \cdot \frac{K(1/R - 1)}{2} & |\text{overshoot}| \leq K/2 \\ \text{overshoot} \cdot (1/R - 1) & \text{overshoot} > K/2 \end{cases}\]

5. Apply Gain + Makeup

\[y = x \cdot 10^{(G_{\text{dB}} + M) / 20}\]

Snapshot Fields

Field	Type	Range	Unit	Description
Input	Float	-80–0	dB	Input level
Output	Float	-80–0	dB	Output level
GR	Float	-60–0	dB	Gain reduction
Envelope	Float	-80–0	dB	Smoothed envelope
Threshold	Float	-80–0	dB	Current threshold
Ratio	Float	0.1–100	:1	Current ratio
Engaging	Bool	0–1		Whether GR is active

Implementation Notes

• Expansion mode: ratio < 1 reduces level below threshold
• RMS detection uses a 512-sample integration window
• Gain smoothing operates on dB values for perceptually uniform behavior
• "Engaging" flag indicates GR < -0.1 dB (UI activity indicator)

Equation Summary

gain_dB = (1-1/R)·max(0, in_dB - T)