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: Component

Split-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=2 or bands=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, and crossover_high_hz reports 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, which macro_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_samples says 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=2 it was 34 % and 71 %, so on an S3 build it that way. It needs audiobiquad, audiodynamics and audioroute, 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_samples does 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.py holds 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_around then 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 _build does. 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; None at 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, and macro(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.

macro_is_live(index)[source]

Whether macro index does anything at this band count. Every macro is live at three bands; at two, Crossover High and the three Mid macros are not.

audioeffects.multibandcompressor.audiomixer_mixer(rate, channels, voices)[source]

The summing node, imported at call time.

audiomixer is a ported CircuitPython module and is on every build this library runs on, so it is not in REQUIRES; it is imported here rather than at module level only to keep the guarded audiodsp imports together at the top.