Source code for audioeffects.expander

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

"""`Expander` - a downward expander in the Drawmer DS201's shape.

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.
#
# What it is. Below the threshold the output falls `ratio` dB for every
# dB the input falls, down to a floor the Depth knob sets - so a quiet
# passage gets quieter without the door-slam of a gate. Above the threshold
# it is a wire. The side chain is a two-ended key band (12 dB/octave at each
# end, `sidechain_poles=2`), the detector is true RMS by default, and an
# external key stream may drive it instead of the audio.
#
# Portability tier: audiodsp. `audiodynamics` is audiodsp's own module and
# not a CircuitPython port (`audiodsp/docs/upstream-diff.md:661`), so the
# import below is guarded and construction raises `ImportError` on a stock
# CircuitPython board.
#
# Latency is zero, at every setting, and no option adds any. Neither
# source reached shows a delay element in the DS201's audio path, and
# RaneNote 155 puts look-ahead in the *gate*'s block diagram rather than the
# expander's - so this class ships no look-ahead option at all and there is
# no latency-adding option to name a millisecond figure for.
# `latency_samples` is 0; measured, an impulse comes back in the frame it
# arrived in. One delay is worth naming and is *not* latency: narrowing the
# key band slows the detector's response to a transient, which the DS201's
# own manual warns about. That is a detector effect and is never reported in
# `latency_samples`.
#
# The tail is zero, except with Key Listen on. The gain is a per-sample
# multiply on the audio, so silence in is exactly zero out in the same frame
# however the envelope stands - measured on the kit's `burst_silence` probe,
# there is no non-zero sample after the burst at all, at any of the three
# rates. Key Listen is the exception: it puts the *side chain's* signal on the
# output instead of the audio, and the key filters have memory, measured on
# that probe at 2373 / 2180 / 1089 frames at 48 / 44.1 / 22.05 kHz with Key Low
# at its minimum. With Key Listen on, `tail_samples` is a bound on that ring
# that follows Key Low, Key High and the rate (at most about 5 100 frames at
# 48 kHz, with Key Low at its minimum); with it off it is 0. Key Listen is
# off in every patch.
#
# Two wire states, both byte-identical to the source: Ratio at 1.0, where
# the gain computer's `over x (ratio - 1)` is zero, and Depth at 0 dB, where the
# floor is zero. Measured, worst 0 LSB on a full-scale ramp.
#
# The ratio law is the RMS detector's, and the Detector toggle changes it.
# With `detector="rms"` - the default, and what five of the seven patches use -
# the slope tracks the set ratio to within 1.92 % anywhere on the Ratio and
# Threshold macros' travel. Put the Detector at *peak* and it does not: a peak
# follower rides each cycle of the waveform, so the gain is modulated inside the
# period and the settled slope falls short - measured -2.48 % at ratio 4,
# -7.52 % at ratio 8 against the trait's 5 % bar, and -29.33 % at patch
# 5 *Hard Downward*'s own shipped settings, whose worst point is 3.75 dB off the
# fitted line. Musically that is the difference between a downward expander and
# a soft, slightly gritty gate; it is what the peak position is *for*, and patch
# 5 is named for it. But the number in E1 is the RMS detector's, and nothing
# here claims the law at the other position.
#
# What it costs, and the one lever the panel has. Measured on the boards
# 2026-09-07: 8.4 % of a 5.333 ms stereo block on the ESP32-P4 and 16.3 % on
# the ESP32-S3, against dossier budgets of 6 % and 12 % - over both. The
# class is one node, so there are no bands, stages or nodes to drop and no
# oversampling to lower; the only cost lever a patch can reach is the Detector
# toggle, and patch 6 `Expander - lean` is patch 0 with it at peak. It is
# worth 5-8 % of the node's own per-frame work on the desktop, where the
# budget needs 26-29 %, so it does not bring the class inside the budget
# and it is not offered as if it did. It changes the sound: see the ratio-law
# paragraph above. The budget itself is under review for the whole phase
# (audiocomponents#48).
#
# Three things the dossier asked for that this class does not do, each
# measured rather than assumed, each with its number in the evidence pack:
#
# * No Hold, and no one-shot envelope (dossier E5). The node's
#   closed/attack/hold/decay machine is gated on `mode ==
#   AUDIODSP_DYNAMICS_GATE` (`audiodsp/src/shared/audiodsp_dynamics.c:452-453`)
#   and *replaces* the gain computer with a binary open/floor
#   (`:679-724`), so the ratio law and the one-shot envelope cannot both
#   exist in one node. `hold_ms` in `DYN_EXPAND` is silently inert -
#   measured, a 1 ms burst under a 200 ms attack renders the same trace with
#   and without it. An expander is the continuous law; `NoiseGate` is the
#   box with the trigger, and E5 is that class's to demonstrate.
# * The key band is 12 dB/octave, not a brick wall (dossier E3). Two
#   poles at each end reject about 25 dB two octaves outside the band, so a
#   loud out-of-band tone *will* open the expander. E3 as the dossier states
#   it - the gain held at its floor for an out-of-band tone all the way to
#   0 dBFS - would need better than 40 dB an octave out, which is an
#   eighth-order key filter no hardware gate carries.
# * The knob times are one-pole time constants (dossier E6), not
#   10-90 % times. `attack_ms` and `release_ms` are the follower's tau; the
#   10-90 % time of the gain-in-dB trace depends on the size of the level
#   step as well as on the setting.
#
# The detector's own window. With `detector="rms"` the level is a
# one-pole mean square over a fixed 10 ms window (the node's unset default,
# `audiodsp_dynamics.c:77-82`). That window is what makes a sine and a square
# of equal RMS get the same gain, and it also puts a floor of its own order
# under the Attack knob. The Detector toggle's peak position removes both.
#
# But the detector reads the key *band*, not the signal, and that costs the
# RMS claim twice over. A sine and a square of equal RMS get the same gain only
# while the band is wide and the ratio moderate: measured at 1 kHz, 15 dB below
# a -6 dBFS threshold, the two are 0.09 dB apart at ratio 2 with Key High at
# the top of its span, 0.55 dB apart at ratio 4, and 0.74 dB apart at
# ratio 2 once Key High comes down to 3 kHz - because the low-pass strips the
# square's harmonics out of the detector and the gain computer multiplies what
# is left by (ratio - 1). Both `Snare Tighten` and `Guitar Amp Hum` narrow the
# band, so both are in that region. It is what a key filter is for and it is
# not a fault; it is a bound the evidence pack's E2 states and this docstring
# would be wrong to leave out.

VENDOR = "PyDevices"

from . import _component

import math

#: How long a two-pole key filter takes to ring from near full scale to
#: under half an LSB, in units of 1 / fc seconds: ln(65536 * 2) time
#: constants of 0.225 / fc each.
KEY_RING_CYCLES = 2.65

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


[docs] class Expander(_component.Component): """A downward expander in the Drawmer DS201's shape: below the threshold, quiet passages get quieter, by a ratio you set and down to a floor you set, without the slam of a gate. Above the threshold it is a wire. **Controls.** Threshold is where the expansion starts. Ratio is how many dB the output falls for every dB the input falls below the threshold; with the RMS detector the slope stays within 5 % of it even at 8. Depth is the floor: a quiet passage falls no further than that, to within 0.5 dB. Ratio 1 and Depth 0 are each a wire, byte for byte. Attack and Release set how fast the detector follows the level. The Effect controls page lists what the knobs span. **The key.** Key Low and Key High, the top just under Nyquist, narrow the band the detector hears, at 12 dB/octave at each end, so a loud tone outside the band can still open it. Key Listen puts that band on the output so you can hear what the detector hears. Pass `key=` another stream and the detector reads that instead of your signal, the DS201's external key. **Detector.** RMS, the default, gives a sine and a square of equal RMS the same gain, to within 0.1 dB at Ratio 2 with the band wide open. Peak rides each cycle of the waveform, so the slope falls short of the ratio and the expander turns into a soft, slightly gritty gate; the Hard Downward patch is built on it. **No hold.** There is no Hold and no one-shot envelope: the expander follows the level continuously. For a gate with a trigger, use `NoiseGate`. **Timing.** Latency is zero at every setting. So is the tail, except with Key Listen on, when the key filters ring on after your signal stops: `tail_samples` bounds that ring, under 6000 frames at 48 kHz. **On a board.** The class needs audiodsp's `audiodynamics`, and on a board without it construction raises `ImportError`. """ NAME = 'Expander' DISPLAY_NAME = 'Expander' CATEGORIES = ('Dynamics',) VERSION = '0.1.0' TIER = _component.AUDIODSP REQUIRES = ("audiodynamics",) #: Nothing in an expander's law refers to tempo, and neither source's #: unit has a tempo input (dossier App. I, D10). The transport is never #: read, so nothing is declared. CAPABILITIES = () #: No look-ahead, no delay line: the gain lands on the frame the #: detector read. Measured by CLICK at 48 kHz and 44.1 kHz. LATENCY_SAMPLES = 0 #: The VCA is a per-sample multiply on the audio, so silence in is #: exactly zero out in the same frame however the envelope stands. The #: Key Listen diagnostic is the one path with memory of its own, it is #: off in every patch, and `tail_samples` bounds its ring while it is on. TAIL_SAMPLES = 0 MACRO_LABELS = ("Threshold", "Ratio", "Depth", "Attack", "Release", "Key Low", "Key High", "Key Listen", "Detector") MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR", 6: "UNIPOLAR", 7: "TOGGLE", 8: "TOGGLE"} _MACRO_RANGES = ( (-80.0, 0.0), # Threshold, dBFS (1.0, 8.0, "log"), # Ratio (0.0, -80.0), # Depth, dB of floor (0.01, 1000.0, "log"), # Attack, ms (2.0, 4000.0, "log"), # Release, ms (25.0, 4000.0, "log"), # Key Low, Hz (250.0, 35000.0, "log"), # Key High, Hz - clamped below Nyquist (0.0, 1.0), # Key Listen (0.0, 1.0), # Detector: 0 peak, 1 RMS ) _MACRO_UNITS = {0: "dBFS", 2: "dB", 3: "ms", 4: "ms", 5: "Hz", 6: "Hz"} #: Patch 0 is the constructor's own defaults on the 0-127 grid. PATCHES = { # Threshold dB, Ratio, Depth dB, Attack ms, Release ms, # Key Low Hz, Key High Hz, Key Listen, Detector. 0: ("Gentle Lift", (70, 25, 32, 69, 77, 0, 127, 0, 127)), 1: ("Noise Floor Trim", (40, 56, 48, 58, 84, 0, 127, 0, 127)), 2: ("Snare Tighten", (87, 109, 40, 43, 62, 45, 89, 0, 127)), 3: ("Guitar Amp Hum", (56, 85, 64, 69, 81, 62, 71, 0, 127)), 4: ("Room Reduction", (71, 67, 24, 78, 100, 0, 127, 0, 127)), 5: ("Hard Downward", (79, 127, 95, 51, 68, 0, 127, 0, 0)), # Patch 0 with the cheaper detector - the only cost lever the # macro surface has, the key filters and the gain computer being # unconditional in the node's own loop. Worth 5-8 % of the node's # per-frame work on the desktop where the budget needs 26-29 %, so # it does not close G6; the evidence pack's section 4 has the A/B # and says so. Note it is NOT patch 0's sound: at peak the ratio # law is the one the docstring bounds above. 6: ("Expander - lean", (70, 25, 32, 69, 77, 0, 127, 0, 0)), } def _build(self, threshold_db=-36.0, ratio=1.5, depth_db=-20.0, attack_ms=5.0, release_ms=200.0, key_low_hz=25.0, key_high_hz=35000.0, key_listen=False, detector_rms=True, key=None, patch=None): """Build the one node this class owns. `key` is an optional second stream for the detector to read instead of the audio - the DS201's external Key input. It is borrowed, not owned: `reset()` and `deinit()` never touch it, exactly as they never touch `source`. A key that runs dry starves the node the way an absent source does (silence), which is the node's documented behaviour and not this class's. """ node = audiodynamics.Dynamics( audiodynamics.DYN_EXPAND, sample_rate=self._sample_rate, channel_count=self._channel_count, # 12 dB/octave at each end of the key band, which is what the # node ask (dossier N-EXP-2) specified for it. sidechain_poles=2, ) node.play(self._source) if key is not None: node.key(key) # `audiodynamics.Dynamics` has no `deinit`/`__enter__`/`__exit__` at # all (`audiodsp/docs/upstream-diff.md:711-714`), so the deinit walk # finds nothing to call on it; `reset` is `reset_buffer`, which # drops the detector envelopes and keeps the side-chain filter # memory on purpose (`:704`). self._own(node, reset=True, deinit=True) self._node = node self._output = node self._init_macros((threshold_db, ratio, depth_db, attack_ms, release_ms, key_low_hz, key_high_hz, 1.0 if key_listen else 0.0, 1.0 if detector_rms else 0.0), patch) def _apply_macro(self, index, position): value = _component.macro_value(self._MACRO_RANGES[index], position) if index == 0: self._node.set(threshold_db=value) elif index == 1: self._node.set(ratio=value) elif index == 2: self._node.set(depth_db=value) elif index == 3: self._node.set(attack_ms=value) elif index == 4: self._node.set(release_ms=value) elif index == 5: self._node.set(sidechain_hz=self._hz(value)) elif index == 6: # Rate-honest: the DS201's key band runs to 35 kHz, which is # above Nyquist at every rate this library runs at, so the top # of the span clamps rather than refusing. self._node.set(sidechain_lp_hz=self._hz(value)) elif index == 7: self._node.set(key_listen=1.0 if position >= 0.5 else 0.0) else: self._node.set(detector="rms" if position >= 0.5 else "peak") @property def tail_samples(self): """0, or with Key Listen on a bound on the key filters' ring. Each key filter is a two-pole section. From a state near full scale it is under half an LSB after about `KEY_RING_CYCLES` / fc seconds, and the two add, so the bound is the sum at Key Low and Key High as they stand. """ self._check_live() if self._macros[7] < 0.5: return 0 rate = float(self._sample_rate) total = 0 for index in (5, 6): hz = self._hz(_component.macro_value(self._MACRO_RANGES[index], self._macros[index])) total += int(math.ceil(KEY_RING_CYCLES * rate / hz)) return total
[docs] def gain_reduction_db(self): """What the gain computer applied on the last frame rendered, in dB. The node's own readout, forwarded. Not part of the component contract - a meter, and the measurement kit's GAINTRACE source. """ self._check_live() return self._node.gain_reduction_db()