smplr 0.22.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.
@@ -114,7 +133,7 @@ type SmplrSamples = {
 /**
  * The top-level smplr.json descriptor. Passed to the Smplr constructor.
  */
-type SmplrJson = {
+type SmplrPreset = {
     /** Schema version. Omit for the current format. Reserved for future migrations. */
     smplr?: "1.0";
     meta?: {
@@ -190,13 +209,13 @@ type VoiceParams = {
 };
 
 /**
- * Loads and caches AudioBuffers for all samples referenced in a SmplrJson.
+ * Loads and caches AudioBuffers for all samples referenced in a SmplrPreset.
  *
  * 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 {
+declare class SampleLoaderImpl {
     #private;
     constructor(context: BaseAudioContext, options?: {
         storage?: Storage;
@@ -209,11 +228,15 @@ declare class SampleLoader {
      * - `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) | {
+    load(json: SmplrPreset, onProgressOrOptions?: ((loaded: number, total: number) => void) | {
         buffers?: Map<string, AudioBuffer>;
         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`/
@@ -324,7 +365,7 @@ interface PluginSmplr extends Smplr {
      *
      * Resolves when all samples are ready.
      */
-    loadInstrument(json: SmplrJson, buffers?: Map<string, AudioBuffer>): Promise<void>;
+    loadInstrument(json: SmplrPreset, buffers?: Map<string, AudioBuffer>): Promise<void>;
 }
 /**
  * Permitted return shapes for an {@link SmplrPlugin}:
@@ -429,13 +470,13 @@ declare const DrumMachine: InstrumentFactory<Partial<DrumMachineConfig & {
 /** Instance type returned by the {@link DrumMachine} factory. */
 type DrumMachine = ReturnType<typeof DrumMachine>;
 /**
- * Convert a DrumMachineInstrument to a SmplrJson descriptor.
+ * Convert a DrumMachineInstrument to a SmplrPreset descriptor.
  *
  * Each sample gets a sequential MIDI number starting at 36 (GM drum map base).
  * Aliases are created for both the full sample name ("kick/1") and the group
  * name ("kick") so both forms work with Smplr.start({ note: "kick" }).
  */
-declare function drumMachineToSmplrJson(instrument: DrumMachineInstrument): SmplrJson;
+declare function drumMachineToPreset(instrument: DrumMachineInstrument): SmplrPreset;
 
 /**
  * The result of an offline render. Provides the raw AudioBuffer and
@@ -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;
@@ -793,17 +967,17 @@ type MellotronJsonConfig = {
     variation?: string;
 };
 /**
- * Convert a Mellotron files.json sample list to SmplrJson.
+ * Convert a Mellotron files.json sample list to SmplrPreset.
  *
  * - Filters by variation string if provided.
  * - Extracts MIDI from the first word of each sample name.
  * - Uses spreadKeyRanges so nearby notes pitch-shift to the nearest sample.
  * - All regions get loopAuto to produce tape-loop playback.
  */
-declare function mellotronToSmplrJson(sampleNames: string[], config: MellotronJsonConfig): SmplrJson;
+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>;
 /**
@@ -820,26 +996,41 @@ type AudioBuffers = Record<string | number, AudioBuffer | undefined>;
  */
 type AudioBuffersLoader = (context: BaseAudioContext, buffers: AudioBuffers) => Promise<void>;
 
-type SamplerConfig = {
+type SamplerBase = {
     storage?: Storage;
-    detune: number;
-    volume: number;
-    velocity: number;
+    detune?: number;
+    volume?: number;
+    pan?: number;
+    velocity?: number;
     decayTime?: number;
     lpfCutoffHz?: number;
-    destination: AudioNode;
-    buffers: Record<string | number, string | AudioBuffer | AudioBuffers> | AudioBuffersLoader;
-    volumeToGain: (volume: number) => number;
+    destination?: AudioNode;
+    volumeToGain?: (volume: number) => number;
     onLoadProgress?: (progress: LoadProgress) => void;
 };
+type SamplerBuffers = Record<string | number, string | AudioBuffer | AudioBuffers> | AudioBuffersLoader;
+type SamplerBuffersInput = {
+    buffers?: SamplerBuffers;
+    preset?: never;
+};
+type SamplerPresetInput = {
+    preset: SmplrPreset;
+    buffers?: never;
+};
+type SamplerConfig = SamplerBase & (SamplerBuffersInput | SamplerPresetInput);
+/** Input accepted by {@link Sampler.reload}: a `SmplrPreset` schema or a flat buffers record/loader. */
+type SamplerReloadInput = SmplrPreset | SamplerBuffers;
+type SamplerExtras = {
+    reload: (input: SamplerReloadInput) => Promise<void>;
+};
 type SamplerJsonOptions = Pick<SamplerConfig, "decayTime" | "lpfCutoffHz" | "detune">;
 type InternalConvertResult = {
-    json: SmplrJson;
+    json: SmplrPreset;
     urlMap: Record<string, string>;
     preloaded: Map<string, AudioBuffer>;
 };
 /**
- * Convert a flat source Record to SmplrJson + separated URL map + pre-loaded buffers.
+ * Convert a flat source Record to SmplrPreset + separated URL map + pre-loaded buffers.
  *
  * - Keys that are valid MIDI names/numbers → MIDI-mapped regions.
  *   If ALL keys are MIDI-parseable, spread key ranges (pitch-shifting).
@@ -848,11 +1039,18 @@ type InternalConvertResult = {
  * - AudioBuffer values → pre-loaded map (no fetch).
  * - String URL values → urlMap (fetched asynchronously by caller).
  */
-declare function samplerToSmplrJson(source: Record<string | number, string | AudioBuffer>, options?: Partial<SamplerJsonOptions>): InternalConvertResult;
+declare function samplerToPreset(source: Record<string | number, string | AudioBuffer>, options?: Partial<SamplerJsonOptions>): InternalConvertResult;
 /**
- * A Sampler instrument.
+ * A Sampler instrument. Accepts either a flat record of samples
+ * (`{ buffers: { C4: "url" } }`) or a full `SmplrPreset`
+ * (`{ preset: { samples, groups, ... } }`) for advanced use cases including
+ * per-region pitch/velocity/round-robin control.
+ *
+ * Use `sampler.reload(input)` to swap content at runtime. `reload` accepts
+ * either shape (flat record or `SmplrPreset`), regardless of which mode was
+ * used at construction.
  */
-declare const Sampler: InstrumentFactory<Partial<SamplerConfig>, {}>;
+declare const Sampler: InstrumentFactory<SamplerConfig, SamplerExtras>;
 /** Instance type returned by the {@link Sampler} factory. */
 type Sampler = ReturnType<typeof Sampler>;
 
@@ -864,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;
 }>, {}>;
@@ -892,22 +1094,26 @@ 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;
 }>, {}>;
 /** Instance type returned by the {@link Soundfont} factory. */
 type Soundfont = ReturnType<typeof Soundfont>;
 /**
- * Convert a list of note names (with optional loop data) to SmplrJson.
+ * Convert a list of note names (with optional loop data) to SmplrPreset.
  * Uses spreadKeyRanges so notes between recorded pitches pitch-shift correctly.
  */
-declare function soundfontToSmplrJson(noteNames: string[], loopData?: LoopData): SmplrJson;
+declare function soundfontToPreset(noteNames: string[], loopData?: LoopData): SmplrPreset;
 
 type Sf2 = {
     instruments: Sf2Instrument[];
@@ -943,19 +1149,25 @@ 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 sf2InstrumentToSmplrJson(sf2Instrument: Sf2Instrument, context: BaseAudioContext): {
-    json: SmplrJson;
+declare function sf2InstrumentToPreset(sf2Instrument: Sf2Instrument, context: BaseAudioContext): {
+    json: SmplrPreset;
     buffers: Map<string, AudioBuffer>;
 };
 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.
@@ -967,12 +1179,14 @@ type SplendidGrandPianoConfig = {
     detune: number;
     /** Default velocity (0–127) when not specified per note. */
     velocity: number;
-    /** Release time in seconds. Maps to SmplrJson defaults.ampRelease. */
+    /** Release time in seconds. Maps to SmplrPreset defaults.ampRelease. */
     decayTime: number;
     /** Destination audio node. Defaults to context.destination. */
     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"]. */
@@ -988,7 +1202,7 @@ declare const SplendidGrandPiano: InstrumentFactory<Partial<SplendidGrandPianoCo
 type SplendidGrandPiano = ReturnType<typeof SplendidGrandPiano>;
 type PianoJsonOptions = Pick<SplendidGrandPianoConfig, "baseUrl" | "detune" | "decayTime" | "notesToLoad" | "formats">;
 /**
- * Convert the LAYERS array and user options into a SmplrJson descriptor.
+ * Convert the LAYERS array and user options into a SmplrPreset descriptor.
  *
  * Each layer becomes a SmplrGroup with its velRange. If `notesToLoad` is
  * specified, layers and samples are filtered accordingly. The PPP layer
@@ -997,7 +1211,7 @@ type PianoJsonOptions = Pick<SplendidGrandPianoConfig, "baseUrl" | "detune" | "d
  * `spreadKeyRanges` is used to pre-compute which key range each sample
  * covers, replacing the old on-the-fly `findNearestMidiInLayer` logic.
  */
-declare function pianoToSmplrJson(options: PianoJsonOptions): SmplrJson;
+declare function pianoToPreset(options: PianoJsonOptions): SmplrPreset;
 declare const LAYERS: ({
     name: string;
     vel_range: number[];
@@ -1010,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, Scheduler, Sequencer, type SequencerInstrument, type SequencerNote, type SequencerNoteEvent, type SequencerOptions, Smolken, type SmolkenConfig, type SmolkenOptions, type Smplr, type SmplrGroup, type SmplrJson, type SmplrOptions, type SmplrPlugin, 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, drumMachineToSmplrJson, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToSmplrJson, pianoToSmplrJson, renderOffline, samplerToSmplrJson, sf2InstrumentToSmplrJson, soundfontToSmplrJson, 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 };