Source code for audioeffects.ladderfilter

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

"""`LadderFilter` - the Moog transistor ladder, rebuilt on `audioladder`.

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.
#
# Portability tier: audiodsp (`REQUIRES = ("audioladder",)`). The linear
# half of this filter is reachable on stock CircuitPython biquads - two of
# them track the analytic ladder to 0.05 dB at every resonance short of
# oscillation - but a biquad cascade is linear, so it can never sustain a
# tone of its own however far the resonance is pushed, and it makes no
# harmonics for the growl to live in. That gap is not a matter of degree,
# which is why `audioladder.Ladder` exists.
#
# Oversample's resampler is a linear interpolation up and a two-tap average
# down, half a sample of group delay for the pair, which the node reports as
# none (`audiodsp/src/shared/audiodsp_ladder.c:302-311`). What it buys is
# small: a 5 kHz sine at 24 dB of Drive measured its non-harmonic energy
# 0.4 dB lower with it on (2026-10-27). It defaults on because half the cost
# is the wrong saving on the one node whose job is to distort.
#
# Cost: budgeted at 14 % of one stereo block on a 240 MHz ESP32-S3 and 8 %
# on a 400 MHz ESP32-P4 with Oversample on, 7 % on the S3 with the lean
# patch (dossier section 3, Tier 3). Measured 2026-09-07: 16.3 % of a block
# on the ESP32-P4 and 26.9 % on the ESP32-S3, over budget on both.
#
# The node starts from a zero state, so exact digital silence into a fresh
# instance stays silent even at k = 4.2; the sustained tone needs something,
# however small, to have arrived first.
#
# Two dossier traits are disconfirmed, with cause, in the evidence pack. T5's
# "a 20 dB input rise moves the resonant peak >= 3 dB" holds on one of the
# six 20 dB windows the surface offers (-20 -> 0 dBFS, -3.857 dB, and the
# peak falls). T1's stopband slope (-23...-27 dB/octave over 4->8 kHz) is
# -29.73 dB/oct at 22.05 kHz, because the bilinear map steepens toward
# Nyquist. Measured at 48 kHz: -12.055 dB at the cutoff, the passband
# 0.00 -> -13.90 dB across k = 0...4, self-oscillation at 999.82 Hz holding
# to +0.01 dB over two seconds, 0.068 % THD, every even harmonic below
# -131 dB re the first.

VENDOR = "PyDevices"

import math

from . import _component

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


#: The Resonance at which the loop sustains, and from which `tail_samples`
#: is `None`.
SELF_OSCILLATION = 4.0

#: `ring_frames`' envelope: the free response of the linear ladder, seen at
#: the output tap, is at most `RING_CONSTANT` times the largest integrator
#: state times rho^(`RING_RATE` n) after n frames, rho being the slowest
#: pole's radius per frame (or 1/2, `RING_FLOOR`, whichever is larger).
#: The rate is under 1 because near Resonance 0 the four poles nearly
#: coincide and the response is a cubic times rho^n, which no constant
#: covers at the full rate. The largest constant this needs, worked out
#: over cutoffs from 20 Hz to the clamp at 22.05, 44.1 and 48 kHz, every
#: Resonance from 0 to 3.969, every tap and both Oversample settings, is
#: 131 (Resonance 0, 20 Hz, four poles), and from 3.975 to 3.997 under 3;
#: 256 is the margin. Rendered, the longest ring at Resonance 0 comes to
#: 0.96 of the count, and near 4 to about half.
RING_CONSTANT = 256.0
RING_RATE = 0.875
RING_FLOOR = 0.5

#: The slowest decay per (oversampled) step for which `ring_frames` gives a
#: count, 2^-20, about eight single-precision rounding steps: the kernel
#: runs in single precision, and nearer Resonance 4 its rounding is as
#: large as the decay it would have to show. At a 20 Hz cutoff, 48 kHz,
#: Oversample on, that is Resonance 3.9884 and up.
RING_SLOWEST = 2.0 ** -20

#: 1/sqrt(2): the analog ladder's poles sit at -1 + k^(1/4) e^(+-j pi/4)
#: and -1 + k^(1/4) e^(+-j 3 pi/4), in units of the cutoff.
_HALF_ROOT_TWO = 0.7071067811865476


[docs] def ring_frames(sample_rate, cutoff_hz, resonance, drive, poles=4, oversample=2, output_gain=1.0, mix=1.0): """Frames from the input's end until the ladder's output is exactly zero, as an upper bound, or `None` from Resonance 4 up and in the narrow band just below it where the slowest decay per step is under `RING_SLOWEST`. At Mix 0 the output is the input, so the count is 0 at any Resonance. Each stage is a bilinear one-pole, so the zero-delay loop's poles are the analog ladder's, mapped by z = (1 + t p) / (1 - t p), t being the prewarped tan(pi fc / rate). For a pole p, 1 - |z|^2 is -4 t Re(p) / |1 - t p|^2, and half of that is a per-step decay rate no faster than the true one. The slow pair's -Re(p) = 1 - k^(1/4)/sqrt(2) is worked out as (4 - k) / 4 over (1 + q/sqrt(2))(1 + q^2/2), q being k^(1/4), so it keeps its digits near 4 in single precision too. No integrator holds more than `drive` plus 2/3 of the Resonance (the saturator's ceiling) times max(1, t) times max(1, 2g)^3, and the output rounds to exact zero under 0.5 / (32768 gain mix). The envelope (`RING_CONSTANT`) then gives the count. This is the linear ladder's decay; the saturator only lowers the loop's gain, and that it does not slow the ring is measured, not derived.""" scale = output_gain * mix if not scale > 0.0: return 0 resonance = float(resonance) if not resonance < SELF_OSCILLATION: return None if resonance < 0.0: resonance = 0.0 rate = float(sample_rate) * oversample cutoff = float(cutoff_hz) if cutoff > rate * 0.49: cutoff = rate * 0.49 if cutoff < 1.0: cutoff = 1.0 t = math.tan(math.pi * cutoff / rate) g = t / (1.0 + t) q = math.sqrt(math.sqrt(resonance)) slow = ((SELF_OSCILLATION - resonance) / 4.0 / ((1.0 + q * _HALF_ROOT_TWO) * (1.0 + 0.5 * q * q))) imag = q * _HALF_ROOT_TWO step = None for real in (-slow, -1.0 - imag): shrink = -4.0 * t * real / ((1.0 - t * real) ** 2 + (t * imag) ** 2) if step is None or shrink < step: step = shrink if not 0.5 * step >= RING_SLOWEST: return None per_frame = 0.5 * step * oversample if per_frame > math.log(1.0 / RING_FLOOR): per_frame = math.log(1.0 / RING_FLOOR) state = ((drive + resonance * (2.0 / 3.0)) * max(1.0, t) * max(1.0, 2.0 * g) ** 3) floor = 0.5 / (32768.0 * scale) return int(math.ceil(math.log(RING_CONSTANT * state / floor) / (RING_RATE * per_frame))) + 1
[docs] class LadderFilter(_component.Component): """A Moog transistor ladder: four filter stages round one feedback loop, with a saturator inside the loop. **Controls.** Cutoff is the filter's corner, held just under half the sample rate. Resonance is the loop's feedback. As it rises the cutoff sharpens and the whole passband sinks, about 14 dB by a Resonance of 4: that droop is the circuit's sound, not a fault. From 4 up, the filter sings a sine of its own at the cutoff, and once it has heard anything it keeps singing after your signal stops. Drive is how hard the saturator is hit, so the growl follows your input level the way it does in the hardware. Passband Comp puts the sunk passband back: at 1 the passband holds its level at any Resonance. Poles picks the output from one to four poles. Oversample runs the loop at twice the rate; it is on by default, and the Ladder - lean patch is Wide Open with it off, for slower boards. Mix at 0 is your dry signal. A jump of Cutoff, Resonance, Drive, Passband Comp or Mix walks there over 20 ms rather than stepping the output. The Effect controls page lists what the knobs span. **Response.** At 48 kHz the four-pole output is 12 dB down at the cutoff and about 50 dB down two octaves above it, and each pole fewer takes about 12 dB off that. **Timing.** Latency is zero at every setting, Oversample included. Below a Resonance of 4, silence in is silence out once the filter rings down: Wide Open's tail is under a millisecond and Growl With Drive's about 285 ms. `tail_samples` is an upper bound on that ring for the settings as they stand; at the slowest settings it is about twice the ring measured. From 4 up the tone does not stop by itself, so the class reports no tail bound, and none either in the hair below 4 where the ring outlasts what single precision can count (from Resonance 3.988 at a 20 Hz cutoff, nearer 4 above it). `reset()` stops it at any setting. **Levels.** The resonance peak and the drive both add gain, so no input level is clean on every setting. Keep the input under -15 dBFS and the defaults and patches stay off the rails. Drive at its top can still push the output onto the rails. Turn Drive, Resonance or your input down. **On a board.** The class needs audiodsp's `audioladder`, and on a board without it construction raises `ImportError`. """ NAME = 'LadderFilter' DISPLAY_NAME = 'Ladder Filter' CATEGORIES = ('Filter',) VERSION = '0.0.2' TIER = _component.AUDIODSP REQUIRES = ("audioladder",) #: No tempo-dependent behaviour anywhere in the class, so the transport #: is never read (dossier App. I, D10). CAPABILITIES = () #: Zero at every setting; see the design notes. The 2x path's half a #: sample of group delay is what this rounds. LATENCY_SAMPLES = 0 #: The class attribute is the self-oscillating case; below k = 4 #: `tail_samples` is `ring_frames` for the settings in force. TAIL_SAMPLES = None #: The defaults and every patch play the ceiling kit's materials #: clean at this level; at -12 dBFS, patch 4 rails on #: a 100 Hz square. INPUT_CEILING_DBFS = -15 #: Settings that clip by design: the rail check skips them. CLIPS_AT_TOP = (2,) MACRO_LABELS = ("Cutoff", "Resonance", "Drive", "Passband Comp", "Poles", "Oversample", "Mix") MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "TOGGLE", 6: "UNIPOLAR"} #: `Resonance` spans past the self-oscillation threshold deliberately: #: k = 4 has to be a position *inside* the travel, or "sustains at 4 and #: not before" cannot be measured from the panel at all. The node clamps #: at the same 4.2 (`audiodsp_ladder.c:130`). #: `Drive` is decibels here and a linear gain at the node, converted in #: `_apply_macro` rather than guessed at by the C. _MACRO_RANGES = ( (20.0, 18000.0, "log"), # 0 Cutoff (0.0, 4.2), # 1 Resonance, the circuit's k (0.0, 24.0), # 2 Drive, dB into the loop (0.0, 1.0), # 3 Passband Comp (1.0, 4.0), # 4 Poles, the output tap (0.0, 1.0), # 5 Oversample, off / 2x (0.0, 1.0), # 6 Mix, 0 is a wire ) _MACRO_UNITS = {0: "Hz", 2: "dB"} #: The 0-127 grid, computed with `_component.macro_of()` from the #: settings the dossier's section 6 names. Patch 0 is the constructor's #: defaults quantized onto that grid, which puts it at 11.73 kHz and #: k = 0.595 rather than the exact 12 kHz and 0.6 a fresh instance #: carries - `macro_position()` is unquantized on the construction path #: on purpose (`_component.py:190-198`). PATCHES = { 0: ('Wide Open', (119, 18, 0, 0, 127, 127, 127)), 1: ('Squelch At The Knee', (66, 109, 32, 0, 127, 127, 127)), 2: ('Sustained Sine At Cutoff', (73, 127, 0, 0, 127, 127, 127)), 3: ('Dark', (51, 45, 0, 0, 127, 127, 127)), 4: ('Growl With Drive', (71, 118, 95, 0, 127, 127, 127)), 5: ('Two Pole Soft', (90, 30, 0, 0, 42, 127, 127)), 6: ('Ladder - lean', (119, 18, 0, 0, 127, 0, 127)), } def _build(self, cutoff_hz=12000.0, resonance=0.6, drive_db=0.0, passband_comp=0.0, poles=4, oversample=True, mix=1.0, patch=None): """One node. Every setting arrives through `_init_macros()`, so the constructor and a later `set_macro()` cannot mean different things. `resonance` is the circuit's feedback k, 0 to 4.2, not a 0..1 knob: the numbers the dossier's traits are stated in are k, and a class that renamed them would make its own gate unreadable. """ # A move of the cutoff, resonance, drive, passband_comp or mix # walks over 20 ms in the node, as the effects' levels do # (`_component.LEVEL_RAMP_MS`), so a jump does not click. The node's # first block plays the settings as they stand, so a new node or a # reset one has nothing to walk from. node = audioladder.Ladder(sample_rate=self._sample_rate, channel_count=self._channel_count, ramp_ms=_component.LEVEL_RAMP_MS) node.play(self._source) # The node holds no external resource -- its output block is inline # in the object (`audioladder/Ladder.h`), so on the two native # builds, which expose no `deinit`, releasing it is dropping the # reference, which the base class's walk already does. self._own(node, reset=True, deinit=True) self._node = node self._output = node self._init_macros((cutoff_hz, resonance, float(drive_db), passband_comp, float(poles), 1.0 if oversample else 0.0, mix), patch) def _apply_macro(self, index, position): span = self._MACRO_RANGES[index] value = _component.macro_value(span, position) if index == 0: # Clamped to 0.49 * sample_rate by `_hz()`, which is the node's # own clamp at `oversample = 1` and inside it at 2. Rate-honest: # at 22.05 kHz the top of this span becomes 10.8 kHz rather than # refusing (`_component.py:487-496`, `audiodsp_ladder.c:79`). self._node.set(cutoff_hz=self._hz(value)) elif index == 1: self._node.set(resonance=value) elif index == 2: # Decibels on the panel, a linear gain at the node. self._node.set(drive=_component.db_to_gain(value)) elif index == 3: self._node.set(passband_comp=value) elif index == 4: self._node.set(poles=int(round(value))) elif index == 5: self._node.set(oversample=2 if position >= 0.5 else 1) else: self._node.set(mix=value) @property def tail_samples(self): """Frames until the output is exactly zero once the input stops, as an upper bound for the settings as they stand, or `None` from a Resonance of 4 up, where the filter sustains, and just below it where single precision cannot show the decay (`ring_frames`).""" self._check_live() return self._tail_bound() def _tail_bound(self): """`tail_samples` without the liveness check: a plain method, so a subclass can reach it on MicroPython, whose `property` has no `fget`.""" def value(index): return _component.macro_value(self._MACRO_RANGES[index], self._macros[index]) resonance = value(1) return ring_frames( self._sample_rate, self._hz(value(0)), resonance, _component.db_to_gain(value(2)), int(round(value(4))), 2 if self._macros[5] >= 0.5 else 1, 1.0 + value(3) * resonance, value(6))