audioeffects.ladderfilter

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.

audioeffects.ladderfilter.SELF_OSCILLATION = 4.0

The Resonance at which the loop sustains, and from which tail_samples is None.

audioeffects.ladderfilter.RING_CONSTANT = 256.0

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.

Type:

ring_frames’ envelope

audioeffects.ladderfilter.RING_SLOWEST = 9.5367431640625e-07

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.

audioeffects.ladderfilter.ring_frames(sample_rate, cutoff_hz, resonance, drive, poles=4, oversample=2, output_gain=1.0, mix=1.0)[source]

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.

class audioeffects.ladderfilter.LadderFilter(source, *options, **keywords)[source]

Bases: 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'

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 tempo-dependent behaviour anywhere in the class, so the transport is never read (dossier App. I, D10).

LATENCY_SAMPLES = 0

Zero at every setting; see the design notes. The 2x path’s half a sample of group delay is what this rounds.

TAIL_SAMPLES = None

The class attribute is the self-oscillating case; below k = 4 tail_samples is ring_frames for the settings in force.

INPUT_CEILING_DBFS = -15

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.

CLIPS_AT_TOP = (2,)

the rail check skips them.

Type:

Settings that clip by design

MACRO_LABELS = ('Cutoff', 'Resonance', 'Drive', 'Passband Comp', 'Poles', 'Oversample', '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: ('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))}

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).

property tail_samples

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).