Source code for audiobiquad

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Biquad and all-pass filters whose tails reach exact zero.

`Biquad` is one filter section in any of seven modes, and `AllPass` is a
cascade of first-order all-pass stages, which is what a phaser is made of.
Both keep their state in floating point, so a ringing tail decays to exactly
zero instead of sitting at one least-significant bit. `Q` is bounded to
0.05 to 60 and `feedback` to plus or minus 0.99: a pole on the unit circle is a
filter that never stops ringing, which is the one thing this module exists to
avoid.

This module is named apart from CircuitPython's `audiofilters` on purpose. It
is not an extension of `audiofilters.Filter` or `audiofilters.Phaser` but a
second set of kernels, so the ported modules stay the same as the ones on a
stock board. For a task-shaped introduction, see "Filter a sound".

Both nodes hand out 256 frames at a time (or fewer, with ``buffer_size``), sit
in an audio chain like any other effect, add no latency, and never report
themselves finished: a chain with nothing left to read gets silence.

A level moved on a playing node walks to its new value in a straight line
over 20 ms instead of stepping, so turning ``mix`` in one call does not click.
A node that has not played yet, or has just been reset, takes its levels at
once.
"""

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

__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."""

LOW_PASS: int
"""A `Biquad` mode: pass what is below ``frequency``. This is 0."""
HIGH_PASS: int
"""A `Biquad` mode: pass what is above ``frequency``. This is 1."""
BAND_PASS: int
"""A `Biquad` mode: pass a band around ``frequency``. This is 2."""
NOTCH: int
"""A `Biquad` mode: remove a band around ``frequency``. This is 3."""
PEAKING_EQ: int
"""A `Biquad` mode: boost or cut a band around ``frequency`` by ``gain_db``.
This is 4."""
LOW_SHELF: int
"""A `Biquad` mode: boost or cut everything below ``frequency`` by
``gain_db``. This is 5."""
HIGH_SHELF: int
"""A `Biquad` mode: boost or cut everything above ``frequency`` by
``gain_db``. This is 6."""
MODES: tuple[int, int, int, int, int, int, int]
"""The seven mode numbers, `LOW_PASS` to `HIGH_SHELF`, in order. They are
numbered exactly as ``synthio.FilterMode`` numbers its modes, so either can be
handed to either."""
FRAMES: int
"""Frames in one block when ``buffer_size`` is not given: 256."""
MAX_STAGES: int
"""The most stages an `AllPass` can have: 16."""

# A number, or a synthio.LFO or synthio.Math read once a block.
_BlockInput = Union[float, object, None]

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

[docs] class Biquad: """One filter section. Every argument is a keyword. ``frequency``, ``Q``, ``gain_db`` and ``mix`` are block inputs: a number, or a ``synthio.LFO`` or ``synthio.Math`` that is read once a block, so an LFO on ``frequency`` arrives about a block late. When ``frequency``, ``Q``, ``gain_db`` or ``mode`` changes while the filter plays, it glides to the new filter over about 20 ms instead of jumping, so a preset change that drops the corner from 20 kHz to 20 Hz does not thump. A filter that has not played yet takes its new settings at once. Args: mode: One of `LOW_PASS`, `HIGH_PASS`, `BAND_PASS`, `NOTCH`, `PEAKING_EQ`, `LOW_SHELF` and `HIGH_SHELF`. The default is `LOW_PASS`. frequency: The corner or centre in Hz. The default is 1000. Q: The resonance, bounded to 0.05 to 60. The default, None, is 0.7071 (Butterworth), and reads back as that number. gain_db: The boost or cut in dB, for `PEAKING_EQ`, `LOW_SHELF` and `HIGH_SHELF`. The default is 0. mix: A crossfade: 0 is a wire, 1 is the filtered signal alone. The default is 1. sample_rate: Frames per second. 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 to 256. The default, None, is 256 frames. Raises: ValueError: ``mode`` is not one of the seven, ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``buffer_size`` is not whole frames from one to 256. """ def __init__( self, *, mode: int = 0, frequency: _BlockInput = 1000, Q: _BlockInput = None, gain_db: _BlockInput = 0, mix: _BlockInput = 1, sample_rate: int = 48000, channel_count: int = 2, buffer_size: int | None = None, ) -> None: ... mode: int """The filter's mode. Setting it raises `ValueError` for a number that is not one of the seven.""" frequency: _BlockInput """The corner or centre in Hz.""" Q: _BlockInput """The resonance, bounded to 0.05 to 60.""" gain_db: _BlockInput """The boost or cut in dB.""" mix: _BlockInput """The crossfade from the dry signal (0) to the filtered one (1).""" 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.""" @property def playing(self) -> bool: """Whether a source is set with `play`.""" @property def coefficients(self) -> tuple[float, float, float, float, float]: """The filter's ``(b0, b1, b2, a1, a2)``, normalised, at the settings in force. Reading it does not advance an LFO on a block input."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream to filter, replacing the last one."""
[docs] def stop(self) -> None: """Forget the source. The node then hands out silence."""
[docs] def clear(self) -> None: """Empty the filter's memory, which stops a ringing tail."""
[docs] def deinit(self) -> None: """Release the node. Later calls other than `deinit` raise `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs] class AllPass: """A cascade of first-order all-pass stages. ``frequency`` really is the frequency at which one stage's phase passes minus 90 degrees, so nothing has to be pre-warped. With ``mix`` at 0.5 the cascade sums with the dry signal into the notches a script phaser makes, and that is where they are deepest. Every argument is a keyword. ``frequency``, ``feedback`` and ``mix`` are block inputs, as for `Biquad`. ``stages`` sizes the node's state, so it can only be given here. Args: stages: How many stages, 1 to `MAX_STAGES`. The default is 4. frequency: The frequency in Hz at which one stage reaches minus 90 degrees. The default is 1000. feedback: Output fed back to the input, bounded to plus or minus 0.99. The default is 0. mix: A crossfade: 0 is a wire, 1 is the all-pass cascade alone. The default is 1. sample_rate: Frames per second. The default is 48000. channel_count: 1 or 2. The default is 2. buffer_size: Bytes in each block, as for `Biquad`. Raises: ValueError: ``stages`` is out of range, ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``buffer_size`` is not whole frames from one to 256. """ def __init__( self, *, stages: int = 4, frequency: _BlockInput = 1000, feedback: _BlockInput = 0, mix: _BlockInput = 1, sample_rate: int = 48000, channel_count: int = 2, buffer_size: int | None = None, ) -> None: ... frequency: _BlockInput """The frequency in Hz at which one stage's phase passes minus 90 degrees.""" feedback: _BlockInput """Output fed back to the input, bounded to plus or minus 0.99.""" mix: _BlockInput """The crossfade from the dry signal (0) to the cascade (1).""" 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.""" @property def playing(self) -> bool: """Whether a source is set with `play`.""" @property def stages(self) -> int: """How many stages the cascade has.""" @property def coefficient(self) -> float: """The coefficient of each stage at the settings in force. Reading it does not advance an LFO on a block input."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream to filter, replacing the last one."""
[docs] def stop(self) -> None: """Forget the source. The node then hands out silence."""
[docs] def clear(self) -> None: """Empty the filter's memory, which stops a ringing tail."""
[docs] def deinit(self) -> None: """Release the node. Later calls other than `deinit` raise `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...