Source code for audioverb

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""A plate reverberator whose network you hand in.

`Tank` is Dattorro's plate reverberator, with the network passed in rather
than compiled in. That is the difference from `audiofreeverb.Freeverb`, whose
comb and all-pass lengths are constants.

::

    plate = audioverb.Tank(
        sample_rate=48000, channel_count=2, max_predelay_ms=200,
        decay=0.7, diffusion=0.75, bandwidth_hz=9000, damping_hz=4500,
        mod_rate_hz=1.0, mod_depth_ms=0.27, mix=0.35)
    plate.play(source)
    audio_out.play(plate)
"""

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

__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 Tank: """A plate reverberator, played like any audio sample. Construction fixes the allocation: ``sample_rate``, ``channel_count`` and ``max_predelay_ms``. It also takes the network, ``delays`` and ``taps``. `set` moves every other option while the node plays and without emptying the lines; giving it ``delays`` or ``taps`` cuts a new network, which does empty them. Every filter is out of the path at zero, so a ``Tank()`` given nothing else is that network with nothing added to it. There is no latency from dry to wet. The tail reaches exact zero rather than sitting at one least significant bit, because every line write is a magnitude truncation, which is the standard cure for the limit cycles of a recirculating fixed-point network. When the source ends, the tail rings out on silence to that zero and the node rests, so a source played into it afterwards meets an empty plate. `audioecho.FeedbackDelay` and `audioconvolve.Convolver` do the same. ``delays`` is twelve line lengths in frames: the four input diffusers, then each tank half's modulated all-pass, delay, all-pass and delay. Each is at least 4. ``taps`` is four values per tap: the output channel (0 or 1), the line (0 to 11), the offset in frames within that line and the gain, with at most 32 taps. Both default to Dattorro's published table, scaled from 29761 Hz to ``sample_rate``. Every argument is a keyword. Args: sample_rate: Frames per second, 1 or more. The default is 48000. channel_count: 1 or 2. The default is 2. max_predelay_ms: The longest pre-delay `predelay_ms` can ask for, in milliseconds, 0 or more. It sets how much memory the pre-delay line takes. The default is 200. delays: The twelve line lengths, in frames. taps: The output taps, a flat sequence of four numbers a tap. decay: How much of the tail comes round again, 0.0 to 0.999, clamped. The default is 0.5. diffusion: The all-pass coefficient of the diffusers, 0.0 to 0.9, clamped. The default is 0.75. damping_hz: A low-pass in the tank's loop, in Hz. 0, the default, is out of the path. bandwidth_hz: A low-pass on the input, in Hz. 0, the default, is out of the path. low_cut_hz: A high-pass on the input, in Hz. 0, the default, is out of the path. predelay_ms: Delay before the reverb, in milliseconds, held between 0 and ``max_predelay_ms``. The default is 0. mod_depth_ms: How far the modulated all-passes move, in milliseconds, 0 to 100, clamped. The default is 0. mod_rate_hz: How fast they move, 0 to 100 Hz, clamped. The default is 0. drive: A saturation on the input, 0.0 to 1.0, clamped. The default is 0. width: The stereo width of the wet signal, 0.0 to 2.0, clamped. The default is 1. tone_db: A tilt of the wet signal, bright to dark, -24 to 24 dB, clamped: half the change up at the top and the same down at the bottom, pivoting at 1 kHz. A balance control, not a trim. The default is 0. mix: How much of the reverb is added, 0.0 to 2.0, clamped. It follows `audiodelays.Echo`: the dry signal stays at unity until 1, and from there it fades out. The default is 0.3. Raises: ValueError: ``sample_rate`` is less than 1, ``channel_count`` is not 1 or 2, ``max_predelay_ms`` is negative, ``delays`` is not twelve lengths of at least 4 frames that fit, or ``taps`` is not whole taps naming a channel, a line and an offset that exist. TypeError: An unknown option was given. MemoryError: The lines do not fit. """ def __init__( self, *, sample_rate: int = 48000, channel_count: int = 2, max_predelay_ms: float = 200.0, delays: Sequence[int] | None = None, taps: Sequence[float] | None = None, decay: float = 0.5, diffusion: float = 0.75, damping_hz: float = 0.0, bandwidth_hz: float = 0.0, low_cut_hz: float = 0.0, predelay_ms: float = 0.0, mod_depth_ms: float = 0.0, mod_rate_hz: float = 0.0, drive: float = 0.0, width: float = 1.0, tone_db: float = 0.0, mix: float = 0.3, ) -> 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 reverberate, replacing the last one."""
[docs] def set( self, *, delays: Sequence[int] = ..., taps: Sequence[float] = ..., decay: float = ..., diffusion: float = ..., damping_hz: float = ..., bandwidth_hz: float = ..., low_cut_hz: float = ..., predelay_ms: float = ..., mod_depth_ms: float = ..., mod_rate_hz: float = ..., drive: float = ..., width: float = ..., tone_db: float = ..., mix: float = ..., ) -> None: """Change options while the tank plays, without emptying the lines. Giving ``delays`` or ``taps`` cuts a new network, which does empty every line and filter. All the options given change together or not at all. Args: delays: As for the constructor. taps: As for the constructor. decay: As for the constructor. diffusion: As for the constructor. damping_hz: As for the constructor. bandwidth_hz: As for the constructor. low_cut_hz: As for the constructor. predelay_ms: As for the constructor. mod_depth_ms: As for the constructor. mod_rate_hz: As for the constructor. drive: As for the constructor. width: As for the constructor. tone_db: As for the constructor. mix: As for the constructor. Raises: TypeError: An unknown option was given, or one of ``sample_rate``, ``channel_count`` or ``max_predelay_ms``, which are fixed when the node is made. ValueError: ``delays`` or ``taps`` are not valid, as for the constructor. """
[docs] def clear(self) -> None: """Empty every line and every filter."""
[docs] def deinit(self) -> None: """Release the node 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: ...