Source code for audioeffects.multibandcompressor

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""`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.
"""

# Design notes, from the rebuild.
#
# Split-band compression: a crossover, one compressor per band, one sum.
#
# There is no unit behind this class. Split-band compression is a *topology* -
# RaneNote 155 draws it as a general variation on the compressor (Fig. 7),
# "divides the incoming signal into two or more frequency bands ... After
# dynamics processing, the individual bands are re-combined into one signal" -
# and the crossover it needs is a published alignment, Linkwitz-Riley, whose two
# properties are "in-phase outputs (0 degrees between outputs) at all
# frequencies" and "the outputs sum to unity at all frequencies" (RaneNote 160).
#
# The topology, at three bands.
#
#     source -> guard -> Splitter(taps=4)
#                          tap 0  ------------------------------> dry  voice 0
#                          tap 1  LP LP ---------------> Dynamics low  voice 1
#                          tap 2  HP HP LP LP ---------> Dynamics mid  voice 2
#                          tap 3  HP HP ---------------> Dynamics high voice 3
#                                                               Mixer -> output
#
# Every crossover is LR4 - two cascaded Butterworth sections a side, Q =
# 0.7071 - which is why no band is polarity-inverted: RaneNote 160's rule is
# that LR-2 and LR-6 need an inversion and LR-4 and LR-8 do not.
#
# Three things this class had to measure rather than reason about.
#
# * The bands are `audiobiquad`, not `audiofilters`. A `synthio.Biquad`
#   cascade inside `audiofilters.Filter` keeps its state in Q12 sample units
#   and rounds to nearest with no dither, so the recursion has fixed points:
#   measured here, a 256-frame DC burst through a LOW_PASS pair holds 2 LSB
#   for ever at 100 Hz and 8 LSB at 40 Hz, while the same pair on
#   `audiobiquad.Biquad` reaches exact zero at frame 1895 and 3987. That is
#   audiodsp#23, and it is the Tier 1 invariant this family is held to first.
#   The dossier's section 4 mapped the ported node; the palette has had the
#   float one since Phase 1.
#
# * The sum is flat but it is not a wire. A Linkwitz-Riley network
#   "behaves like an all-pass": unity magnitude, rotating phase. So `Mix` at
#   zero is a real bypass and not "the bands, summed, which ought to be
#   the same thing". It is not the same thing, and the byte compare would say
#   so. Nor is the dry tap at unity enough: a mixer voice at level 1.0 scales
#   by 32768/32767 on every target (audiodsp#95), so `_refresh_output` hands
#   back the borrowed source itself and puts no node of this class's in the
#   path at all. Mix back up from 0 comes back as the class was built: the
#   crossover and detectors cleared, the voices re-armed. It used to play what
#   the bands held when Mix went to 0, up to 22 264 LSB out of silence
#   (audiocomponents#113).
#
# * How close the two crossovers may get. The three-way parallel split has
#   a floor that is a function of the crossover *ratio*, not of the
#   frequencies: measured on these nodes, the sum deviates by 0.19 dB at 8:1,
#   0.99 dB at 4:1 and 7.96 dB at 2:1. The upper crossover is therefore
#   clamped to at least eight times the lower one. It is a clamp and never a
#   refusal, in the shape the rate-honesty invariant asks for, and
#   `crossover_high_hz` reports what was actually applied.
#
# Latency: zero, at every setting, and nothing here can add any. The
# crossover is IIR and the detectors do not look ahead. `audiodynamics` offers
# a lookahead of up to 50 ms; this class does not expose it, because a
# multiband's job is the balance between bands and the ceiling belongs to
# `Limiter`, which is built on that lookahead and reports it.
#
# One thing the dossier asked for that this class does not deliver, and it
# is arithmetic rather than a bug. M3 asks that driving one band to 12 dB of
# reduction move that band's whole passband by 12 dB within half a decibel.
# No band does it, and no crossover-plus-compressor can. A band's own
# skirt takes it below unity towards its corners, and a fixed threshold then
# buys `(1 - 1/ratio)` of that shortfall less reduction there. Measured at
# 200/2000 Hz, ratio 4, soloed, each band read across its own passband, out
# to its own -6 dB corners:
#
#     band   window        per-tone reduction        mean      tilt
#     low    30..141 Hz    -12.51 .. -10.69 dB      -11.91    1.82 dB
#     mid    283..1414     -11.89 .. -10.58         -11.27    1.31 dB
#     high   2828..16000   -12.01 .. -10.58         -11.64    1.42 dB
#
# against a 0.5 dB bar on both the depth and the tilt. The arithmetic is exact
# for the mid band: its window edges sit 1.75 dB below its own peak, and
# `(1 - 1/4) x 1.75 = 1.31`. At the -6 dB corner itself the band is 6 dB down
# and the shortfall is 4.5 dB.
#
# The low band carries a second effect on top of that one. Below about 50 Hz
# the RMS detector's 10 ms window is shorter than one period of the tone, so
# its envelope ripples and the gain follows it: lengthening the window to
# 30 ms takes the low band's tilt from 1.82 to 1.58 dB, which is the
# control that separates the two causes.
#
# An earlier window sat an octave inside each corner - 400 to 1000 Hz of the
# mid band's 200 to 2000, 1.3 of its 3.3 octaves - and reported 0.73 / 0.27 /
# 0.37 dB. That is where the "within 0.25 dB" this docstring used to claim
# came from. The window was chosen after the trait was frozen; the table above
# is the trait's own words, and M3's depth and evenness clauses are
# disconfirmed in the evidence pack, with this cause.
#
# What *does* hold is the clause the name is about: driving any band moves no
# other band - 0.00 dB on a soloed read, 0.30 dB worst on the harder
# read, the summed output with nothing muted. In practice a band compresses to
# the number you dial in the middle of its range and about a decibel less than
# that at its edges.
#
# Two bands or three is a constructor option, not a knob. `bands=2` builds
# one crossover, four biquads and two detectors; `bands=3` builds two, eight and
# three. A knob that muted the middle band would still pay for it every block -
# the Mixer pulls a voice at level 0 exactly as hard as one at unity - so the
# cheap build has to be a different build. At two bands the split is at
# Crossover Low, the upper band is the High macros, and Crossover High and
# the three Mid macros are inert; the class says so in `macro_is_live()`.
#
# The class docstring before the player's text, kept for its figures. Its
# node and pull counts count the graph differently from `_nodes`.
#
# Two or three bands, each with its own compressor, summed back flat.
#
# `audiodsp` tier: `audiobiquad` for a crossover whose tail reaches exact
# zero, `audiodynamics` for the per-band detectors, `audioroute` for the
# fan-out.
#
# What it is for. One compressor on a full mix is a compressor the bass
# drives: every kick pumps the vocal. Splitting the band first gives the
# low end its own threshold and leaves the rest of the mix where it was.
# Patch 1 ("Bass Control") is that, at its plainest - the low band working
# and the others idle.
#
# Flat at rest, to a fraction of a decibel, and measured. Every band at
# unity, 30 Hz to 20 kHz: +0.001 / -0.119 dB at the 200/2000 Hz split
# and +0.000 / -0.000 dB at two bands. The three-band floor is the
# topology's own - the low band never passes through the upper crossover's
# all-pass - and it is why the two crossovers are held eight to one apart.
#
# Bands do not bleed into each other: driving any one band to 12 dB of
# reduction moves the others by 0.00 dB soloed and at worst 0.30 dB on
# the summed output. The driven band does not move evenly, and no
# band does: across its own passband, out to its own -6 dB corners, the
# reduction tilts 1.82 dB (low), 1.31 dB (mid) and 1.42 dB
# (high) against a 0.5 dB bar, and the mean lands 0.09 / 0.73 / 0.36 dB
# short of the 12 asked for. That is the band's own skirt against a fixed
# threshold - `(1 - 1/ratio)` of the shortfall at each tone - and the
# module docstring has the arithmetic. Dial the number you want in the
# middle of a band and expect about a decibel less at its edges.
#
# `Mix` at zero is a true bypass, byte-identical to the source,
# because a Linkwitz-Riley network at unity is an all-pass and not a wire.
# There is no mixer in the path there - `output` is the class's input
# node, a `Filter` with no filter, which is a copy - because a mixer voice
# at level 1.0 is not unity on any target: upstream's Q15 level is
# `1.0 * 32768` and the kernel then divides by 32767, so every sample at
# or above 32736 comes out one LSB larger (audiodsp#95). Through the dry
# voice this class's Mix 0 differed from its source on 15 of 32768 samples
# of a full-scale ramp; it is now exact at 22.05, 44.1 and 48 kHz, mono
# and stereo, on all three interpreters. In between, Mix is parallel
# compression: the dry tap and the summed bands, crossfaded.
#
# Latency 0 at every setting, and no option here can add any. The
# crossover is IIR; the detectors do not look ahead.
#
# On an ESP32-S3, build it with `bands=2`. At three bands no patch
# keeps up there and the sound breaks up; at two bands it does, with the
# split at Crossover Low and the Mid macros idle. No patch can stand in
# for this: every macro position builds the same graph.
#
# Cost. This is the most expensive class in the Dynamics family.
# Measured in October 2026, its costliest patch (Loudness; all five sit
# within 0.2 ms of each other) takes 54.0 % of a 256-frame stereo block
# on an ESP32-P4 and 107.0 % on an ESP32-S3, so the S3 cannot run it in
# real time; built with `bands=2` it is 34.2 % and 71.1 %. At three
# bands it owns 18 nodes, eight of them biquads,
# and pulls 72 of them per eight blocks; `bands=2` is the cheaper build
# at 12 nodes and 48 pulls - four biquads, two detectors, three mixer
# voices - and on the desktop it measured between 75 % and 79 % of the
# three-band cost over three runs on a loaded host.
#
# There is no lean patch and there cannot be one. Every macro
# position and every shipped patch was walked - 243 of them - and the
# graph is the same 18 nodes and 72 pulls at all of them, because the
# Mixer pulls a voice at level 0 exactly as hard as one at unity. The one
# position that is not is Mix 0, where `output` is the source and
# nothing this class owns is pulled at all; no shipped patch sits there.
# Only the constructor can make a *working* instance cheaper.

VENDOR = "PyDevices"

from array import array

from . import _component

try:
    import audiobiquad
except ImportError:      # a stock CircuitPython board, or an old audiodsp
    audiobiquad = None
try:
    import audiodynamics
except ImportError:
    audiodynamics = None
try:
    import audioroute
except ImportError:
    audioroute = None

import audiocore
import audiofilters


#: Butterworth Q. Two sections at this Q cascaded is one LR4 half, which is
#: the alignment whose two halves sum to unity with no polarity inversion
#: (RaneNote 160: "LR-2 and LR-6 need inverting, while LR-4 and LR-8 do not").
_BUTTERWORTH_Q = 0.7071067811865475

#: 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.
MIN_CROSSOVER_RATIO = 8.0

#: The tail of one LR4 half, in periods of its corner frequency, measured on
#: `audiobiquad.Biquad` from a full-scale DC burst to the last non-zero
#: sample. The float state decays geometrically and is flushed to exact zero
#: below 1e-20, so this is a real number and not an asymptote; the margin
#: above the measured 2.90 is there because `tail_samples` may be long but
#: may never be short.
_TAIL_PERIODS = 3.6

#: Frames the guard hands back in one call. 256 is what every other node on
#: the palette hands out, so the graph runs in one block size. It used to
#: have to be at or under the Splitter's 8192-frame ring as well; since
#: audiodsp#87 the Splitter takes any call in pieces and that clause is gone.
_GUARD_FRAMES = 256


[docs] class MultibandCompressor(_component.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. """ #: Construction arms the voices on silence (`Component._play_voice`), #: so a Mix 0 set before the first pull hands out the source whole. LAZY_BUILD = True NAME = 'MultibandCompressor' DISPLAY_NAME = 'Multiband Compressor' CATEGORIES = ('Dynamics',) VERSION = '0.1.0' TIER = _component.AUDIODSP REQUIRES = ("audiobiquad", "audiodynamics", "audioroute") #: No band's behaviour refers to tempo, so the transport is never read #: (dossier App. I, D10). CAPABILITIES = () #: Zero at every setting: an IIR crossover rotates phase, it does not #: delay onset, and no detector here looks ahead. LATENCY_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. TAIL_SAMPLES = 0 #: 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. INPUT_CEILING_DBFS = -9 #: Settings that clip by design: the rail check skips them. CLIPS_AT_TOP = (8, 9, 10) 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", ) MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR", 7: "UNIPOLAR", 8: "BIPOLAR", 9: "BIPOLAR", 10: "BIPOLAR", 11: "UNIPOLAR", 12: "UNIPOLAR", 13: "UNIPOLAR", } _MACRO_RANGES = ( (40.0, 800.0, "log"), (800.0, 8000.0, "log"), (-60.0, 0.0), (-60.0, 0.0), (-60.0, 0.0), (1.0, 20.0, "log"), (1.0, 20.0, "log"), (1.0, 20.0, "log"), (-12.0, 12.0), (-12.0, 12.0), (-12.0, 12.0), (0.1, 100.0, "log"), (5.0, 1000.0, "log"), (0.0, 1.0), ) _MACRO_UNITS = { 0: "Hz", 1: "Hz", 2: "dBFS", 3: "dBFS", 4: "dBFS", 8: "dB", 9: "dB", 10: "dB", 11: "ms", 12: "ms", } #: 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. 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)), } #: Which macros do something at each band count. At two bands there is no #: middle band and no upper crossover, and a host that greys a control #: out reads this rather than guessing from the label. _LIVE_AT_TWO = (0, 2, 4, 5, 7, 8, 10, 11, 12, 13) # -- construction -------------------------------------------------- def _build(self, bands=3, crossover_low_hz=200.0, crossover_high_hz=2000.0, low_threshold_db=-18.0, mid_threshold_db=-18.0, high_threshold_db=-18.0, low_ratio=3.0, mid_ratio=3.0, high_ratio=3.0, low_gain_db=0.0, mid_gain_db=0.0, high_gain_db=0.0, attack_ms=10.0, release_ms=150.0, mix=1.0, patch=None): """`bands` is 2 or 3 and fixes the topology; everything else is a macro. Nothing here adds latency at any setting, so there is no millisecond figure to name: `latency_samples` is 0 for the life of the instance.""" if bands not in (2, 3): raise ValueError("bands must be 2 or 3, not %r" % (bands,)) self._bands = bands self._low_hz = 0.0 self._high_hz = 0.0 #: Where Mix is, whether the band voices are on their sources, and #: whether the graph is wired up at all yet. `_refresh_output` reads #: all three and is a no-op until `_build` says so. self._mix = 1.0 self._primed = False self._ready = False rate = self._sample_rate channels = self._channel_count #: What the Splitter pulls from, and what `Mix` 0 hands back. self._head = head = self._build_input() taps = bands + 1 #: `reset=False`: `audioroute.Splitter` is a container, not an #: `audiosample`, and has no `reset_buffer`. After a reset every #: cursor is still at `write_pos`, so the audio left in the ring is #: behind every reader and is never heard. It does have `deinit()` #: since audiodsp#58, and releasing it releases the taps owned below; #: on an audiodsp without one, `getattr` skips the call. self._split = self._own(audioroute.Splitter(head, taps=taps), reset=False) self._taps = [self._own(self._split.tap(index)) for index in range(taps)] #: Owned **first**, so the reverse walk resets it **last**, and this #: is not a style choice. `audiomixer`'s reset does not only clear a #: voice: it resets that voice's source and then pulls a fresh chunk #: through it (`audiomixer/MixerVoice.c:97`, and the CPython shim's #: `MixerVoice.reset` line for line). Reset tail-first, as everything #: else here is, and that pull runs through eight biquads that have #: not been cleared yet and lands their ring-down in the voice's own #: buffer, where nothing later in the walk can reach it: measured, #: 4775 LSB from the low band and 2985 from the mid, gone after a #: second `reset()`. Reset last and the chunk it pulls comes through #: filters that are already silent. self._mixer = self._own(audiomixer_mixer(rate, channels, taps), reset=self._reset_mixer) #: The silence `_play_voices` opens the mixer's level gates on. It #: holds no state, so it declines its own reset. self._silence = self._own(audiocore.RawSample( array("h", bytes(2 * 2 * channels)), sample_rate=rate, channel_count=channels), reset=False) self._sections = [] self._detectors = [] for band in range(bands): chain = self._band_chain(band) detector = self._own(audiodynamics.Dynamics( audiodynamics.DYN_COMPRESS, sample_rate=rate, channel_count=channels, detector="rms", attack_ms=attack_ms, release_ms=release_ms)) detector.play(chain) self._detectors.append(detector) self._output = self._mixer self._init_macros( (crossover_low_hz, crossover_high_hz, low_threshold_db, mid_threshold_db, high_threshold_db, low_ratio, mid_ratio, high_ratio, low_gain_db, mid_gain_db, high_gain_db, attack_ms, release_ms, mix), patch) #: The voices are played **after** the macros, and that ordering is a #: measurement. `MixerVoice.play` resets its new source and pulls a #: chunk from it on the spot (`audiomixer/MixerVoice.c:75-79`), so a #: voice played before `_init_macros` holds 256 frames rendered #: through eight biquads still sitting at their construction #: frequency of 1 kHz. That is the head of every render, on every #: instance, and no macro move can reach it afterwards. self._play_voices() self._ready = True self._refresh_output() def _build_input(self): """The node the Splitter pulls from, which is never the source. **This guard no longer guards anything.** It was built because the Splitter wrote whatever its immediate source handed back in one call into an 8192-frame ring and dragged every cursor past it, so a whole-buffer source - `audiocore.RawSample` hands its entire array back in one `get_buffer` - lost the first n - 8192 frames of it. Since audiodsp#87 the Splitter takes a call bigger than its ring in pieces, and the head arrives. Measured at audiodsp `977ef26`: the class renders the same bytes with this node and without it, at every source block from 256 to 32768 frames, and burst material survives unguarded (`tests/test_cpython_effects_multiband.py`, `test_m5_the_guard_no_longer_changes_the_render`). It is kept for now, not because it is needed, but because dropping a node changes the graph a shipped class was costed on and the board rows cannot be re-taken until the P4 and S3 are plugged in. It is a `Filter` with no filter, which is a copy, and it is the cheapest node on the palette. It is still its own method because it is the seam the `NoGuard` fixture cuts - which is now the *equality* test above, not a fault. M5's live fault is a source that keeps only its last ring. """ self._guard = self._own(audiofilters.Filter( filter=None, mix=1, buffer_size=_GUARD_FRAMES * self._channel_count * 2, sample_rate=self._sample_rate, channel_count=self._channel_count, bits_per_sample=16, samples_signed=True)) self._guard.play(self._source, loop=False) return self._guard def _band_modes(self, band): """The biquad modes for one band, low to high. Two sections a side is LR4, which is the alignment that needs no polarity inversion. One a side is LR2, which does - and which is the M2 planted fault, cut at this method. """ low_pass = audiobiquad.LOW_PASS high_pass = audiobiquad.HIGH_PASS if band == 0: return (low_pass, low_pass) if band == self._bands - 1: return (high_pass, high_pass) return (high_pass, high_pass, low_pass, low_pass) def _band_chain(self, band): """The biquad cascade for one band, played off its own tap. Band 0 is LP4 at the lower corner; the last band is HP4 at the upper one; the middle band, when there is one, is HP4 at the lower corner into LP4 at the upper. Every section is created here and re-tuned in place by `_apply_crossovers`, so a crossover move allocates nothing. """ modes = self._band_modes(band) node = self._taps[band + 1] built = [] for mode in modes: section = self._own(audiobiquad.Biquad( mode=mode, frequency=1000.0, Q=_BUTTERWORTH_Q, sample_rate=self._sample_rate, channel_count=self._channel_count)) section.play(node) built.append(section) node = section self._sections.append(built) return node def _play_voices(self): """Hand every voice its source. Also the second half of `reset()`. The gates open first, on one block of silence, so the dry voice is at unity from its first sample (`_component.open_level_gates`); without it a Mix 0 bypass rendered its first 256 frames silent on a ramp. This runs after the macros, so the levels it opens at are the ones the class was built with. **At Mix 0 the voices are left on that silence.** `_refresh_output` hands the bypass back off `self._head`, and a voice playing tap 0 would drag a block of the head through the Splitter on `play()` alone (`MixerVoice.play` fetches there and then) - so the bypass would start one block in. Leaving them silent also means the whole graph behind this mixer is never pulled while Mix is 0. """ _component.open_level_gates( self._mixer, [self._mixer.voice[index] for index in range(self._bands + 1)], self._silence) if self._mix <= 0.0: self._primed = False return self._play_voice(self._mixer.voice[0], self._taps[0], loop=True) for band in range(self._bands): self._play_voice(self._mixer.voice[band + 1], self._detectors[band], loop=True) self._primed = True WALKS_TO_BYPASS = True
[docs] def reset(self): """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.""" self._resetting = True try: self._reset_rearmed(self._refresh_output, ("_primed",)) finally: self._resetting = False
def _reset_mixer(self): """Clear the Mixer, then hand its voices back their sources. `audiodsp`'s `audiomixer` rewinds a voice on reset; **upstream CircuitPython's stops it**, and a stopped voice never plays again (audiodsp's `docs/upstream-diff.md`, "Resetting a Mixer silenced it, permanently"). audiodsp fixed that in its own copy, so a class that only calls `reset_buffer` here works on this port and is silent for ever after its first `reset()` on a stock board -- measured on `bin/circuitpython-effects`, where `voice[0].playing` is `False` after the reset and the render is zeros from there on. Re-playing is what the fixed node does anyway: `play()` rewinds the source and takes a chunk. Because the Mixer is owned first and so walked last, that chunk comes through nodes this reset has already cleared. """ if getattr(self, "_resetting", False): # `reset()` stops the voices and plays them once the patch is in # (`_reset_rearmed`). A host reset of CircuitPython's stock # Mixer here reached the voices' sources and cost the reset a # block of the source, as it did Saturation's. return audiocore.reset_buffer(self._mixer) self._play_voices() # -- the live surface --------------------------------------------- @property def bands(self): """2 or 3, as the constructor was asked for. It is not a macro: see the class docstring.""" self._check_live() return self._bands @property def crossover_low_hz(self): """The lower corner actually applied, after the Nyquist clamp.""" self._check_live() return self._low_hz @property def crossover_high_hz(self): """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.""" self._check_live() return self._high_hz if self._bands == 3 else None @property def tail_samples(self): """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. """ self._check_live() return int(_TAIL_PERIODS * self._sample_rate / self._low_hz) + 1
[docs] def macro_is_live(self, index): """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.""" self._check_live() self._macro_index(index) return self._bands == 3 or index in self._LIVE_AT_TWO
# -- macros -------------------------------------------------------- def _apply_macro(self, index, position): if index <= 1: self._apply_crossovers() elif index <= 4: self._set_band(index - 2, threshold_db=self.macro(index)) elif index <= 7: self._set_band(index - 5, ratio=self.macro(index)) elif index <= 10: self._set_band(index - 8, makeup_db=self.macro(index)) elif index == 11: for detector in self._detectors: detector.set(attack_ms=self.macro(11)) elif index == 12: for detector in self._detectors: detector.set(release_ms=self.macro(12)) else: self._apply_mix(_component.macro_value(self._MACRO_RANGES[13], position)) def _set_band(self, band, **options): """A per-band setting. `band` is the macro's band - 0 low, 1 mid, 2 high - which is the detector's index only at three bands. At two there is no middle band and the Mid macros land nowhere.""" if self._bands == 3: target = band elif band == 1: return else: target = 0 if band == 0 else 1 self._detectors[target].set(**options) def _apply_crossovers(self): """Re-tune every section in place, with the ratio clamp applied. The lower corner is authoritative and the upper one is pushed up to meet it, rather than the two arguing: a mutual clamp has no defined answer when both macros move. Neither is ever refused - a corner above the running rate's usable band becomes the highest that rate has, which is the rate-honesty invariant's shape. """ self._low_hz = self._hz(self.macro(0)) if self._bands == 2: self._high_hz = self._low_hz self._tune(0, (self._low_hz, self._low_hz)) self._tune(1, (self._low_hz, self._low_hz)) return wanted = self._hz(self.macro(1)) floor = self._hz(self._low_hz * MIN_CROSSOVER_RATIO) self._high_hz = wanted if wanted > floor else floor self._tune(0, (self._low_hz, self._low_hz)) self._tune(1, (self._low_hz, self._low_hz, self._high_hz, self._high_hz)) self._tune(2, (self._high_hz, self._high_hz)) def _tune(self, band, frequencies): """Re-tune one band's cascade. `frequencies` names one corner per LR4 section; a build with fewer sections a side (the M2 fault) takes them in the same order, which is why this walks the sections and not the list. """ sections = self._sections[band] wanted = list(frequencies) while len(wanted) > len(sections): del wanted[len(wanted) // 2] for index in range(len(sections)): sections[index].frequency = wanted[index] def _apply_mix(self, mix): """Dry against the summed bands. At 0 this is the whole bypass: the band voices contribute exactly nothing and the dry tap is at unity, which is a byte compare against the source and not a claim about the sum being flat.""" self._mix = mix self._mixer.voice[0].level = 1.0 - mix for band in range(self._bands): self._mixer.voice[band + 1].level = mix self._refresh_output() def _refresh_output(self): """At Mix 0 the output is the class's input, not a path through it. A mixer voice at level 1.0 is not unity: upstream's Q15 level is `1.0 * 32768` and the kernel divides by 32767, so on a stereo mixer the right channel - and on a mono one both - comes out one LSB larger at every sample from 32736 up (audiodsp#95). Through the dry voice this class's Mix 0 differed from its source on 15 of 32768 samples of a full-scale ramp. So Mix 0 puts no mixer in the path at all, which is the answer `Fuzz` and `Overdrive` already give. **What is handed back is `self._head`, not `self._source`, and the difference is one node wide.** `_build_input`'s guard is an `audiofilters.Filter`, and `Filter.play()` resets its source and fetches a block from it on the spot - so by the end of construction the first 256 frames of the source are inside the guard. Handing back the source would start the bypass 256 frames in; handing back the guard hands back those frames, and the guard is a `Filter` with no filter, which is a copy: measured bit-exact against a full-scale ramp on all three interpreters, at both channel counts. It is also the node the Splitter reads, so a Mix move off 0 picks the graph up at exactly the sample the bypass stopped on. `NoGuard` sets `_head` to the source itself, and there the bypass *is* the borrowed source, which is what audiodsp#87 finally allows. Coming back off 0, the voices are handed their sources with the level gates opened first. Since CircuitPython 10.3.0 a voice takes a level change only at a zero crossing and a freshly played one starts at zero, so without that block of silence the first frames after the move would be silent and the level would step in at the block boundary - which is the click this avoids (`_component.open_level_gates`). `_apply_mix` sets the levels before it calls here, so the gates open at the levels Mix just asked for. """ if not self._ready: return if self._mix <= 0.0: self._route_around(self._head) return # Back off the bypass, the crossover and the detectors still hold # what they held when Mix went to 0, and each voice the block it had # queued. Cleared, then the voices re-played once through the # cleared nodes, as `_build` does (audiocomponents#113). The guard # is the bypass's own node and still live, so it is kept; the mixer # is kept out of the walk because its registered reset re-plays the # voices twice over. if self._rejoin(keep=(self._head, self._mixer)): self._primed = False if not self._primed: # Off a walked bypass the mixer walks in from the dry alone. voices = self._mixer.voice self._rearm_from( [(voices[0], 1.0)] + [(voices[band + 1], 0.0) for band in range(self._bands)], self._play_voices) self._output = self._mixer
[docs] def audiomixer_mixer(rate, channels, voices): """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. """ import audiomixer return _component.ramp_levels( audiomixer.Mixer(voice_count=voices, sample_rate=rate, channel_count=channels, bits_per_sample=16, samples_signed=True), rate)