Repository navigation
Conversation
`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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Made with Claude
src/measure.tsreads delay, LFO rate, excursion, correlation and detune off rendered audio; landed red, with eightit.failing()assertions.src/dsp.tshand-written onscripts/_delay.ts, replacing 257 lines of Faust output anddsp/chorus.{dsp,rs}.VOICINGStable; white-chorus feedback tried and dropped on a measurement.THIRD-PARTY-LICENSES.mdentry retired.