audioeffects.multibandcompressor
MultibandCompressor - split-band compression, two or three bands.
The player’s text is the class docstring; the CLAIMS table in the class’s
test file ties its claim sentences to tests.
- audioeffects.multibandcompressor.MIN_CROSSOVER_RATIO = 8.0
How close the two crossovers may get, at three bands. The parallel three-way’s worst deviation is a function of this ratio and of nothing else: measured on these nodes, 0.19 dB at 8:1, 0.99 dB at 4:1 and 7.96 dB at 2:1, against a trait that allows 0.25 dB.
- class audioeffects.multibandcompressor.MultibandCompressor(source, *options, **keywords)[source]
Bases:
ComponentSplit-band compression: the mix split into two or three bands, each with its own compressor, then summed back flat. Use it when one compressor on the whole mix lets the bass pump everything else.
Bands. Build it with
bands=2orbands=3; nothing else is accepted. The splits are Crossover Low and Crossover High. Crossover High is held at least eight times Crossover Low: ask for less and it moves up rather than refusing, andcrossover_high_hzreports where it landed. At two bands the split is at Crossover Low, the upper band uses the High macros, and Crossover High and the three Mid macros do nothing, whichmacro_is_live()reports.Flat at rest. With every Ratio at 1 the bands sum to within 0.25 dB of the input from 30 Hz to 16 kHz, at two bands and at three. Each band alone is 6 dB down at its corner, within 0.5 dB.
Each band. The bands have a Threshold, a Ratio and a Gain apiece, and Attack and Release are shared across the bands. Driving one band to 12 dB of reduction moves the middle of that band by 12 dB, within 0.5 dB, and the other bands by under 0.5 dB. Towards its own corners a band compresses less than you dialled, so dial the number you want for the middle of the band. The Effect controls page lists what the knobs span and the patches.
Mix. Mix crossfades the input with the summed bands, so between its stops it is parallel compression. Mix 0 is the source byte for byte, at 22.05 kHz, 44.1 kHz and 48 kHz, mono and stereo, and moving off it does not click. Brought back up from 0, it starts as it was built rather than playing what the bands held. Keep the input under -9 dBFS and the defaults and patches stay off the rails. A band’s Gain at its top can still push the output onto the rails.
Latency and tail. It adds no latency at any setting. The tail reaches exact zero, and
tail_samplessays when.Patches. Master Glue is the constructor’s defaults.
Boards. At three bands its costliest patch was measured at 54 % of a block on an ESP32-P4 and 107 % on an ESP32-S3, so the S3 can’t keep up. Built with
bands=2it was 34 % and 71 %, so on an S3 build it that way. It needsaudiobiquad,audiodynamicsandaudioroute, so a stock CircuitPython board can’t run it.- LAZY_BUILD = True
Construction arms the voices on silence (
Component._play_voice), so a Mix 0 set before the first pull hands out the source whole.
- NAME = 'MultibandCompressor'
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 = ()
No band’s behaviour refers to tempo, so the transport is never read (dossier App. I, D10).
- LATENCY_SAMPLES = 0
an IIR crossover rotates phase, it does not delay onset, and no detector here looks ahead.
- Type:
Zero at every setting
- TAIL_SAMPLES = 0
Overridden as a property below - the ring-down is the lower crossover’s, so it depends on the rate and on where that macro is.
After a reset, a rejoin or a control move the detectors can leave the output under 16 LSB from an untouched copy for up to three blocks, which
tail_samplesdoes not bound. See “Detector and coupling state” in docs/reference/component-api.md.
- INPUT_CEILING_DBFS = -9
The defaults and every patch play the ceiling kit’s materials clean at this level; at -6 dBFS, patch 3 rails on a 147 Hz square.
- CLIPS_AT_TOP = (8, 9, 10)
the rail check skips them.
- Type:
Settings that clip by design
- MACRO_LABELS = ('Crossover Low', 'Crossover High', 'Low Threshold', 'Mid Threshold', 'High Threshold', 'Low Ratio', 'Mid Ratio', 'High Ratio', 'Low Gain', 'Mid Gain', 'High Gain', 'Attack', 'Release', 'Mix')
Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.
- PATCHES = {0: ('Master Glue', (68, 51, 89, 89, 89, 47, 47, 47, 64, 64, 64, 85, 82, 127)), 1: ('Bass Control', (47, 51, 76, 127, 127, 59, 0, 0, 64, 64, 64, 97, 88, 127)), 2: ('Vocal Bus', (78, 73, 85, 93, 89, 39, 39, 39, 64, 64, 64, 92, 76, 127)), 3: ('De-Boom', (34, 51, 64, 127, 127, 76, 0, 0, 64, 64, 64, 72, 94, 127)), 4: ('Loudness', (68, 51, 76, 76, 76, 29, 29, 29, 79, 71, 79, 85, 88, 76))}
Patch 0 is the constructor’s defaults on the 0-127 grid, to the nearest grid point. A BIPOLAR gain of exactly 0 dB is MIDI 64 exactly since audiocomponents#87 – it used to sit at 63.5, unreachable, and 64 stood for 0.09 dB.
tests/test_cpython_effects_multiband.pyholds the table to that, span by span, rather than to a hand-copied list.
- WALKS_TO_BYPASS = True
A class sets this when its graph, at Mix 0, walks to the source it routes around: its mixer levels to the dry alone, on ramped mixers (
ramp_levels)._route_aroundthen lets the port switch once the walk has landed rather than at once. Mix 0 is still the source, byte for byte, from then on.
- reset()[source]
Clear every node and restore patch 0, then hand the voices their sources at patch 0’s levels, as
_builddoes. The walk used to re-play them at the outgoing patch’s levels, before patch 0 went in, so the levels moved after the gates had opened and landed late, a few LSB (up to 70 here) off a fresh instance for the first blocks.
- property bands
2 or 3, as the constructor was asked for. It is not a macro: see the class docstring.
- property crossover_low_hz
The lower corner actually applied, after the Nyquist clamp.
- property crossover_high_hz
The upper corner actually applied, after the eight-to-one clamp and the Nyquist clamp;
Noneat two bands, where there is no upper crossover. It can sit above the Crossover High macro’s own value - that is the clamp doing its job, andmacro(1)still reports what was asked for.
- property tail_samples
How long the crossover rings, in samples at this rate.
The only memory in this class is the biquads’: the detectors hold an envelope and no audio, and neither the Mixer nor the Splitter holds a line. The lowest corner is the slowest, and a float recursion flushed to zero below 1e-20 really does arrive - measured, one LR4 half at 40 Hz rings for 2.90 periods of its corner and one at 100 Hz for 2.88, from a full-scale DC burst.
- audioeffects.multibandcompressor.audiomixer_mixer(rate, channels, voices)[source]
The summing node, imported at call time.
audiomixeris a ported CircuitPython module and is on every build this library runs on, so it is not inREQUIRES; it is imported here rather than at module level only to keep the guarded audiodsp imports together at the top.