audioeffects.convolutionreverb

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.

audioeffects.convolutionreverb.PARTITION = 256

One partition, in frames; the node’s FRAMES.

audioeffects.convolutionreverb.MAX_PARTITIONS = 512

58-60`), and in taps. It is the same count of taps at every rate.

Type:

The node’s ceiling in partitions (`audiodsp_convolve.h

audioeffects.convolutionreverb.FLOOR_SECONDS = 0.06

under it Decay, which runs from the node’s 50 ms floor, would have no travel.

Type:

The shortest allocation the class builds

audioeffects.convolutionreverb.NODE_DECAY_FLOOR = 0.05

183` at 0d35a90) and its clamps on predelay and diffusion (:184, :185), in seconds and milliseconds.

Type:

The node’s shortest decay (`audiodsp_convolve.c

audioeffects.convolutionreverb.DAMPING_LOW_HZ = 500.0

just under fs / (2 pi), where the node’s exp_small stops moving the coefficient.

Type:

Damping’s span, log, and the clamp as a fraction of the rate

audioeffects.convolutionreverb.IR_GAIN_MIN_DB = -24.0

ir_gain_db and start_ms spans, measured mode.

audioeffects.convolutionreverb.ROOMS = 64

1 + round(position * 63), 64 rooms.

Type:

Room seeds

audioeffects.convolutionreverb.TRIM_PEAK_DB = 12.0

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

audioeffects.convolutionreverb.OUT_LIFT_DB = 3.15

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.

audioeffects.convolutionreverb.room_trim(peak_gain)[source]

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.

audioeffects.convolutionreverb.read_wav(path, sample_rate)[source]

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

class audioeffects.convolutionreverb.ConvolutionReverb(source, *options, **keywords)[source]

Bases: 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'

The stable provider name audioeffects.create() discovers.

TIER = 'audiodsp'

STOCK or AUDIODSP, with REQUIRES naming the audiodsp-own modules an AUDIODSP class needs.

Type:

roadmap §3

CAPABILITIES = ()

The contract’s static reads. CAPABILITIES names "tempo_sync" if and only if the class reads self._transport().

LATENCY_SAMPLES = 256

One partition, the loaded state. An instance reports what its node holds (latency_samples below): 0 on an empty impulse.

INPUT_CEILING_DBFS = -15.5

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.

MACRO_LABELS = ('Decay', 'Damping', 'Predelay', 'Diffusion', 'Room', 'Mix')

Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 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))}

_component.macro_of of the dossier’s section 6 settings; patch 0 is the constructor’s defaults on the grid.

property node

The one audioconvolve.Convolver this class built.

property measured

True when an impulse was given: the room is that impulse.

property live_macros

The macro indexes this instance has: all six synthesized, only Mix (5) in measured mode.

property seconds

The allocation asked for; in measured mode, the trimmed impulse’s own length.

property allocated_seconds

The allocation actually held: partitions x 256 / fs.

property decay_seconds

The room’s T60 by the Decay law, or None in measured mode.

property latency_samples

256 whenever the node holds an impulse, 0 when it holds none, read from the node.

property tail_samples

latency_samples plus the loaded impulse rounded up to a partition; 0 when nothing is loaded.