Source code for audioconvolve

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Apply an impulse response to a stream, by partitioned FFT.

`Convolver` convolves its source with a measured impulse response, such as a
room, a cabinet or a spring, or with a room it synthesizes itself. It adds one
block of latency once an impulse is loaded.
"""

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, and the size of one partition: 256."""
MAX_PARTITIONS: int
"""The most partitions an impulse can take: 512, so impulses up to
``MAX_PARTITIONS * FRAMES`` frames long."""

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

[docs] class Convolver: """Convolves a stream with an impulse response, played like any audio sample. The tail keeps ringing after the source ends, so a room rings out. A convolver with nothing loaded passes its input through. The capacity for the impulse is fixed when the convolver is made, because something downstream may already be pulling from it: size it with ``max_taps``, or give an ``impulse`` to size it from. Args: impulse: Optional. The impulse response, as signed 16-bit samples, interleaved when ``impulse_channels`` is 2. If given, it is loaded now. impulse_channels: Channels in ``impulse``: 1, which is shared by both audio channels, or 2, which gives each channel its own. sample_rate: Frames per second. max_taps: The longest impulse, in frames, that `load` and `synthesize` can later bring. The default is the length of ``impulse``, or 4096 frames when there is none. A longer ``impulse`` raises it. ir_channels: Channels the stored impulse has, 1 or 2. The default is ``impulse_channels``. gain: A linear gain on ``impulse`` as it is loaded. The default is 1.0. mix: Wet and dry balance, 0.0 to 1.0, clamped, where the dry stays at unity until 0.5 and the wet is already at full level there, as in `audiofreeverb`. The default is 0.5. channel_count: Audio channels, 1 or 2. wet_gain: A linear gain on the wet signal alone, 0.0 to 4.0, clamped. The default is 1.0. Raises: ValueError: A channel count is out of range, ``impulse`` is not a whole number of 16-bit frames, or the impulse is too long. """ def __init__( self, impulse: bytes | bytearray | memoryview | None = None, impulse_channels: int = 1, sample_rate: int = 48000, max_taps: int = 0, ir_channels: int = 0, gain: float | None = None, mix: float | None = None, channel_count: int = 2, wet_gain: float | 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 audio channels: 1 or 2.""" @property def taps(self) -> int: """The length of the loaded impulse in frames, rounded up to a whole number of partitions. 0 when nothing is loaded.""" @property def latency(self) -> int: """Frames of delay the convolver adds: `FRAMES` once an impulse is loaded, 0 before, since an empty convolver passes its input through.""" @property def room_peak_gain(self) -> float: """The most the last `synthesize` room brings a low full-scale input back, as a linear gain, before ``wet_gain``. A dark room gathers its energy low and reads high. 0.0 after `load` or before any `synthesize`."""
[docs] def play(self, source: _AudioSample, /) -> None: """Set the stream to convolve, replacing the last one. Raises: ValueError: The stream's channel count differs from this node's. """
[docs] def set(self, *, mix: float = ..., wet_gain: float = ...) -> None: """Change options while the node plays. Args: mix: As for the constructor. wet_gain: As for the constructor. Raises: TypeError: An unknown option was given. """
[docs] def load(self, impulse: bytes | bytearray | memoryview, channels: int = 1, gain: float | None = None) -> None: """Load an impulse response while the node plays. Audio in flight is kept: the block being played crossfades from the old impulse to the new one, with no frame dropped or repeated. An empty impulse unloads it. Args: impulse: Signed 16-bit samples, interleaved when ``channels`` is 2. channels: Channels in ``impulse``, 1 or 2. gain: A linear gain applied as it is loaded. The default is 1.0. Raises: ValueError: ``channels`` is out of range, ``impulse`` is not a whole number of frames, or it is longer than ``max_taps``. """
[docs] def synthesize( self, decay: float | None = None, damping_hz: float | None = None, predelay_ms: float | None = None, diffusion_ms: float | None = None, seed: int = 1, ) -> None: """Load a synthesized room: decaying noise, normalised to unit energy. The same arguments always give the same room, bit for bit, on every interpreter. Args: decay: The time the room takes to fall by 60 dB, in seconds. The default is 2.0. damping_hz: Rolls the tail's top off as it decays, in Hz. The default is 0.0, which leaves it bright. predelay_ms: Silence before the room starts, in milliseconds. The default is 0.0. diffusion_ms: Fades the tail in over this many milliseconds rather than starting it at full amplitude, so the room does not sound like a burst of noise. The default is 0.0. seed: Chooses the noise. Different seeds are different rooms. """
[docs] def room_peak_gain_for( self, decay: float | None = None, damping_hz: float | None = None, predelay_ms: float | None = None, diffusion_ms: float | None = None, seed: int = 1, ) -> float: """The `room_peak_gain` that `synthesize` would give for the same arguments, worked out without loading anything. Set the wet level from it before calling `synthesize`, so the audio in flight fades to the new room at its new level. """
[docs] def clear(self) -> None: """Empty the convolver's memory of past audio, so the room stops ringing."""
[docs] def deinit(self) -> None: """Release the convolver 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: ...