smplr 0.23.0 → 0.24.0

package/dist/index.d.mts

@@ -35,6 +35,23 @@ declare class Channel {
     disconnect(): void;
 }
 
+/**
+ * Wrap a class so it is callable both as `X(...)` (preferred) and as
+ * `new X(...)` (kept for compatibility with pre-1.0 examples). Returns
+ * a value with both call and construct signatures.
+ *
+ * Used by the auxiliary exports (`Sequencer`, `Reverb`, `CacheStorage`,
+ * `Scheduler`, `SampleLoader`) to match the dual signature already shipped
+ * by `InstrumentFactory`. Instrument factories themselves use the richer
+ * `Instrument()` builder instead, which owns option-splitting and the
+ * ready-promise lifecycle.
+ */
+type Constructable<A extends unknown[], R> = {
+    (...args: A): R;
+    /** @deprecated Call as a function: `X(...)` instead of `new X(...)`. */
+    new (...args: A): R;
+};
+
 type StorageResponse = {
     readonly status: number;
     arrayBuffer(): Promise<ArrayBuffer>;
@@ -45,11 +62,13 @@ type Storage = {
     fetch: (url: string) => Promise<StorageResponse>;
 };
 declare const HttpStorage: Storage;
-declare class CacheStorage implements Storage {
+declare class CacheStorageImpl implements Storage {
     #private;
     constructor(name?: string);
     fetch(url: string): Promise<StorageResponse>;
 }
+declare const CacheStorage: Constructable<[name?: string | undefined], CacheStorageImpl>;
+type CacheStorage = ReturnType<typeof CacheStorage>;
 
 /**
  * Inheritable playback parameters. Can appear at global defaults, group, or region level.
@@ -196,7 +215,7 @@ type VoiceParams = {
  * or decoded twice. Multiple Smplr instances can share one SampleLoader by
  * passing it via SmplrOptions.loader.
  */
-declare class SampleLoader {
+declare class SampleLoaderImpl {
     #private;
     constructor(context: BaseAudioContext, options?: {
         storage?: Storage;
@@ -214,6 +233,10 @@ declare class SampleLoader {
         onProgress?: (loaded: number, total: number) => void;
     }): Promise<Map<string, AudioBuffer>>;
 }
+declare const SampleLoader: Constructable<[context: BaseAudioContext, options?: {
+    storage?: Storage;
+} | undefined], SampleLoaderImpl>;
+type SampleLoader = ReturnType<typeof SampleLoader>;
 
 /**
  * Standalone scheduler. Dispatches NoteEvents immediately when they fall within the
@@ -221,7 +244,7 @@ declare class SampleLoader {
  *
  * Multiple Smplr instances can share a single Scheduler for coordinated timing.
  */
-declare class Scheduler {
+declare class SchedulerImpl {
     #private;
     constructor(context: BaseAudioContext, options?: {
         lookaheadMs?: number;
@@ -242,6 +265,11 @@ declare class Scheduler {
      */
     stop(): void;
 }
+declare const Scheduler: Constructable<[context: BaseAudioContext, options?: {
+    lookaheadMs?: number;
+    intervalMs?: number;
+} | undefined], SchedulerImpl>;
+type Scheduler = ReturnType<typeof Scheduler>;
 
 type SmplrOptions = {
     /** Custom storage backend for sample fetching (e.g. CacheStorage). */
@@ -299,6 +327,19 @@ interface Smplr {
      * not been set (matches MIDI's "undefined controller defaults to 0" convention).
      */
     getCC(cc: number): number;
+    /**
+     * Set the cents detune applied to every future note. Mutates the instrument's
+     * playback defaults in place; takes effect on notes scheduled after the call.
+     * In-flight notes are unaffected.
+     */
+    setDetune(cents: number): void;
+    /**
+     * Set whether every future note plays its sample reversed. Mutates the
+     * instrument's playback defaults in place. The reversed-buffer cache is
+     * populated lazily on demand; no cache invalidation is needed in either
+     * direction.
+     */
+    setReverse(reverse: boolean): void;
     /**
      * Stop all voices, dispose the output channel, and stop the scheduler.
      * The instance must not be used after this call — subsequent `start`/`stop`/
@@ -534,6 +575,19 @@ type SequencerNote = {
     velocity?: number;
     /** Probability (0–100) that this note fires on each pass. Default 100 (always). */
     chance?: number;
+    /**
+     * Expand into N evenly-spaced sub-notes over `duration`. Requires `duration`;
+     * silently ignored if `duration` is omitted. Default 1 (no ratchet). When >1,
+     * each sub-note's `noteId` is suffixed with `#0`, `#1`, … so individual
+     * ratchet voices can be stopped via `stopNote("id#0")`.
+     */
+    ratchet?: number;
+    /**
+     * Multiplicative velocity decay per ratchet step: each step's velocity is
+     * scaled by `(1 - decay) ** step_index`. 0 = constant, 1 = silence by last
+     * step. Default 0.
+     */
+    ratchetVelocityDecay?: number;
 };
 /**
  * Any instrument the Sequencer can drive.
@@ -558,10 +612,20 @@ type SequencerNoteEvent = {
     noteIndex: number;
     note: SequencerNote;
 };
+/**
+ * Time signature as a `{ numerator, denominator }` pair (e.g. `{ numerator: 7, denominator: 8 }`
+ * for 7/8). The numerator counts beats per bar; the denominator defines the
+ * note value of one beat (4 = quarter note, 8 = eighth note, …).
+ */
+type TimeSignature = {
+    numerator: number;
+    denominator: number;
+};
 type SequencerOptions = {
     bpm?: number;
     ppq?: number;
-    timeSignature?: number;
+    /** Time signature. Accepts `4` (interpreted as 4/4) or `{ numerator, denominator }`. */
+    timeSignature?: number | TimeSignature;
     loop?: boolean;
     loopStart?: string | number;
     loopEnd?: string | number;
@@ -577,35 +641,128 @@ type SequencerOptions = {
     /** Emit a "step" event at this interval. Accepts musical notation or ticks: "16n", "8n", ticks, etc. */
     stepSize?: string | number;
 };
-declare class Sequencer {
+/**
+ * Per-track options accepted by {@link Sequencer.addTrack} and
+ * {@link Sequencer.setPatterns}.
+ */
+type AddTrackOptions = {
+    /**
+     * Stable track id. Required to address this track via
+     * {@link Sequencer.setTrackVolume}, {@link Sequencer.muteTrack},
+     * {@link Sequencer.soloTrack}, etc.
+     */
+    id?: string;
+    /** Per-track humanize. Overrides {@link SequencerOptions.humanize} when set. */
+    humanize?: {
+        timingMs?: number;
+        velocity?: number;
+    };
+    /** Multiplicative velocity scalar in [0, 1+]. Default 1. */
+    volume?: number;
+    /** When true, this track does not dispatch any notes. Default false. */
+    muted?: boolean;
+    /**
+     * When true, only soloed tracks dispatch notes. If any track in the pattern
+     * is soloed, every non-soloed track is silenced. Default false.
+     */
+    solo?: boolean;
+};
+/**
+ * Public shape for one pattern accepted by {@link Sequencer.setPatterns}.
+ */
+type PatternInput = {
+    tracks: Array<{
+        instrument: SequencerInstrument;
+        notes: SequencerNote[];
+    } & AddTrackOptions>;
+    /**
+     * Pattern length override in ticks or musical time. Defaults to the longest
+     * track in this pattern.
+     */
+    loopEnd?: string | number;
+};
+declare class SequencerImpl {
     private readonly _context;
     private readonly _clock;
     private readonly _ppq;
     private _timeSignature;
     private _stepTicks;
-    private _tracks;
+    /**
+     * Patterns. Always at least one (the implicit default pattern). Replaced
+     * atomically by {@link setPatterns}.
+     */
+    private _patterns;
+    /** Indices into {@link _patterns} defining playback order. */
+    private _chainOrder;
+    /** Current position within {@link _chainOrder}. */
+    private _chainIndex;
+    /**
+     * True once {@link setPatterns} has been called. After this point,
+     * `addTrack` / `removeTrack` / `clearTracks` throw because the chain shape
+     * is owned by the patterns array.
+     */
+    private _patternsExplicit;
     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;
+    /**
+     * Add a track to the (implicit, default) pattern. Throws after
+     * {@link setPatterns} has been called — use {@link setPatterns} to mutate
+     * the chain.
+     */
+    addTrack(instrument: SequencerInstrument, notes: SequencerNote[], options?: AddTrackOptions): this;
     removeTrack(instrument: SequencerInstrument): this;
     clearTracks(): this;
+    /**
+     * Replace the sequencer's patterns. Each pattern owns its own tracks and
+     * optional `loopEnd`. After this call, `addTrack` / `removeTrack` /
+     * `clearTracks` throw — the chain is owned by the patterns array.
+     *
+     * `chainOrder` is reset to `[0, 1, …, patterns.length - 1]`.
+     */
+    setPatterns(patterns: PatternInput[]): this;
+    /** Current chain order: indices into the patterns array, in playback order. */
+    get chainOrder(): number[];
+    /**
+     * Set a new chain order. Each entry must be a valid pattern index.
+     * Throws if `order` is empty or contains an out-of-range index.
+     */
+    set chainOrder(order: number[]);
+    /**
+     * Set a track's multiplicative volume scalar. Affects every note dispatched
+     * by the track from the next flush onwards. No-op if no track has the
+     * given id. Search is scoped to the currently-playing pattern.
+     */
+    setTrackVolume(id: string, volume: number): this;
+    /** Mute a track by id. No-op if no track has the given id. */
+    muteTrack(id: string): this;
+    /** Unmute a track by id. No-op if no track has the given id. */
+    unmuteTrack(id: string): this;
+    /** Solo a track by id. While any track is soloed, non-soloed tracks are silenced. */
+    soloTrack(id: string): this;
+    /** Remove the solo flag from a track. */
+    unsoloTrack(id: string): this;
+    /**
+     * Locate a track by id, scoped to the currently-playing pattern.
+     */
+    private _findTrack;
+    private _setTrackFlag;
+    private _buildTrack;
+    private _currentPattern;
+    private _assertImplicitPattern;
+    private _computePatternTotalTicks;
     get state(): TransportState;
     /**
      * Start playback from `offsetTick`, or resume from pause if no offset given.
@@ -625,8 +782,8 @@ declare class Sequencer {
     togglePlayPause(): this;
     get bpm(): number;
     set bpm(value: number);
-    get timeSignature(): number;
-    set timeSignature(value: number);
+    get timeSignature(): TimeSignature;
+    set timeSignature(value: number | TimeSignature);
     /** Current transport position as "bar:beat:tick" (1-indexed). */
     get position(): string;
     /**
@@ -639,7 +796,10 @@ declare class Sequencer {
     /** Loop start in ticks. */
     get loopStart(): number;
     set loopStart(value: string | number);
-    /** Loop end in ticks. Defaults to the end of the longest track. */
+    /**
+     * Loop end in ticks for the currently-playing pattern. Defaults to the end
+     * of the pattern's longest track.
+     */
     get loopEnd(): number;
     set loopEnd(value: string | number);
     /**
@@ -658,19 +818,20 @@ declare class Sequencer {
     /**
      * 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)                       |
-     * | "step"         | (stepIndex: number, time: number)                 |
-     * | "noteOn"       | (event: SequencerNoteEvent)                       |
-     * | "noteOff"      | (event: SequencerNoteEvent)                       |
+     * | Event           | Args                                              |
+     * |-----------------|---------------------------------------------------|
+     * | "statechange"   | (state: "playing" \| "paused" \| "stopped")       |
+     * | "start"         |                                                   |
+     * | "stop"          |                                                   |
+     * | "pause"         |                                                   |
+     * | "end"           |                                                   |
+     * | "loop"          |                                                   |
+     * | "patternChange" | (patternIndex: number, time: number)              |
+     * | "beat"          | (beat: number, time: number)                      |
+     * | "bar"           | (bar: number, time: number)                       |
+     * | "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;
@@ -683,8 +844,6 @@ declare class Sequencer {
     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;
     /**
@@ -693,6 +852,8 @@ declare class Sequencer {
      */
     private _resetRepeatEvents;
 }
+declare const Sequencer: Constructable<[context: BaseAudioContext, options?: SequencerOptions | undefined], SequencerImpl>;
+type Sequencer = ReturnType<typeof Sequencer>;
 
 declare function getElectricPianoNames(): string[];
 type ElectricPianoOptions = Partial<{
@@ -700,6 +861,8 @@ type ElectricPianoOptions = Partial<{
     storage: Storage;
     destination: AudioNode;
     volume: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan: number;
     velocity: number;
     onLoadProgress: (progress: LoadProgress) => void;
     /** Audio formats to try, in order of preference. Defaults to ["ogg", "m4a"]. */
@@ -710,6 +873,8 @@ declare const ElectricPiano: InstrumentFactory<Partial<{
     storage: Storage;
     destination: AudioNode;
     volume: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan: number;
     velocity: number;
     onLoadProgress: (progress: LoadProgress) => void;
     /** Audio formats to try, in order of preference. Defaults to ["ogg", "m4a"]. */
@@ -732,6 +897,8 @@ type VersilianConfig = {
 type VersilianOptions = Partial<VersilianConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>;
@@ -744,6 +911,8 @@ type VersilianOptions = Partial<VersilianConfig & {
 declare const Versilian: InstrumentFactory<Partial<VersilianConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>, {}>;
@@ -760,6 +929,7 @@ declare function getMalletNames(): string[];
 declare const Mallet: InstrumentFactory<Partial<VersilianConfig & {
     destination?: AudioNode;
     volume?: number;
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>, {}>;
@@ -775,6 +945,8 @@ type MellotronConfig = {
 type MellotronOptions = Partial<MellotronConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     decayTime?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
@@ -782,6 +954,8 @@ type MellotronOptions = Partial<MellotronConfig & {
 declare const Mellotron: InstrumentFactory<Partial<MellotronConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     decayTime?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
@@ -803,7 +977,7 @@ type MellotronJsonConfig = {
 declare function mellotronToPreset(sampleNames: string[], config: MellotronJsonConfig): SmplrPreset;
 
 declare const PARAMS: readonly ["preDelay", "bandwidth", "inputDiffusion1", "inputDiffusion2", "decay", "decayDiffusion1", "decayDiffusion2", "damping", "excursionRate", "excursionDepth", "wet", "dry"];
-declare class Reverb {
+declare class ReverbImpl {
     #private;
     readonly input: AudioNode;
     constructor(context: AudioContext);
@@ -813,6 +987,8 @@ declare class Reverb {
     ready(): Promise<this>;
     connect(output: AudioNode): void;
 }
+declare const Reverb: Constructable<[context: AudioContext], ReverbImpl>;
+type Reverb = ReturnType<typeof Reverb>;
 
 type AudioBuffers = Record<string | number, AudioBuffer | undefined>;
 /**
@@ -824,6 +1000,7 @@ type SamplerBase = {
     storage?: Storage;
     detune?: number;
     volume?: number;
+    pan?: number;
     velocity?: number;
     decayTime?: number;
     lpfCutoffHz?: number;
@@ -885,12 +1062,16 @@ type SmolkenConfig = {
 type SmolkenOptions = Partial<SmolkenConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>;
 declare const Smolken: InstrumentFactory<Partial<SmolkenConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>, {}>;
@@ -913,12 +1094,16 @@ type SoundfontConfig = {
 type SoundfontOptions = Partial<SoundfontConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>;
 declare const Soundfont: InstrumentFactory<Partial<SoundfontConfig & {
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
     onLoadProgress?: (progress: LoadProgress) => void;
 }>, {}>;
@@ -964,6 +1149,8 @@ type Soundfont2Options = {
     createSoundfont: (data: Uint8Array) => Sf2;
     destination?: AudioNode;
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     velocity?: number;
 };
 declare function sf2InstrumentToPreset(sf2Instrument: Sf2Instrument, context: BaseAudioContext): {
@@ -974,9 +1161,13 @@ type Soundfont2SamplerExtras = {
     readonly instrumentNames: string[];
     loadInstrument(instrumentName: string): Promise<void> | undefined;
 };
+declare const Soundfont2: InstrumentFactory<Soundfont2Options, Soundfont2SamplerExtras>;
+/** Instance type returned by the {@link Soundfont2} factory. */
+type Soundfont2 = ReturnType<typeof Soundfont2>;
+/** @deprecated Use `Soundfont2` instead. */
 declare const Soundfont2Sampler: InstrumentFactory<Soundfont2Options, Soundfont2SamplerExtras>;
-/** Instance type returned by the {@link Soundfont2Sampler} factory. */
-type Soundfont2Sampler = ReturnType<typeof Soundfont2Sampler>;
+/** @deprecated Use `Soundfont2` instead. */
+type Soundfont2Sampler = Soundfont2;
 
 /**
  * Configuration options for SplendidGrandPiano.
@@ -994,6 +1185,8 @@ type SplendidGrandPianoConfig = {
     destination?: AudioNode;
     /** Master volume (0–127 MIDI scale). */
     volume?: number;
+    /** Stereo pan position (-1 = full left, 0 = centre, +1 = full right). */
+    pan?: number;
     /** Called after each buffer is loaded or served from cache. */
     onLoadProgress?: (progress: LoadProgress) => void;
     /** Audio formats to try, in order of preference. Defaults to ["ogg", "m4a"]. */
@@ -1031,4 +1224,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { CacheStorage, DrumMachine, type DrumMachineOptions, ElectricPiano, type ElectricPianoOptions, HttpStorage, Instrument, LAYERS, type LoadProgress, Mallet, Mellotron, type MellotronConfig, type MellotronOptions, NAME_TO_PATH, type NoteEvent, type PlaybackParams, type RenderOfflineOptions, RenderResult, Reverb, SampleLoader, Sampler, type SamplerConfig, type SamplerReloadInput, Scheduler, Sequencer, type SequencerInstrument, type SequencerNote, type SequencerNoteEvent, type SequencerOptions, Smolken, type SmolkenConfig, type SmolkenOptions, type Smplr, type SmplrGroup, type SmplrOptions, type SmplrPlugin, type SmplrPreset, type SmplrRegion, type SmplrSamples, Soundfont, type Soundfont2Options, Soundfont2Sampler, type SoundfontOptions, SplendidGrandPiano, type SplendidGrandPianoConfig, type StopFn, type StopTarget, type Storage, type StorageResponse, Versilian, type VersilianConfig, type VersilianOptions, type VoiceParams, audioBufferToWav, audioBufferToWav16, drumMachineToPreset, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };
+export { type AddTrackOptions, CacheStorage, DrumMachine, type DrumMachineOptions, ElectricPiano, type ElectricPianoOptions, HttpStorage, Instrument, LAYERS, type LoadProgress, Mallet, Mellotron, type MellotronConfig, type MellotronOptions, NAME_TO_PATH, type NoteEvent, type PatternInput, type PlaybackParams, type RenderOfflineOptions, RenderResult, Reverb, SampleLoader, Sampler, type SamplerConfig, type SamplerReloadInput, Scheduler, Sequencer, type SequencerInstrument, type SequencerNote, type SequencerNoteEvent, type SequencerOptions, Smolken, type SmolkenConfig, type SmolkenOptions, type Smplr, type SmplrGroup, type SmplrOptions, type SmplrPlugin, type SmplrPreset, type SmplrRegion, type SmplrSamples, Soundfont, Soundfont2, type Soundfont2Options, Soundfont2Sampler, type SoundfontOptions, SplendidGrandPiano, type SplendidGrandPianoConfig, type StopFn, type StopTarget, type Storage, type StorageResponse, type TimeSignature, Versilian, type VersilianConfig, type VersilianOptions, type VoiceParams, audioBufferToWav, audioBufferToWav16, drumMachineToPreset, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };