@jpdutoit/squelchy 0.0.1 → 0.0.3

package/docs/GUIDE.md

@@ -0,0 +1,420 @@
+# @jpdutoit/squelchy: guide
+
+Short recipes for the parts the module reference doesn't cover: working with modules, typed units, the transport for scheduling, sequencing synth voices, one-shot actions, sample kits and offline rendering. Every TypeScript example here is compile-checked against the published types before each release.
+
+- `docs/MODULES.md`: every module's ports and parameters, for reading.
+- `docs/modules.json`: the same reference as JSON, for `jq` and scripts ([see below](#module-reference-with-jq)).
+
+## Modules
+
+`X.create(ctx, params?)` builds a module. Each port is a property named by its slug, so you wire modules with plain `connect()`. `input(slug)` and `output(slug)` return the same objects.
+
+```ts
+import { preload, Vco, Lfo, Vcf, semitones, hz, note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx); // once per context, before any create()
+
+const vco = Vco.create(ctx, { offset: semitones(45) }); // unpatched, offset is the note: 45 = A2
+const lfo = Lfo.create(ctx, { frequency: hz(0.2), amount: semitones(18) });
+const filter = Vcf.create(ctx, { note: note('C6'), resonance: 4 });
+
+vco.out.connect(filter.in);
+lfo.out.connect(filter.modFreq); // CV inputs sum onto the knob's value
+filter.out.connect(ctx.destination);
+
+// Same connection, spelled out:
+lfo.output('out').connect(filter.input('modFreq'));
+```
+
+### Changing parameters: `set()` vs `params`
+
+- **`params.<key>`** is a native `AudioParam` for every parameter that drives the DSP 1:1. Use it for anything timed: ramps, curves and `setValueAtTime`.
+- **`set(key, value)`** changes any parameter immediately. Some parameters are `set()`-only: switches (enums), and values that rebuild something internally (a waveshaper curve, a filter bank, a resonance mapping). The types enforce this, and the module reference marks every parameter as automatable or `set()`-only.
+
+```ts
+import { preload, Vcf, note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+const filter = Vcf.create(ctx);
+
+filter.set('filterType', 'bandpass'); // switch: set() only
+filter.set('resonance', 8);           // set() only
+filter.params.note.setTargetAtTime(note('C7'), ctx.currentTime, 0.5); // native automation
+
+// @ts-expect-error resonance is not a native AudioParam
+filter.params.resonance;
+
+filter.dispose(); // disconnect and release when you're done
+```
+
+## Units
+
+Notes, semitones, Hz, seconds and beats are distinct types, so passing seconds where a note is expected won't compile. At runtime they are plain numbers with zero overhead. Dimensionless values (mix, feedback, drive) are plain `number`.
+
+```ts
+import {
+  note, noteToHz, hzToNote, transpose, interval, semitones, cents, centsToSemitones,
+  db, dbToGain, gainToDb, ms, msToSeconds, sec, hz, now, Vco,
+  type Seconds,
+} from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+
+note('A4');                          // 69 (MIDI numbering, 69 = A4 = 440 Hz)
+noteToHz(note('A4'));                // 440
+hzToNote(hz(261.63));                // ≈ 60 (C4)
+transpose(note('C4'), semitones(7)); // 67 (G4)
+interval(note('C4'), note('G4'));    // 7 semitones
+centsToSemitones(cents(50));         // 0.5
+dbToGain(db(-6));                    // ≈ 0.5
+gainToDb(0.5);                       // ≈ -6 dB
+msToSeconds(ms(250));                // 0.25 s
+
+// Arithmetic gives back a plain number; re-brand the result with a helper or a cast.
+const later: Seconds = sec(now(ctx) + 0.5);
+
+// @ts-expect-error a bare number is not Semitones; write semitones(60)
+Vco.create(ctx, { offset: 60 });
+```
+
+**Pitch signals.** V/OCT outputs are typed `Signal<Note>`: absolute key positions, 69 = A4, 1 unit = 1 semitone. Web Audio's `connect()` can't check its destination, so the type protects the functions you write. `asPitch()` marks a deliberate crossover, like using an LFO as a pitch source:
+
+```ts
+import { preload, Lfo, Vco, asPitch, type Signal, type Note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+
+function playOn(pitch: Signal<Note>) {
+  const vco = Vco.create(ctx);
+  pitch.connect(vco.voct);
+  return vco;
+}
+
+const lfo = Lfo.create(ctx);
+// @ts-expect-error an LFO's output is CV, not pitch
+playOn(lfo.out);
+playOn(asPitch(lfo.out)); // deliberate: you said so
+```
+
+## Scheduling with the transport
+
+Musical positions are plain numbers in **beats** (quarter notes): bar 2 of a 4/4 song starts at beat 4, and a 16th note is 0.25. Audio times are `ctx.currentTime` seconds, as everywhere in Web Audio. Events are written ahead of time with exact start times, so timing doesn't depend on the main thread.
+
+Bars and beats count from 0, as on a timeline: `{ bar: 0 }` is the first bar and `{ bar: 1 }` starts at beat 4.
+
+A **pattern** is a plain array, one element per step. A **voice** is anything with `trigger(time, hit)`, or a plain function `(time, hit) => void`.
+
+```ts
+import { createTransport, steps, beats, Kick, Hat } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx, { bpm: 120, beatsPerBar: 4 });
+const kick = Kick.create(ctx);
+const hat = Hat.create(ctx);
+kick.connect(ctx.destination);
+hat.connect(ctx.destination);
+
+transport.play(steps('x... x... x... x...'), kick);      // spaces and | are ignored
+transport.play(steps('..x. ..x. ..x. ..x.'), hat, {
+  every: beats(0.25), // step length in beats (default: 16ths)
+  swing: 0.3,         // 0..1, delays every odd step
+  gate: 0.5,          // note length as a fraction of a step
+  start: 'bar',       // 'now' | 'beat' | 'bar' | { bar: n } | { beat: n }; default 'bar'
+  loop: true,         // true = forever, false = once, n = n times
+});
+transport.start();
+```
+
+### Pattern steps
+
+- **Hits:** any value. `true` from `steps()`, a `Note` from `notes()`, or whatever your voice understands.
+- **Rests:** `null`, `undefined`, `false`, `0`, `'.'` and `'-'`.
+- **Per-step velocity and length:** `{ value, velocity, length }`, where `length` is in steps.
+
+```ts
+import { createTransport, notes, note, beats, NoteCv, type Step, type Note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx);
+const cv = NoteCv.create(ctx);
+
+const melody = notes('C3 . Eb3 G3 - C4 . G3 .'); // '.' and '-' are rests
+const bass: Step<Note>[] = [
+  { value: note('C2'), velocity: 1, length: 3 }, // accented, held for 3 steps
+  null, null,
+  { value: note('C2'), velocity: 0.5 },
+];
+
+transport.play(melody, cv);
+transport.play(bass, cv, { every: beats(0.5) });
+```
+
+Plain functions work as voices, so any existing Web Audio code can follow a pattern:
+
+```ts
+import { createTransport, steps } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx);
+
+transport.play(steps('x.x. x..x'), (time, hit) => {
+  const osc = ctx.createOscillator();
+  osc.frequency.value = hit.step === 0 ? 880 : 440;
+  osc.connect(ctx.destination);
+  osc.start(time);
+  osc.stop(time + hit.duration);
+});
+transport.start();
+```
+
+### Changing things while playing
+
+```ts
+import { createTransport, steps, beats, now, Hat } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx, { bpm: 100 });
+const hat = Hat.create(ctx);
+hat.connect(ctx.destination);
+transport.start();
+
+const hats = transport.play(steps('x.x.x.x.'), hat);
+hats.set(steps('xxxxxxxx')); // swaps at the next loop, so it stays in time
+hats.stop('bar');            // stop at the next bar line (no argument = stop now)
+hats.stop({ bar: 8 });       // or at a specific bar
+
+transport.bpm = 128;         // tempo changes apply from the next scheduled event
+
+transport.beatAt(now(ctx));  // where are we, in beats?
+transport.timeAt(beats(16)); // when is bar 5, in seconds?
+transport.stop();            // stop everything
+```
+
+### Automation at musical positions
+
+`transport.at(position, fn)` calls `fn(time)` just ahead of that musical position, with its exact audio time, so you can schedule any `AudioParam` in musical time. It returns a cancel function.
+
+```ts
+import { createTransport, preload, Vcf, note, sec } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+const transport = createTransport(ctx, { bpm: 120 });
+const filter = Vcf.create(ctx, { note: note('C4') });
+filter.out.connect(ctx.destination);
+
+const bar = sec((transport.beatsPerBar * 60) / transport.bpm);
+
+// Open the filter over two bars, starting at bar 3.
+const cancel = transport.at({ bar: 2 }, (t) => {
+  filter.params.note.setValueAtTime(note('C4'), t);
+  filter.params.note.linearRampToValueAtTime(note('C7'), t + 2 * bar);
+});
+transport.start();
+// cancel(); // if you change your mind before it fires
+```
+
+### Syncing visuals
+
+Hits are scheduled ahead of time, so don't draw from inside a voice. Use `onHit` instead: it fires when the hit is actually **heard**, including output latency.
+
+```ts
+import { createTransport, steps, Kick } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx);
+const kick = Kick.create(ctx);
+kick.connect(ctx.destination);
+const highlight = (step: number) => { /* light up step `step` */ };
+
+transport.play(steps('x...x...'), kick, { onHit: (hit) => highlight(hit.step) }); // one playback
+const unsubscribe = transport.onHit((hit) => console.log(hit.beat, hit.value)); // every playback
+transport.start();
+```
+
+## Sequencing a synth voice
+
+`NoteCv` turns pattern hits into two control signals: `gate` (high for each note's length) and `pitch` (the note number). Patch them like hardware: pitch into a VCO's `voct`, gate into an envelope's `trigger`. With `voct` patched, the VCO's `offset` becomes a transpose, so set it to 0 to play the notes as written.
+
+```ts
+import { preload, createTransport, notes, semitones, sec, NoteCv, Vco, Envelope, Vcf, note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+const transport = createTransport(ctx, { bpm: 124 });
+
+const cv = NoteCv.create(ctx);
+const vco = Vco.create(ctx, { offset: semitones(0), skew: 1 });
+const env = Envelope.create(ctx, { attack: sec(0.005), decay: sec(0.25), sustain: 0.2, release: sec(0.1), depth: semitones(36) });
+const filter = Vcf.create(ctx, { note: note('C4'), resonance: 6 });
+
+cv.pitch.connect(vco.voct);
+cv.gate.connect(env.trigger);
+vco.out.connect(filter.in);
+env.env.connect(filter.modFreq); // the envelope also sweeps the cutoff, by `depth` semitones
+filter.out.connect(env.in);      // Envelope has a built-in VCA: in → out
+env.out.connect(ctx.destination);
+
+transport.play(notes('C2 C2 . C3 . C2 Eb2 . G2 . C2 . Bb1 . C2 .'), cv, { gate: 0.6 });
+transport.start();
+```
+
+## One-shot actions with `pulse()`
+
+Actions like a tape stop or kicking the spring tank are **gate inputs**. They react to a rising edge, like a trigger cable on hardware. `pulse(input, time)` fires one at an exact time. It works the same whether it's called from a button, a pattern or `transport.at`, and it sums with anything else patched into that input.
+
+```ts
+import { preload, createTransport, steps, pulse, sec, TapeStop, SpringReverb, Kick } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+const transport = createTransport(ctx);
+
+const kick = Kick.create(ctx);
+const spring = SpringReverb.create(ctx, { mix: 0.4 });
+const tape = TapeStop.create(ctx, { time: sec(1.5) });
+kick.connect(spring.in);
+spring.out.connect(tape.in);
+tape.out.connect(ctx.destination);
+
+transport.play(steps('x...x...x...x...'), kick);
+transport.play(steps('........x.......'), (t) => pulse(spring.knock, t)); // kick the tank every other bar
+transport.at({ bar: 4 }, (t) => pulse(tape.trigger, t)); // tape stop at bar 5…
+transport.at({ bar: 5 }, (t) => pulse(tape.trigger, t)); // …and back up a bar later
+
+// From a button, right now:
+const onClick = () => pulse(tape.trigger);
+transport.start();
+```
+
+## Sample kits
+
+Every kit is CC0 or public domain, and each one carries its own `license`. Each kit is its own import, and its audio ships inside the package. Import only the kits you use: your bundler copies and hashes just their sound files, and nothing is fetched from a third-party server. Voices are `bd sd rim clap ch oh lt mt ht cym perc` (`VOICE_KEYS`). If a kit lacks a voice, you get the closest one it has, e.g. `oh` falls back to `ch`, then `cym`.
+
+| Import | Kit | Family | Voices |
+|---|---|---|---|
+| `import { Roland808 } from '@jpdutoit/squelchy/kits/roland-808'` | Roland TR-808 | Machines | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { Tr909 } from '@jpdutoit/squelchy/kits/tr-909'` | Roland TR-909 | Machines | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { Tr707 } from '@jpdutoit/squelchy/kits/tr-707'` | Roland TR-707 | Machines | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { Tr606 } from '@jpdutoit/squelchy/kits/tr-606'` | Roland TR-606 | Machines | bd sd ch oh lt mt ht cym |
+| `import { Compu78 } from '@jpdutoit/squelchy/kits/compu-78'` | Compu-78 | Machines | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { Dr5Studio } from '@jpdutoit/squelchy/kits/dr5-studio'` | Studio Kit | Acoustic | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { TapeDust } from '@jpdutoit/squelchy/kits/tape-dust'` | Tape Dust | Character | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { HardCell } from '@jpdutoit/squelchy/kits/hard-cell'` | Hard Cell | Character | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { Rx5Fm } from '@jpdutoit/squelchy/kits/rx5-fm'` | Yamaha RX5 | Digital | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { MicroClick } from '@jpdutoit/squelchy/kits/micro-click'` | Micro Click | Digital | bd sd rim clap ch oh lt mt ht cym perc |
+| `import { DeepAnalogue } from '@jpdutoit/squelchy/kits/deep-analogue'` | Deep Analogue | Acoustic | bd sd rim clap ch oh lt mt ht cym perc |
+
+```ts
+import { createTransport, steps, loadSampleSet, SampleVoice, VOICE_KEYS } from '@jpdutoit/squelchy';
+import { Tr909 } from '@jpdutoit/squelchy/kits/tr-909';
+
+const ctx = new AudioContext();
+console.log(Tr909.name, Tr909.license);
+
+const kit = await loadSampleSet(ctx, Tr909);
+console.log(VOICE_KEYS.filter((k) => !kit.buffers[k])); // voices this kit covers by fallback
+
+const bd = SampleVoice.create(ctx, kit, 'bd');
+const tom = SampleVoice.create(ctx, kit, 'lt');
+bd.connect(ctx.destination);
+tom.connect(ctx.destination);
+
+const transport = createTransport(ctx);
+transport.play(steps('x...x...x...x...'), bd);
+transport.play([true, null, 3, null, 7, 12, null, null], tom); // numbers repitch in semitones
+transport.start();
+```
+
+A step value of `0` is a rest, so use `true` for an unshifted hit.
+
+**How the audio gets into your build.** A kit's voice URLs are written as `new URL('./tr-909/bd.flac', import.meta.url)`. Vite (8.3 or newer, in dev and build), webpack 5 and Parcel all recognise that pattern: they copy each file of the kits you import into your output with a content hash and rewrite the URL. Loading the package unbundled, e.g. from a CDN like jsDelivr, resolves the files next to the kit module.
+
+**Your own kit.** `loadSampleSet` takes any `SampleSetInfo`, so you can point voices at your own files:
+
+```ts
+import { loadSampleSet, type SampleSetInfo } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const mine: SampleSetInfo = {
+  name: 'My kit', blurb: 'Field recordings', family: 'Character',
+  credit: 'Me', license: 'CC0', licenseUrl: 'https://creativecommons.org/publicdomain/zero/1.0/',
+  voices: { bd: '/audio/kick.wav', sd: new URL('./snare.wav', import.meta.url).href },
+};
+const kit = await loadSampleSet(ctx, mine);
+```
+
+## Offline rendering and custom clocks
+
+On an `OfflineAudioContext`, the transport schedules the whole render up front, so the result is exact and needs no timers. Handy for bouncing loops and for tests.
+
+```ts
+import { preload, createTransport, steps, sec, Kick, Reverb } from '@jpdutoit/squelchy';
+
+const offline = new OfflineAudioContext(2, 48000 * 8, 48000); // 8 seconds
+await preload(offline);
+const transport = createTransport(offline, { bpm: 120 });
+const kick = Kick.create(offline);
+const reverb = Reverb.create(offline, { decay: sec(3) });
+kick.connect(reverb.in);
+reverb.out.connect(offline.destination);
+
+transport.play(steps('x...x...x...x...'), kick);
+transport.start(sec(0));
+const rendered: AudioBuffer = await offline.startRendering();
+```
+
+A realtime transport runs its own 25 ms timer. Pass `clock: 'manual'` to drive it yourself, for example from a worker timer or a test loop. Call `tick()` more often than the `lookahead` (default 0.1 s):
+
+```ts
+import { createTransport } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx, { clock: 'manual' });
+transport.start();
+setInterval(() => transport.tick(), 20);
+```
+
+## Module reference with jq
+
+`docs/modules.json` is the whole module reference as one object, keyed by export name. It contains what you need to use a module and nothing internal:
+
+```json
+{
+  "Delay": {
+    "name": "Delay",
+    "panel": "DELAY",
+    "import": "import { Delay } from '@jpdutoit/squelchy';",
+    "summary": "Echo Effect",
+    "description": "…",
+    "categories": ["Time"],
+    "inputs":  { "in":  { "signal": "audio", "name": "Audio Input", "description": "…", "target": "AudioNode" } },
+    "outputs": { "out": { "signal": "audio", "name": "Audio Output", "description": "…", "type": "AudioNode" } },
+    "params":  { "time": { "name": "Delay Time", "description": "…", "type": "Seconds", "unit": "s",
+                           "default": 0.3, "min": 0.01, "max": 1, "scale": "log", "automatable": true } }
+  }
+}
+```
+
+- `panel` is the module's name on squelchy.studio.
+- `signal` is one of `audio`, `modulation`, `gate` or `pitch`.
+- An input's `target` is `AudioParam` when the input sums straight onto a parameter.
+- `automatable: true` means `params.<key>` exists.
+
+From a project with the package installed:
+
+```sh
+DOCS=node_modules/@jpdutoit/squelchy/docs/modules.json
+
+jq 'keys' "$DOCS"                                   # every module
+jq '.Delay' "$DOCS"                                 # one module's full docs
+jq '.Vcf.params.note' "$DOCS"                       # one parameter
+jq '.Delay.params | map_values(.default)' "$DOCS"   # defaults, shaped like create() params
+jq '.Vco.inputs | keys' "$DOCS"                     # a module's inputs
+jq -r 'to_entries[] | select(.value.categories | index("Time")) | .key' "$DOCS"      # modules in a category
+jq -r 'to_entries[] | select(any(.value.inputs[]; .signal == "gate")) | .key' "$DOCS" # modules with a gate input
+jq -r 'to_entries[] | .key as $m | .value.params | to_entries[] | select(.value.automatable | not) | "\($m).\(.key)"' "$DOCS" # set()-only params
+```