smplr 0.18.1 → 0.19.0

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 passed to the constructor. */
+    readonly context: AudioContext;
+    constructor(context: AudioContext, json: SmplrJson, options?: SmplrOptions);
+    constructor(context: AudioContext, 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 */
@@ -246,6 +412,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 +432,7 @@ type SequencerInstrument = {
     }): unknown;
 };
 /** Emitted with "noteOn" and "noteOff" events. */
-type NoteEvent = {
+type SequencerNoteEvent = {
     noteId: string | number;
     trackIndex: number;
     noteIndex: number;
@@ -286,12 +454,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 +548,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 +558,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 +597,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 +626,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 +657,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 +715,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 +755,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 +789,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 +848,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 +888,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 +917,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, 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, drumMachineToSmplrJson, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, mellotronToSmplrJson, pianoToSmplrJson, samplerToSmplrJson, sf2InstrumentToSmplrJson, soundfontToSmplrJson, spreadKeyRanges };