Skip to content

Chorus revamp - #54

Merged
danigb merged 7 commits into
mainfrom
chorus
Sep 12, 2026
Merged

danigb merged 7 commits into
mainfrom
chorus

Conversation

@danigb

@danigb danigb commented Sep 12, 2026 •

Copy link
Copy Markdown
Owner

Made with Claude

  • Measure a chorus — src/measure.ts reads delay, LFO rate, excursion, correlation and detune off rendered audio; landed red, with eight it.failing() assertions.
  • One delay line and a voice — src/dsp.ts hand-written on scripts/_delay.ts, replacing 257 lines of Faust output and dsp/chorus.{dsp,rs}.
  • An LFO bank that does not repeat — two accumulators at an irrational ratio, depth coupled to rate.
  • Three voicings — one VOICINGS table; white-chorus feedback tried and dropped on a measurement.
  • Parameters — five params in real units, stereo input, major changeset.
  • The wet path sits behind the dry — CE-2 pole cascade, Mutable's gain law, and a non-finite guard the IIR filters made necessary.
  • README, docs, demo and the licence — README rewritten against the measurements, docs page led by the migration table, demo rebuilt on a saw stack, and the THIRD-PARTY-LICENSES.md entry retired.

`worklet.test.ts` was 84 lines: registration, a descriptor snapshot, and a
block of 440 Hz coming out finite and not all zeros. All four parameters being
wired to the wrong four things passed it. A sine table holding a cosine passed
it. An LFO capped at a seventh of its declared range passed it. Nothing in it
knew what a chorus was, so nothing in it could have failed.

`src/measure.ts` reads physical quantities off the output instead: tap
positions in milliseconds from an impulse, LFO rate in hertz by autocorrelating
the amplitude envelope, excursion in milliseconds by sampling the tap position
around one LFO cycle, L/R correlation, mono-sum level in dB, and detune in
cents through Dattorro's extrema. `spectrum.test.ts` calibrates each one
against a signal whose answer is known before the measurement runs.

**The suite lands red on purpose.** It is written against the engine it is
about to condemn, because a suite that has never failed has not been shown to
work, and because writing it after the rewrite would mean writing it against
code that already passes. Eight assertions are `it.failing()`, each carrying
what the engine measures today beside what it should:

| Measurement | Measured now |
| --- | --- |
| `delay` moves the taps | it does not; it sets the dry gain, exactly `1 - knob` |
| `rate` sets the LFO rate | it sets the base delay: 3.333 / 6.667 / 13.333 ms at 0.25 / 0.5 / 1.0 |
| `depth` sets the excursion | it sets the per-voice offset: first tap 10.667 -> 15.999 ms with the LFOs stopped |
| `deviation` is a spread | it is the LFO rate in Hz: 0.0830 / 0.1659 / 0.2489 / 0.3320 at 0.25 / 0.5 / 0.75 / 1.0 |
| the LFO reaches 7 Hz | it reaches 1 Hz |
| L/R correlation in 0.1 ... 0.5 | 0.4124 at the defaults, -0.0001 with everything at maximum |
| mono sum within 1.5 dB | -3.59 dB |
| delay in ms is rate-independent | 5.805 / 5.333 / 2.667 ms at 44.1 / 48 / 96 kHz - a sample count in millisecond's clothing |

Every number is a fresh measurement from this harness, not a value copied out
of the research: two independent measurements agreeing is the point, and they
agree to the fourth decimal.

Four assertions pass today and are here to keep passing: `readHermite`
reproduces a cubic exactly where a linear read is off by three orders of
magnitude, a NaN block does not poison the engine, a parameter step mid-render
does not click, and the cents conversion matches a hand computation.

`_delay.ts` and `_spectrum.ts` are copied in, so `chorus` joins the shared
delay-line and measurement lists in `worklet-copies.test.ts`. Neither reaches
`index.ts`; `spectrum.test.ts` asserts the bundle contains none of it.
The engine was 257 lines of Faust output carrying its own `Float32Array(8192)`
masked ring and its own two-point linear read, across eight voices. That last
combination is the one Dattorro 6.1 rules out by name - "a multivoice (more
than two) chorus design using linear interpolation subjects the signal to
significantly audible amounts of low-pass filtering" - and the ring is one of
the six `scripts/_delay.ts` names in its own header as the reason it exists.

`src/dsp.ts` is now hand-written around `createDelayLine`: two lines, a `Voice`
record that is a base delay, a modulation scale, a phase offset and a pair of
output gains, and a `compute()` that ramps every parameter per sample. A voice
does not know which voicing it belongs to, which is what makes the three
voicings a table rather than three code paths.

`readHermite` rather than a linear read, and the three papers that look like
they disagree reconcile once you notice Dattorro's objection is to *two-point*
linear specifically: Hermite is FIR so Valimaki's allpass transient never
arises, it is 4-point so the multivoice warning does not apply, and it is
Niemitalo's own pick for un-oversampled audio. It was already written, already
tested and already in the repository.

`dsp/chorus.dsp`, `dsp/chorus.rs` and `dsp/compie.sh` are deleted. The licence
entry that `chorus.dsp` required comes out with the docs.

**Four of the eight red assertions are now green**, in the units they were
always written in:

- the tap sits at the delay it was asked for, in milliseconds, and reads the
  same at 44.1, 48 and 96 kHz - where the Faust engine gave 5.805 / 5.333 /
  2.667 ms for one setting, a sample count in millisecond's clothing;
- the dry path is at the gain `mix` asks for, not `1 - delay`.

The four that need a moving read position stay `it.failing()`: there is no LFO
bank yet, and until there is, this is a fixed comb filter. That is the correct
intermediate state, and the ticket is explicit that it is not to be tuned by
ear before the modulation exists.

Three new assertions the primitive was adopted for: nothing is allocated after
`createChorus` returns (a `Float32Array` construction counter around 200
blocks, not an assumption), `reset()` returns the engine to its initial state
sample for sample, and a parameter step mid-render stays under
`maxAbsoluteDifference`'s bound.

The parameters become `rate`, `depth`, `mix`, `width` here because the engine
needs them to compile; their units, their k-rate grounds, `mode`, the stereo
input and the migration note are the parameters ticket. The inlined processor
goes from 4145 to 2231 bytes on the way.
The engine that was here ran eight LFOs at `rate x {1, 1/2, 1/3, 1/4, 1/6,
1/7, 1/8}` Hz. Every one of those is a rational fraction of every other, so the
whole eight-voice pattern closed on a period of `8/rate` seconds - a
sixteen-second loop at the default setting. That is the RS-101 construction,
one clock divided 1:2:4:8, and the RS-101 is described as sounding
correspondingly more regular than the RS-09, which used four independent LFOs.
Mutable's `Ensemble` takes the other road with two accumulators at 0.75 Hz and
6.57 Hz.

Two accumulators here, and a voice reads whichever of them its weights ask for,
at its own phase offset. `phase += inc; if (phase >= 1) phase -= 1`, and
`Math.sin` rather than a wavetable - the table is exactly what broke before.
`fillTable` ignored its `fn` argument, so both of Faust's `os.oscp` tables held
a cosine and the per-voice phase offsets never computed: `table[0]` read
1.000000 where `sin` gives 0.

**Plaits' rate pair is 0.75 and 6.57 Hz and their ratio is `219/25`**, so the
pair still closes after 25 slow cycles - 33 s at the default rate. The fast
multiplier is `6*PHI - 1 = 8.7082` instead: irrational by construction, and it
puts the fast LFO at 6.531 Hz, 0.6 % from Plaits' figure and incommensurate for
good rather than for 33 seconds. Asserted against every fraction with a
denominator under 60.

**`depth` is coupled to `rate` by a published rule.** Martens & Marui (2006)
tested 25 listeners across vibrato, flange and stereo chorus and found the
useful-range boundaries substantially the same for all three; regressed on
modulation period, the upper bound is `D(us) = 4800*(1/rate) - 350`, R^2 =
0.94. `depth: 1` means "as deep as this rate can carry", clamped by the
voicing's own ceiling - so one knob stays musical from 0.5 Hz to 7 Hz instead
of at one setting. Measured excursion matches the derivation to within 8 % at
0.5, 2, 6 and 7 Hz, and the two ends differ by a factor of twenty rather than
being equal.

`rate: 0` holds every phase where it is. Real behaviour - a static comb - and
also what lets the impulse measurements read a base delay without chasing a
moving tap, which the old engine could only do by passing a value below the
range its source declared.

The two LFO assertions this suite landed red now pass: the rate is in hertz,
linear across 1 / 3 / 7 Hz, at 44.1, 48 and 96 kHz alike, and it reaches the
7 Hz the Faust source declared before `params.ts` truncated it to 1. Detune is
stated in cents through Dattorro's extrema - 2 ms at 0.5 Hz is +/- 10.84 cents
- which is the number the README can use.

Still red: L/R correlation and the mono sum. Both voices sit on the same base
delay until the voicing table lands.
The chorus that was here had one sound and no name for it: eight voices spread
across `curdel*(i+1)/8` reaching 85 ms, which is Dattorro's *doubling* range
(10-100 ms) rather than his chorus range (1-30, nominal 5). At the defaults
half the effect was doubling. It was not a Juno, an ensemble or a Dimension -
it was a generic multi-tap smear, and the reason it had no character is that
nobody chose one.

Three now, and they are five tables and an output matrix rather than three code
paths. `mode` selects a row; the row carries voice count, per-voice base delay
and phase, accumulator weights, output gains and the defaults for the other
four knobs. The inner loop branches on nothing `mode` decides - the table is
resolved once per block.

- **`JUNO`** (default) - two voices antiphase from one LFO, one to each
  channel, dry summed. 3 ms centre (`rune06`'s `CENTER_DELAY_MS`), 0.5 Hz
  (Juno-60 mode I; all three of its modes are reachable through `rate`), 2 ms
  ceiling. Inside Dattorro Table 7's chorus range.
- **`ENSEMBLE`** - three taps at exact thirds on a dual-rate pair, Plaits'
  numbers: 4.0 ms base (192 samples at 48 kHz), deviation `slow*160 + fast*16`
  normalised, 3.67 ms ceiling (Plaits' "Max deviation: 176"), 0.75 Hz. The
  centre voice reads the mid of both lines so a stereo source stays centred.
- **`DIMENSION`** - the same two antiphase taps combined as a *difference*,
  `L = d0 - d1`. 8.5 ms base, 2.5 ms ceiling, 0.5 Hz (SDD-320).

The output matrix *is* the gain pair on each voice, which is why `JUNO` and
`DIMENSION` share their entire structure and differ in two numbers.

**The difference output does what it is supposed to.** Peak-to-peak pitch
excursion at each voicing's own defaults, wet only, from the fundamental
tracker:

| voicing | pitch spread |
| --- | --- |
| `JUNO` | 13.00 cents |
| `ENSEMBLE` | 38.88 cents |
| `DIMENSION` | **0.31 cents** |

Chorus without the vibrato, measured rather than claimed - and asserted, along
with the property underneath it: at `depth: 0` the two voices coincide and
`DIMENSION`'s wet path is exactly zero.

**White-chorus feedback was tried and dropped, with numbers.** Dattorro's
Table 6 offers blend 0.7071 / feedforward 1.0 / feedback 0.7071 from a fixed
unmodulated tap, on the argument that the circuit then approximates an allpass
and the comb colouration cancels. Measured as magnitude ripple over
100 Hz - 10 kHz from the impulse response of one frozen voice: plain
feedforward **15.31 dB**, white chorus with a fixed feedback tap **30.62 dB**,
white chorus with a moving feedback tap **22.63 dB**. Every variant is more
coloured, not less. Two caveats are in the comment: his argument is about the
summed response under modulation rather than one frozen tap, and the real Juno
has no feedback path either way.

Mode changes cross-fade over 5 ms - out, swap the table at the envelope's zero,
back in - which is `rune06`'s `FADE_MS`. Asserted with
`maxAbsoluteDifference`, along with no tap leaving `[1, size - 4]` anywhere in
the table and finite output across every voicing's whole range.

Phases sit at a quarter and three quarters rather than 0 and a half: still
exactly antiphase, but it puts the voices at opposite ends of their travel when
`rate` is 0, so a stopped LFO is a static two-tap comb rather than both voices
landing on the same sample.
`mode`, `rate` in hertz, `depth`, `mix`, `width`. The four that were here were
all wired to the wrong four things, and this is where that is said out loud:
the changeset carries the permutation table and the plain statement that every
existing patch will sound different.

`params.ts`'s header used to defend all four being normalised knob positions
because "this is a pedal, not a modular utility". That is a reasonable position
for a control with no natural unit, and not one for a delay time or an LFO
rate - and it was arguing for a convention Faust happened to expose rather than
one anybody picked. The rule that replaces it: **physical where a unit exists,
normalised where the useful range is a function of another parameter.** `rate`
is hertz; `depth` stays 0..1 because its useful range is a function of `rate`
and of the voicing, and a millisecond value would be a number the user has to
solve Martens & Marui's regression to choose. Both halves of that are stated in
the file, including why `rate` is not treated the same way.

Every `k-rate` carries its ground per `_worklet.ts`: `mode` is structural, the
other four are consumed once per block and ramped per sample inside
`compute()`. `npm run check:rates` passes.

**Stereo in.** `worklet.ts` read `inputs[0][0]` and nothing else, so a stereo
source was silently halved; it takes both channels now, and mono in still
produces stereo out because that is the point of the effect. Asserted with
different tones in each channel: 220 Hz stays the loudest thing in the left
output and 550 Hz in the right.

**And it flushes.** The old guard returned early on a missing input, which
freezes up to 20 ms of signal in the line for whatever reconnects next to
find. Silence is fed instead, the way `analog-delay` does, and the tail decays
to under 1e-6 within 20 blocks.

Descriptor defaults are `JUNO`'s own, so `Chorus(ac)` with nothing passed is a
complete answer - asserted against the voicing table rather than duplicated by
hand. `CHORUS_MODE_DEFAULTS` is exported for the other two: an AudioParam has
one `defaultValue` and cannot ask a table for one, so selecting a voicing and
taking its settings is two lines in a host rather than a sentinel outside the
declared range.

`JUNO` and `ENSEMBLE` sit inside Dattorro Table 7's chorus range (1-30 ms,
nominal 5), asserted from the table. `DIMENSION` at 8.5 ms is in the overlap
with doubling on purpose - that is the SDD-320's number, and it is a decision
rather than an accident.
There was no filtering anywhere in the engine this replaces. Eight delayed
copies summed at full bandwidth and mixed with the dry is what a chorus sounds
like when nobody decided what it should sound like: bright, thin, and sitting
on top of the source rather than behind it.

`rune06`'s CE-2 pole set - 10620 / 8830 / 7234 / 4020 Hz - is now on the wet
output as a cascade of TPT one-poles, post-filter only. A BBD needs one before
the line too because the line is a sampler; a digital line is not.

**The pole count is a measurement, not a shrug.** Four poles against the two
lower ones alone: within 0.3 dB below 2 kHz, within 1.1 dB at 4 kHz, 4.2 dB
apart at 8 kHz and 16.3 dB at 16 kHz. Two buy the audible body; the other two
buy the top two octaves, which is the region that decides whether the wet sits
behind the dry. Four for JUNO and DIMENSION, two for ENSEMBLE. Measured -3 dB
corner 4043-4799 Hz across the three voicings and all three sample rates.

DIMENSION's 150 Hz wet high-pass and complementary dry shelf: its mono level
over 40-200 Hz is -0.48 dB against the input, the best of the three.

Gain staging is Mutable's rule verbatim, `dry = 1 - mix*0.5`, with the wet
normalised per *channel* by the gains that reach it rather than by voice count.
Mono sum on pink noise at each voicing's defaults: -0.51 / -0.70 / -1.02 dB.

**Two measurements did not land where the tickets expected.** Broadband
correlation is 0.891 / 0.954 / 0.904 rather than 0.1 ... 0.5, and per-band
correlation is lower at the bottom than at the top rather than the reverse.
Both are consequences of summing an unfiltered dry with a wet path rolled off
at 4 kHz, both are recorded in the code and the changeset with the numbers and
the reasoning, and neither was tuned away to make an assertion pass. The
mechanism the band was about is intact: the LFO phase spreading decorrelates
the wet, and the per-band assertion pins where.

Correlation is measured on pink noise. White noise puts half its energy above
12 kHz, which no musical signal does, and measured on white any filtered-wet
chorus reads near 1 - not because the effect is narrow but because the
measurement is looking where the effect isn't.

**The filters made a NaN permanent**, which a delay line alone does not: every
one-pole is `state = state + g*something`. The block is scanned once after
rendering and anything non-finite resets the engine and zeroes it - `vaf 05`'s
finding and its answer. Ten seconds of silence stays finite and out of the
denormals.

`measure.ts` gains `transferDb` (rectangular, because an impulse response is
the transfer function and a window would taper the impulse away), `cornerHz`
(a running maximum, because reading a corner off a comb finds the first null),
`bandpass`, `bandCorrelation`, `bandMonoDb` and `pink`. Each is calibrated in
`spectrum.test.ts` against a signal whose answer is known first - including
that pink noise has equal energy per octave, with white noise as the control.
Every document about this package described the labels rather than the
behaviour, so all of them were wrong about all four parameters. The README
promised that "the width comes from spreading the voices' LFOs apart", from an
engine whose phase offsets were computed against a sine table containing a
cosine. The docs page passed a `feedback` parameter that has never existed on
this module. None of it was dishonest: it is what happens when documentation is
written from a parameter list, and the parameter list was permuted before
anybody read it.

The README keeps its prose register and replaces its claims - the three
voicings and what each is for, a parameter table in real units, the detune
range in cents, a "Measured quality" section where every row is an assertion in
`dsp.test.ts`, and a "Sourced numbers" section giving each constant's origin.
The detune table is asserted too, so it cannot drift from the engine. The Faust
credit paragraph is gone.

The docs page leads with the migration table, because anyone with a working
patch has four parameters that all changed meaning at once.

The demo puts the voicing selector first and the knobs second, runs on a
detuned saw stack through an envelope rather than one 440 Hz sine, and has a
bypass - `mix: 0`, which is exact, since the dry gain is `1 - 0.5*mix`.
Selecting a voicing applies that voicing's own settings.

**The repository has no non-MIT file any more.** `dsp/chorus.dsp` carried a
`chorus_mono` definition copied from the Faust distribution,
LGPL-2.1-or-later, and the notice recorded that it had no `faustlibraries`
equivalent to swap it for. A hand-written engine removed the reason. Its
`THIRD-PARTY-LICENSES.md` entry and the note singling it out as the exception
are both gone.

The site's own dependencies are not installed in this worktree, so the demo is
typed against the API rather than built. Every workspace test passes: 2338
across 70 suites, `check:rates` clean, `prettier --check` clean.
@danigb
danigb merged commit efb5141 into main Sep 12, 2026
1 check passed
@danigb
danigb deleted the chorus branch September 12, 2026 13:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant