Source code for audiomodal

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""A bank of resonators, which is what a struck object is.

A drum head, a marimba bar, a bell or a wine glass rings as a sum of decaying
sinusoids at frequencies that are not harmonics of anything. Give `Bank` that
list of modes and a short noise burst for the stick, and it is that object.
"""

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

FRAMES: int
"""Frames in one block: 256."""
MAX_MODES: int
"""The most modes a bank can have: 64."""
MIN_DECAY_MS: int
"""The shortest decay a mode takes, in milliseconds: 1."""
MAX_DECAY_MS: int
"""The longest decay a mode takes, in milliseconds: 30000."""

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

[docs] class Bank: """A bank of resonators, played like any audio sample. The bank is fed a stimulus with `play`, usually a short noise burst, and rings at the modes you set. The tail keeps ringing after the stimulus stops, because a drum whose decay ended the instant the stick left would be the one thing this node exists not to be. A new bank has no modes set, so with the default ``mix`` of 1.0 it is silent, not a passthrough. Use ``mix=0.0`` for the untouched signal. Every argument is a keyword. ``modes``, ``sample_rate`` and ``channel_count`` fix the allocation, so they can only be given here. Args: modes: How many resonators, 1 to `MAX_MODES`. The default is 8. sample_rate: Frames per second. channel_count: 1 or 2. mix: How much of the ringing replaces the dry signal, 0.0 to 1.0, clamped. The default is 1.0. gain: Output gain, 0.0 to 16.0, clamped. The default is 1.0. Raises: ValueError: ``modes`` is out of range or ``channel_count`` is not 1 or 2. TypeError: An unknown keyword was given. """ def __init__( self, *, modes: int = 8, sample_rate: int = 48000, channel_count: int = 2, mix: float = ..., gain: float = ..., ) -> 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.""" @property def modes(self) -> int: """How many modes the bank holds.""" @property def ringing(self) -> bool: """Whether any mode still holds energy. This is exact, not a threshold, so a voice allocator can ask whether a drum has stopped."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream that excites the modes, replacing the last one."""
[docs] def set_mode(self, index: int, frequency: float, decay: float, gain: float, /) -> None: """Place one mode. Args: index: The mode, 0 up to ``modes - 1``. frequency: The mode's frequency in Hz, clamped just below half the sample rate. decay: The time the mode takes to fall by 60 dB, in seconds, from 0.001 to 30.0. This is not a Q. gain: The peak of the mode's impulse response, from -16.0 to 16.0. A modal table read out of a paper goes in as published. Raises: IndexError: ``index`` is out of range. """
[docs] def set_modes(self, table: list[tuple[float, float, float]] | tuple[tuple[float, float, float], ...], /) -> None: """Place the whole list of modes in one call. Args: table: Rows of ``(frequency, decay, gain)``, as for `set_mode`, placed from mode 0. A table shorter than the bank silences the rest, so a shorter table is a smaller drum and not a chord of two. Raises: ValueError: The table has more rows than the bank has modes, or a row is not three values. """
[docs] def set(self, *, mix: float = ..., gain: float = ...) -> None: """Change options while the bank plays, without stopping anything ringing. All of them change together or not at all. Args: mix: As for the constructor. gain: As for the constructor. Raises: TypeError: An unknown option was given. """
[docs] def clear(self) -> None: """Stop everything ringing at once."""
[docs] def deinit(self) -> None: """Release the bank and let go of its stimulus. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...