SD-Reverb signal path

Every stage from an input sample to an output sample written as arithmetic, with the constants, the smoothing, the sample-rate dependences and a measured check.

46 minutes read

9635 words

This page follows a stereo signal through SD-Reverb, from the sample the host hands in to the sample the host takes back. Every operation on the way is written down as arithmetic. Each stage is described twice, first in words and then in symbols. The symbols are the specification and the words are what the symbols mean.

Everything here is derived from the source code as it stands at commit 4ec3060, dated 4 September 2026. No documentation, website text or memory of earlier versions was used. Where a number is quoted, the file it comes from is given. A handful of the predictions are checked at the end against an impulse response, rendered by the repository’s own offline tool.

The mathematics assumes only the ground covered by the Fundamentals section, and each page of it is named where it is first needed. Building a morphing reverb covers the same plugin as a route in, from what a room does to sound through to the design decisions. Reading it first is optional.

The path in outline

A reverb takes a sound and adds to it the reflections a room would have added. SD-Reverb builds those reflections from delayed copies of the input. Those copies are fed back on themselves, mixed together, and made a little quieter and a little duller on every trip round the loop. The input reaches that loop through a short chain of preparation stages, and the result is blended with the untouched input at the end.

The dry signal is scaled at the very end and nowhere else. No stage filters it, delays it or widens it. Everything upstream of the mix is the wet signal.

The two stages that do most of the work are the early stage and the late field. Both are the same kind of object, a feedback delay network. That is a set of delay lines whose outputs are mixed by a matrix and written back into the lines. The early stage is a small one, with three lines and heavy loss per trip, and it produces a handful of distinct echoes. The late field is a larger one, with six lines and small loss per trip, and it produces the dense, slowly fading wash.

Samples, blocks and chunks

A digital audio signal is a list of numbers. Each number is the air pressure at one instant, and the instants are equally spaced. At a sample rate of $f_s = 48\,000$ samples per second, consecutive numbers are $1/48\,000$ of a second apart. Signals and samples explains this from the start. This page needs only two ideas. A signal is a sequence $x[n]$ indexed by an integer $n$ , and a delay by $D$ samples means using $x[n-D]$ in place of $x[n]$ .

SD-Reverb works on two such sequences at once, a left channel $x_L[n]$ and a right channel $x_R[n]$ . The numbers are 32-bit floating point, nominally in the range $-1$ to $+1$ . The host does not deliver them one at a time but in blocks of some hundreds or thousands of samples (Reverb.cpp). Inside, the reverb cuts each block into chunks of at most 64 samples. Some things happen once per chunk, such as parameter smoothing and advancing the slow modulations. The audio arithmetic itself happens once per sample.

When the host changes a parameter in the middle of a block, the shells split the block at that sample and call the reverb twice. A change therefore lands exactly where the host asked (src/clap/Plugin.cpp). The reverb never sees this. It only ever sees a run of samples and the current parameter values.

All arithmetic on audio is done in single precision. Coefficients are computed in double precision when a parameter changes and then stored as single precision.

Notation

Parameters are written by their panel names. All of them except Mode, Decay, Predelay, Low Cut, Morph Rate and Trim are plain numbers from 0 to 1. Decay is in seconds, Predelay in milliseconds, Low Cut in hertz and Morph Rate in hertz. Tone Tilt runs from $-1$ to $+1$ and Trim is in decibels. Mode is one of Hall, Chamber, Cathedral and Drift, numbered 0 to 3. The host sees some of these through a curve, and the section on parameter smoothing lists them. The reverb itself only ever receives the real units.

The front end

The source is Reverb::process in src/dsp/Reverb.cpp.

The dry copy

The first thing the reverb does with each input sample is keep a copy of it.

That copy is what dry means in the mix at the end. Nothing below touches it.

Low cut

Very low frequencies build up in a reverb and turn to mud. The wet path therefore starts with a filter that removes what lies below a chosen frequency and leaves everything above it. The dry signal keeps its low end, and only what enters the room is thinned.

The filter is a one-pole high-pass. The page on one-pole filters, shelves and all-passes builds it from the smoothing recurrence. Per channel, with a state $s[n]$ that starts at 0,

and the same for the right channel with its own state. The state $s$ is a running average of the input that follows slow changes and ignores fast ones. Subtracting it from the input leaves the fast changes. The coefficient sets where slow ends and fast begins.

Here $f_{\mathrm{lc}}$ is the Low Cut frequency, clamped to 20 to 500 Hz (Reverb.cpp). At the default 80 Hz and $f_s = 48\,000$ , $c_{\mathrm{lc}} = 0.010417$ . The response to a steady sine of frequency $f$ has magnitude

which is 0 at $f = 0$ , about $1/\sqrt 2$ at $f = f_{\mathrm{lc}}$ , and rises towards 1 above it. The coefficient rather than the frequency is what the parameter smoother glides.

Pre-delay

In a real hall the first reflection arrives some milliseconds after the direct sound, because the walls are further away than the source. Predelay holds the wet signal back by 0 to 200 ms before any of the reflections are built. That keeps the reverb from smearing the attack of the dry sound. The delay can be a fraction of a sample. When the control is moved the delay length glides rather than jumps, so there is no click.

The target delay in samples is $P^\star = f_s \cdot t_{\mathrm{pd}} / 1000$ for a Predelay of $t_{\mathrm{pd}}$ milliseconds, clamped to 0 to 200. The delay actually applied at sample $n$ follows it with a per-sample recurrence.

Each sample closes one two-thousandth of the distance still to go. A change therefore settles with a time constant of 2000 samples, or 41.7 ms at 48 kHz.

At $P[n] < 1$ the pre-delay line is bypassed entirely and $p_L[n] = a_L[n]$ , with the line neither read nor written. Otherwise the line is read at the fractional position $P[n]$ , and the new input is then written at the head. Reading between samples uses four neighbours and a cubic Hermite curve through them (src/dsp/InterpolatedDelayLine.hpp). With $D = \lfloor P[n] \rfloor$ and $\mu = P[n] - D$ the fractional part, take the four stored samples around the target position,

and evaluate the cubic from the inside out.

At $\mu = 0$ this returns $y_0 = a[n-D]$ exactly and at $\mu = 1$ it returns $y_1 = a[n-D-1]$ exactly. In between it draws a curve whose slope at each end matches the slope of the neighbouring samples. So $p[n]$ is $a$ delayed by $P[n]$ samples, to a close approximation, for any $P[n]$ .¹

The pre-delay’s memory is written with the low-cut signal $a$ , so the two stages compose. The early stage receives the input with its lows removed and then held back.

The level follower

The last thing the front end does is watch how loud the signal entering the reflection stages is. This changes no audio. It produces one number per chunk, the morph velocity scale $\sigma$ (src/dsp/AdaptiveMorphRate.hpp). The section on the trajectory uses it to slow the movement of the late field while the input is loud.

Per sample the level is the larger of the two channels’ magnitudes, $\ell[n] = \max(|p_L[n]|, |p_R[n]|)$ . An envelope $\varepsilon$ follows it with a fast attack and a slow release.

The first case is the attack, at 50 ms, and the second the release, at 1.2 s.

So $\sigma$ is 1 in silence and falls to $1 - \textit{Morph Adapt}$ once the envelope reaches $0.25$ , which is about $-12$ dBFS. The value used for the chunk is the one computed at its last sample. With Morph Adapt at 0 the scale is exactly 1 whatever the input, which is the constant-rate morphing guarantee the tests pin.

The early reflections stage

The source is src/dsp/EarlyReflections.cpp.

The first reflections off the nearest walls arrive as a few distinct echoes, one after another, each a little quieter. SD-Reverb makes them with three short delay lines of 6 to 26 ms at the default Size, depending on Mode. The input is written into the lines, and what comes out of them after their delay is the stage’s output. That output is also scaled down to 40 per cent, mixed across the three lines, and written back in. Each echo therefore spawns a few fainter echoes before dying away after a few trips. The stage produces a handful of reflections rather than a tail, and the test at tests/test_early.cpp checks exactly that.

Call the three lines’ stored sequences $q_0, q_1, q_2$ and their delays $E_0, E_1, E_2$ samples. Per sample the stage reads the three delayed values $v_i = q_i[n - E_i]$ and forms the stereo output from them.

It then scales by the feedback, $v \leftarrow 0.4\,v$ , and mixes the three lines with a Householder reflection $A_3 = I - 2\,u u^{\mathsf T}$ , where $u$ is a unit vector.

Last, it adds the input and writes the result back at the head of each line.

Those five steps together say that line 0 receives half the left input, line 1 half the right, and line 2 half the difference. The left output listens to lines 0 and 2, and the right output to lines 1 and 2 with the sign of line 2 flipped. Written as one recurrence,

The output is read before the input is written, so there is no zero-delay path. The first thing the early stage emits is the first delay $E_{\min}$ samples after the input arrived. Each further trip round the loop multiplies by $0.4$ , which is about $-8$ dB, so after four trips a reflection is down by more than 30 dB.

Each Mode has a table of three lengths in samples, written for 48 kHz (src/dsp/tables/DelaySets.hpp), and Size scales them.

Size 0 halves every length and Size 1 multiplies it by 1.5. The tables are in samples rather than milliseconds, and the section on sample rate says what that means at other rates.

The mixing vector $u$ is not fixed. It moves slowly around the balanced direction $(1,1,1)/\sqrt3$ , at a third of the late field’s Morph Rate and with $0.7$ times its Morph Depth. The section on the trajectory gives the path. The early stage uses whatever vector it is handed at the start of each chunk.

Input diffusion

The source is src/dsp/AllpassDiffuser.hpp, with the blend in Reverb.cpp.

The early stage’s output is what feeds the late field. Before it gets there it passes through a chain of eight all-pass stages per channel. An all-pass filter changes when energy arrives without changing how much of each frequency there is. A single click going in comes out as a cluster of smaller clicks spread over some milliseconds. A steady tone comes out at exactly the same level. This smears the input in time, so the late field is fed something already dense and starts its wash sooner. The Diffusion knob blends between the plain early output at 0 and the fully smeared version at 1. The direct early output that goes to the wet mix is taken before this stage. The first reflections therefore stay crisp whatever Diffusion is set to.

One stage with delay $M$ samples and coefficient $g$ keeps a delay line $w$ .

Its transfer function and magnitude response are

the second because numerator and denominator on the unit circle are complex conjugates up to a factor of unit modulus. Its response to a single impulse is a first echo of $-g$ at once, then $(1-g^2)$ after $M$ samples, then $g(1-g^2)$ after $2M$ . Each one is $g$ times the last. At $g = 0.7$ that is $-0.70,\ 0.51,\ 0.357,\ 0.250$ and onward, whose squares sum to exactly 1.

The eight stages are in series, each channel with its own delays, rounded from milliseconds.

The coefficient is $g = 0.7$ for every stage, and the reverb never changes it. The chain’s transfer function is the product of the eight, still of unit magnitude. Its impulse response is the eight single responses convolved together, a cluster lasting some tens of milliseconds whose direct term is $(-0.7)^8 = 0.0576$ .

With $h_L$ the chain’s output and $\delta$ the effective diffusion, the late field receives

and likewise on the right. For $\delta$ strictly between 0 and 1 the combination $(1-\delta) + \delta\,H_{\mathrm{ap}}$ is not itself all-pass. Its magnitude varies with frequency between $|1 - 2\delta|$ and 1. Only the two ends of the knob are exactly neutral in level.

The effective diffusion is the knob raised by a floor. A long decay with little diffusion lets individual delay lines ring as audible pitches, so the reverb raises a floor under the knob as Decay grows.

Here $T$ is the smoothed Decay in seconds. There is no floor up to 4 s, and it rises to 0.5 at 8 s and beyond. The same $\delta$ also shapes the late field’s mixing vector.

The late field

The source is src/dsp/FDN.cpp, with src/dsp/MultibandDamping.cpp, src/dsp/FeedbackNonlinearity.hpp, src/dsp/RoomTone.hpp and src/dsp/HouseholderMatrix.hpp.

The late field is six delay lines in a loop, 15 to 180 ms long at the default Size depending on Mode. Over the whole Size range that is 7.5 to 270 ms. What comes out of each line is sent to the output, which is the reverb tail a listener hears. The same value is also made quieter, by a factor chosen so that the tail takes exactly Decay seconds to fall by 60 dB. The bass loses less per trip and the treble loses more. A gentle limiter that does nothing at normal levels comes next, then a barely audible whisper of filtered noise when Air Level is up. Last, a matrix that conserves the total energy mixes the value with the other five. The six results are written back into the lines together with the new input.

Six lines whose lengths share no common factor produce echoes that never line up, so the sum sounds smooth rather than fluttery. Every trip round the loop loses a fixed fraction, so the tail is an exponential decay. The fraction depends on frequency, so the tail’s colour decays too.

Call the lines’ stored sequences $\ell_0, \dots, \ell_5$ and their delays $D_0, \dots, D_5$ . Per sample, the field runs seven steps in this order. Step one reads the lines.

Step two takes the output taps, before anything else touches $v$ .

Step three applies the damping, per line, which is a frequency-dependent gain below 1.

Step four applies the soft limit, per line.

Step five adds the room tone, per line, and only when Air Level is above 0.

Step six mixes, with the Householder reflection $A = I - 2 r r^{\mathsf T}$ and $\lVert r \rVert = 1$ .

Step seven injects the input and writes the lines back.

When Entry Drift is off, $B(t)$ is the fixed matrix

The left input enters lines 0, 2 and 4 with line 2 inverted, and the right enters lines 1, 3 and 5 with line 3 inverted, each at half amplitude. The output taps read lines 0, 1 and 2 for the left and 3, 4 and 5 for the right. Each output channel therefore hears two lines fed by one input channel and one fed by the other. That asymmetry is what makes the two outputs differ from each other while both channels share one network.

The delays

As for the early stage, each Mode has a table for 48 kHz scaled by Size.

Every table is pairwise coprime, meaning no two entries share a factor, which keeps the echo pattern from repeating early. The rounding in equation (29) does not preserve that property at other Size settings. The longest possible delay is $8641 \times 1.5 = 12\,962$ samples, inside the 32768-sample buffers each line allocates.

Damping and the three bands

Sound in a room loses energy at every wall and in the air, and it loses more of its high frequencies than its low ones. SD-Reverb copies this by giving each line a gain below 1 that differs in three frequency regions, below about 250 Hz, between 250 and 4000 Hz, and above 4000 Hz. The middle region’s gain is set so that the tail falls 60 dB in exactly Decay seconds. The low region decays 1.3 times slower than that. The high region decays faster, by a margin that grows with Size. Air absorbs treble per metre travelled, so a bigger room loses more of it. Tone Tilt leans the whole curve darker or brighter.

A sample circulating in line $i$ makes one trip every $D_i$ samples, which is every $D_i / f_s$ seconds, and is multiplied by $g_i$ each trip. After $T$ seconds it has made $T f_s / D_i$ trips and is at $g_i^{\,T f_s / D_i}$ of its starting value. Requiring that to be $10^{-3}$ , which is $-60$ dB, gives the sixty-decibel gain .

Longer lines get a smaller $g_i$ so that all six decay at the same rate per second. At the Hall defaults, with $T = 2.4$ s, the six values are $0.944, 0.927, 0.841, 0.830, 0.817, 0.761$ .

The three bands get three decay times, $T$ , $T m_{\mathrm{lo}}$ and $T m_{\mathrm{hi}}$ .

Here $\tau$ is Tone Tilt. With the tilt at 0, the highs decay in $0.9\,T$ at Size 0 and $0.55\,T$ at Size 1. From the three times come three gains by equation (30), and the filter is built from their ratios.

The ratio $\gamma^{\mathrm{lo}}$ is slightly above 1, holding the lows up relative to the mids, and $\gamma^{\mathrm{hi}}$ is slightly below.

The filter is two shelves , each built from one one-pole low-pass, followed by the mid gain. With two states $s^{\mathrm{lo}}_i$ and $s^{\mathrm{hi}}_i$ per line,

Equation (33) adds $(\gamma^{\mathrm{lo}} - 1)$ times the low-passed signal. Below the corner the low-pass passes everything, so the gain there is $\gamma^{\mathrm{lo}}$ , and above it the low-pass passes nothing, so the gain is 1. Equation (34) adds $(\gamma^{\mathrm{hi}} - 1)$ times the high-passed signal, which is the input minus the low-pass, so the gain is 1 below the corner and $\gamma^{\mathrm{hi}}$ above. The corners are 250 Hz and 4000 Hz, with coefficients as in equation (3).

Both values are for $f_s = 48\,000$ . As a transfer function, with $L_c(z) = c / (1 - (1-c) z^{-1})$ the one-pole low-pass,

At $f = 0$ this is exactly $g_i^{\mathrm{mid}}\gamma_i^{\mathrm{lo}}$ , the low band’s target. At the highest representable frequency, $f_s/2$ , the one-pole low-pass is not quite zero but $c/(2-c)$ , which is 0.016 for the low corner and 0.256 for the high one. The high band’s gain is therefore approached rather than reached. For the longest Hall line the target is 0.686 and the value at $f_s/2$ is 0.706. The repository’s own test allows 5 per cent at the top of the band. The section on measurements shows what that does to a measured decay time.

Putting the three regions side by side at the Hall defaults, with Decay 2.4 s, Size 0.5 and tilt 0:

The transitions are gradual, an octave or so wide on each side of the corner, because a one-pole filter is gentle.

The soft limit

If anything ever pushed the loop’s level far above normal, such as an extreme Decay with a very loud input, the values could grow without bound. A gentle curve applied to each line value makes that impossible. It is indistinguishable from a straight line for values below about 1, bends over for larger ones, and never lets anything through above 2. In normal use it does nothing measurable.

The threshold is $\Theta = 3$ (src/dsp/FeedbackNonlinearity.hpp).

Its slope is $\phi'(x) = 1 - x^2/\Theta^2$ , which is 1 at zero and falls to 0 at $\pm\Theta$ , where the curve meets the flat part with no kink. So $\phi$ never amplifies, since $|\phi(x)| \le |x|$ and $0 \le \phi' \le 1$ . That is what lets the stability argument below count it as harmless. At $x = 0.1$ it returns $0.09996$ , at $x = 1$ it returns $0.963$ , at $x = 2$ it returns $1.704$ , and at $x \ge 3$ exactly 2.

Room tone

A real room carries a floor of quiet air movement. When Air Level is above 0, each line has a tiny amount of soft noise added to it inside the loop. The noise therefore circulates through the loop and picks up the room’s colour, in the way any other content of the loop does. At the default Air Level of 0.30 it sits about 80 dB below full scale, far under the tail it rides on. Air Motion makes its level breathe slowly, over a cycle of about 6.7 seconds. At Air Level 0 the step is skipped entirely.

Each line $i$ has its own noise generator $\nu_i$ , from six different seeds, built in three parts (src/dsp/RoomTone.hpp). A 32-bit xorshift generator produces a pseudo-random integer $S$ each sample, and the top 24 bits are mapped to a number $\xi$ in $[-1, 1)$ . This is white noise, with every frequency equally present.

Three one-pole low-passes with different corners are then summed with a direct term, which tilts the spectrum towards pink .

The three pole radii correspond to corners of about 18 Hz, 288 Hz and 4.3 kHz at 48 kHz. They scale with the sample rate. A one-pole low-pass at 8 kHz then takes the edge off, with $\nu_i \leftarrow \nu_i + c_{8\mathrm k}\,(\pi_{\mathrm k} - \nu_i)$ and $c_{8\mathrm k} = 1 - e^{-2\pi\cdot 8000/f_s}$ .

The amplitude is common to all six lines and wanders with a sine at 0.15 Hz.

So $\lambda = 10^{-4}$ , which is $-80$ dBFS, at the default. With Air Motion at 1 the level swings between $0.1\lambda$ and $1.9\lambda$ .

The noise is added in step five, after damping and before the mixing matrix. Its first appearance in the output is therefore only after it has been mixed and delayed. From then on it decays and re-enters like any other content of the loop.

The moving mixing matrix

The source is src/dsp/HouseholderMatrix.hpp and src/dsp/MatrixMorph.hpp.

The matrix

After damping, the six line values are mixed, so that each line’s next input is a combination of all six. The rule has to conserve energy, or the loop would either die faster than Decay says or run away. SD-Reverb uses a reflection , which mirrors the six-dimensional vector of line values in the plane perpendicular to a chosen direction $r$ . A mirror image is exactly as long as the original, which is the conservation needed.

With a unit vector $r$ ,

The second form is how it is computed. It is one dot product and one scaled subtraction, twelve multiplications for six lines, and the 36 matrix entries are never written down. Three properties follow, each pinned by a test in tests/test_matrix.cpp. The length $\lVert A v \rVert$ equals $\lVert v \rVert$ for every $v$ , so energy is conserved. Applying $A$ twice gives $A\,A = I$ . The direction $r$ is flipped, with $A\,r = -r$ , and $A\,v = v$ whenever $v$ is perpendicular to $r$ .

Any unit vector gives a valid matrix. The balanced vector $r = (1,1,1,1,1,1)/\sqrt6$ gives $A = I - \tfrac13 J$ , where $J$ is the all-ones matrix. Every line then receives $\tfrac23$ of its own value minus $\tfrac13$ of each other line, which is the maximum mixing. A vector concentrated on one line, $r = (1,0,0,0,0,0)$ , gives $A = \operatorname{diag}(-1,1,1,1,1,1)$ and no mixing at all. Each line then feeds only itself and the network is six independent comb filters.

The Diffusion knob, through $\delta$ of equation (20), chooses a base vector between those two.

The value at $\delta = 1$ is the balanced vector, and at $\delta = 0$ it is the concentrated one. Halfway between, at $\delta = 0.5$ , it reads $(0.839, 0.243, \dots, 0.243)$ .

The trajectory

A fixed matrix gives a fixed set of resonances. A tail that lasts seconds can then reveal them as a faint metallic ring. SD-Reverb moves the vector $r$ slowly around a closed loop near the base vector. Morph Rate sets the cycles per second and Morph Depth sets the amount. Every point on the loop is a unit vector, so the matrix is exactly energy-conserving at every instant. The movement therefore changes which resonances are excited without changing how fast the tail decays. The measurement below confirms this, with the decay time varying by under 3 per cent across the loop.

The loop is built from $K$ anchor directions, with $K = 6$ for the late field and $K = 4$ for the early stage and Entry Drift.

Here $\bar a_k$ is the mean over $i$ , subtracted so that each anchor sums to zero. Each anchor is pushed away from the base vector by a per-mode spread $\rho$ and normalised.

A phase $\varphi$ in $[0,1)$ advances once per chunk of $m$ samples, gated by the velocity scale $\sigma$ of equation (10).

That happens only when both $f_{\mathrm{morph}} > 0$ and Morph Depth is above 0. Otherwise $\varphi$ stays where it is. The current vector is then

The operation $\operatorname{slerp}$ is spherical linear interpolation , the way to move between two unit vectors along the sphere rather than along the chord. With $\Omega = \arccos(a \cdot b)$ ,

and at $\Omega < 10^{-5}$ the code uses ordinary straight-line interpolation followed by normalisation. Every result has unit length, so $A$ is always exactly a reflection.

The phase therefore walks round the polygon $L_0 \to L_1 \to \dots \to L_{K-1} \to L_0$ on the sphere, and Morph Depth pulls the point back towards the base vector. Depth 0 means staying at $r_0$ and depth 1 means following the polygon. At Morph Depth exactly 0 the code returns $r_0$ without computing anything, which is why a rate change at depth 0 is bit-for-bit inaudible.

Two facts about the anchors follow from equation (44). Take $k = K - 1$ , the last anchor, with $K = N$ . The argument of the sine is then $2\pi(i+1)$ plus a constant. The same holds for $k = 2$ when $N = 3$ and $K = 4$ . The sine is then the same for every $i$ , and subtracting the mean leaves exactly zero. So one anchor of every loop is the base vector itself, and the loop passes through $r_0$ once per cycle. At the Hall spread of 0.35 with $\delta = 1$ , the other five late anchors sit 26 to 31 degrees from the base vector.

Both the late and early trajectories are advanced with the same $\sigma$ . The Entry Drift trajectory always advances with $\sigma = 1$ . The late field’s base vector is rebuilt every chunk from the smoothed $\delta$ , so turning Diffusion moves the whole loop.

Entry Drift

The source is src/dsp/InputMatrixMorph.hpp, with the crossfade in FDN.cpp.

With the injection matrix $B_0$ of equation (28) fixed, the same note played twice excites the room the same way twice. Entry Drift slowly changes which of the six lines the input enters, and by how much, so that the second note takes a slightly different door. It never changes how loud the input is, and it is kept from moving the stereo image. The three lines the left channel feeds are rotated among themselves, and the three the right channel feeds likewise, by the same 3 by 3 reflection.

A unit vector $u_B(t)$ on a $K = 4$ trajectory of its own defines $R_3 = I - 2 u_B u_B^{\mathsf T}$ . Given the input pair, the static injection $\iota = B_0\,[f_L, f_R]^{\mathsf T}$ is formed first, and the two triples are then reflected separately.

Because $R_3$ is a reflection, each triple keeps its length. The left channel’s total injection is $\tfrac{\sqrt3}{2}|f_L|$ before and after, whatever $u_B$ is, and tests/test_entrydrift.cpp checks this to $10^{-4}$ .

One consequence of using a reflection is that $R_3$ is never the identity. Even at the smallest non-zero depth, where $u_B$ is the balanced vector $(1,1,1)/\sqrt3$ , the left triple $(\tfrac12, -\tfrac12, \tfrac12)\,f_L$ becomes $(\tfrac16, -\tfrac56, \tfrac16)\,f_L$ . Switching the feature on therefore moves the entry pattern to a different fixed pattern of the same strength, and the trajectory then wanders around that one. The switch itself is covered by a 30 ms linear crossfade $a$ between the static and the reflected injection.

When Entry Drift returns to 0 the fade runs back to 0 and the static code path is taken again. With the feature at 0, Entry Rate has no effect on the output at all.

Stability of the loop

A feedback loop is safe when every trip round it loses energy. Three of the late field’s steps cannot add energy, and one always removes some. Together that is enough.

Look at what one pass of steps three to seven does to the vector $v$ of six line values. Ignore the input and the room tone for the moment. The reflection at step six leaves $\lVert v \rVert$ unchanged by equation (42). The soft limit at step four never increases any component, because $|\phi(x)| \le |x|$ . The damping at step three is a linear filter per line whose gain at every frequency is below 1. From equation (37) the low shelf’s magnitude lies between $\gamma^{\mathrm{lo}}$ and about 1, and the high shelf’s between about 1 and $\gamma^{\mathrm{hi}}$ . So $|H_i| \le g_i^{\mathrm{mid}}\max(\gamma_i^{\mathrm{lo}}, 1) < 1$ whenever Decay is finite. The product $g_i^{\mathrm{mid}}\gamma_i^{\mathrm{lo}}$ is the low band’s own gain $10^{-3D_i/(T m_{\mathrm{lo}} f_s)}$ , below 1 for any line length and any finite Decay, the largest of 50 s included. The delay lines themselves only store values.

The energy in the loop is therefore multiplied by a factor below 1 every circulation, and with no input it decays geometrically to zero. The tests hold the tail below $10^{-6}$ after 10 s of silence with a 2 s Decay, and finite for a full-scale impulse train at Decay 50 s. With input, the loop’s content is the sum of a decaying copy of every input sample that ever entered. That is exactly what a reverb tail is. The room tone is a bounded input like any other. This argument does not depend on $r$ being fixed, which is why the morphing above is free.

Iterating a matrix is the general statement of this. A map that is a length-keeping matrix times a gain below 1 has orbits whose length follows that gain.

Wet signal, width, mix and trim

The early stage’s direct output and the late field’s output are summed, the former scaled by Early Level.

If an engine crossfade is running, this sum is formed for both engines and blended. The stereo image is then adjusted in mid and side form.

Width 1 leaves the signal unchanged and 0 collapses it to mono, with both channels equal to $m$ . The default of 0.8 shrinks the difference between the channels to 80 per cent. This applies to the wet signal only.

Dry and wet are blended with an equal-power law .

Here $\eta$ is the smoothed Enabled value, which is 1 when on. Because $\cos^2 + \sin^2 = 1$ , the total power stays constant across the knob when dry and wet are unrelated signals, which they are. At Mix 0.5 both gains are $0.707$ , and at the default 0.3 they are $0.891$ and $0.454$ .

The same holds for the right. Trim is clamped to $\pm 24$ dB, a factor of 15.85 either way, and is applied after the mix, so it scales the dry signal too.

When the Enabled switch is turned off, $\eta$ ramps towards 0 through the same per-chunk smoother as Mix. The wet signal fades out over about 22 chunks, which is 29 ms at 48 kHz. Once $\eta \le 10^{-4}$ the wet path is not computed at all. The reverb’s memory is cleared and the output is $G_{\mathrm{trim}}\,x$ until the switch returns. Switching back on therefore starts from an empty room.

The meters are peak detectors on the input and output chunks. They read the audio and change nothing.

Changing the delay lengths

The source is Reverb::maybeReconfigure and FDN::adoptFieldFrom.

Most controls can be applied to a running reverb by changing a number. The delay lengths need more, because shortening a delay line while a tail is in it would skip part of the stored sound and click. So the reverb keeps two complete early-plus-late engines, of which only one is normally running. When Mode or Size changes enough to need new lengths, the idle engine is set up with them. It is also given a copy of the sounding engine’s stored audio, so that it continues the same tail re-read at the new lengths. The output then crossfades from the old engine to the new one over 40 ms. If nothing is sounding at that moment the switch is made instantly instead.

Let $\varsigma = 0.5 + \textit{Size}$ be the delay scale. A reconfiguration is needed when the mode differs from the one applied, or when $|\varsigma - \varsigma_{\text{applied}}| > 0.03$ . Size therefore moves the delays in steps of at least 0.03, while its effect on damping through equation (31) is continuous.

The wet level is tracked by a peak follower over chunks, $\omega \leftarrow \max(\text{chunk peak},\ 0.99\,\omega)$ . If $\omega < 10^{-5}$ , or the reverb has not yet processed anything, the active engine is reconfigured and cleared in place. Otherwise the standby engine is configured and a crossfade begins. It receives the active engine’s delay-line contents and filter states, but neither its gains nor its delays. Per sample, with $\chi$ rising from 0 to 1 in steps of $1/(0.040 f_s)$ ,

Both engines process the same input during the fade, and both are handed the same mixing vectors. When $\chi$ reaches 1 the roles swap and the now-idle engine is cleared. A change requested during a fade is applied when the fade ends.

Parameter smoothing

A parameter change from the host is a step. Applied directly, a step in a gain is a click. So every continuous parameter glides towards its target, and the gliding is where the values the audio actually uses come from.

Each of the following moves 35 per cent of the way to its target once per chunk of 64 samples.

Those parameters are Mix, Width, Enabled, Early Level, Decay, Tone Tilt, Morph Depth, Entry Drift and Air Level. Three more are smoothed in a converted form: Trim as a linear gain, Diffusion as $\delta$ , and Low Cut as the coefficient $c_{\mathrm{lc}}$ . After $k$ chunks the remaining distance is $0.65^k$ . One per cent is reached after 11 chunks, which is 14.7 ms at 48 kHz. Decay, Tone Tilt, Morph Depth, Entry Drift and Air Level are pushed into the engines only when they have moved by more than $10^{-5}$ . A static parameter therefore costs nothing.

Predelay is smoothed per sample instead, by equation (5).

Morph Rate, Entry Rate, Morph Adapt, Air Motion, Mode and Size’s effect on delay lengths are not smoothed, by design. The first three set speeds rather than positions, so a step in them produces no step in the audio. Size’s effect on damping is applied immediately, because it only changes the decay gains, and a change of gain alters a running tail gradually.

On the very first block after preparation every smoothed value is set to its target directly. A freshly loaded plugin therefore does not spend its first chunks ramping. This is also what makes Morph Depth 0 and Entry Drift 0 exact from the first sample.

Four parameters reach the reverb through a curve from a host value $t$ in $[0,1]$ (src/dsp/Parameters.cpp).

Sample rate dependences

Every time constant expressed in seconds or hertz is converted with $f_s$ and therefore sounds the same at any rate. That covers the low cut and damping corners of equation (3), the pre-delay target, and the diffuser delays of equation (18). It covers the envelope follower of equation (9), the room tone’s 8 kHz roll-off and its 0.15 Hz wander. It covers the crossfade and Entry Drift fades, the morph phase increment of equation (46), and the decay gains of equation (30).

What is expressed in samples changes with the rate instead. The delay tables of equations (15) and (29) are sample counts for 48 kHz and are used as they are at any rate. At 96 kHz every early and late delay is half as long in time. The Hall’s 20 to 95 ms become 10 to 47.5 ms, the echo pattern compresses by two, and the room sounds smaller in that respect. The decay time is unaffected, because equation (30) compensates.

The per-chunk smoothing of equation (56) moves 35 per cent per 64 samples, so its 14.7 ms settling at 48 kHz is 7.3 ms at 96 kHz. The pre-delay glide of equation (5) has a time constant of 2000 samples, which is 41.7 ms at 48 kHz and 20.8 ms at 96 kHz.

The pink-noise coefficients of equation (39) are fixed pole radii, so the room tone’s spectrum also shifts up in proportion to the rate.

The plugin boundary

The three shells, for CLAP, AUv2 and AUv3, all present the same contract and hand the reverb the same two arrays.

Audio is stereo in, stereo out, 32-bit float and non-interleaved. The CLAP port is declared stereo and a block with fewer than two channels is refused. The AUv2 accepts only a two-channel float format. The AUv3 requires two output buffers and zeroes its input when none is connected or the source declares silence. A mono source has to be presented as stereo by the host.

Reported latency is zero. Pre-delay is a delay the user asked for, not one the host is told to compensate.

The reported tail is $1.5$ times Decay plus Predelay seconds, so an offline bounce keeps rendering after the last note.

Every process call runs with the processor’s flush-to-zero and denormals-are-zero flags set and restores them on exit (src/util/DenormalGuard.hpp). A decaying tail otherwise reaches numbers so small that the processor slows down handling them, and with the flags set such numbers become exactly 0. The test at tests/test_realtime_safety.cpp confirms a 20-second tail contains none.

The AUv2 answers the host’s bypass property with a 5 ms linear crossfade between its output and the untouched input, then clears the reverb. That path is outside the reverb and independent of the Enabled parameter. The CLAP and AUv3 shells have no host-bypass path of their own, and Enabled is the switch.

Nothing else in the shells touches audio. Parameter events are converted through the curves above and passed to the setters between slices of the block.

The algorithm in order

Per block of $n_{\mathrm b}$ samples, in chunks of $m \le 64$ , the reverb does the following once per chunk.

1. Glide the smoothed parameters by equation (56), and compute $G_{\mathrm{dry}}$ , $G_{\mathrm{wet}}$ , $G_{\mathrm{trim}}$ and $\delta$ .
2. If Enabled has settled at off, clear the room once, output $G_{\mathrm{trim}} x$ , and skip the rest.
3. For each sample of the chunk, run the front end, equations (1) to (9), producing $d$ , $p$ and the last-sample $\sigma$ of equation (10).
4. Advance the late and early morph phases by equation (46) with $\sigma$ . Compute $r$ and $u$ by equation (47) and hand them to the active engine, and to the standby one when fading.
5. Run the early stage on $p$ , equations (11) to (13), giving $e$ .
6. Run the diffusion chain on $e$ , equations (16) to (19), giving $f$ .
7. Run the late field on $f$ , equations (21) to (27), giving $w$ . Entry Drift’s trajectory advances by equation (46) with $\sigma = 1$ at the start of the engine’s block.
8. Repeat 5 to 7 for the standby engine if a crossfade is running.
9. For each sample, apply equations (51) to (55), producing $y$ .
10. Update the wet peak follower and raise the meters.

Inside the late field at step 7, each sample runs the same nine operations for six lines: read, tap, damp, limit, add tone, reflect, inject, write, advance.

Measurements against the equations

The repository’s offline tool renders a unit impulse through the reverb with Mix at 1 and Air Level at 0 and measures the result. Predictions below come from the equations above and measurements from the tool. The tool’s band measurements use one-pole probes at 150 Hz, at 500 to 2200 Hz and at 7 kHz. Those sit inside the shelf transitions rather than at the band extremes. That is why the low and high measurements land between the mid target and the band target.

The first sample a listener hears, at the Hall defaults with Predelay 20 ms, Early Level 0.35, Width 0.8 and Low Cut 80 Hz:

The amplitude is the early tap $1/\sqrt3$ of line 0, which holds half the left input after the low cut’s first-sample gain $1 - c_{\mathrm{lc}}$ . That is scaled by Early Level, then narrowed by Width through equation (52) with the right channel still silent. The late field’s first contribution arrives 961 samples later and is far smaller, because the diffuser’s direct term is $0.7^8$ .

Decay times follow. The mid band target equals Decay, the low band is $1.3$ times it, and the high band is $(0.9 - 0.35\,\textit{Size})$ times it at tilt 0.

The mid band lands within about 8 per cent of Decay in every case, a little short in all but the Tilt +1 row. That is inside the tolerance the repository’s own test sets. The ordering of low above mid above high holds in every untilted case. The high band at Size 1 measures 1.60 s against a 1.32 s target. The 7 kHz probe lies where the high shelf of equation (34) is only part-way to its full effect, exactly as equation (37) predicts.

Normalised echo density in 20 ms windows from 0 to 120 ms, where 1 means fully dense:

Freezing the late trajectory at eight phases and measuring the broadband decay time gives 2.05 to 2.06 s at the Hall defaults, a spread of 0 per cent. At Tilt $-1$ it gives 2.02 to 2.08 s, a spread of 3 per cent. The moving matrix does not move the decay, as the section on the trajectory claims.

Table of constants

Source map

Figure sources

One script draws the figure. It plots the measured decay times of the table above against the ones equation (30) asks for. It also prints the spread it draws, so the caption and the plot cannot drift apart. The measurements are typed in from that table rather than recomputed, because they come from the compiled plugin. It needs NumPy and Matplotlib.

uv run --with numpy --with matplotlib python3 decay.py

• Audio
• Dsp
• C++