Source code for audiodelays

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Delay-based effects: echo, chorus, flanger, pitch shifters and a multi-tap delay.

These are CircuitPython's `audiodelays` effects, with the same names and
arguments, so code written for a CircuitPython board runs unchanged. Each one
is an audio source that reads another audio source: give it a source with
`play`, hand the effect to an output or a mixer, and it processes the audio
a block at a time.

The effects take a ``buffer_size`` in bytes for each block, the sample format
(``sample_rate``, ``bits_per_sample``, ``samples_signed``, ``channel_count``)
the source has to match, and then their own options. Every argument is a
keyword. Options that can change while the effect plays are block inputs: a
number, or a ``synthio.LFO`` or ``synthio.Math`` read once a block. A level
moved on a playing node walks to its new value over 20 ms instead of
stepping, so turning a knob does not click.

`audioecho.FeedbackDelay` is a separate delay with a filter, a soft-clip and a
cross-feed in its feedback loop; reach for it when `Echo` is not enough.
"""

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

# 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 Echo: """A single-tap echo with feedback. The delay line repeats the source, each repeat ``decay`` times as loud as the one before. ``filter`` is applied to the signal inside the feedback loop, so each repeat is filtered again. With ``freq_shift`` on, a change to ``delay_ms`` while playing shifts the pitch of the repeats, as moving a tape head does; with it off the repeats do not shift. Args: max_delay_ms: The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 500. delay_ms: The delay in milliseconds, up to ``max_delay_ms``. The default is 250. decay: How much of each repeat feeds back, 0.0 to 1.0. The default is 0.7. filter: A filter, or a sequence of them, applied inside the feedback loop, or None for none. mix: The balance of the effect, 0.0 for the dry signal only, 1.0 for the echo only. The default is 0.25. freq_shift: Whether a change to ``delay_ms`` shifts the pitch of the repeats. The default is True. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``max_delay_ms`` is not 1 to 4000. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, max_delay_ms: int = 500, delay_ms: _BlockInput = ..., decay: _BlockInput = ..., filter: object | None = None, mix: _BlockInput = ..., buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, freq_shift: bool = True, ) -> None: ... delay_ms: _BlockInput """The delay in milliseconds.""" decay: _BlockInput """How much of each repeat feeds back, 0.0 to 1.0.""" filter: object | None """The filter, or sequence of filters, in the feedback loop.""" mix: _BlockInput """The balance from the dry signal (0.0) to the echo (1.0).""" freq_shift: bool """Whether a change to ``delay_ms`` shifts the repeats' pitch.""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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 Chorus: """A chorus: the source mixed with slightly detuned, delayed copies of itself. ``voices`` sets how many copies, and may be fractional, so a chorus can fade from one voice to two. Args: max_delay_ms: The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 50. delay_ms: The centre delay of the copies in milliseconds. The default is 50. voices: How many copies are mixed in. The default is 1.0. mix: The balance from the dry signal (0.0) to the copies only (1.0). The default is 0.5. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``max_delay_ms`` is not 1 to 4000. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, max_delay_ms: int = 50, delay_ms: _BlockInput = ..., voices: _BlockInput = ..., mix: _BlockInput = ..., buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, ) -> None: ... delay_ms: _BlockInput """The centre delay of the copies in milliseconds.""" voices: _BlockInput """How many copies are mixed in.""" mix: _BlockInput """The balance from the dry signal (0.0) to the copies (1.0).""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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 Flanger: """A flanger: a short, swept delay mixed with the source, with feedback. A low-frequency oscillator sweeps the delay from ``min_delay_ms`` up towards ``max_delay_ms``, by as much of the span as ``depth`` says. Args: max_delay_ms: The longest delay the sweep can reach, 1 to 100. It sizes the delay line, so it can only be given here. The default is 10. min_delay_ms: The shortest delay of the sweep in milliseconds. The default is 1.0. rate: How fast the sweep runs, in Hz. The default is 0.5. depth: How much of the span between the shortest and longest delay the sweep covers. The default is 0.5. feedback: How much of the delayed signal feeds back. The default is 0.5. mix: The balance from the dry signal (0.0) to the delayed one (1.0). The default is 0.5. invert: Whether the delayed signal is inverted, which moves the notches from the harmonics to between them. The default is False. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``max_delay_ms`` is not 1 to 100. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, max_delay_ms: int = 10, min_delay_ms: _BlockInput = ..., rate: _BlockInput = ..., depth: _BlockInput = ..., feedback: _BlockInput = ..., mix: _BlockInput = ..., invert: bool = False, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, ) -> None: ... min_delay_ms: _BlockInput """The shortest delay of the sweep in milliseconds.""" rate: _BlockInput """How fast the sweep runs, in Hz.""" depth: _BlockInput """How much of the delay span the sweep covers.""" feedback: _BlockInput """How much of the delayed signal feeds back.""" mix: _BlockInput """The balance from the dry signal (0.0) to the delayed one (1.0).""" mix_ramp: int """How many frames a change of `mix` walks over, 0 to 96000. With 0, the default, a change lands at the next block, as CircuitPython's flanger does. Set, a change walks from where the mix stands to the new value in a straight line over that many frames, so a jump doesn't click: 960 is 20 ms at 48 kHz. A move during a walk starts a new walk from where it stands. A new node's first mix, and the first after a reset, land at once. Not in CircuitPython.""" invert: bool """Whether the delayed signal is inverted.""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def lfo_value(self) -> float: """Where the sweep is now, as the oscillator's triangle from 0.0 to 1.0.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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 GranularPitchShift: """A pitch shifter that plays overlapping grains of the source. Grains are short slices of the recent input, replayed at a different speed. It keeps the tempo and shifts the pitch. Args: semitones: How far to shift the pitch, in semitones. Negative is down. The default is 0. mix: The balance from the dry signal (0.0) to the shifted one (1.0). The default is 1. grain_size: How many frames in a grain, 2 or more. The default is 1024. density: How many grains play at once, 1 to 8. The default is 2. spread: How much each grain's start is randomised, 0.0 to 1.0. The default is 0. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``grain_size`` is below 2 or ``density`` is not 1 to 8. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, semitones: _BlockInput = 0, mix: _BlockInput = 1, grain_size: int = 1024, density: int = 2, spread: _BlockInput = 0, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, ) -> None: ... semitones: _BlockInput """How far to shift the pitch, in semitones.""" mix: _BlockInput """The balance from the dry signal (0.0) to the shifted one (1.0).""" spread: _BlockInput """How much each grain's start is randomised.""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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 PitchShift: """A pitch shifter that reads the source through an overlapping window. Where `GranularPitchShift` plays many grains, this plays one window at a time, which costs less. ``freeze`` holds the window so a note sustains. Args: semitones: How far to shift the pitch, in semitones. Negative is down. The default is 0. mix: The balance from the dry signal (0.0) to the shifted one (1.0). The default is 1. window: The size of the window in bytes, at least one frame. The default is 1024. overlap: How many bytes the windows overlap by. The default is 128. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``window`` is shorter than one frame. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, semitones: _BlockInput = 0, mix: _BlockInput = 1, window: int = 1024, overlap: int = 128, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, ) -> None: ... semitones: _BlockInput """How far to shift the pitch, in semitones.""" mix: _BlockInput """The balance from the dry signal (0.0) to the shifted one (1.0).""" freeze: bool """Whether the window is held, so the sound sustains.""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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 MultiTapDelay: """A delay with several taps, each at its own position and level. A tap is read from the delay line at a fraction of ``delay_ms``, and its level scales what is heard there. Args: max_delay_ms: The longest delay the effect can be set to, 1 to 4000. It sizes the delay line, so it can only be given here. The default is 500. delay_ms: The delay in milliseconds, up to ``max_delay_ms``. The default is 250. decay: How much of the output feeds back, 0.0 to 1.0. The default is 0.7. mix: The balance from the dry signal (0.0) to the taps (1.0). The default is 0.25. taps: The taps: a sequence of positions, or of ``(position, level)`` pairs, each from 0.0 to 1.0, where a position is a fraction of ``delay_ms``. A bare position has a level of 1. None, the default, is no taps. buffer_size: How many bytes the effect hands out in each block. The default is 512. sample_rate: Frames per second, 1 or more. The default is 8000. bits_per_sample: 8 or 16. The default is 16. samples_signed: Whether samples are signed. The default is True. channel_count: 1 or 2. The default is 1. Raises: ValueError: ``max_delay_ms`` is not 1 to 4000, ``taps`` is empty, or a pair is not two values. TypeError: ``taps`` is not iterable. ValueError: ``channel_count`` is not 1 or 2, ``sample_rate`` is below 1, or ``bits_per_sample`` is not 8 or 16. """ def __init__( self, *, max_delay_ms: int = 500, delay_ms: _BlockInput = 250, decay: _BlockInput = ..., mix: _BlockInput = ..., taps: Iterable[float | tuple[float, float]] | None = None, buffer_size: int = 512, sample_rate: int = 8000, bits_per_sample: int = 16, samples_signed: bool = True, channel_count: int = 1, ) -> None: ... delay_ms: _BlockInput """The delay in milliseconds.""" decay: _BlockInput """How much of the output feeds back, 0.0 to 1.0.""" mix: _BlockInput """The balance from the dry signal (0.0) to the taps (1.0).""" taps: Iterable[float | tuple[float, float]] | None """The taps. Reading gives ``(position, level)`` pairs, or None for no taps; any iterable of positions or pairs can be set.""" sample_rate: int """Frames per second. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: 8 or 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2.""" @property def playing(self) -> bool: """Whether a source is playing."""
[docs] def play(self, sample: _AudioSample, *, loop: bool = False) -> Self: """Start reading a source. Args: sample: The audio to process. Its sample format has to match the effect's. loop: Whether to start the source again when it ends. Returns: The effect itself. """
[docs] def stop(self) -> None: """Stop reading the source. The tail is not played out."""
[docs] def deinit(self) -> None: """Release the effect. 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: ...