@jpdutoit/squelchy 0.0.4 → 0.0.5

package/README.md

@@ -18,7 +18,7 @@ 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) }); // unpatched, offset is the note: 57 = A3
+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 });
 
@@ -32,6 +32,8 @@ 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.

package/docs/GUIDE.md

@@ -15,7 +15,7 @@ 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 vco = Vco.create(ctx, { offset: semitones(45) }); // nothing in voct = note 0 (C-1); 45 semitones up = A2
 const lfo = Lfo.create(ctx, { frequency: hz(0.2), amount: semitones(18) });
 const filter = Vcf.create(ctx, { note: note('C6'), resonance: 4 });
 
@@ -27,6 +27,8 @@ filter.out.connect(ctx.destination);
 lfo.output('out').connect(filter.input('modFreq'));
 ```
 
+**Pitch is V/OCT plus `offset`.** A VCO plays the note on its `voct` input plus `offset` semitones, and it has no hidden "note" setting: Web Audio inputs can only add, so nothing can switch off when a cable arrives. With `voct` empty, the input is note 0 (C-1), so `offset` counts up from there: `semitones(69)` plays A4. To write the note by name, measure from note 0: `interval(note(0), note('A4'))`. With a sequencer or keyboard in `voct`, set `offset` to 0 to play the notes as written, or ±12 for an octave.
+
 ### 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`.
@@ -49,6 +51,21 @@ filter.params.resonance;
 filter.dispose(); // disconnect and release when you're done
 ```
 
+**Ramping pitch and cutoff.** Pitch and cutoff parameters are notes or semitones (a VCO's `offset`, filter cutoffs), so they are already logarithmic: every 12 is an octave. A `linearRampToValueAtTime` between two values sweeps evenly in pitch, which is usually what you want. `exponentialRampToValueAtTime` is the Hz habit: on a note parameter it curves the sweep a second time, so it crawls through the low end and rushes the top.
+
+```ts
+import { preload, Vcf, note } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+await preload(ctx);
+const filter = Vcf.create(ctx, { filterType: 'bandpass', note: note('C4') });
+const t = ctx.currentTime;
+
+// A riser: 5 octaves, evenly in pitch over 4 seconds.
+filter.params.note.setValueAtTime(note('C4'), t);
+filter.params.note.linearRampToValueAtTime(note('C9'), t + 4);
+```
+
 ## 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`.
@@ -103,7 +120,7 @@ playOn(asPitch(lfo.out)); // deliberate: you said so
 
 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.
+Bars and beats count from 0, as on a timeline: `{ bar: 0 }` is the first bar, `{ bar: 1 }` starts at beat 4, and `{ bar: 1, beat: beats(2) }` is the third beat of the second bar (beat 6).
 
 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`.
 
@@ -122,7 +139,7 @@ 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'
+  start: 'bar',       // 'now' | 'beat' | 'bar' | { bar: n } | { bar: n, beat: n } | { beat: n }; default 'bar'
   loop: true,         // true = forever, false = once, n = n times
 });
 transport.start();
@@ -214,6 +231,8 @@ transport.stop();            // stop everything
 
 `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.
 
+`fn` runs a lookahead early, so it's the wrong place for UI. Pass `onAudible` for that: it fires when the position is actually heard, output latency included, just like `onHit`. Cancelling cancels both.
+
 ```ts
 import { createTransport, preload, Vcf, note, sec } from '@jpdutoit/squelchy';
 
@@ -225,11 +244,12 @@ filter.out.connect(ctx.destination);
 
 const bar = sec((transport.beatsPerBar * 60) / transport.bpm);
 
-// Open the filter over two bars, starting at bar 3.
+// Open the filter over two bars, starting at bar 3; tell the UI when the sweep is heard.
+const showDrop = () => { /* update the screen */ };
 const cancel = transport.at({ bar: 2 }, (t) => {
   filter.params.note.setValueAtTime(note('C4'), t);
   filter.params.note.linearRampToValueAtTime(note('C7'), t + 2 * bar);
-});
+}, { onAudible: showDrop });
 transport.start();
 // cancel(); // if you change your mind before it fires
 ```
@@ -249,6 +269,7 @@ 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.at({ bar: 8 }, () => {}, { onAudible: () => highlight(-1) });       // a moment, not a hit
 transport.start();
 ```
 
@@ -279,6 +300,21 @@ transport.play(notes('C2 C2 . C3 . C2 Eb2 . G2 . C2 . Bb1 . C2 .'), cv, { gate:
 transport.start();
 ```
 
+To change the notes on their way to the voice, wrap it in a function. `transpose()` keeps the result typed as a note:
+
+```ts
+import { createTransport, notes, transpose, semitones, NoteCv, type Hit, type Note, type Seconds } from '@jpdutoit/squelchy';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx);
+const cv = NoteCv.create(ctx);
+
+let key = semitones(0);
+const inKey = (time: Seconds, hit: Hit<Note>) => cv.trigger(time, { ...hit, value: transpose(hit.value, key) });
+transport.play(notes('C2 . Eb2 G2'), inKey);
+key = semitones(5); // later hits play a fourth up
+```
+
 ## 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.
@@ -354,6 +390,25 @@ transport.start();
 
 A sample voice is one-shot, like a drum machine: every hit plays the whole sample, whatever the step's gate length. Its step value is a note, so the same `notes()` melody plays on a sampler and on a synth voice.
 
+**Swapping kits while playing.** `voice.setKit(kit)` plays later hits from another kit. Patterns, connections and sidechains stay as they are, and samples already ringing (or scheduled within the lookahead) finish on the old kit, so nothing gets cut off.
+
+```ts
+import { createTransport, steps, loadSampleSet, SampleVoice } from '@jpdutoit/squelchy';
+import { Tr909 } from '@jpdutoit/squelchy/kits/tr-909';
+import { Roland808 } from '@jpdutoit/squelchy/kits/roland-808';
+
+const ctx = new AudioContext();
+const transport = createTransport(ctx);
+const bd = SampleVoice.create(ctx, await loadSampleSet(ctx, Tr909), 'bd');
+bd.connect(ctx.destination);
+transport.play(steps('x...x...x...x...'), bd);
+transport.start();
+
+const tr808 = await loadSampleSet(ctx, Roland808);
+bd.setKit(tr808); // hits scheduled from now on (about a lookahead ahead) play the 808
+console.log(bd.kit.set.name);
+```
+
 **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:

package/docs/MODULES.md

@@ -1190,7 +1190,7 @@ Categories: Sources · Worklets: map-voct-to-freq, waveshaper
 |---|---|---|---|
 | `skew` | `1` | -1 – 1 | **Waveshape Skew** — Symmetry of the waveform: −1 reversed sawtooth, 0 symmetric, +1 sawtooth. Automatable: `params.skew` is a native AudioParam. |
 | `shape` | `0` | -1 – 1 | **Waveshape Curvature** — Curvature of the waveform: −1 square, 0 triangle, +1 sine. Automatable: `params.shape` is a native AudioParam. |
-| `offset` | `69` | -48 – 108 semitones | **Pitch Offset** — Semitones added to the V/OCT input (12 = one octave). Unpatched the input is silent, so this is the note itself: 69 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave. Automatable: `params.offset` is a native AudioParam. |
+| `offset` | `69` | -48 – 108 semitones | **Pitch Offset** — Semitones added to the V/OCT input (12 = one octave). Unpatched, the input is silent (note 0, C−1), so the offset counts up from there: 69 semitones above C−1 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave. Automatable: `params.offset` is a native AudioParam. |
 | `detune` | `0` | -1 – 1 semitones | **Detune** — Fine pitch offset in semitones; ±1 = ±100 cents. Use for detuning oscillators against each other. Automatable: `params.detune` is a native AudioParam. |
 | `gain` | `0.5` | 0 – 1 | **Output Level** — Amplitude of the oscillator output signal. Automatable: `params.gain` is a native AudioParam. |
 

package/docs/modules.json

@@ -3164,7 +3164,7 @@
       },
       "offset": {
         "name": "Pitch Offset",
-        "description": "Semitones added to the V/OCT input (12 = one octave). Unpatched the input is silent, so this is the note itself: 69 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave.",
+        "description": "Semitones added to the V/OCT input (12 = one octave). Unpatched, the input is silent (note 0, C−1), so the offset counts up from there: 69 semitones above C−1 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave.",
         "type": "Semitones",
         "unit": "semitone",
         "default": 69,

package/index.d.ts

@@ -125,12 +125,20 @@ export type Signal<Q> = AudioNode & {
 /** Reinterpret a node as a pitch signal — the greppable escape hatch for
  *  deliberate cross-quantity patches. */
 export declare const asPitch: (n: AudioNode) => Signal<Note>;
-/** Where a playback starts. Default 'bar' = next bar line (beat 0 if stopped). */
+/** A musical position. 'now' | 'beat' | 'bar' are the next of each from the
+ *  current position (beat 0 if stopped). `{ bar: 3, beat: 2 }` is beat 2 of
+ *  bar 3 (both count from 0); `{ beat: n }` is an absolute beat. */
 export type StartAt = "now" | "beat" | "bar" | {
 	bar: number;
+	beat?: Beats;
 } | {
 	beat: Beats;
 };
+interface AtOptions {
+	/** Fires when the position is actually heard (output latency included),
+	 *  like `onHit`. Use it for UI; `fn` runs a lookahead early, for audio. */
+	onAudible?: (time: Seconds) => void;
+}
 /** Rich step form, for when a plain value isn't enough. */
 export interface StepObject<V> {
 	value: V;
@@ -211,8 +219,10 @@ export interface Transport {
 	resolve(at: StartAt): Beats;
 	/** Play a pattern array through a voice. */
 	play<V>(pattern: readonly Step<V>[], voice: Voice<V>, opts?: PlayOptions<V>): Playback<V>;
-	/** Run `fn(time)` once at a musical position — for automation, e.g. `vca.set('gain', 0, time)`. */
-	at(when: StartAt | Beats, fn: (time: Seconds) => void): () => void;
+	/** Run `fn(time)` once, a lookahead before a musical position, with its exact
+	 *  audio time — for automation. `onAudible` fires when that moment is heard.
+	 *  Returns a cancel function (cancels both). */
+	at(when: StartAt | Beats, fn: (time: Seconds) => void, opts?: AtOptions): () => void;
 	/** Global visual tap: every hit of every playback, fired when audible. Returns unsubscribe. */
 	onHit(cb: (hit: Hit) => void): () => void;
 	/** Schedule everything due inside the lookahead window. Auto-called in 'auto' mode. */
@@ -322,13 +332,22 @@ export interface SampleVoiceOptions {
 	/** The note that plays the sample unshifted. Default 60 (C4). */
 	root?: Note;
 }
+/** A sample voice: a VoiceInstance whose kit can be swapped while playing. */
+export interface SampleVoiceInstance extends VoiceInstance<Note | boolean> {
+	/** The kit hits are played from. */
+	readonly kit: LoadedSampleSet;
+	/** Play later hits from another kit (same voice key, same fallback chain).
+	 *  Hits already scheduled (up to the transport's lookahead) and samples
+	 *  still ringing keep the old kit, so the swap never cuts a tail. */
+	setKit(kit: LoadedSampleSet): void;
+}
 /** A one-shot sample voice, like a drum machine: every hit plays the whole
  *  sample, whatever the step's gate length. velocity 0..1 scales level. A
  *  `Note` value plays the sample at that note (`root` = unshifted), the same
  *  numbers `NoteCv` plays, so `notes()` melodies work on both; anything else
  *  (e.g. `true` from steps()) plays it unshifted. */
 export declare const SampleVoice: {
-	create(ctx: BaseAudioContext, kit: LoadedSampleSet, key: VoiceKey, opts?: SampleVoiceOptions): VoiceInstance<Note | boolean>;
+	create(ctx: BaseAudioContext, kit: LoadedSampleSet, key: VoiceKey, opts?: SampleVoiceOptions): SampleVoiceInstance;
 };
 export interface AcidFilterParams {
 	/** Cutoff Note. Base cutoff as a note (67 ≈ 400 Hz, 69 = 440 Hz) for the iconic squelchy acid sound. Drives the V/OCT worklet 1:1 — the panel knob shows the equivalent Hz. Range 15–135 notes. Default 67. */
@@ -1647,7 +1666,7 @@ export interface VcoParams {
 	skew?: number;
 	/** Waveshape Curvature. Curvature of the waveform: −1 square, 0 triangle, +1 sine. Range -1–1. Default 0. */
 	shape?: number;
-	/** Pitch Offset. Semitones added to the V/OCT input (12 = one octave). Unpatched the input is silent, so this is the note itself: 69 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave. Range -48–108 semitones. Default 69. */
+	/** Pitch Offset. Semitones added to the V/OCT input (12 = one octave). Unpatched, the input is silent (note 0, C−1), so the offset counts up from there: 69 semitones above C−1 = A4. Driven by an absolute pitch CV (keyboard, sequencer), set 0 to play as-is or ±12 to shift an octave. Range -48–108 semitones. Default 69. */
 	offset?: Semitones;
 	/** Detune. Fine pitch offset in semitones; ±1 = ±100 cents. Use for detuning oscillators against each other. Range -1–1 semitones. Default 0. */
 	detune?: Semitones;

package/index.js

@@ -180,26 +180,29 @@ function createTransport(ctx, opts = {}) {
     if (at === "now") return now2;
     if (at === "beat") return Math.ceil(now2 - EPS);
     if (at === "bar") return Math.ceil(now2 / beatsPerBar - EPS) * beatsPerBar;
-    if ("bar" in at) return at.bar * beatsPerBar;
+    if ("bar" in at) return at.bar * beatsPerBar + (at.beat ?? 0);
     return at.beat;
   }
   const latency = () => ctx.outputLatency || ctx.baseLatency || 0;
-  function emitTap(hit, local) {
-    if (!local && taps.size === 0) return;
-    const fire = () => {
-      local?.(hit);
-      for (const cb of taps) cb(hit);
-    };
+  function whenAudible(time, fire) {
     if (offline) {
       fire();
-      return;
+      return void 0;
     }
-    const delay = Math.max(0, (hit.time - ctx.currentTime + latency()) * 1e3);
+    const delay = Math.max(0, (time - ctx.currentTime + latency()) * 1e3);
     const id = setTimeout(() => {
       tapTimers.delete(id);
       fire();
     }, delay);
     tapTimers.add(id);
+    return id;
+  }
+  function emitTap(hit, local) {
+    if (!local && taps.size === 0) return;
+    whenAudible(hit.time, () => {
+      local?.(hit);
+      for (const cb of taps) cb(hit);
+    });
   }
   function horizonBeat() {
     if (offline) return beatAt(ctx.length / ctx.sampleRate);
@@ -320,16 +323,20 @@ function createTransport(ctx, opts = {}) {
         }
       };
     },
-    at(when, fn) {
+    at(when, fn, o = {}) {
       const b = typeof when === "number" ? when : resolve(when);
       let fired = false;
+      let audibleTimer;
       const job = {
         nextBeat: () => b,
         run(until) {
           if (fired) return false;
           if (b < until) {
             fired = true;
-            fn(timeAt(b));
+            const time = timeAt(b);
+            fn(time);
+            const onAudible = o.onAudible;
+            if (onAudible) audibleTimer = whenAudible(time, () => onAudible(time));
             return false;
           }
           return true;
@@ -340,6 +347,10 @@ function createTransport(ctx, opts = {}) {
       return () => {
         fired = true;
         jobs.delete(job);
+        if (audibleTimer !== void 0) {
+          clearTimeout(audibleTimer);
+          tapTimers.delete(audibleTimer);
+        }
       };
     },
     onHit(cb) {
@@ -604,8 +615,9 @@ async function loadSampleSet(ctx, set, opts = {}) {
 var SampleVoice = {
   create(ctx, kit, key, opts = {}) {
     const out = ctx.createGain();
-    const buf = kit.buffer(key);
     const root = opts.root ?? 60;
+    let current = kit;
+    let buf = kit.buffer(key);
     const trigger = (when, h) => {
       if (!buf) return;
       const src = ctx.createBufferSource();
@@ -619,6 +631,13 @@ var SampleVoice = {
     return {
       output: out,
       trigger,
+      get kit() {
+        return current;
+      },
+      setKit(next) {
+        current = next;
+        buf = next.buffer(key);
+      },
       connect: (d) => {
         out.connect(d);
         return d;