smplr 0.18.0 → 0.18.1

package/README.md

@@ -349,9 +349,9 @@ seq.addTrack(piano, [
 ]);
 
 seq.addTrack(drums, [
-  { note: "kick",  at: "1:1" },
+  { note: "kick", at: "1:1" },
   { note: "snare", at: "1:2" },
-  { note: "kick",  at: "1:3" },
+  { note: "kick", at: "1:3" },
   { note: "snare", at: "1:4" },
 ]);
 
@@ -363,60 +363,68 @@ seq.start();
 
 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)       |
+| 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: { timing: 0.01, velocity: 8 }, // optional randomisation
+  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.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"
+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.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
+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.loopStart = "1:1"; // ticks or string notation
+seq.loopEnd = "3:1"; // ticks or string notation
 
-seq.progress;            // 0..1 within the loop range
+seq.progress; // 0..1 within the loop range
 ```
 
 #### Pattern API
@@ -440,19 +448,30 @@ 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.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
+seq.off("beat", handler); // remove a listener
 ```
 
 #### Note events
@@ -471,12 +490,12 @@ seq.on("noteOff", (event) => {
 
 The `event` object (`NoteEvent`) contains:
 
-| Field        | Type               | Description                                      |
-|--------------|--------------------|--------------------------------------------------|
+| 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                          |
+| `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`:
 
@@ -489,15 +508,18 @@ seq.addTrack(piano, [
 
 #### Humanize
 
-Add subtle randomisation to timing (seconds) and velocity for a more natural feel:
+Add subtle randomisation to timing and velocity for a more natural feel:
 
 ```js
 const seq = new Sequencer(context, {
   bpm: 90,
-  humanize: { timing: 0.012, velocity: 8 },
+  humanize: { timingMs: 12, velocity: 8 },
 });
 ```
 
+- `timingMs`: maximum random offset in milliseconds (±). Default 0.
+- `velocity`: maximum random offset in MIDI velocity units (±). Default 0.
+
 ---
 
 ## Instruments

package/dist/index.d.mts

@@ -259,12 +259,8 @@ type SequencerInstrument = {
         duration?: number;
         velocity?: number;
         noteId?: string | number;
-        onStart?: (event: {
-            noteId?: string | number;
-        }) => void;
-        onEnded?: (event: {
-            noteId?: string | number;
-        }) => void;
+        onStart?: (event: unknown) => void;
+        onEnded?: (event: unknown) => void;
     }): unknown;
 };
 /** Emitted with "noteOn" and "noteOff" events. */
@@ -285,9 +281,9 @@ type SequencerOptions = {
     lookaheadMs?: number;
     /** How often (ms) the flush loop runs. Default 50. */
     intervalMs?: number;
-    /** Randomise timing (seconds) and velocity per note for a human feel. */
+    /** Randomise timing (ms) and velocity per note for a human feel. */
     humanize?: {
-        timing?: number;
+        timingMs?: number;
         velocity?: number;
     };
 };
@@ -313,6 +309,8 @@ declare class Sequencer {
     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;
@@ -324,6 +322,16 @@ declare class Sequencer {
     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;
@@ -359,17 +367,18 @@ declare class Sequencer {
     /**
      * Listen to a sequencer event.
      *
-     * | Event     | Args                         |
-     * |-----------|------------------------------|
-     * | "start"   |                              |
-     * | "stop"    |                              |
-     * | "pause"   |                              |
-     * | "end"     |                              |
-     * | "loop"    |                              |
-     * | "beat"    | (beat: number, time: number) |
-     * | "bar"     | (bar: number, time: number)  |
-     * | "noteOn"  | (event: NoteEvent)           |
-     * | "noteOff" | (event: NoteEvent)           |
+     * | 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;
@@ -379,6 +388,8 @@ declare class Sequencer {
     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). */

package/dist/index.d.ts

@@ -259,12 +259,8 @@ type SequencerInstrument = {
         duration?: number;
         velocity?: number;
         noteId?: string | number;
-        onStart?: (event: {
-            noteId?: string | number;
-        }) => void;
-        onEnded?: (event: {
-            noteId?: string | number;
-        }) => void;
+        onStart?: (event: unknown) => void;
+        onEnded?: (event: unknown) => void;
     }): unknown;
 };
 /** Emitted with "noteOn" and "noteOff" events. */
@@ -285,9 +281,9 @@ type SequencerOptions = {
     lookaheadMs?: number;
     /** How often (ms) the flush loop runs. Default 50. */
     intervalMs?: number;
-    /** Randomise timing (seconds) and velocity per note for a human feel. */
+    /** Randomise timing (ms) and velocity per note for a human feel. */
     humanize?: {
-        timing?: number;
+        timingMs?: number;
         velocity?: number;
     };
 };
@@ -313,6 +309,8 @@ declare class Sequencer {
     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;
@@ -324,6 +322,16 @@ declare class Sequencer {
     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;
@@ -359,17 +367,18 @@ declare class Sequencer {
     /**
      * Listen to a sequencer event.
      *
-     * | Event     | Args                         |
-     * |-----------|------------------------------|
-     * | "start"   |                              |
-     * | "stop"    |                              |
-     * | "pause"   |                              |
-     * | "end"     |                              |
-     * | "loop"    |                              |
-     * | "beat"    | (beat: number, time: number) |
-     * | "bar"     | (bar: number, time: number)  |
-     * | "noteOn"  | (event: NoteEvent)           |
-     * | "noteOff" | (event: NoteEvent)           |
+     * | 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;
@@ -379,6 +388,8 @@ declare class Sequencer {
     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). */

package/dist/index.js

@@ -1532,6 +1532,8 @@ var Sequencer = class {
     this._totalTicks = 0;
     /** Guards against scheduling the auto-stop setTimeout more than once. */
     this._endScheduled = false;
+    /** Active voices keyed by noteId, so individual notes can be stopped. */
+    this._activeVoices = /* @__PURE__ */ new Map();
     var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
     this._context = context;
     this._ppq = (_a = options.ppq) != null ? _a : 480;
@@ -1553,7 +1555,7 @@ var Sequencer = class {
     this._lookaheadSec = ((_e = options.lookaheadMs) != null ? _e : 200) / 1e3;
     this._intervalMs = (_f = options.intervalMs) != null ? _f : 50;
     this._humanize = {
-      timing: (_h = (_g = options.humanize) == null ? void 0 : _g.timing) != null ? _h : 0,
+      timing: (_h = (_g = options.humanize) == null ? void 0 : _g.timingMs) != null ? _h : 0,
       velocity: (_j = (_i = options.humanize) == null ? void 0 : _i.velocity) != null ? _j : 0
     };
   }
@@ -1590,7 +1592,7 @@ var Sequencer = class {
       this._clock.resume();
       this._scheduledThrough = this._context.currentTime;
       this._startLoop();
-      this._emit("start");
+      this._emitStateChange("playing");
       return this;
     }
     const startTick = offsetTick != null ? offsetTick : 0;
@@ -1599,23 +1601,44 @@ var Sequencer = class {
     this._endScheduled = false;
     this._resetRepeatEvents(startTick);
     this._startLoop();
-    this._emit("start");
+    this._emitStateChange("playing");
     return this;
   }
   pause() {
     if (this._clock.state !== "playing") return this;
     this._clock.pause();
     this._stopLoop();
-    this._emit("pause");
+    this._emitStateChange("paused");
     return this;
   }
   stop() {
     this._clock.stop();
     this._stopLoop();
     this._endScheduled = false;
-    this._emit("stop");
+    this._activeVoices.clear();
+    this._emitStateChange("stopped");
     return 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, time) {
+    const stopFn = this._activeVoices.get(noteId);
+    if (stopFn) {
+      stopFn(time);
+      this._activeVoices.delete(noteId);
+    }
+    return this;
+  }
+  /**
+   * Toggle between playing and paused. If stopped, starts from the beginning.
+   */
+  togglePlayPause() {
+    if (this._clock.state === "playing") return this.pause();
+    return this.start();
+  }
   // ---------------------------------------------------------------------------
   // Tempo
   // ---------------------------------------------------------------------------
@@ -1719,17 +1742,18 @@ var Sequencer = class {
   /**
    * Listen to a sequencer event.
    *
-   * | Event     | Args                         |
-   * |-----------|------------------------------|
-   * | "start"   |                              |
-   * | "stop"    |                              |
-   * | "pause"   |                              |
-   * | "end"     |                              |
-   * | "loop"    |                              |
-   * | "beat"    | (beat: number, time: number) |
-   * | "bar"     | (bar: number, time: number)  |
-   * | "noteOn"  | (event: NoteEvent)           |
-   * | "noteOff" | (event: NoteEvent)           |
+   * | 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, callback) {
     if (!this._listeners.has(event)) {
@@ -1788,6 +1812,7 @@ var Sequencer = class {
         this._stopLoop();
         this._clock.stop();
         this._emit("end");
+        this._emit("statechange", "stopped");
       }, delay);
     }
   }
@@ -1806,19 +1831,25 @@ var Sequencer = class {
         const durationSec = note.duration !== void 0 ? this._clock.tickDuration(
           parseTicks(note.duration, this._ppq, this._timeSignature)
         ) : void 0;
-        const timingOffset = this._humanize.timing ? (Math.random() * 2 - 1) * this._humanize.timing : 0;
+        const timingOffset = this._humanize.timing ? (Math.random() * 2 - 1) * this._humanize.timing / 1e3 : 0;
         const velocityOffset = this._humanize.velocity ? Math.round((Math.random() * 2 - 1) * this._humanize.velocity) : 0;
         const noteId = (_a = note.id) != null ? _a : noteIndex;
         const noteEvent = { noteId, trackIndex, noteIndex, note };
-        track.instrument.start({
+        const result = track.instrument.start({
           note: note.note,
-          time: audioTime + timingOffset,
+          time: Math.max(0, audioTime + timingOffset),
           duration: durationSec,
           velocity: ((_b = note.velocity) != null ? _b : 100) + velocityOffset,
           noteId,
           onStart: () => this._emit("noteOn", noteEvent),
-          onEnded: () => this._emit("noteOff", noteEvent)
+          onEnded: () => {
+            this._activeVoices.delete(noteId);
+            this._emit("noteOff", noteEvent);
+          }
         });
+        if (typeof result === "function") {
+          this._activeVoices.set(noteId, result);
+        }
       }
     }
     for (const rep of this._repeatEvents) {
@@ -1858,6 +1889,12 @@ var Sequencer = class {
       }
     }
   }
+  /** Emit both the specific state event ("start"/"pause"/"stop") and the unified "statechange" event. */
+  _emitStateChange(state) {
+    const eventName = state === "playing" ? "start" : state === "paused" ? "pause" : "stop";
+    this._emit(eventName);
+    this._emit("statechange", state);
+  }
   /** Recompute _totalTicks from all track notes (at + duration). */
   _recomputeTotalTicks() {
     let max = 0;