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_smallstops 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_dbandstart_msspans, 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, toTRIM_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; aboveTRIM_PEAK_DB + TRIM_KNEE_DBit 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_gainispeak_gain: 1.0 up to the knee, then down by the excess overTRIM_PEAK_DB, through a quadratic soft kneeTRIM_KNEE_DBeither 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 atsample_rate.The file is read once;
datais thedatachunk’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:
ComponentA 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_dbtrims it from -24 to +12 dB, andstart_mscuts up to 200 ms from its start. Only Mix is live then: the other five knobs raiseIndexError. A WAV at another rate raisesValueError, and so does an impulse with no energy or astart_msthat trims away every frame. An empty impulse,impulse=b"", is an undelayed wire whose Mix does nothing and whosereset()silences nothing.The allocation.
secondsis 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 raisesValueError.Latency and tail.
latency_samplesreads 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_sampleslate, while the source keeps feeding it and nothing resets it.tail_samplesislatency_samplesplus the loaded room rounded up to a whole block of 256 frames. More thantail_samplesframes 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 callsaudiocore.reset_bufferon 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.
CAPABILITIESnames"tempo_sync"if and only if the class readsself._transport().
- LATENCY_SAMPLES = 256
One partition, the loaded state. An instance reports what its node holds (
latency_samplesbelow): 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 holdsroom_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 andir_gain_dband 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_ofof the dossier’s section 6 settings; patch 0 is the constructor’s defaults on the grid.
- property node
The one
audioconvolve.Convolverthis 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_samplesplus the loaded impulse rounded up to a partition; 0 when nothing is loaded.