@jpdutoit/squelchy

The modules behind Squelchy, the modular synth in your browser, as plain Web Audio building blocks. Oscillators, filters, envelopes, effects and drum kits behave like native nodes: you connect() them, and parameters that drive the sound 1:1 are real AudioParams you can automate.

• Zero dependencies, zero asset setup. AudioWorklet processors are inlined and registered from blob URLs.
• Tree-shakeable. Import one module and only its worklets end up in your bundle.
• Typed units. Notes, semitones, Hz, seconds and beats are distinct types, so mixing them up is a compile error.

npm install @jpdutoit/squelchy

Quick start

import { preload, Vco, Lfo, Delay, semitones, sec, hz } from '@jpdutoit/squelchy';

const ctx = new AudioContext();
await preload(ctx); // registers the worklets of the modules you import

const vco = Vco.create(ctx, { offset: semitones(57) }); // nothing in voct = note 0 (C-1); 57 semitones up = A3
const lfo = Lfo.create(ctx, { frequency: hz(5), amount: semitones(0.3) });
const delay = Delay.create(ctx, { time: sec(0.3), feedback: 0.4, mix: 0.35 });

lfo.out.connect(vco.modDetune); // vibrato
vco.out.connect(delay.in);
delay.out.connect(ctx.destination);

// Parameters that map 1:1 onto the DSP are native AudioParams.
delay.params.mix.linearRampToValueAtTime(0.8, ctx.currentTime + 2);

Browsers only start audio after a user gesture, so create or resume() the AudioContext inside a click handler.

Importing the package is safe on the server (SSR, Node tests): nothing touches Web Audio until you call preload() or create(), so a static import in shared code is fine.

Patterns and time

Musical positions are plain numbers in beats, and patterns are plain arrays.

import { createTransport, steps, Kick, Hat } from '@jpdutoit/squelchy';

const ctx = new AudioContext();
const transport = createTransport(ctx, { bpm: 120 });
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);
transport.play(steps('..x...x...x...x.'), hat);
transport.start();

Sample kits

Drum kits are CC0 / public domain and ship inside the package, one import per kit. Your bundler copies and hashes the sound files of the kits you import, and only those. The full list is in docs/GUIDE.md.

import { loadSampleSet, SampleVoice, now } from '@jpdutoit/squelchy';
import { Roland808 } from '@jpdutoit/squelchy/kits/roland-808';

const ctx = new AudioContext();
const kit = await loadSampleSet(ctx, Roland808);
const bd = SampleVoice.create(ctx, kit, 'bd');
bd.connect(ctx.destination);
bd.trigger(now(ctx)); // times are typed Seconds; now(ctx) is ctx.currentTime

Vite 6 or 7: add optimizeDeps: { exclude: ['@jpdutoit/squelchy'] } to vite.config, or kit sounds fail to load in the dev server (production builds work either way). Vite 8 needs nothing. Details in docs/GUIDE.md.

Reference

• docs/GUIDE.md: recipes for scheduling (transport options, automation at musical positions, synced visuals), sequencing synth voices, pulse() actions, units, sample kits and offline rendering.
• docs/MODULES.md: every module's ports, parameters, ranges and defaults, and which parameters are automatable (the rest change instantly with set()).
• docs/modules.json: the same reference keyed by export name, for jq (e.g. jq '.Delay' node_modules/@jpdutoit/squelchy/docs/modules.json).
• Types need the DOM lib in your tsconfig.json.
• Under a strict Content-Security-Policy, allow worker-src blob: so the worklets can load.