Repository navigation
Conversation
`createArpeggiator` takes its random source as an argument, defaulting to
`Math.random`. That is the whole of the change to the shipped module: the
worklet passes nothing, and the regenerated `processor.ts` differs by
`b(e=Math.random)`.
It is the seam the next four tickets need. Every test in this package was
written around the randomness rather than through it - `worklet.test.ts` loops
forty times "because two random notes can repeat", `scales.test.ts` collects a
`Set` over 400 cycles and can never assert that note 3 follows note 2 - so the
ticket that gives the module an order would have landed with no way to prove
the order right. Those hedged tests stay for now; deleting them here would
remove coverage without replacing it.
`dsp.test.ts` gains the numeric net, explicitly labelled a baseline to be
broken and not a contract to keep:
| measured under Math.random | |
| --- | --- |
| immediate repeats, TriadMajor / PentatonicMinor / Major | 33% / 20% / 14% |
| 12 triggers failing to sound all 7 notes of a major scale | 77% |
| steps above Nyquist at baseNote 127, octaves 10 | 92% |
| steps above Nyquist at baseNote 96, octaves 4 | 15% |
Ticket 04 has to take the first two to zero and say so. The Nyquist rows are
ticket 02's, recorded twice over: `it.failing("never emits a note above MIDI
127")` is that ticket's assertion written a ticket early, so it flips by
deleting a word.
The repeat rates are asserted over 200 000 triggers rather than the 60 000 they
were measured over, because `toBeCloseTo(x, 2)` at 60 000 draws is two and a
half standard deviations and would fail about one run in a hundred for nothing.
`benchmarks/arp-rate/` measures both of `worklet.ts`'s paths - the a-rate split
write and the k-rate fill - because tickets 03, 04 and 05 all add state to a
function called once per sample. Today: 0.025 us/block k-rate, 0.79 us a-rate,
0.03% of a block. Its README says plainly that this is not a performance
problem and that the folder exists so the number cannot move quietly, and it
records the 0.72-1.15 us spread against the research's 0.405 us rather than
tuning the harness until they agree.
The xorshift32 the tests seed with lives in `src/test-random.ts` and is imported
by nothing `index.ts` reaches, so it cannot enter the published bundle. There is
no user-facing `seed` parameter and there will not be one.
Three defects, all reachable from the declared parameter ranges, all in
`nextRandom` and the two lines above it. No API change.
**The fold.** `baseNote` is declared 0...127 and `octaves` 1...10, and the sum
had no ceiling: at both maxima the module emitted MIDI 246, which is 12.1 MHz,
with 92% of its steps above Nyquist. At `baseNote: 96, octaves: 4` - C7 with a
four-octave range, a setting somebody would dial - it was still 15%. Nothing
errored on any of it, which is worse than an error: `polyblep-oscillator` caps
`frequency` at 20000 and a native `OscillatorNode` clamps to Nyquist, so every
note past the top collapsed onto one pitch and the arpeggiator silently stopped
moving at the top of its range.
Fold rather than clamp, because folding by twelve keeps the pitch class and a
folded note is therefore still a member of the set. Clamping gives a note the
user did not choose; skipping one changes the pattern's length, which stops
being coherent as soon as ticket 03 gives the pattern a length. Yarns folds the
same way and rune06 folds at 96.
**The floor.** `Math.floor(random() * 2.5)` yields 0, 1 and 2 - three octaves
for a request of two and a half - and an `AudioParam` hands over a fractional
value from any ramp or from any node patched into it. Floored once per call.
`baseNote` is deliberately *not* floored: fractional values are fine tuning,
`baseNote: 60.5` is a quarter tone, and the README now says so, because until
now nothing did.
**The first note.** `current` was seeded with the literal 60, so
`Arp(ac, { baseNote: 48 })` held 261.63 Hz until its first trigger - neither the
root nor a member of the set. It is now `NaN` until the first call resolves it
to `baseNote`. For a module that holds its output between triggers, the value it
holds before the first one is audible for as long as the clock takes to tick.
Ticket 01's `it.failing("never emits a note above MIDI 127")` becomes a passing
test, and grows into a sweep of all 35 840 `baseNote` x `octaves` x `scale`
combinations. Exhaustive in combinations and short in triggers, because the
failure mode is a combination and not a rare draw. Its two siblings - the tests
that asserted 92% and 15% of steps were above Nyquist - are deleted rather than
inverted: they recorded a defect that no longer exists, and they are not to be
restored.
The pitch-class check is the one that says why this is a fold: every folded note
is still a member of the mask that produced it. And the seeded eight-note
sequence pinned in ticket 01 is asserted again from the other side, as the guard
that the fold is inert where nothing can overflow.
The ticket this folder exists for. `mode` - Up, Down, UpDownExclusive,
UpDownInclusive, Random - and with it the module stops being "a random walk over
a set of notes, not a pattern player" and becomes the thing it has been named
since 2024.
**The engine stores a position, not a note.** One flat index walks the
`len * octaves` sequence and `readNote()` maps it to a note when the note is
read. Three things follow, and all three are why it is a flat index rather than
the nested note/octave counters Yarns and Plaits use: `baseNote` transposes a
pattern that is already running; the value held before the first trigger is the
note about to be played, with no special case; and the traversal refers to
nothing but an index and a length, so it lifts out of this file whole the day
`Poly` wants the same modes over a stack of held notes. Ticket 05 needs the same
property for a different reason - it changes `readNote()` and leaves `advance()`
untouched.
Two behaviour breaks, both deliberate and both in the changeset. `mode` defaults
to `Up` rather than `Random`, because preserving a defect through a default is
not compatibility. `scale` defaults to `TriadMinor` rather than to the root
alone, because `Arp(ac, { trigger })` has to make music - a one-note set is one
note forever, the same class of defect as `euclid`'s `steps: 0`, and it is also
the degenerate case that hangs `UpDownExclusive` without the `size === 1` guard.
The guard is a correctness item: an unbounded loop in a worklet is a render
quantum that never returns, and it was reachable from the shipped defaults.
`Random` ships here unchanged and reachable, at `maxValue: 4`, rather than being
held back to ticket 04 as that ticket's descriptor sketch implies. Three
statements in the ticket require it - "Random keeps its 33.1% repeat rate until
04", "01's baseline tests should still pass here", and "keep `nextRandom()`
reachable" - and none of them is true of a mode nobody can select. It draws the
octave first and the note second, which is the order the old pick drew them in,
so a seeded stream produces the same notes it did before there was an order.
**The hedged tests are gone.** `worklet.test.ts`'s "advances twice for two
triggers in one block" no longer loops forty times "because two random notes can
repeat" - it asserts three exact frequencies. `scales.test.ts`'s `collectNotes`
no longer collects a `Set` over 400 cycles; it asserts that a major scale plays
in order, twice round, and that two octaves of a triad are 60 64 67 72 76 79.
Neither loop should be restored: they existed because nothing in this package
could predict a note, and both were replaced by an assertion that could not have
been written before ticket 01.
The two seeded eight-note arrays pinned by tickets 01 and 02 shift by one
element, and the shift is the whole of the change: the engine emits the note it
is sitting on and *then* advances, so the first trigger sounds the root and the
first draw lands on the second trigger. Both tests say so where they are pinned.
New assertions: the two KeyStep Pro sequences verbatim, the turnaround happening
at the ends of the whole range rather than at each octave, a full cycle visiting
every (note, octave) pair exactly once across all 120 combinations, a set that
shrinks under the traversal at every offset of a full cycle, a mode change that
continues rather than restarts, and an exhaustive 5 x 12 x 10 sweep with a step
counter so a hang fails the test instead of hanging the runner.
`Random` stops repeating itself and `RandomOther` joins it. Both changes are
measured against the baseline ticket 01 wrote for exactly this purpose, and the
tests that recorded that baseline now assert zero.
**What it cost.** A memoryless uniform pick repeats the note it just played 1/n
of the time: 33% on a major triad, which is the input an arpeggiator is *for*.
Under a fixed envelope a repeated note is a step that did not happen, so one
step in three was silently dropped. And it did not cover its own set - twelve
triggers over a seven-note scale sounded all seven in under a quarter of runs.
`Random` now draws until the position differs, which is Plaits' approach. The
loop is bounded by the `size === 1` guard ticket 03 added for the traversal: with
more than one entry there is always something else to draw, and the expected
number of draws is `size / (size - 1)` - 2.0 on a two-note set, 1.17 on a
seven-note one, on a path that runs on triggers rather than samples.
`RandomOther` is Ableton's, specified as "won't repeat a note until all others
are used": Fisher-Yates over the whole `len * octaves` sequence, drained one
entry per trigger, reshuffled when empty. The bag is a preallocated
`Int32Array(120)` - twelve pitch classes over ten octaves is the largest
sequence the parameters can declare - written in place, so nothing allocates on
a trigger.
Two details that are not optional. The bag is *entered* at seeding rather than
stepped into, because the engine emits the note it is sitting on and then
advances: without it the starting index would sound once before the first pass
and once inside it, and a pass would not be a permutation. And `refill` swaps its
first entry away from the note just played, because a plain Fisher-Yates repeats
across a pass boundary once every `size` passes - which is the one thing this
mode promises cannot happen. The test gives it 10 000 boundaries to fail on.
**The baseline is inverted, not deleted.** `describe("baseline: what a
memoryless random pick costs")` becomes `describe("randomness with a memory")`
and keeps the old numbers in its header, so the diff shows what moved. Zero
repeats is asserted exhaustively over all 28 scales x four octave counts x both
modes - a property of the construction rather than a statistic, so 2000 triggers
per combination finds a violation as surely as 60 000 would. Coverage: a bag
sounds all seven notes of a major scale in seven triggers, always; `Random` still
misses about two runs in three, which is better than the 77% it replaced and
nowhere near a permutation. That gap is the evidence the two modes are not
substitutes.
The seeded eight-note array moves for the second time, because a rejected draw
consumes the stream. The test says so where it is pinned.
`mode`'s `maxValue` goes 4 to 5 rather than the ticket's 3 to 5, because ticket
03 shipped `Random` reachable.
`octaveMode`: `Serial` - the whole set, then up an octave, which is what the module already did - and `Repeat`, each note in every octave before the next note. A minor triad over three octaves, `Up`, is 60 63 67 · 72 75 79 · 84 87 91 one way and 60 72 84 · 63 75 87 · 67 79 91 the other: three stacked arpeggios, or a rising sequence of octave leaps on each chord tone, from an identical chord and an identical direction. `octaves` said how far the pattern reached and nothing said how it got there. Every product in the survey hardcodes serial traversal, Mutable included; u-he's Hive is the only one that exposes the choice, and it is the single highest-value idea in the research. **It is one branch in `readNote()` and `advance()` does not change at all.** That is the return on ticket 03's decision to walk a flat index rather than the nested note/octave counters Yarns and Plaits use: the two mappings are transposes of the same `len * octaves` rectangle, so both visit every (note, octave) pair exactly once per cycle and the traversal walks the same index range either way. Asserted rather than assumed, over all 120 combinations - and the enumeration test reads from MIDI 0 rather than 60, because at the top of the range ticket 02's fold makes a complete cycle look incomplete by collapsing two octaves onto one note. Six modes x two octave modes is twelve traversals from two small k-rate enums, and both are `AudioParam`s. Inert at `octaves: 1`, where the mappings agree - asserted for every mode and a spread of scales, because a user who never raises `octaves` should not be able to tell the parameter exists. `Serial` is left exactly as it was, and that is a test rather than an assertion in prose: a five-argument call and a six-argument call asking for `Serial` are compared run for run over six modes, four scales and ten octave counts, which also pins the argument default. Two of Hive's four orders are deliberately absent, with the measurements in the ticket. `leap` only enumerates the full rectangle when the set size and the octave count are coprime - at 3 x 3 it covers 3 of 9 pairs - and a mode that silently plays a third of the notes you asked for is worse than no mode. `round` needs the octave axis to carry its own sequence rather than a positional mapping, which is the one thing this design does not give away for free.
The callout is gone. `site/content/docs/(sequencers)/arp.mdx` shipped "This module is WIP. Currently it only generates a random note from a given scale" for two years, and it was true for all of them; it is the single most visible thing this folder fixes. `packages/arp/README.md`'s "a random walk over a set of notes, not a pattern player" went with ticket 03. **Two things were never documented at all**, and both are now in the first screen of the README and the page. The module takes MIDI in and emits hertz out - `baseNote` is a note number, the output is a frequency - which is what lets it connect straight to an oscillator and is what a reader arriving from any other arpeggiator will not expect, because every one of them emits note events. And `baseNote` is continuous: 60.5 is a quarter tone, which ticket 02 decided deliberately and nothing said. **What it does not do, and where that lives**, as a section rather than a footnote. Rate, gate length, swing and rhythm are `Clock` and `Euclid`; a ratchet is a faster `Clock` gated by the step. Held notes, latch and as-played order belong to `Poly`'s arp mode, because a worklet cannot receive `noteOn` - same vocabulary, two tiers, which is the scope decision the whole folder rests on and would otherwise be re-asked forever. **`ArpMode` and `ArpOctaveMode` were missing from the umbrella's explicit enum re-exports.** `tsup`'s dts bundler drops enums from `export *`, so both existed at runtime and not in the published types - the trap `ArpScale` and six others already had a line for, and the docs page's own first code block would not have typechecked for a consumer. **`docs.test.ts` gains an `arp` entry, and it earned its place immediately.** Tickets 04 and 05 both edited the README's parameter table by string replacement; Prettier had realigned its columns since it was written, so the replacements matched nothing, and `mode`'s range plus the whole `octaveMode` row were never written. Nothing said so. The table is now checked against `descriptors` in both directions - names, defaults, ranges, rates - in the README and on the page, and both mode tables are checked to be byte-identical between the two and to list every enum member exactly once. `descriptors.test.ts` gains `Arp.mode` and `Arp.octaveMode` to its enum-span rows for the same reason. The example is rebuilt around the feature rather than the defect it used to demonstrate: a mode selector, an octave-mode selector, an octaves slider, and a chord progression automating `scale` through four pitch-class masks over one root. That last one is the thing nothing in the survey can do - in every hardware arpeggiator the chord is in your fingers - and a demo is the only place it lands as a feature rather than a sentence. `Euclid` is dropped from the patch: the screen is about order, and a rhythmic mask on top of it makes two figures harder to tell apart. Its own page keeps the audit's `steps: 16, beats: 5` rotation question.
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