smplr 0.17.1 → 0.18.1

package/README.md

@@ -328,6 +328,200 @@ const piano = new SplendidGrandPiano(context, { storage });
 
 ⚠️ `CacheStorage` is based on [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) and only works in secure environments that runs with `https`. Read your framework documentation for setup instructions. For example, in nextjs you can use https://www.npmjs.com/package/next-dev-https. For vite there's https://github.com/liuweiGL/vite-plugin-mkcert. Find the appropriate solution for your environment.
 
+## Sequencer
+
+`Sequencer` schedules notes from one or more tracks against any smplr instrument with sample-accurate timing.
+
+```js
+import { Sequencer, SplendidGrandPiano, DrumMachine } from "smplr";
+
+const context = new AudioContext();
+const piano = new SplendidGrandPiano(context);
+const drums = new DrumMachine(context, { instrument: "TR-808" });
+
+const seq = new Sequencer(context, { bpm: 120, loop: true });
+
+seq.addTrack(piano, [
+  { note: "C4", at: "1:1", duration: "4n" },
+  { note: "E4", at: "1:2", duration: "4n" },
+  { note: "G4", at: "1:3", duration: "4n" },
+  { note: "C5", at: "1:4", duration: "2n" },
+]);
+
+seq.addTrack(drums, [
+  { note: "kick", at: "1:1" },
+  { note: "snare", at: "1:2" },
+  { note: "kick", at: "1:3" },
+  { note: "snare", at: "1:4" },
+]);
+
+seq.loopEnd = "2:1"; // 1 bar
+seq.start();
+```
+
+#### Time notation
+
+Note positions and durations accept several formats:
+
+| Format     | Meaning                        |
+| ---------- | ------------------------------ |
+| `"4n"`     | quarter note                   |
+| `"8n"`     | eighth note                    |
+| `"4n."`    | dotted quarter (1.5×)          |
+| `"1m"`     | one measure                    |
+| `"2:1"`    | bar 2, beat 1 (1-indexed)      |
+| `"2:3:48"` | bar 2, beat 3, +48 ticks       |
+| `96`       | raw ticks (number passthrough) |
+
+#### Constructor options
+
+```js
+const seq = new Sequencer(context, {
+  bpm: 120, // default 120
+  ppq: 480, // pulses per quarter note, default 480
+  timeSignature: 4, // beats per bar, default 4
+  loop: false, // default false
+  loopStart: 0, // loop start position (ticks or string)
+  loopEnd: "2:1", // loop end position; defaults to end of longest track
+  lookaheadMs: 200, // scheduling lookahead, default 200
+  intervalMs: 50, // flush interval, default 50
+  humanize: { timingMs: 10, velocity: 8 }, // optional randomisation
+});
+```
+
+#### Playback
+
+```js
+seq.start(); // start from beginning (or resume from pause if no offset given)
+seq.pause(); // freeze position
+seq.stop(); // stop and reset to 0
+seq.togglePlayPause(); // pause if playing, start/resume otherwise
+
+seq.state; // "stopped" | "playing" | "paused"
+```
+
+Individual sequenced notes can be stopped by their id:
+
+```js
+seq.stopNote("intro-c"); // stop immediately
+seq.stopNote("intro-c", time); // stop at a scheduled time
+```
+
+#### Tempo and position
+
+```js
+seq.bpm = 140; // change BPM live, no glitch
+seq.timeSignature = 3; // change time signature
+
+seq.position; // current position as "bar:beat:tick" string
+seq.position = "3:1"; // seek while playing or stopped
+```
+
+#### Loop
+
+```js
+seq.loop = true;
+seq.loopStart = "1:1"; // ticks or string notation
+seq.loopEnd = "3:1"; // ticks or string notation
+
+seq.progress; // 0..1 within the loop range
+```
+
+#### Pattern API
+
+`scheduleRepeat` fires a callback at a regular musical interval, passing the exact AudioContext time:
+
+```js
+const cancel = seq.scheduleRepeat((time) => {
+  piano.start({ note: "C4", time, duration: 0.1 });
+}, "8n"); // every eighth note
+
+cancel(); // stop repeating
+```
+
+An optional third argument sets the start position:
+
+```js
+seq.scheduleRepeat(callback, "4n", "2:1"); // start at bar 2
+```
+
+#### Events
+
+```js
+seq.on("statechange", (state) => {
+  // state: "playing" | "paused" | "stopped"
+  setSeqState(state);
+});
+
+seq.on("beat", (beat, time) => {
+  const delay = (time - context.currentTime) * 1000;
+  setTimeout(() => metronome.flash(), delay);
+});
+
+seq.on("bar", (bar, time) => {
+  ui.updateBar(bar);
+});
+seq.on("loop", () => {
+  console.log("looped");
+});
+seq.on("end", () => {
+  console.log("done");
+});
+seq.on("start", () => {});
+seq.on("stop", () => {});
+seq.on("pause", () => {});
+
+seq.off("beat", handler); // remove a listener
+```
+
+#### Note events
+
+`noteOn` and `noteOff` events fire when the instrument's `onStart` / `onEnded` callbacks are called, so they are driven by the actual audio playback — not by the scheduling lookahead.
+
+```js
+seq.on("noteOn", (event) => {
+  console.log(event.noteId, event.trackIndex, event.noteIndex);
+  highlight(event.noteId);
+});
+seq.on("noteOff", (event) => {
+  unhighlight(event.noteId);
+});
+```
+
+The `event` object (`NoteEvent`) contains:
+
+| Field        | Type               | Description                                            |
+| ------------ | ------------------ | ------------------------------------------------------ |
+| `noteId`     | `string \| number` | The note's `id` if provided, otherwise its array index |
+| `trackIndex` | `number`           | Index of the track in the order it was added           |
+| `noteIndex`  | `number`           | Index of the note within its track's notes array       |
+| `note`       | `SequencerNote`    | The original note object                               |
+
+You can set a custom `id` on any `SequencerNote` to use as `noteId`:
+
+```js
+seq.addTrack(piano, [
+  { id: "intro-c", note: "C4", at: "1:1", duration: "4n" },
+  { id: "intro-e", note: "E4", at: "1:2", duration: "4n" },
+]);
+```
+
+#### Humanize
+
+Add subtle randomisation to timing and velocity for a more natural feel:
+
+```js
+const seq = new Sequencer(context, {
+  bpm: 90,
+  humanize: { timingMs: 12, velocity: 8 },
+});
+```
+
+- `timingMs`: maximum random offset in milliseconds (±). Default 0.
+- `velocity`: maximum random offset in MIDI velocity units (±). Default 0.
+
+---
+
 ## Instruments
 
 ### Sampler

package/dist/index.d.mts

@@ -122,7 +122,7 @@ type SmplrJson = {
 /**
  * A note event passed to Smplr.start(). Can be a full object, a note name, or a MIDI number.
  */
-type NoteEvent = {
+type NoteEvent$1 = {
     note: string | number;
     velocity?: number;
     time?: number;
@@ -132,8 +132,8 @@ type NoteEvent = {
     loop?: boolean;
     ampRelease?: number;
     stopId?: string | number;
-    onStart?: (event: NoteEvent) => void;
-    onEnded?: (event: NoteEvent) => void;
+    onStart?: (event: NoteEvent$1) => void;
+    onEnded?: (event: NoteEvent$1) => void;
 } | string | number;
 /**
  * Target for Smplr.stop(). Can be a full object, a stopId, or a MIDI number.
@@ -199,7 +199,7 @@ declare class DrumMachine {
     getSampleNames(): string[];
     getGroupNames(): string[];
     getSampleNamesForGroup(groupName: string): string[];
-    start(sample: NoteEvent): StopFn;
+    start(sample: NoteEvent$1): StopFn;
     stop(sample?: StopTarget): void;
     disconnect(): void;
     /** @deprecated */
@@ -218,6 +218,189 @@ declare class DrumMachine {
  */
 declare function drumMachineToSmplrJson(instrument: DrumMachineInstrument): SmplrJson;
 
+/**
+ * TransportClock
+ *
+ * Converts between musical ticks and AudioContext time with support for:
+ *   - BPM changes mid-playback (via checkpoints)
+ *   - Pause / resume
+ *   - Seek to arbitrary tick position
+ *   - Loop restart (seekAt a future audio time)
+ *
+ * All time values are in AudioContext seconds (context.currentTime).
+ * Ticks are the internal unit: ppq ticks per quarter note.
+ *
+ * Principle: a Checkpoint records that at a specific audio time, a specific
+ * tick position was reached at a specific BPM. Checkpoints are always ordered
+ * by audioTime. The conversion functions find the last checkpoint whose
+ * audioTime (or tick) is <= the query value and interpolate from there.
+ */
+type TransportState = "stopped" | "playing" | "paused";
+
+type SequencerNote = {
+    /** Optional identifier for this note. Used as `noteId` in noteOn/noteOff events. Defaults to the note's array index. */
+    id?: string | number;
+    note: string | number;
+    /** Musical position: ticks, "4n", "1m", "2:1", "1:1.5", etc. */
+    at: string | number;
+    /** Note duration: ticks, "4n", "8n", etc. Omit for a one-shot trigger. */
+    duration?: string | number;
+    velocity?: number;
+};
+/**
+ * Any instrument the Sequencer can drive.
+ * Compatible with SplendidGrandPiano, DrumMachine, Smplr, and any object
+ * that has a `start()` method accepting note + optional scheduling params.
+ */
+type SequencerInstrument = {
+    start(event: {
+        note: string | number;
+        time?: number;
+        duration?: number;
+        velocity?: number;
+        noteId?: string | number;
+        onStart?: (event: unknown) => void;
+        onEnded?: (event: unknown) => void;
+    }): unknown;
+};
+/** Emitted with "noteOn" and "noteOff" events. */
+type NoteEvent = {
+    noteId: string | number;
+    trackIndex: number;
+    noteIndex: number;
+    note: SequencerNote;
+};
+type SequencerOptions = {
+    bpm?: number;
+    ppq?: number;
+    timeSignature?: number;
+    loop?: boolean;
+    loopStart?: string | number;
+    loopEnd?: string | number;
+    /** How far ahead (ms) to pre-schedule notes. Default 200. */
+    lookaheadMs?: number;
+    /** How often (ms) the flush loop runs. Default 50. */
+    intervalMs?: number;
+    /** Randomise timing (ms) and velocity per note for a human feel. */
+    humanize?: {
+        timingMs?: number;
+        velocity?: number;
+    };
+};
+declare class Sequencer {
+    private readonly _context;
+    private readonly _clock;
+    private readonly _ppq;
+    private _timeSignature;
+    private _tracks;
+    private _repeatEvents;
+    private _listeners;
+    private _loop;
+    private _loopStartTick;
+    /** null = default to _totalTicks */
+    private _loopEndOverride;
+    private _lookaheadSec;
+    private _intervalMs;
+    private _humanize;
+    private _intervalId;
+    /** AudioContext time high-water mark: notes up to here have been scheduled. */
+    private _scheduledThrough;
+    /** Computed from track notes; the tick where the last note ends. */
+    private _totalTicks;
+    /** Guards against scheduling the auto-stop setTimeout more than once. */
+    private _endScheduled;
+    /** Active voices keyed by noteId, so individual notes can be stopped. */
+    private _activeVoices;
+    constructor(context: BaseAudioContext, options?: SequencerOptions);
+    addTrack(instrument: SequencerInstrument, notes: SequencerNote[]): this;
+    removeTrack(instrument: SequencerInstrument): this;
+    clearTracks(): this;
+    get state(): TransportState;
+    /**
+     * Start playback from `offsetTick`, or resume from pause if no offset given.
+     */
+    start(offsetTick?: number): this;
+    pause(): this;
+    stop(): this;
+    /**
+     * Stop a single note that was scheduled by the sequencer.
+     * @param noteId  The id of the note (from SequencerNote.id or auto-assigned index).
+     * @param time    Optional AudioContext time to schedule the stop.
+     */
+    stopNote(noteId: string | number, time?: number): this;
+    /**
+     * Toggle between playing and paused. If stopped, starts from the beginning.
+     */
+    togglePlayPause(): this;
+    get bpm(): number;
+    set bpm(value: number);
+    get timeSignature(): number;
+    set timeSignature(value: number);
+    /** Current transport position as "bar:beat:tick" (1-indexed). */
+    get position(): string;
+    /**
+     * Seek to a position. Accepts ticks or any time string ("2:1", "4n", …).
+     * Works while playing (seamless) or stopped/paused.
+     */
+    set position(value: string | number);
+    get loop(): boolean;
+    set loop(value: boolean);
+    /** Loop start in ticks. */
+    get loopStart(): number;
+    set loopStart(value: string | number);
+    /** Loop end in ticks. Defaults to the end of the longest track. */
+    get loopEnd(): number;
+    set loopEnd(value: string | number);
+    /**
+     * Normalised loop position [0, 1]. Always 0 when loop=false.
+     */
+    get progress(): number;
+    /**
+     * Schedule a callback to fire on every `interval` while the sequencer plays.
+     * Returns a cancel function.
+     *
+     * @param callback  Called with the exact AudioContext time of each firing.
+     * @param interval  Musical interval: "4n", "8n", "1m", ticks, etc.
+     * @param startAt   First firing position (default 0 = beginning).
+     */
+    scheduleRepeat(callback: (time: number) => void, interval: string | number, startAt?: string | number): () => void;
+    /**
+     * Listen to a sequencer event.
+     *
+     * | Event          | Args                                              |
+     * |----------------|---------------------------------------------------|
+     * | "statechange"  | (state: "playing" \| "paused" \| "stopped")       |
+     * | "start"        |                                                   |
+     * | "stop"         |                                                   |
+     * | "pause"        |                                                   |
+     * | "end"          |                                                   |
+     * | "loop"         |                                                   |
+     * | "beat"         | (beat: number, time: number)                      |
+     * | "bar"          | (bar: number, time: number)                       |
+     * | "noteOn"       | (event: NoteEvent)                                |
+     * | "noteOff"      | (event: NoteEvent)                                |
+     */
+    on(event: string, callback: (...args: any[]) => void): this;
+    off(event: string, callback: (...args: any[]) => void): this;
+    private _startLoop;
+    private _stopLoop;
+    private _flush;
+    private _scheduleWindow;
+    private _emitBeatsInWindow;
+    private _emit;
+    /** Emit both the specific state event ("start"/"pause"/"stop") and the unified "statechange" event. */
+    private _emitStateChange;
+    /** Recompute _totalTicks from all track notes (at + duration). */
+    private _recomputeTotalTicks;
+    /** Format a raw tick count as "bar:beat:tick" (all 1-indexed). */
+    private _tickToPosition;
+    /**
+     * Reset all repeat events so their next firing is the first occurrence
+     * at or after `fromTick`.
+     */
+    private _resetRepeatEvents;
+}
+
 declare function getElectricPianoNames(): string[];
 type ElectricPianoOptions = Partial<{
     instrument: string;
@@ -241,7 +424,7 @@ declare class ElectricPiano {
     });
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -270,7 +453,7 @@ declare class Versilian {
     constructor(context: BaseAudioContext, options?: VersilianOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -301,7 +484,7 @@ declare class Mellotron {
     constructor(context: BaseAudioContext, options?: MellotronOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -359,7 +542,7 @@ declare class Sampler {
     constructor(context: AudioContext, options?: Partial<SamplerConfig>);
     loaded(): Promise<this>;
     get output(): OutputChannel;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
     disconnect(): void;
 }
@@ -399,7 +582,7 @@ declare class Smolken {
     constructor(context: BaseAudioContext, options?: SmolkenOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -433,7 +616,7 @@ declare class Soundfont {
     get output(): OutputChannel;
     loaded(): Promise<this>;
     disconnect(): void;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
 }
 /**
@@ -492,7 +675,7 @@ declare class Soundfont2Sampler {
     get instrumentNames(): string[];
     get output(): OutputChannel;
     loadInstrument(instrumentName: string): Promise<void> | undefined;
-    start(sample: NoteEvent | string | number): StopFn;
+    start(sample: NoteEvent$1 | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
     disconnect(): void;
 }
@@ -532,7 +715,7 @@ declare class SplendidGrandPiano {
     get loadProgress(): LoadProgress;
     /** @deprecated Use `load` instead. */
     loaded(): Promise<this>;
-    start(event: NoteEvent): StopFn;
+    start(event: NoteEvent$1): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -561,4 +744,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { CacheStorage, DrumMachine, type DrumMachineOptions, ElectricPiano, type ElectricPianoOptions, HttpStorage, LAYERS, Mallet, Mellotron, type MellotronConfig, type MellotronOptions, NAME_TO_PATH, Reverb, Sampler, type SamplerConfig, Smolken, type SmolkenConfig, type SmolkenOptions, Soundfont, type Soundfont2Options, Soundfont2Sampler, type SoundfontOptions, SplendidGrandPiano, type SplendidGrandPianoConfig, type Storage, type StorageResponse, Versilian, type VersilianConfig, type VersilianOptions, drumMachineToSmplrJson, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, mellotronToSmplrJson, pianoToSmplrJson, samplerToSmplrJson, sf2InstrumentToSmplrJson, soundfontToSmplrJson, spreadKeyRanges };
+export { CacheStorage, DrumMachine, type DrumMachineOptions, ElectricPiano, type ElectricPianoOptions, HttpStorage, LAYERS, Mallet, Mellotron, type MellotronConfig, type MellotronOptions, NAME_TO_PATH, type NoteEvent, Reverb, Sampler, type SamplerConfig, Sequencer, type SequencerInstrument, type SequencerNote, type SequencerOptions, Smolken, type SmolkenConfig, type SmolkenOptions, Soundfont, type Soundfont2Options, Soundfont2Sampler, type SoundfontOptions, SplendidGrandPiano, type SplendidGrandPianoConfig, type Storage, type StorageResponse, Versilian, type VersilianConfig, type VersilianOptions, drumMachineToSmplrJson, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, mellotronToSmplrJson, pianoToSmplrJson, samplerToSmplrJson, sf2InstrumentToSmplrJson, soundfontToSmplrJson, spreadKeyRanges };