Source code for audioeffects.convolutionreverb

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""`ConvolutionReverb` - a room made by convolution, synthesized or loaded.

The player's text is the class docstring, and every sentence in it that
makes a claim is tied to a test by the `CLAIMS` table in the class's test
file.
"""

VENDOR = "PyDevices"

import math

from . import _component

try:
    import audioconvolve
except ImportError:                     # pragma: no cover - a stock board
    audioconvolve = None


#: One partition, in frames; the node's `FRAMES`.
PARTITION = 256

#: The node's ceiling in partitions (`audiodsp_convolve.h:58-60`), and in
#: taps. It is the same count of taps at every rate.
MAX_PARTITIONS = 512
CEILING_TAPS = MAX_PARTITIONS * PARTITION

#: The shortest allocation the class builds: under it Decay, which runs
#: from the node's 50 ms floor, would have no travel.
FLOOR_SECONDS = 0.06

#: The node's shortest decay (`audiodsp_convolve.c:183` at 0d35a90) and its
#: clamps on predelay and diffusion (`:184`, `:185`), in seconds and milliseconds.
NODE_DECAY_FLOOR = 0.05
PREDELAY_MAX_MS = 200.0
DIFFUSION_MAX_MS = 500.0

#: Damping's span, log, and the clamp as a fraction of the rate: just under
#: fs / (2 pi), where the node's `exp_small` stops moving the coefficient.
DAMPING_LOW_HZ = 500.0
DAMPING_HIGH_HZ = 7500.0
DAMPING_CLAMP = 0.159

#: `ir_gain_db` and `start_ms` spans, measured mode.
IR_GAIN_MIN_DB = -24.0
IR_GAIN_MAX_DB = 12.0
START_MAX_MS = 200.0

#: Room seeds: 1 + round(position * 63), 64 rooms.
ROOMS = 64

#: The wet trim, from the room itself. The room is normalised to unit energy,
#: so a dark or short one gathers that energy low and brings a low input back
#: louder than it went in. The node reads how much as it synthesizes
#: (`Convolver.room_peak_gain`: the step response's peak and the
#: steady-state peak of a full-scale square from 40 to 160 Hz, the worse
#: side), and the trim holds that, the room alone, to `TRIM_PEAK_DB`: a
#: -12 dBFS input then peaks at full scale. Where the room reads 1 dB or
#: more under it the trim is exactly 1.0; above `TRIM_PEAK_DB + TRIM_KNEE_DB`
#: it takes the excess off; between, a quadratic knee joins the two with no
#: corner, and is never above what holds. The dry is not trimmed, so with it
#: mixed in the sum can go higher (`INPUT_CEILING_DBFS`).
TRIM_PEAK_DB = 12.0
TRIM_KNEE_DB = 1.0
#: Damping out is a different room from its step below, brighter by a
#: one-pole: it reads about 3.15 dB lower (3.04 to 3.31 on average at 22.05 to
#: 48 kHz, 2.05 to 3.82 over 512 rooms). Read that much higher, out is trimmed
#: as the step below it is, so the top step moves the level by no more than
#: that spread, where it jumped 2.4 dB, and never trims out less than it
#: needs.
OUT_LIFT_DB = 3.15
_OUT_LIFT = 10.0 ** (OUT_LIFT_DB / 20.0)
_DB20 = 20.0 / math.log(10.0)


[docs] def room_trim(peak_gain): """The wet gain for a room whose `room_peak_gain` is `peak_gain`: 1.0 up to the knee, then down by the excess over `TRIM_PEAK_DB`, through a quadratic soft knee `TRIM_KNEE_DB` either side of it. Never above 1.0. Rounded to 1/4096, so it is the same number in single and double precision.""" if not peak_gain > 0.0: return 1.0 excess = _DB20 * math.log(peak_gain) - TRIM_PEAK_DB if excess <= -TRIM_KNEE_DB: return 1.0 if excess < TRIM_KNEE_DB: db = -(excess + TRIM_KNEE_DB) ** 2 / (4.0 * TRIM_KNEE_DB) else: db = -excess return int(10.0 ** (db / 20.0) * 4096.0 + 0.5) / 4096.0
DECAY_I, DAMPING_I, PREDELAY_I, DIFFUSION_I, ROOM_I, MIX_I = range(6) SYNTHESIS_MACROS = (DECAY_I, DAMPING_I, PREDELAY_I, DIFFUSION_I, ROOM_I) def _floor3(value): """`value` floored to three decimal places, so the number a message names is one that builds (2.730 s is 131 040 taps; 2.731 s raises).""" return int(value * 1000.0) / 1000.0 def _u16(data, at): return data[at] | (data[at + 1] << 8) def _u32(data, at): return _u16(data, at) | (_u16(data, at + 2) << 16)
[docs] def read_wav(path, sample_rate): """`(data, channels)` from a 16-bit PCM WAV at `sample_rate`. The file is read once; `data` is the `data` chunk's bytes. A WAV at another rate raises naming both rates: an effect does not resample. """ with open(path, "rb") as handle: head = handle.read(12) if len(head) < 12 or head[0:4] != b"RIFF" or head[8:12] != b"WAVE": raise ValueError("ConvolutionReverb: %r is not a RIFF WAVE file" % (path,)) channels = None while True: chunk = handle.read(8) if len(chunk) < 8: break size = _u32(chunk, 4) name = chunk[0:4] if name == b"fmt ": body = handle.read(size) if size & 1: handle.read(1) if len(body) < 16: raise ValueError("ConvolutionReverb: %r has a short fmt " "chunk" % (path,)) tag = _u16(body, 0) channels = _u16(body, 2) rate = _u32(body, 4) bits = _u16(body, 14) if tag not in (1, 0xFFFE) or bits != 16: raise ValueError( "ConvolutionReverb: %r is not 16-bit PCM (format %d, " "%d bits)" % (path, tag, bits)) if channels not in (1, 2): raise ValueError( "ConvolutionReverb: %r has %d channels; an impulse " "is mono or stereo" % (path, channels)) if rate != sample_rate: raise ValueError( "ConvolutionReverb: %r is a %d Hz impulse and the " "graph runs at %d Hz; an effect does not resample" % (path, rate, sample_rate)) elif name == b"data": if channels is None: raise ValueError("ConvolutionReverb: %r has its data " "before its fmt chunk" % (path,)) return handle.read(size), channels else: handle.seek(size + (size & 1), 1) raise ValueError("ConvolutionReverb: %r has no data chunk" % (path,))
def _byte_width(impulse, view): """Bytes per item of `view`: 1 for bytes-likes, 2 for an int16 array.""" width = getattr(view, "itemsize", None) if width is None: typecode = getattr(impulse, "typecode", None) width = 2 if typecode in ("h", "H") else 1 if width not in (1, 2): raise TypeError("ConvolutionReverb: impulse must be bytes-like int16 " "frames, or an int16 array") return width def _sum_squares(view, width, frames, channels, lane): """sum_k (h[k, lane] / 32768)^2 over `frames` frames of `view`. Every term is an exact binary fraction and, on a desktop, so is the sum, so every interpreter computes the same number from the same file. """ total = 0.0 if width == 2: for index in range(lane, frames * channels, channels): value = view[index] if value >= 32768: value -= 65536 value = value / 32768.0 total += value * value return total step = 2 * channels for index in range(2 * lane, frames * step, step): value = view[index] | (view[index + 1] << 8) if value >= 32768: value -= 65536 value = value / 32768.0 total += value * value return total
[docs] class ConvolutionReverb(_component.Component): """A room behind your dry signal, made by convolution: synthesized from five knobs, or the room your own impulse was recorded in. With nothing loaded the class synthesizes a short room from noise. By default the room is 0.08 s long. **The controls.** Decay is how long the room rings, Damping darkens its tail, Predelay puts silence between the dry and the room, and Diffusion fades the room in instead of starting it as a burst. Room picks one of 64 rooms of the same size. Damping runs from 500 Hz at its bottom stop to out at its top stop. At 22.05 kHz its brightest positions below the top stop clamp and all make the same room. Mix runs from 0 to 2: the dry at unity up to 1, the room alone at 2. With Damping out, each of the 64 Rooms falls 60 dB within 3 % of the Decay time. With Damping in, the 64 Rooms fall 60 dB within 2 % of the Decay time on average. A single Room with Damping in can take more than 15 % longer. A synthesized room plays through a level trim read off the room itself: none where the room brings a low square back 1 dB or more under 12 dB louder, and otherwise just enough to hold it to 12 dB, so the defaults play about 1 dB down at 48 kHz. One step of Decay or Damping moves the room's level by 0.5 dB at most. Anywhere on the knobs, a synthesized room alone is clean up to -13.5 dBFS in, and with the dry mixed in up to -15.5 dBFS, its input ceiling: the trim holds a low square's steady state at -12 dBFS, its onset rises about 1.3 dB past that, and the dry is not trimmed. Each side of a stereo room is normalised on its own, so the room sits in the middle. **Your own impulse.** Hand it `impulse=`, int16 frames or the path to a 16-bit PCM WAV at the graph's rate, and the room is that recording. The room is then your source convolved with the impulse at unit energy, within 1 LSB. `ir_gain_db` trims it from -24 to +12 dB, and `start_ms` cuts up to 200 ms from its start. Only Mix is live then: the other five knobs raise `IndexError`. A WAV at another rate raises `ValueError`, and so does an impulse with no energy or a `start_ms` that trims away every frame. An empty impulse, `impulse=b""`, is an undelayed wire whose Mix does nothing and whose `reset()` silences nothing. **The allocation.** `seconds` is the longest room the instance can hold, carved once when you build it: from 0.06 s up to 131 072 frames, and outside that the constructor raises `ValueError`. **Latency and tail.** `latency_samples` reads 256 while an impulse is loaded and 0 on the empty impulse. Held at Mix 0, the output is your source, byte for byte, `latency_samples` late, while the source keeps feeding it and nothing resets it. `tail_samples` is `latency_samples` plus the loaded room rounded up to a whole block of 256 frames. More than `tail_samples` frames after your input's last non-zero frame, the output is exact zero. **Moving the knobs.** No frame of your dry signal drops or repeats when you move a room knob, at any Mix, however many moves you make. From the end of the block in flight, the output is that of an instance that always had the new settings. A Mix move acts from the end of the block in flight, so Mix 0 reaches the plain source up to 256 frames late. `reset()` empties the room and returns to patch 0. With an impulse loaded, `reset()` in the middle of a stream silences the block in flight, 256 frames, dry included, and with Mix set back to 0 your source carries on on time after it. A host that calls `audiocore.reset_buffer` on the output does the same. **Limits shared by the family.** A control that jumps makes the output step: move it in small steps from the host if you need it smooth. When your source ends, the tail rings out as it would on silence. """ NAME = 'ConvolutionReverb' #: NaN is this option's own stop, not the default (documented above). _NAN_OWN = ('damping_hz',) DISPLAY_NAME = 'Convolution Reverb' CATEGORIES = ('Reverb',) VERSION = '0.1.0' TIER = _component.AUDIODSP REQUIRES = ("audioconvolve",) CAPABILITIES = () #: One partition, the loaded state. An instance reports what its node #: holds (`latency_samples` below): 0 on an empty impulse. LATENCY_SAMPLES = PARTITION TAIL_SAMPLES = None #: Where no synthesized setting reaches the rail, after `room_trim`, with #: the dry in. Measured on the kit's ceiling material (with its 163 Hz #: square) over 1600 settings drawn at random, every Room and both sides, #: at 48 and 22.05 kHz: the worst, Decay 83, Damping 40, Predelay 0, #: Diffusion 127, Room seed 17 at 48 kHz, is clean to -13.3 dBFS with the #: room alone and to -15.0 dBFS at Mix 1, where the dry adds to it; this #: rounds the second down. The trim holds `room_peak_gain`, a low square's #: steady state, at 12 dB; a square's onset rises about 1.3 dB past that. #: A loaded impulse brings its own level and `ir_gain_db` and is not #: covered. INPUT_CEILING_DBFS = -15.5 MACRO_LABELS = ("Decay", "Damping", "Predelay", "Diffusion", "Room", "Mix") MACRO_MODES = { 0: "UNIPOLAR", 1: "UNIPOLAR", 2: "UNIPOLAR", 3: "UNIPOLAR", 4: "UNIPOLAR", 5: "UNIPOLAR", } _MACRO_RANGES = ( (0.0, 1.0), # 0 Decay, law position (DAMPING_LOW_HZ, DAMPING_HIGH_HZ, "log"), # 1 Damping; top = out (0.0, 1.0), # 2 Predelay, position (0.0, 1.0), # 3 Diffusion, position (1.0, float(ROOMS)), # 4 Room, seed 1..64 (0.0, 2.0), # 5 Mix; dry unity to 1 ) _MACRO_UNITS = {1: "Hz"} #: `_component.macro_of` of the dossier's section 6 settings; patch 0 is #: the constructor's defaults on the grid. PATCHES = { 0: ("Full Room", (127, 117, 0, 64, 0, 38)), 1: ("Short Room", (38, 98, 13, 64, 4, 44)), 2: ("Late Room", (127, 124, 76, 64, 12, 51)), 3: ("Dark Room", (102, 52, 25, 64, 20, 44)), 4: ("Bright Room", (102, 127, 0, 32, 8, 51)), 5: ("Soft Onset", (127, 108, 38, 127, 24, 63)), 6: ("Tight Room", (0, 124, 25, 0, 2, 76)), 7: ("Wet Only", (127, 117, 0, 64, 0, 127)), } def _build(self, decay=1.0, damping_hz=6000.0, predelay=0.0, diffusion=0.5, room=1, mix=0.6, seconds=0.08, impulse=None, impulse_channels=1, ir_gain_db=0.0, start_ms=0.0, patch=None): #: True while several macros are applied at once (the constructor, #: `program_change`, `reset`); the room is synthesized once, after. self._deferred = True #: The synthesis tuple the node holds, or None. self._loaded = None #: The wet gain the node holds (`room_trim`). self._trim = 1.0 self._measured = impulse is not None rate = self._sample_rate if self._measured: self._node = self._load_impulse(impulse, impulse_channels, ir_gain_db, start_ms) else: seconds = float(seconds) taps = int(round(seconds * rate)) self._check_allocation(taps, seconds) self._seconds = seconds self._node = audioconvolve.Convolver( max_taps=self._partitions(taps) * PARTITION, ir_channels=self._channel_count, sample_rate=rate, channel_count=self._channel_count) # `clear()` drops the history and the block in flight and keeps the # impulse (`Convolver.c:230` at 0d35a90): a reset empties the room, # it does not rebuild it. self._own(self._node, reset=self._node.clear) self._node.play(self._source) self._output = self._node damping_hz = float(damping_hz) if not 0.0 < damping_hz < DAMPING_HIGH_HZ: damping_hz = DAMPING_HIGH_HZ # 0 (or the top) is out try: self._init_macros((decay, damping_hz, predelay, diffusion, room, mix), patch) finally: self._deferred = False self._refresh() # -- the allocation (D2) ------------------------------------------- def _partitions(self, taps): """Partitions for `taps`: the law, and never fewer than one.""" return max(1, (taps + PARTITION - 1) // PARTITION) def _check_allocation(self, taps, seconds=None): """Raise, naming the class and the limit, over the ceiling or (in synthesized mode) under the floor. The node's own `impulse is too long` never reaches the caller.""" rate = self._sample_rate if taps > CEILING_TAPS: raise ValueError( "%s: %d taps at %d Hz is over the ceiling of %d taps (%d " "partitions), %.3f s at this rate" % (self.NAME, taps, rate, CEILING_TAPS, MAX_PARTITIONS, _floor3(CEILING_TAPS / float(rate)))) if seconds is not None and not seconds >= FLOOR_SECONDS: raise ValueError( "%s: seconds=%r is under the floor of %.3f s, where Decay " "would have no travel" % (self.NAME, seconds, FLOOR_SECONDS)) # -- measured mode (D1) -------------------------------------------- def _trim_frames(self, start_ms): """Frames `start_ms` trims: int(start_ms * fs / 1000), truncated, with the product formed first so a whole-ms trim is exact.""" return int(start_ms * self._sample_rate / 1000.0) def _load_impulse(self, impulse, impulse_channels, ir_gain_db, start_ms): rate = self._sample_rate if isinstance(impulse, str): impulse, impulse_channels = read_wav(impulse, rate) if impulse_channels not in (1, 2): raise ValueError("%s: impulse_channels must be 1 or 2" % self.NAME) ir_gain_db = float(ir_gain_db) if not IR_GAIN_MIN_DB <= ir_gain_db <= IR_GAIN_MAX_DB: raise ValueError("%s: ir_gain_db=%r is outside %.0f..%+.0f dB" % (self.NAME, ir_gain_db, IR_GAIN_MIN_DB, IR_GAIN_MAX_DB)) start_ms = float(start_ms) if not 0.0 <= start_ms <= START_MAX_MS: raise ValueError("%s: start_ms=%r is outside 0..%.0f ms" % (self.NAME, start_ms, START_MAX_MS)) view = memoryview(impulse) if getattr(view, "ndim", 1) != 1: # A (frames, channels) array would otherwise fail at the trim's # slice with Python's bare NotImplementedError. raise TypeError("%s: impulse must be one-dimensional int16 " "frames; flatten a (frames, channels) array " "first" % self.NAME) width = _byte_width(impulse, view) size = len(view) * width if size % (2 * impulse_channels): raise ValueError("%s: impulse length must be whole int16 frames" % self.NAME) frames = size // (2 * impulse_channels) trim = self._trim_frames(start_ms) if frames and trim >= frames: # Clamping would build the unloaded wire, a Mix that does # nothing, with no error (ruling (o)). Only `impulse=b""` is # the deliberate empty room. raise ValueError( "%s: start_ms=%r trims %d frames at %d Hz and the impulse " "has %d; the trim leaves no room, and a Mix that does " "nothing" % (self.NAME, start_ms, trim, rate, frames)) if trim > frames: trim = frames frames -= trim per_frame = impulse_channels * (2 // width) view = view[trim * per_frame:] self._check_allocation(frames) self._seconds = frames / float(rate) room_channels = min(impulse_channels, self._channel_count) node = audioconvolve.Convolver( max_taps=self._partitions(frames) * PARTITION, ir_channels=room_channels, sample_rate=rate, channel_count=self._channel_count) if frames: energy = 0.0 for lane in range(room_channels): energy += _sum_squares(view, width, frames, impulse_channels, lane) if not energy > 0.0: node.deinit() raise ValueError( "%s: the impulse has %d frames and no energy; a silent " "room is a dead Mix" % (self.NAME, frames)) gain = (10.0 ** (ir_gain_db / 20.0) / (energy / room_channels) ** 0.5) node.load(view, impulse_channels, gain) return node # -- the laws (section 6) ------------------------------------------ def _value(self, index): return _component.macro_value(self._MACRO_RANGES[index], self._macros[index]) def _predelay_ms(self): span = (self._seconds - NODE_DECAY_FLOOR) * 1000.0 / 2.0 if span > PREDELAY_MAX_MS: span = PREDELAY_MAX_MS return self._macros[PREDELAY_I] * span def _decay_seconds(self, predelay_ms): room = self._seconds - predelay_ms / 1000.0 return NODE_DECAY_FLOOR * (room / NODE_DECAY_FLOOR) ** \ self._macros[DECAY_I] def _damping_hz(self): position = self._macros[DAMPING_I] if position >= 1.0: return 0.0 hz = _component.macro_value(self._MACRO_RANGES[DAMPING_I], position) ceiling = DAMPING_CLAMP * self._sample_rate if hz > ceiling: hz = ceiling return self._hz(hz) def _seed(self): return 1 + int(round(self._macros[ROOM_I] * (ROOMS - 1))) def _synthesis(self): """(decay s, damping Hz, predelay ms, diffusion ms, seed): what the node is handed for the current positions.""" predelay = self._predelay_ms() t60 = self._decay_seconds(predelay) span = t60 * 1000.0 / 4.0 if span > DIFFUSION_MAX_MS: span = DIFFUSION_MAX_MS return (t60, self._damping_hz(), predelay, self._macros[DIFFUSION_I] * span, self._seed()) # -- applying ------------------------------------------------------ def _apply_macro(self, index, position): del position if self._deferred: return if index == MIX_I: self._node.set(mix=self._value(MIX_I) * 0.5) return self._refresh() def _refresh(self): """Hand the node the room and the Mix. The room is re-synthesized only when its tuple differs from the one it holds.""" if not self._measured: room = self._synthesis() if room != self._loaded: # The new room's reading, taken before it is built, and its # trim set before the synthesis, so the block in flight fades # from the old room at its level to the new at its own. trim = self._room_trim(room) if trim != self._trim: self._node.set(wet_gain=trim) self._trim = trim self._node.synthesize(decay=room[0], damping_hz=room[1], predelay_ms=room[2], diffusion_ms=room[3], seed=room[4]) self._loaded = room # The node takes 0..1 and doubles it (`audiodsp_convolve.c:88`); # halving is a power of two, so it adds no rounding of its own. self._node.set(mix=self._value(MIX_I) * 0.5) def _room_trim(self, room): """The wet gain for the room `room` (a `_synthesis()` tuple): `room_trim` of the `room_peak_gain` the node reads for it, lifted by `OUT_LIFT_DB` with Damping out, wherever Mix is.""" peak = self._node.room_peak_gain_for( decay=room[0], damping_hz=room[1], predelay_ms=room[2], diffusion_ms=room[3], seed=room[4]) if room[1] == 0.0: peak *= _OUT_LIFT return room_trim(peak) def _apply_positions(self, positions, patch_index): """Apply a patch (or a rack's restore) whole, then synthesize once. In measured mode only its Mix is audible; the synthesis positions are stored and inert. Inside the constructor the one synthesis is the constructor's own.""" outer = self._deferred self._deferred = True try: _component.Component._apply_positions(self, positions, patch_index) finally: self._deferred = outer if not outer: self._refresh() def _macro_index(self, index): index = _component.Component._macro_index(self, index) if self._measured and index != MIX_I: raise IndexError( "%s holds a measured impulse, so macro %d %r is not live: the " "loaded impulse is the room, and only Mix (macro %d) is" % (self.NAME, index, self.MACRO_LABELS[index], MIX_I)) return index # -- the reads ----------------------------------------------------- @property def node(self): """The one `audioconvolve.Convolver` this class built.""" self._check_live() return self._node @property def measured(self): """True when an impulse was given: the room is that impulse.""" self._check_live() return self._measured @property def live_macros(self): """The macro indexes this instance has: all six synthesized, only Mix (5) in measured mode.""" self._check_live() if self._measured: return (MIX_I,) return (DECAY_I, DAMPING_I, PREDELAY_I, DIFFUSION_I, ROOM_I, MIX_I) @property def seconds(self): """The allocation asked for; in measured mode, the trimmed impulse's own length.""" self._check_live() return self._seconds @property def allocated_seconds(self): """The allocation actually held: partitions x 256 / fs.""" self._check_live() taps = self._partitions(int(round(self._seconds * self._sample_rate))) return taps * PARTITION / float(self._sample_rate) @property def decay_seconds(self): """The room's T60 by the Decay law, or None in measured mode.""" self._check_live() if self._measured: return None return self._synthesis()[0] @property def latency_samples(self): """256 whenever the node holds an impulse, 0 when it holds none, read from the node.""" self._check_live() return self._latency() def _latency(self): """`latency_samples` as a plain method, so a subclass can reach it on MicroPython, whose `property` has no `fget`.""" return int(self._node.latency) @property def tail_samples(self): """`latency_samples` plus the loaded impulse rounded up to a partition; 0 when nothing is loaded.""" self._check_live() taps = int(self._node.taps) if not taps: return 0 return self._latency() + taps