Source code for audioladder

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""A transistor ladder filter.

`Ladder` is a low-pass filter that behaves like the circuit. `audiofilters.Filter`
is a better *resonant low-pass* than this one: a cascade of biquads tracks
the analytic response to a fraction of a decibel. It is also linear, so it
never sustains a tone of its own, has no harmonics to speak of and sounds the
same however hard you hit it. A ladder does those three things, and that is
what this module is for.

::

    import audioladder

    ladder = audioladder.Ladder(
        sample_rate=48000,      # and channel_count=1 or 2
        cutoff_hz=800.0,        # where the filter turns over
        resonance=3.6,          # 0 to 4.2; at 4 it sustains a tone at the cutoff
        drive=2.5,              # linear gain into the loop, 1 being unity
        poles=4,                # tap stage 1 to 4: 6, 12, 18 or 24 dB an octave
        passband_comp=0.0,      # 0 to 1, how much of the passband to give back
        oversample=2,           # 1 or 2; 2 folds back fewer of its harmonics
        mix=1.0,                # 0 a wire, 1 the filter
        cutoff_octaves=10.0,    # octaves for a full-scale cutoff input
    )
    ladder.play(source)
    ladder.set(cutoff_hz=1200.0)   # any option, mid-stream, once a block
    ladder.modulate(cutoff=lfo)    # the cutoff read from a stream, every sample
    ladder.clear()                 # empty the integrators; stops a sustained tone
"""

from __future__ import annotations
from types import TracebackType
from typing import Protocol, Self

__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""

class _AudioSample(Protocol):
    @property
    def sample_rate(self) -> int: ...
    @property
    def bits_per_sample(self) -> int: ...
    @property
    def channel_count(self) -> int: ...

[docs] class Ladder: """A four-pole transistor ladder low-pass filter, played like any audio sample. It hands out 256 frames at a time, or fewer with ``buffer_size``, and renders 16-bit audio. Every option is a keyword. ``sample_rate``, ``channel_count`` and ``buffer_size`` can only be given here; the rest can be given here or to `set`. Args: sample_rate: Frames per second, 1 or more. The default is 48000. channel_count: 1 or 2. The default is 2. buffer_size: Bytes in each block, a whole number of frames from one frame to 256. None, the default, is 256 frames. cutoff_hz: Where the filter turns over, in Hz. The default is 1000. It is held between 1 Hz and just under half the sample rate. resonance: Feedback around the loop, 0.0 to 4.2, clamped. The default is 0. At 4 the loop sustains a tone at the cutoff; a little past it is where a ladder is usually played. drive: A linear gain into the loop, 0.0 to 64.0, clamped, where 1 is unity. The default is 1. poles: Which stage the output is tapped from, 1 to 4, which is 6, 12, 18 or 24 dB an octave above the cutoff. The default is 4. The feedback comes from the fourth stage at every tap. passband_comp: How much of the passband the feedback takes away to give back, 0.0 to 1.0, clamped. At a resonance of 4 the whole band below the cutoff is 14 dB down; 1 gives all of it back. The default is 0, which leaves the filter as the circuit behaves. oversample: 1 or 2. At 2, the default, the filter runs at twice the rate, so fewer of the harmonics it makes fold back above Nyquist. mix: A crossfade, 0.0 to 1.0, clamped. 0 is a wire and 1 is the filter. This is not the 0 to 2 scale of `audiodelays.Echo`. The default is 1. cutoff_octaves: How many octaves a full-scale `modulate` input moves the cutoff, of either sign. The default is 10. ramp_ms: How long a change of ``cutoff_hz``, ``resonance``, ``drive``, ``passband_comp`` or ``mix`` takes to arrive, 0 to 1000 ms, clamped. The cutoff walks evenly in pitch and the rest in a straight line, a step every 8 frames, so a jump does not click. A change during a walk turns from where the walk stands. The default is 0, which lands a change at the next block. ``poles`` and ``oversample`` always land at once. cutoff: A stream to read the cutoff from, as for `modulate`. Raises: ValueError: ``sample_rate`` is less than 1, ``channel_count`` is not 1 or 2, or ``buffer_size`` is not whole frames up to 256. TypeError: An unknown option was given. """ def __init__( self, *, sample_rate: int = 48000, channel_count: int = 2, buffer_size: int | None = None, cutoff_hz: float = 1000.0, resonance: float = 0.0, drive: float = 1.0, poles: int = 4, passband_comp: float = 0.0, oversample: int = 2, mix: float = 1.0, cutoff_octaves: float = 10.0, ramp_ms: float = 0.0, cutoff: _AudioSample | None = None, ) -> None: ... sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream to filter, replacing the last one."""
[docs] def set( self, *, cutoff_hz: float = ..., resonance: float = ..., drive: float = ..., poles: int = ..., passband_comp: float = ..., oversample: int = ..., mix: float = ..., cutoff_octaves: float = ..., ramp_ms: float = ..., ) -> None: """Change options while the filter plays. The cutoff moves once a block, which is plenty for an envelope or a knob; with ``ramp_ms`` set, a move walks there over that long instead of landing at the next block. Swept by an audio-rate signal that way, it is heard as a staircase, a buzz at the block rate; use `modulate` for that. All the options given change together or not at all. Args: cutoff_hz: As for the constructor. resonance: As for the constructor. drive: As for the constructor. poles: As for the constructor. passband_comp: As for the constructor. oversample: As for the constructor. mix: As for the constructor. cutoff_octaves: As for the constructor. ramp_ms: As for the constructor. Raises: TypeError: An unknown option was given. """
[docs] def modulate(self, *, cutoff: _AudioSample | None) -> None: """Read the cutoff from a stream, every sample. For an input at ``v`` of full scale the cutoff is ``cutoff_hz * 2 ** (v * cutoff_octaves)``, so filter FM sounds like filter FM. Only the first channel of a stereo input is read. An input of zero, or none at all, leaves the filter exactly as ``cutoff_hz`` sets it. Args: cutoff: The stream, mono or stereo, or None to disconnect it. Raises: TypeError: An input other than ``cutoff`` was named. ValueError: The stream is not mono or stereo. """
[docs] def clear(self) -> None: """Empty the integrators. This stops a tone the loop is sustaining."""
[docs] def deinit(self) -> None: """Release the filter and let go of its source. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...