audioeffects.limiter
A lookahead brickwall limiter: a ceiling the signal does not get past.
The player’s text is the class docstring; the CLAIMS table in the class’s
test file ties its claim sentences to tests.
- class audioeffects.limiter.Limiter(source, *options, **keywords)[source]
Bases:
ComponentBrickwall limiting against a ceiling, with optional lookahead and true-peak detection.
Ceiling and Gain. Ceiling sets the level nothing gets past. Gain drives the signal into it, and below the ceiling it is exactly the gain it says, within 0.1 dB. Below the ceiling nothing else is touched: the level holds within 0.05 dB, and at Ceiling 0 dB with no Gain the limiter is a wire. The Effect controls page lists what the knobs span and the patches.
Lookahead. Lookahead defaults to 0 ms, so out of the box the limiter adds no latency. With it on, the latency is the lookahead in whole samples, up to 480 samples at 48 kHz and 220 at 22.05 kHz, and the host is told the moment you move it. A short burst stays within 0.1 dB of the ceiling at every Lookahead setting, and a single-sample spike is caught at every setting from 0.5 ms up. Lengthening the lookahead while audio plays inserts that much silence; it never replays old audio.
Release is the distortion knob. The gain follows the signal sample by sample, so a fast release distorts low notes. Release is how fast the gain recovers, and a 60 Hz sine driven 12 dB into the ceiling measures 12.0 % THD at the 5 ms end of the Release macro. The default patch sits at 149 ms and 0.71 %, under 1 % at 48 kHz and 44.1 kHz.
True Peak. Off, the ceiling holds on the samples, and a peak between two samples can rise more than 2.5 dB over it. On, with any lookahead at all, the waveform between the samples stays within 0.5 dB of the ceiling at 48 kHz and 44.1 kHz. On with Lookahead 0 it is a sample ceiling only: a full-scale ramp gets more than 2 dB past it, because a peak between samples can’t be caught with no delay to catch it in. True Peak adds no latency of its own.
Knee. At Knee 0 the ceiling is a brickwall. Knee softens the bend, and at 12 dB the bend is more than 4 dB wide.
Stereo. The two channels are always limited together, so the image doesn’t wander when one side is loud. A mono source is limited on its own channel.
Patches. Catch The Peaks, Delivery Ceiling and Loud (True Peak) turn True Peak on, and an ESP32-S3 can’t keep up with them: both stages with True Peak on were measured at 6.550 ms of work in a 5.333 ms block, and the sound breaks up. Play Delivery Ceiling - lean there instead. It keeps Delivery Ceiling’s lookahead and release, turns True Peak off and sits 3 dB lower, and a worst-phase tone driven 6 dB into it stays under -0.94 dB even between the samples.
Latency is the lookahead, and so is the tail. It needs
audiodynamics, so a stock CircuitPython board can’t run it.- NAME = 'Limiter'
The stable provider name
audioeffects.create()discovers.
- TIER = 'audiodsp'
STOCK or AUDIODSP, with REQUIRES naming the audiodsp-own modules an AUDIODSP class needs.
- Type:
roadmap §3
- CAPABILITIES = ()
A ceiling has no tempo. The class never reads
self._transport().
- LATENCY_SAMPLES = 0
the lookahead is a macro. The class attributes are the default patch’s values, and the properties below report what this instance is actually set to.
- Type:
Both are per instance, not per class
- MACRO_LABELS = ('Ceiling', 'Gain', 'Lookahead', 'Release', 'True Peak', 'Knee')
Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.
- BRICKWALL_RATIO = 1000000.0
DYN_LIMIThas no knee term in its gain computer at all (audiodsp_dynamics.c:369-370), so the Knee macro rides aDYN_COMPRESSnode instead, at a ratio high enough that Knee 0 measures 0.0000 dB/dB of slope above the threshold - a brickwall by measurement, not by mode name. It is a class attribute and not a module constant so that L6’s fault of the same kind - a limiting law with a finite ratio - can be planted as a subclass and shown to be a state no macro and no patch of this class can reach.
- TRUE_PEAK_OVERSAMPLED = 2
The 4x true-peak level.
Truestill means the node’s older half-band estimate, which is why this is a number here and not a flag.
- TRUE_PEAK_RESERVE_SAMPLES = 12
The true-peak reserve, in samples, and why it is a sample count and not a millisecond figure. The node’s 4x detector reads a 12-tap polyphase window (
AUDIODSP_DYNAMICS_TP_TAPS,audiodsp_dynamics.h:51;oversampled_peak,audiodsp_dynamics.c:349-357), so the inter-sample peak it names at sample n happened about five and a half samples earlier. A gain computed from that number can only be applied to audio at least that far behind the detector - with no delay in the catch stage the peak has already left the node, which is why a true-peak ceiling with no lookahead is a sample-peak ceiling however the toggle is set (measured: +2.22 dB TP onramp_fs, evidence L1). Twelve samples is one whole window, and it is taken out of the Lookahead macro rather than added to it, solatency_samplesis still exactly what the macro asks for. Planting0here is L1’s fault of the same kind.
- property latency_samples
The lookahead, in samples: 0 unless the Lookahead macro has been moved off zero.
- property tail_samples
The same number. The only thing this class holds after its input goes silent is whatever is still in the lookahead delay; there is no reverberant or feedback state anywhere in it.