# 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()