smplr 0.18.1 → 0.20.0

package/README.md

@@ -522,6 +522,84 @@ const seq = new Sequencer(context, {
 
 ---
 
+## Export Audio
+
+Render audio offline (faster than real-time) and export it as a WAV file. Uses `OfflineAudioContext` under the hood.
+
+```js
+import { renderOffline } from "smplr";
+
+const result = await renderOffline(async (context) => {
+  const piano = await new SplendidGrandPiano(context).load;
+  piano.start({ note: "C4", time: 0, duration: 1 });
+  piano.start({ note: "E4", time: 0.5, duration: 1 });
+});
+
+result.downloadWav("export.wav");
+```
+
+#### Options
+
+```js
+const result = await renderOffline(callback, {
+  duration: 10, // Total duration in seconds (auto-detected if omitted)
+  sampleRate: 48000, // Sample rate (default: 48000)
+  channels: 2, // Number of channels (default: 2)
+});
+```
+
+When `duration` is omitted, a 60-second buffer is used and trailing silence is automatically trimmed. Pass an explicit `duration` for longer renders or to preserve trailing silence.
+
+#### RenderResult
+
+`renderOffline` returns a `RenderResult` object:
+
+- `result.audioBuffer` — the raw `AudioBuffer`
+- `result.toWav()` — encode as 32-bit float WAV `Blob` (lossless)
+- `result.toWav16()` — encode as 16-bit integer WAV `Blob` (smaller file)
+- `result.downloadWav(filename?)` — download as 32-bit WAV
+- `result.downloadWav16(filename?)` — download as 16-bit WAV
+- `result.duration` — actual duration in seconds
+- `result.sampleRate` — sample rate used
+
+WAV encoding is lazy — it only happens when you call `toWav()` or `toWav16()`.
+
+#### Buffer reuse
+
+If you already have an instrument loaded, pass the same `SampleLoader` to avoid re-fetching samples:
+
+```js
+import { SplendidGrandPiano, SampleLoader, renderOffline } from "smplr";
+
+const loader = new SampleLoader(audioContext);
+const piano = new SplendidGrandPiano(audioContext, { loader });
+await piano.load;
+
+// Offline render reuses cached buffers — no re-fetch
+const result = await renderOffline(async (context) => {
+  const offlinePiano = await new SplendidGrandPiano(context, { loader }).load;
+  offlinePiano.start({ note: "C4", time: 0, duration: 1 });
+});
+```
+
+#### Bug reports
+
+Use offline rendering to generate reproducible audio files for issue reports. No install needed — just open your browser's DevTools console on any page and paste:
+
+```js
+const { renderOffline, SplendidGrandPiano } = await import("https://esm.sh/smplr");
+
+const result = await renderOffline(async (context) => {
+  const piano = await new SplendidGrandPiano(context).load;
+  piano.start({ note: "C4", time: 0, duration: 2 });
+});
+result.downloadWav16("bug-report.wav");
+```
+
+This will download a WAV file you can attach to your issue or pull request.
+
+---
+
 ## Instruments
 
 ### Sampler

package/dist/index.d.mts

@@ -7,6 +7,7 @@ type ChannelConfig = {
     destination: AudioNode;
     volume: number;
     volumeToGain: (volume: number) => number;
+    pan?: number;
 };
 type OutputChannel = Omit<Channel, "input">;
 /**
@@ -19,6 +20,8 @@ declare class Channel {
     readonly setVolume: (vol: number) => void;
     readonly input: AudioNode;
     constructor(context: BaseAudioContext, options?: Partial<ChannelConfig>);
+    get pan(): number;
+    set pan(value: number);
     addInsert(effect: AudioNode | AudioInsert): void;
     addEffect(name: string, effect: AudioNode | {
         input: AudioNode;
@@ -58,6 +61,7 @@ type PlaybackParams = {
     loop?: boolean;
     loopStart?: number;
     loopEnd?: number;
+    reverse?: boolean;
 };
 /**
  * An individual sample region. Maps a sample to a range of notes and velocities.
@@ -122,7 +126,7 @@ type SmplrJson = {
 /**
  * A note event passed to Smplr.start(). Can be a full object, a note name, or a MIDI number.
  */
-type NoteEvent$1 = {
+type NoteEvent = {
     note: string | number;
     velocity?: number;
     time?: number;
@@ -132,8 +136,9 @@ type NoteEvent$1 = {
     loop?: boolean;
     ampRelease?: number;
     stopId?: string | number;
-    onStart?: (event: NoteEvent$1) => void;
-    onEnded?: (event: NoteEvent$1) => void;
+    onStart?: (event: NoteEvent) => void;
+    onEnded?: (event: NoteEvent) => void;
+    reverse?: boolean;
 } | string | number;
 /**
  * Target for Smplr.stop(). Can be a full object, a stopId, or a MIDI number.
@@ -153,6 +158,166 @@ type LoadProgress = {
     loaded: number;
     total: number;
 };
+/**
+ * Fully resolved playback parameters for a single Voice.
+ * Output of resolveParams() — all fields are required, no optionals except ampVelCurve/loopAuto.
+ */
+type VoiceParams = {
+    detune: number;
+    velocity: number;
+    volume: number;
+    ampRelease: number;
+    ampAttack: number;
+    lpfCutoffHz: number;
+    offset: number;
+    loop: boolean;
+    loopStart: number;
+    loopEnd: number;
+    ampVelCurve?: [number, number];
+    /** If set, loop points are computed from buffer.duration at play time. */
+    loopAuto?: {
+        startRatio: number;
+        endRatio: number;
+    };
+    reverse?: boolean;
+};
+
+/**
+ * Loads and caches AudioBuffers for all samples referenced in a SmplrJson.
+ *
+ * The cache is keyed by resolved URL, so the same audio file is never fetched
+ * or decoded twice. Multiple Smplr instances can share one SampleLoader by
+ * passing it via SmplrOptions.loader.
+ */
+declare class SampleLoader {
+    #private;
+    constructor(context: BaseAudioContext, options?: {
+        storage?: Storage;
+    });
+    /**
+     * Load all samples referenced in `json`. Returns a Map of sample name →
+     * AudioBuffer. Progress is reported via `onProgress` callback or via
+     * options object.
+     *
+     * - `buffers` in options: pre-loaded buffers — skips fetch for these names.
+     * - All samples load in parallel. Failed samples are silently omitted.
+     */
+    load(json: SmplrJson, onProgressOrOptions?: ((loaded: number, total: number) => void) | {
+        buffers?: Map<string, AudioBuffer>;
+        onProgress?: (loaded: number, total: number) => void;
+    }): Promise<Map<string, AudioBuffer>>;
+}
+
+/**
+ * Standalone scheduler. Dispatches NoteEvents immediately when they fall within the
+ * lookahead window, or queues them for future dispatch via a self-managing interval.
+ *
+ * Multiple Smplr instances can share a single Scheduler for coordinated timing.
+ */
+declare class Scheduler {
+    #private;
+    constructor(context: BaseAudioContext, options?: {
+        lookaheadMs?: number;
+        intervalMs?: number;
+    });
+    /**
+     * Schedule a callback for a NoteEvent.
+     *
+     * - If the event's time falls within the lookahead window (or has no time), the
+     *   callback is called synchronously and a no-op StopFn is returned.
+     * - Otherwise the event is queued, the interval is started if needed, and a StopFn
+     *   is returned that removes the event from the queue before it is dispatched.
+     */
+    schedule(event: NoteEvent, callback: (event: NoteEvent) => void): StopFn;
+    /**
+     * Clear all queued (not-yet-dispatched) events and stop the interval.
+     * Does not affect voices that are already playing.
+     */
+    stop(): void;
+}
+
+type SmplrOptions = {
+    /** Custom storage backend for sample fetching (e.g. CacheStorage). */
+    storage?: Storage;
+    /** Destination audio node. Defaults to context.destination. */
+    destination?: AudioNode;
+    /** Master volume (0–127 MIDI scale). Defaults to 100. */
+    volume?: number;
+    /** Custom volume-to-gain mapping function. Defaults to midiVelToGain. */
+    volumeToGain?: (volume: number) => number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). Defaults to 0. */
+    pan?: number;
+    /** Default note velocity when not specified in NoteEvent (0–127). Defaults to 100. */
+    velocity?: number;
+    /** Shared SampleLoader instance. If omitted, a private one is created. */
+    loader?: SampleLoader;
+    /** Shared Scheduler instance. If omitted, a private one is created. */
+    scheduler?: Scheduler;
+    /** Called after each buffer is loaded (or served from cache). */
+    onLoadProgress?: (progress: LoadProgress) => void;
+    /** Called when a note is dispatched to the audio engine (slightly before playback). */
+    onStart?: (event: NoteEvent) => void;
+    /** Called when each voice's audio node ends. */
+    onEnded?: (event: NoteEvent) => void;
+};
+/**
+ * The main sampler class. Loads samples described by a SmplrJson descriptor,
+ * matches notes to regions, and plays them through a Channel.
+ *
+ * Multiple Smplr instances can share a SampleLoader (shared cache) and/or a
+ * Scheduler (coordinated timing) by passing them via SmplrOptions.
+ *
+ * Pattern A — json provided at construction:
+ *   `new Smplr(context, json, options?)`
+ *
+ * Pattern B — json loaded later via loadInstrument():
+ *   `new Smplr(context, options?)`  then  `smplr.loadInstrument(json)`
+ */
+declare class Smplr {
+    #private;
+    /** Resolves with `this` once all sample buffers are loaded. */
+    readonly load: Promise<Smplr>;
+    /** The AudioContext (or OfflineAudioContext) passed to the constructor. */
+    readonly context: BaseAudioContext;
+    constructor(context: BaseAudioContext, json: SmplrJson, options?: SmplrOptions);
+    constructor(context: BaseAudioContext, options?: SmplrOptions);
+    /**
+     * Load (or replace) the instrument descriptor. Creates a new RegionMatcher
+     * and fetches all sample buffers. Pre-loaded buffers (e.g. base64-decoded)
+     * can be passed via the `buffers` parameter — those skip the fetch step.
+     *
+     * Returns a Promise that resolves when all samples are ready.
+     */
+    loadInstrument(json: SmplrJson, buffers?: Map<string, AudioBuffer>): Promise<void>;
+    /** Current loading progress snapshot. `total` is known before loading starts. */
+    get loadProgress(): LoadProgress;
+    /** The output channel — use to add effects, adjust volume, or route audio. */
+    get output(): OutputChannel;
+    /**
+     * Set a MIDI CC value. Affects region matching for groups/regions that have
+     * ccRange constraints (e.g. CC64 sustain pedal).
+     */
+    setCC(cc: number, value: number): void;
+    /**
+     * Start playing a note. Returns a StopFn that cancels the note if it hasn't
+     * played yet, or stops the resulting voices if it has.
+     */
+    start(event: NoteEvent): StopFn;
+    /**
+     * Stop voices.
+     *
+     * - No argument → stop all active voices
+     * - String or number → stop all voices with that stopId
+     * - `{ stopId }` → stop voices with that stopId, optionally at a future time
+     * - `{ time }` (no stopId) → stop all voices at a future time
+     */
+    stop(target?: StopTarget): void;
+    /**
+     * Stop all voices, disconnect the output channel, and stop the scheduler.
+     * The instance should not be used after this call.
+     */
+    disconnect(): void;
+}
 
 /**
  * Given a list of [midi, sampleName] pairs, return one entry per sample with
@@ -188,6 +353,7 @@ type DrumMachineConfig = {
 type DrumMachineOptions = Partial<DrumMachineConfig & {
     destination?: AudioNode;
     volume?: number;
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>;
@@ -199,7 +365,7 @@ declare class DrumMachine {
     getSampleNames(): string[];
     getGroupNames(): string[];
     getSampleNamesForGroup(groupName: string): string[];
-    start(sample: NoteEvent$1): StopFn;
+    start(sample: NoteEvent): StopFn;
     stop(sample?: StopTarget): void;
     disconnect(): void;
     /** @deprecated */
@@ -218,6 +384,73 @@ declare class DrumMachine {
  */
 declare function drumMachineToSmplrJson(instrument: DrumMachineInstrument): SmplrJson;
 
+/**
+ * The result of an offline render. Provides the raw AudioBuffer and
+ * lazy WAV encoding / download convenience methods.
+ */
+declare class RenderResult {
+    #private;
+    readonly audioBuffer: AudioBuffer;
+    readonly duration: number;
+    readonly sampleRate: number;
+    constructor(audioBuffer: AudioBuffer);
+    /** Encode as 32-bit float WAV. Cached after first call. */
+    toWav(): Blob;
+    /** Encode as 16-bit integer WAV. Cached after first call. */
+    toWav16(): Blob;
+    /** Download as 32-bit float WAV file. */
+    downloadWav(filename?: string): void;
+    /** Download as 16-bit integer WAV file. */
+    downloadWav16(filename?: string): void;
+}
+
+interface RenderOfflineOptions {
+    /** Total duration in seconds. When omitted, uses 60s max and trims trailing silence. */
+    duration?: number;
+    /** Sample rate. Default: 48000. */
+    sampleRate?: number;
+    /** Number of output channels. Default: 2 (stereo). */
+    channels?: number;
+}
+/**
+ * Render audio offline using an OfflineAudioContext.
+ *
+ * The callback receives an OfflineAudioContext. Create instruments,
+ * schedule notes using absolute times (starting from 0), then return.
+ * The audio is rendered as fast as possible (not real-time).
+ *
+ * Returns a RenderResult with the rendered AudioBuffer and
+ * convenience methods for WAV encoding and download.
+ *
+ * @example
+ * ```ts
+ * const result = await renderOffline(async (context) => {
+ *   const piano = await new SplendidGrandPiano(context).load;
+ *   piano.start({ note: "C4", time: 0, duration: 1 });
+ * });
+ * result.downloadWav("export.wav");
+ * ```
+ */
+declare function renderOffline(callback: (context: OfflineAudioContext) => Promise<void>, options?: RenderOfflineOptions): Promise<RenderResult>;
+
+/**
+ * Encode an AudioBuffer as a WAV file Blob.
+ *
+ * Supports 32-bit float (lossless) and 16-bit integer (CD quality) formats.
+ */
+/** Encode AudioBuffer as 32-bit float WAV. */
+declare function audioBufferToWav(buffer: AudioBuffer): Blob;
+/** Encode AudioBuffer as 16-bit integer WAV. */
+declare function audioBufferToWav16(buffer: AudioBuffer): Blob;
+
+/**
+ * Trim trailing silence from an AudioBuffer.
+ *
+ * Scans all channels from the end to find the last sample above the threshold,
+ * then returns a new AudioBuffer trimmed to that length.
+ */
+declare function trimSilence(buffer: AudioBuffer): AudioBuffer;
+
 /**
  * TransportClock
  *
@@ -246,6 +479,8 @@ type SequencerNote = {
     /** Note duration: ticks, "4n", "8n", etc. Omit for a one-shot trigger. */
     duration?: string | number;
     velocity?: number;
+    /** Probability (0–100) that this note fires on each pass. Default 100 (always). */
+    chance?: number;
 };
 /**
  * Any instrument the Sequencer can drive.
@@ -264,7 +499,7 @@ type SequencerInstrument = {
     }): unknown;
 };
 /** Emitted with "noteOn" and "noteOff" events. */
-type NoteEvent = {
+type SequencerNoteEvent = {
     noteId: string | number;
     trackIndex: number;
     noteIndex: number;
@@ -286,12 +521,15 @@ type SequencerOptions = {
         timingMs?: number;
         velocity?: number;
     };
+    /** Emit a "step" event at this interval. Accepts musical notation or ticks: "16n", "8n", ticks, etc. */
+    stepSize?: string | number;
 };
 declare class Sequencer {
     private readonly _context;
     private readonly _clock;
     private readonly _ppq;
     private _timeSignature;
+    private _stepTicks;
     private _tracks;
     private _repeatEvents;
     private _listeners;
@@ -377,8 +615,9 @@ declare class Sequencer {
      * | "loop"         |                                                   |
      * | "beat"         | (beat: number, time: number)                      |
      * | "bar"          | (bar: number, time: number)                       |
-     * | "noteOn"       | (event: NoteEvent)                                |
-     * | "noteOff"      | (event: NoteEvent)                                |
+     * | "step"         | (stepIndex: number, time: number)                 |
+     * | "noteOn"       | (event: SequencerNoteEvent)                       |
+     * | "noteOff"      | (event: SequencerNoteEvent)                       |
      */
     on(event: string, callback: (...args: any[]) => void): this;
     off(event: string, callback: (...args: any[]) => void): this;
@@ -386,6 +625,7 @@ declare class Sequencer {
     private _stopLoop;
     private _flush;
     private _scheduleWindow;
+    private _emitStepsInWindow;
     private _emitBeatsInWindow;
     private _emit;
     /** Emit both the specific state event ("start"/"pause"/"stop") and the unified "statechange" event. */
@@ -424,7 +664,7 @@ declare class ElectricPiano {
     });
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -453,7 +693,7 @@ declare class Versilian {
     constructor(context: BaseAudioContext, options?: VersilianOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -484,7 +724,7 @@ declare class Mellotron {
     constructor(context: BaseAudioContext, options?: MellotronOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -542,7 +782,7 @@ declare class Sampler {
     constructor(context: AudioContext, options?: Partial<SamplerConfig>);
     loaded(): Promise<this>;
     get output(): OutputChannel;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
     disconnect(): void;
 }
@@ -582,7 +822,7 @@ declare class Smolken {
     constructor(context: BaseAudioContext, options?: SmolkenOptions);
     get output(): OutputChannel;
     get loadProgress(): LoadProgress;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -616,7 +856,7 @@ declare class Soundfont {
     get output(): OutputChannel;
     loaded(): Promise<this>;
     disconnect(): void;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
 }
 /**
@@ -675,7 +915,7 @@ declare class Soundfont2Sampler {
     get instrumentNames(): string[];
     get output(): OutputChannel;
     loadInstrument(instrumentName: string): Promise<void> | undefined;
-    start(sample: NoteEvent$1 | string | number): StopFn;
+    start(sample: NoteEvent | string | number): StopFn;
     stop(sample?: StopTarget | string | number): void;
     disconnect(): void;
 }
@@ -715,7 +955,7 @@ declare class SplendidGrandPiano {
     get loadProgress(): LoadProgress;
     /** @deprecated Use `load` instead. */
     loaded(): Promise<this>;
-    start(event: NoteEvent$1): StopFn;
+    start(event: NoteEvent): StopFn;
     stop(target?: StopTarget): void;
     disconnect(): void;
 }
@@ -744,4 +984,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, 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 };
+export { CacheStorage, DrumMachine, type DrumMachineOptions, ElectricPiano, type ElectricPianoOptions, HttpStorage, LAYERS, type LoadProgress, Mallet, Mellotron, type MellotronConfig, type MellotronOptions, NAME_TO_PATH, type NoteEvent, type PlaybackParams, type RenderOfflineOptions, RenderResult, Reverb, SampleLoader, Sampler, type SamplerConfig, Scheduler, Sequencer, type SequencerInstrument, type SequencerNote, type SequencerNoteEvent, type SequencerOptions, Smolken, type SmolkenConfig, type SmolkenOptions, Smplr, type SmplrGroup, type SmplrJson, type SmplrOptions, type SmplrRegion, type SmplrSamples, Soundfont, type Soundfont2Options, Soundfont2Sampler, type SoundfontOptions, SplendidGrandPiano, type SplendidGrandPianoConfig, type SpreadResult, type StopFn, type StopTarget, type Storage, type StorageResponse, Versilian, type VersilianConfig, type VersilianOptions, type VoiceParams, audioBufferToWav, audioBufferToWav16, drumMachineToSmplrJson, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, mellotronToSmplrJson, pianoToSmplrJson, renderOffline, samplerToSmplrJson, sf2InstrumentToSmplrJson, soundfontToSmplrJson, spreadKeyRanges, trimSilence };