smplr 0.25.0 → 0.26.0

package/README.md

@@ -71,7 +71,7 @@ Samples are stored at https://github.com/smpldsnds and there is no need to downl
 
 #### Using a package manager
 
-Use npm or your favourite package manager to install the library to use it in your project:
+Install with npm or your favourite package manager:
 
 ```
 npm i smplr
@@ -105,29 +105,27 @@ The package needs to be served as a URL from a service like [unpkg](https://unpk
 
 `smplr` ships eleven instruments out of the box. Pick one and jump to its section in the [Instrument reference](#instrument-reference) for setup details.
 
-| Instrument                                  | Description                               | Names helper                  |
-| ------------------------------------------- | ----------------------------------------- | ----------------------------- |
-| [`Sampler`](#sampler)                       | Your own buffers or SFZ-style preset      | —                             |
-| [`Soundfont`](#soundfont)                   | General MIDI soundfonts                   | `getSoundfontNames()`         |
-| [`SplendidGrandPiano`](#splendidgrandpiano) | Sampled Steinway grand, 4 velocity layers | —                             |
-| [`ElectricPiano`](#electric-piano)          | CP80, PianetT, Wurlitzer, TX81Z           | `getElectricPianoNames()`     |
-| [`DrumMachine`](#drum-machines)             | Classic drum machines (TR-808, …)         | `getDrumMachineNames()`       |
-| [`DrumAbuse`](#drumabuse)                   | ~210 machines (Synthabuse collection)     | `getDrumAbuseMachineNames()`  |
-| [`Mallet`](#mallets)                        | VCSL mallets                              | `getMalletNames()`            |
-| [`Mellotron`](#mellotron)                   | Mellotron archive samples                 | `getMellotronNames()`         |
-| [`Smolken`](#smolken-double-bass)           | Smolken double bass (Arco/Pizz/Switched)  | `getSmolkenNames()`           |
-| [`Versilian`](#versilian)                   | VCSL multi-instrument (partial support)   | `getVersilianInstruments()` * |
-| [`Soundfont2`](#soundfont2)                 | Reads .sf2 files directly                 | —                             |
+| Instrument                                  | Description                               | Names helper                 |
+| ------------------------------------------- | ----------------------------------------- | ---------------------------- |
+| [`Sampler`](#sampler)                       | Your own buffers or SFZ-style preset      | —                            |
+| [`Soundfont`](#soundfont)                   | General MIDI soundfonts                   | `getSoundfontNames()`        |
+| [`SplendidGrandPiano`](#splendidgrandpiano) | Sampled Steinway grand, 4 velocity layers | —                            |
+| [`ElectricPiano`](#electric-piano)          | CP80, PianetT, Wurlitzer, TX81Z           | `getElectricPianoNames()`    |
+| [`DrumMachine`](#drum-machines)             | Classic drum machines (TR-808, …)         | `getDrumMachineNames()`      |
+| [`DrumAbuse`](#drumabuse)                   | ~210 machines (Synthabuse collection)     | `getDrumAbuseMachineNames()` |
+| [`Mallet`](#mallets)                        | VCSL mallets                              | `getMalletNames()`           |
+| [`Mellotron`](#mellotron)                   | Mellotron archive samples                 | `getMellotronNames()`        |
+| [`Smolken`](#smolken-double-bass)           | Smolken double bass (Arco/Pizz/Switched)  | `getSmolkenNames()`          |
+| [`Versilian`](#versilian)                   | VCSL multi-instrument (partial support)   | `getVersilianInstruments()`  |
+| [`Soundfont2`](#soundfont2)                 | Reads .sf2 files directly                 | —                            |
 
-`*` `getVersilianInstruments` is async because the catalog is fetched from the network on first call (cached thereafter).
+Each names helper returns strings to pass as the factory's `instrument` option. `getVersilianInstruments` is async (the catalog is fetched once and cached).
 
-Each names helper returns the strings you can pass to the corresponding factory's `instrument` option.
-
-If none of the bundled instruments fits your use case, you can author your own — see [Defining your own instrument](#defining-your-own-instrument).
+To build your own instrument, see [Defining your own instrument](#defining-your-own-instrument).
 
 ## Using an instrument
 
-Every smplr instrument follows the same usage pattern. This section covers what's shared across all of them; for instrument-specific options, see the [Instrument reference](#instrument-reference).
+The shared API below applies to every instrument. Instrument-specific options live in the [Instrument reference](#instrument-reference).
 
 ### Create and load
 
@@ -191,13 +189,13 @@ All instruments share some configuration options, passed as the second argument
 
 #### Start and stop notes
 
-The `start` function accepts a bunch of options:
+The `start` function accepts these options:
 
 ```js
 piano.start({ note: "C4", velocity: 80, time: 5, duration: 1 });
 ```
 
-The `velocity` is a number between 0 and 127 the represents at which velocity the key is pressed. The bigger the number, louder the sound. But `velocity` not only controls the loudness. In some instruments, it also affects the timbre.
+`velocity` (0–127) represents how hard the key is pressed: louder at higher values, and on some instruments it also changes timbre.
 
 The `start` function returns a `stop` function for the given note:
 
@@ -224,9 +222,9 @@ piano.stop(60); // stop the note(s) started with `note: 60`
 
 #### Schedule notes
 
-You can schedule notes using `time` and `duration` properties. Both are measured in seconds. Time is the number of seconds since the AudioContext was created, like in `audioContext.currentTime`
+Schedule notes via the `time` and `duration` properties (both in seconds). `time` is measured against `audioContext.currentTime`.
 
-For example, next example plays a C major arpeggio, one note per second:
+This plays a C major arpeggio, one note per second:
 
 ```js
 const now = context.currentTime;
@@ -318,9 +316,7 @@ piano.output.setEffectMix("reverb", 0.5);
 
 ### Events
 
-Two events are supported `onStart` and `onEnded`. Both callbacks will receive as parameter started note.
-
-Events can be configured globally:
+Two events are available: `onStart` and `onEnded`. Both callbacks receive the started note as a parameter, and can be configured globally:
 
 ```js
 const context = new AudioContext();
@@ -396,7 +392,7 @@ const context = new StandardizedAudioContext() as unknown as AudioContext;
 const marimba = Soundfont(context, { instrument: "marimba" });
 ```
 
-In case you need to use the `Reverb` module (or any other module that needs `AudioWorkletNode`) you need to enforce to use the one from `standardized-audio-context` package. Here is how:
+If you use `Reverb` (or anything else that needs `AudioWorkletNode`), force the `standardized-audio-context` version:
 
 ```ts
 import {
@@ -488,13 +484,13 @@ seq.clearTracks(); // remove every track
 
 `addTrack`'s third argument accepts:
 
-| Field      | Type                                        | Description                                                           |
-| ---------- | ------------------------------------------- | --------------------------------------------------------------------- |
-| `id`       | `string`                                    | Stable id for `setTrackVolume` / `muteTrack` / `soloTrack`.            |
-| `humanize` | `{ timingMs?: number; velocity?: number }`  | Per-track humanize. Overrides the sequencer-level setting when set.   |
-| `volume`   | `number`                                    | Multiplicative velocity scalar (default 1). `0.5` halves velocities.   |
-| `muted`    | `boolean`                                   | When true, this track does not dispatch notes.                         |
-| `solo`     | `boolean`                                   | When true, only soloed tracks play.                                    |
+| Field      | Type                                       | Description                                                          |
+| ---------- | ------------------------------------------ | -------------------------------------------------------------------- |
+| `id`       | `string`                                   | Stable id for `setTrackVolume` / `muteTrack` / `soloTrack`.          |
+| `humanize` | `{ timingMs?: number; velocity?: number }` | Per-track humanize. Overrides the sequencer-level setting when set.  |
+| `volume`   | `number`                                   | Multiplicative velocity scalar (default 1). `0.5` halves velocities. |
+| `muted`    | `boolean`                                  | When true, this track does not dispatch notes.                       |
+| `solo`     | `boolean`                                  | When true, only soloed tracks play.                                  |
 
 After `setPatterns` is called (see [Pattern chain](#pattern-chain-song-mode)), `addTrack` / `removeTrack` / `clearTracks` throw — the chain is owned by the patterns array.
 
@@ -663,22 +659,28 @@ seq.addTrack(piano, notes, { humanize: { timingMs: 0, velocity: 0 } });
 
 #### SequencerNote fields
 
-| Field                  | Type                | Description                                                                  |
-| ---------------------- | ------------------- | ---------------------------------------------------------------------------- |
-| `note`                 | `string \| number`  | Note name or MIDI number.                                                    |
-| `at`                   | `string \| number`  | Musical position (ticks or `"bar:beat[.frac][:ticks]"` / `"4n"` / `"1m"`).   |
-| `duration`             | `string \| number?` | Duration; omit for a one-shot trigger.                                       |
-| `velocity`             | `number?`           | Velocity 0–127. Default 100.                                                 |
-| `id`                   | `string \| number?` | Used as `noteId` in `noteOn` / `noteOff` events. Default: array index.       |
+| Field                  | Type                | Description                                                                   |
+| ---------------------- | ------------------- | ----------------------------------------------------------------------------- |
+| `note`                 | `string \| number`  | Note name or MIDI number.                                                     |
+| `at`                   | `string \| number`  | Musical position (ticks or `"bar:beat[.frac][:ticks]"` / `"4n"` / `"1m"`).    |
+| `duration`             | `string \| number?` | Duration; omit for a one-shot trigger.                                        |
+| `velocity`             | `number?`           | Velocity 0–127. Default 100.                                                  |
+| `id`                   | `string \| number?` | Used as `noteId` in `noteOn` / `noteOff` events. Default: array index.        |
 | `chance`               | `number?`           | Probability 0–100 that this note fires on each pass. Re-rolled on every loop. |
-| `ratchet`              | `number?`           | Expand into N sub-notes over `duration` (requires `duration`).               |
-| `ratchetVelocityDecay` | `number?`           | Per-step velocity decay; each sub-note scaled by `(1 - decay)^i`.            |
+| `ratchet`              | `number?`           | Expand into N sub-notes over `duration` (requires `duration`).                |
+| `ratchetVelocityDecay` | `number?`           | Per-step velocity decay; each sub-note scaled by `(1 - decay)^i`.             |
 
 Example:
 
 ```js
 seq.addTrack(drums, [
-  { note: "hat", at: "1:4", duration: "8n", ratchet: 4, ratchetVelocityDecay: 0.2 },
+  {
+    note: "hat",
+    at: "1:4",
+    duration: "8n",
+    ratchet: 4,
+    ratchetVelocityDecay: 0.2,
+  },
   { note: "snare", at: "1:2", chance: 50 }, // fires 50% of the time
 ]);
 ```
@@ -697,7 +699,7 @@ seq.setPatterns([
 ]);
 
 seq.chainOrder = [0, 1, 2, 1, 2]; // intro, verse, chorus, verse, chorus
-seq.loop = true;                  // loop the whole chain
+seq.loop = true; // loop the whole chain
 seq.start();
 
 seq.on("patternChange", (idx) => ui.highlightPattern(idx));
@@ -796,7 +798,7 @@ Detailed configuration for each bundled instrument. For the shared API (load, pl
 
 ### Sampler
 
-An audio buffer sampler. Pass a `buffers` object with the files to be load:
+An audio buffer sampler. Pass a `buffers` map of name → URL:
 
 #### Buffers mode
 
@@ -816,7 +818,7 @@ And then use the name of the buffer as note name:
 sampler.start({ note: "kick" });
 ```
 
-#### Advanced mode
+#### Preset mode
 
 For advanced use cases (per-region pitch/velocity/round-robin, SFZ-like multi-sample instruments, runtime swaps), pass a `SmplrPreset` directly:
 
@@ -843,7 +845,7 @@ sampler.start({ note: 60 });
 await sampler.reload(kitB);
 ```
 
-The full `SmplrPreset` schema is documented in [SMPLR_PRESET.md](./SMPLR_PRESET.md). Note: `buffers` and `preset` are mutually exclusive on construction — pass exactly one.
+The full `SmplrPreset` schema is documented in [PRESET_SCHEMA.md](./PRESET_SCHEMA.md). Note: `buffers` and `preset` are mutually exclusive on construction — pass exactly one.
 
 `sampler.reload(input)` accepts either shape (flat buffers record or full `SmplrPreset`), regardless of which mode was used at construction.
 
@@ -1032,10 +1034,10 @@ await drums.load;
 drums.start({ note: "kick" });
 
 // Samples are grouped by instrument name, like DrumMachine:
-drums.getGroupNames();                // => ["kick", "snare", "hi-hat", ...]
+drums.getGroupNames(); // => ["kick", "snare", "hi-hat", ...]
 drums.getSampleNamesForGroup("kick"); // => ["kick/1", "kick/2", ...]
-drums.start({ note: "kick" });        // first sample in the group
-drums.start({ note: "kick/1" });      // a specific sample
+drums.start({ note: "kick" }); // first sample in the group
+drums.start({ note: "kick/1" }); // a specific sample
 ```
 
 If a machine has more than one sample set, pass `set` to pick a specific one. Omit to load the first set.
@@ -1057,8 +1059,8 @@ import {
   getDrumAbuseMachinesForPack,
 } from "smplr";
 
-getDrumAbusePackNames();               // => ["vol1", "vol2", "vol3", "vol4", "vol5"]
-getDrumAbuseMachinesForPack("vol1");   // => machine ids in vol1
+getDrumAbusePackNames(); // => ["vol1", "vol2", "vol3", "vol4", "vol5"]
+getDrumAbuseMachinesForPack("vol1"); // => machine ids in vol1
 
 const drums = DrumAbuse(new AudioContext(), {
   source: { kind: "pack", pack: "vol1", instrument: "bass-drum" },
@@ -1079,7 +1081,7 @@ const doubleBass = await Smolken(context, { instrument: "Arco" }).load;
 
 ### Versilian
 
-Versilian is a sample capable of using the [Versilian Community Sample Library](https://github.com/sgossner/VCSL).
+Plays instruments from the [Versilian Community Sample Library](https://github.com/sgossner/VCSL).
 
 ⚠️ Not all features are implemented. Some instruments may sound incorrect ⚠️
 
@@ -1116,8 +1118,6 @@ sampler.load.then(() => {
 });
 ```
 
-Still limited support. API may vary.
-
 ## Defining your own instrument
 
 If none of the bundled instruments fits your use case, you can author your own with the `Instrument` builder and the `Smplr` interface.

package/dist/index.d.mts

@@ -208,68 +208,90 @@ type VoiceParams = {
     reverse?: boolean;
 };
 
+/** Options accepted by `SampleLoader(context, options)`. */
+type SampleLoaderOptions = {
+    /** Custom storage backend (e.g. `CacheStorage` for offline). Defaults to `HttpStorage`. */
+    storage?: Storage;
+};
+/** Options accepted by `loader.load(json, options)`. */
+type SampleLoaderLoadOptions = {
+    /** Pre-decoded buffers keyed by sample name — skip fetch for these. */
+    buffers?: Map<string, AudioBuffer>;
+    /** Called once per sample (including cache hits) with cumulative progress. */
+    onProgress?: (loaded: number, total: number) => void;
+};
+type SampleLoaderFactory = {
+    (context: BaseAudioContext, options?: SampleLoaderOptions): SampleLoader;
+    /** @deprecated Call as a function: `SampleLoader(...)` instead of `new SampleLoader(...)`. */
+    new (context: BaseAudioContext, options?: SampleLoaderOptions): SampleLoader;
+};
 /**
- * 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.
+ * Loads and decodes AudioBuffers for the samples referenced by a {@link SmplrPreset}.
+ * Used internally by every smplr instrument; pass an instance via
+ * {@link SmplrOptions.loader} to share buffer caching across multiple instruments.
  */
-declare class SampleLoaderImpl {
-    #private;
-    constructor(context: BaseAudioContext, options?: {
-        storage?: Storage;
-    });
+interface SampleLoader {
     /**
-     * Load all samples referenced in `json`. Returns a Map of sample name →
-     * AudioBuffer. Progress is reported via `onProgress` callback or via
-     * options object.
+     * Load all samples referenced by `json`. Returns a Map keyed by sample
+     * name (`region.sample`), values are decoded `AudioBuffer`s. Failed
+     * samples are silently omitted (callers handle absence at lookup time).
      *
-     * - `buffers` in options: pre-loaded buffers — skips fetch for these names.
-     * - All samples load in parallel. Failed samples are silently omitted.
+     * Internally cached by resolved URL, so repeated calls with the same
+     * baseUrl/format/path do not re-fetch.
+     *
+     * @param json The preset describing samples to load.
+     * @param options
+     *   - `buffers`: pre-decoded buffers keyed by sample name — skip fetch for these.
+     *   - `onProgress`: called with `(loaded, total)` per sample (including cache hits).
+     */
+    load(json: SmplrPreset, options?: SampleLoaderLoadOptions): Promise<Map<string, AudioBuffer>>;
+    /**
+     * @deprecated Pass `{ onProgress }` instead. The bare-callback form is kept
+     * for compatibility; the options form is the canonical 1.x signature.
      */
-    load(json: SmplrPreset, onProgressOrOptions?: ((loaded: number, total: number) => void) | {
-        buffers?: Map<string, AudioBuffer>;
-        onProgress?: (loaded: number, total: number) => void;
-    }): Promise<Map<string, AudioBuffer>>;
+    load(json: SmplrPreset, 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>;
+declare const SampleLoader: SampleLoaderFactory;
 
+/** Options accepted by `Scheduler(context, options)`. */
+type SchedulerOptions = {
+    /**
+     * How far ahead of `currentTime` events are dispatched synchronously.
+     * Defaults to 200ms.
+     */
+    lookaheadMs?: number;
+    /**
+     * How often the queue is polled for events ready to dispatch.
+     * Defaults to 50ms.
+     */
+    intervalMs?: number;
+};
+type SchedulerFactory = {
+    (context: BaseAudioContext, options?: SchedulerOptions): Scheduler;
+    /** @deprecated Call as a function: `Scheduler(...)` instead of `new Scheduler(...)`. */
+    new (context: BaseAudioContext, options?: SchedulerOptions): Scheduler;
+};
 /**
- * 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.
+ * Schedules note events for future dispatch. Used internally by every smplr
+ * instrument; pass an instance via {@link SmplrOptions.scheduler} to share one
+ * scheduler across multiple instruments.
  */
-declare class SchedulerImpl {
-    #private;
-    constructor(context: BaseAudioContext, options?: {
-        lookaheadMs?: number;
-        intervalMs?: number;
-    });
+interface Scheduler {
     /**
-     * Schedule a callback for a NoteEvent.
+     * Dispatch `callback` at `event.time`. If `event.time` is within the
+     * scheduler's lookahead window (or omitted), the callback fires synchronously
+     * and the returned {@link StopFn} is a no-op. Otherwise the event is queued.
      *
-     * - 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.
+     * The returned function removes the event from the queue before dispatch.
      */
     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.
+     * Clear all queued (not-yet-dispatched) events and stop the polling
+     * interval. Does not affect voices already playing.
      */
     stop(): void;
 }
-declare const Scheduler: Constructable<[context: BaseAudioContext, options?: {
-    lookaheadMs?: number;
-    intervalMs?: number;
-} | undefined], SchedulerImpl>;
-type Scheduler = ReturnType<typeof Scheduler>;
+declare const Scheduler: SchedulerFactory;
 
 type SmplrOptions = {
     /** Custom storage backend for sample fetching (e.g. CacheStorage). */
@@ -1273,4 +1295,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { type AddTrackOptions, CacheStorage, DRUM_ABUSE_PACKS, DrumAbuse, type DrumAbuseConfig, type DrumAbuseExtras, type DrumAbuseOptions, type DrumAbusePackId, type DrumAbuseSource, 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, drumAbuseSampleUrl, drumMachineToPreset, getDrumAbuseMachineNames, getDrumAbuseMachinePack, getDrumAbuseMachinesForPack, getDrumAbusePackNames, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };
+export { type AddTrackOptions, CacheStorage, DRUM_ABUSE_PACKS, DrumAbuse, type DrumAbuseConfig, type DrumAbuseExtras, type DrumAbuseOptions, type DrumAbusePackId, type DrumAbuseSource, 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, type SampleLoaderLoadOptions, type SampleLoaderOptions, Sampler, type SamplerConfig, type SamplerReloadInput, Scheduler, type SchedulerOptions, 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, drumAbuseSampleUrl, drumMachineToPreset, getDrumAbuseMachineNames, getDrumAbuseMachinePack, getDrumAbuseMachinesForPack, getDrumAbusePackNames, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };

package/dist/index.d.ts

@@ -208,68 +208,90 @@ type VoiceParams = {
     reverse?: boolean;
 };
 
+/** Options accepted by `SampleLoader(context, options)`. */
+type SampleLoaderOptions = {
+    /** Custom storage backend (e.g. `CacheStorage` for offline). Defaults to `HttpStorage`. */
+    storage?: Storage;
+};
+/** Options accepted by `loader.load(json, options)`. */
+type SampleLoaderLoadOptions = {
+    /** Pre-decoded buffers keyed by sample name — skip fetch for these. */
+    buffers?: Map<string, AudioBuffer>;
+    /** Called once per sample (including cache hits) with cumulative progress. */
+    onProgress?: (loaded: number, total: number) => void;
+};
+type SampleLoaderFactory = {
+    (context: BaseAudioContext, options?: SampleLoaderOptions): SampleLoader;
+    /** @deprecated Call as a function: `SampleLoader(...)` instead of `new SampleLoader(...)`. */
+    new (context: BaseAudioContext, options?: SampleLoaderOptions): SampleLoader;
+};
 /**
- * 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.
+ * Loads and decodes AudioBuffers for the samples referenced by a {@link SmplrPreset}.
+ * Used internally by every smplr instrument; pass an instance via
+ * {@link SmplrOptions.loader} to share buffer caching across multiple instruments.
  */
-declare class SampleLoaderImpl {
-    #private;
-    constructor(context: BaseAudioContext, options?: {
-        storage?: Storage;
-    });
+interface SampleLoader {
     /**
-     * Load all samples referenced in `json`. Returns a Map of sample name →
-     * AudioBuffer. Progress is reported via `onProgress` callback or via
-     * options object.
+     * Load all samples referenced by `json`. Returns a Map keyed by sample
+     * name (`region.sample`), values are decoded `AudioBuffer`s. Failed
+     * samples are silently omitted (callers handle absence at lookup time).
      *
-     * - `buffers` in options: pre-loaded buffers — skips fetch for these names.
-     * - All samples load in parallel. Failed samples are silently omitted.
+     * Internally cached by resolved URL, so repeated calls with the same
+     * baseUrl/format/path do not re-fetch.
+     *
+     * @param json The preset describing samples to load.
+     * @param options
+     *   - `buffers`: pre-decoded buffers keyed by sample name — skip fetch for these.
+     *   - `onProgress`: called with `(loaded, total)` per sample (including cache hits).
+     */
+    load(json: SmplrPreset, options?: SampleLoaderLoadOptions): Promise<Map<string, AudioBuffer>>;
+    /**
+     * @deprecated Pass `{ onProgress }` instead. The bare-callback form is kept
+     * for compatibility; the options form is the canonical 1.x signature.
      */
-    load(json: SmplrPreset, onProgressOrOptions?: ((loaded: number, total: number) => void) | {
-        buffers?: Map<string, AudioBuffer>;
-        onProgress?: (loaded: number, total: number) => void;
-    }): Promise<Map<string, AudioBuffer>>;
+    load(json: SmplrPreset, 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>;
+declare const SampleLoader: SampleLoaderFactory;
 
+/** Options accepted by `Scheduler(context, options)`. */
+type SchedulerOptions = {
+    /**
+     * How far ahead of `currentTime` events are dispatched synchronously.
+     * Defaults to 200ms.
+     */
+    lookaheadMs?: number;
+    /**
+     * How often the queue is polled for events ready to dispatch.
+     * Defaults to 50ms.
+     */
+    intervalMs?: number;
+};
+type SchedulerFactory = {
+    (context: BaseAudioContext, options?: SchedulerOptions): Scheduler;
+    /** @deprecated Call as a function: `Scheduler(...)` instead of `new Scheduler(...)`. */
+    new (context: BaseAudioContext, options?: SchedulerOptions): Scheduler;
+};
 /**
- * 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.
+ * Schedules note events for future dispatch. Used internally by every smplr
+ * instrument; pass an instance via {@link SmplrOptions.scheduler} to share one
+ * scheduler across multiple instruments.
  */
-declare class SchedulerImpl {
-    #private;
-    constructor(context: BaseAudioContext, options?: {
-        lookaheadMs?: number;
-        intervalMs?: number;
-    });
+interface Scheduler {
     /**
-     * Schedule a callback for a NoteEvent.
+     * Dispatch `callback` at `event.time`. If `event.time` is within the
+     * scheduler's lookahead window (or omitted), the callback fires synchronously
+     * and the returned {@link StopFn} is a no-op. Otherwise the event is queued.
      *
-     * - 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.
+     * The returned function removes the event from the queue before dispatch.
      */
     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.
+     * Clear all queued (not-yet-dispatched) events and stop the polling
+     * interval. Does not affect voices already playing.
      */
     stop(): void;
 }
-declare const Scheduler: Constructable<[context: BaseAudioContext, options?: {
-    lookaheadMs?: number;
-    intervalMs?: number;
-} | undefined], SchedulerImpl>;
-type Scheduler = ReturnType<typeof Scheduler>;
+declare const Scheduler: SchedulerFactory;
 
 type SmplrOptions = {
     /** Custom storage backend for sample fetching (e.g. CacheStorage). */
@@ -1273,4 +1295,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-export { type AddTrackOptions, CacheStorage, DRUM_ABUSE_PACKS, DrumAbuse, type DrumAbuseConfig, type DrumAbuseExtras, type DrumAbuseOptions, type DrumAbusePackId, type DrumAbuseSource, 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, drumAbuseSampleUrl, drumMachineToPreset, getDrumAbuseMachineNames, getDrumAbuseMachinePack, getDrumAbuseMachinesForPack, getDrumAbusePackNames, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };
+export { type AddTrackOptions, CacheStorage, DRUM_ABUSE_PACKS, DrumAbuse, type DrumAbuseConfig, type DrumAbuseExtras, type DrumAbuseOptions, type DrumAbusePackId, type DrumAbuseSource, 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, type SampleLoaderLoadOptions, type SampleLoaderOptions, Sampler, type SamplerConfig, type SamplerReloadInput, Scheduler, type SchedulerOptions, 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, drumAbuseSampleUrl, drumMachineToPreset, getDrumAbuseMachineNames, getDrumAbuseMachinePack, getDrumAbuseMachinesForPack, getDrumAbusePackNames, getDrumMachineNames, getElectricPianoNames, getMalletNames, getMellotronNames, getSmolkenNames, getSoundfontKits, getSoundfontNames, getVersilianInstruments, loadVersilianInstrument, mellotronToPreset, pianoToPreset, renderOffline, samplerToPreset, sf2InstrumentToPreset, soundfontToPreset, trimSilence };