smplr 0.22.0 → 0.23.0

package/README.md

@@ -254,7 +254,7 @@ Or stop the specified one. The argument is a `stopId` — by default the same va
 
 ```js
 piano.stop("C4"); // stop the note(s) started with `note: "C4"`
-piano.stop(60);   // stop the note(s) started with `note: 60`
+piano.stop(60); // stop the note(s) started with `note: 60`
 ```
 
 #### Schedule notes
@@ -308,8 +308,8 @@ Set and read MIDI Control Change values on the instrument:
 
 ```js
 piano.setCC(64, 127); // sustain pedal on
-piano.getCC(64);      // => 127
-piano.setCC(64, 0);   // sustain pedal off
+piano.getCC(64); // => 127
+piano.setCC(64, 0); // sustain pedal off
 ```
 
 Unset CCs default to `0` (matches MIDI's "undefined controller defaults to 0" convention).
@@ -677,15 +677,15 @@ This will download a WAV file you can attach to your issue or pull request.
 
 Each instrument family exposes a synchronous helper that returns the names you can pass to its factory:
 
-| Factory | Names helper |
-|---|---|
-| `Soundfont` | `getSoundfontNames(): string[]` |
-| `ElectricPiano` | `getElectricPianoNames(): string[]` |
-| `Mallet` | `getMalletNames(): string[]` |
-| `Mellotron` | `getMellotronNames(): string[]` |
-| `DrumMachine` | `getDrumMachineNames(): string[]` |
-| `Smolken` | `getSmolkenNames(): string[]` |
-| `Versilian` | `getVersilianInstruments(): Promise<string[]>` |
+| Factory         | Names helper                                   |
+| --------------- | ---------------------------------------------- |
+| `Soundfont`     | `getSoundfontNames(): string[]`                |
+| `ElectricPiano` | `getElectricPianoNames(): string[]`            |
+| `Mallet`        | `getMalletNames(): string[]`                   |
+| `Mellotron`     | `getMellotronNames(): string[]`                |
+| `DrumMachine`   | `getDrumMachineNames(): string[]`              |
+| `Smolken`       | `getSmolkenNames(): string[]`                  |
+| `Versilian`     | `getVersilianInstruments(): Promise<string[]>` |
 
 `getVersilianInstruments` is async because the catalog is fetched from the network on first call (cached thereafter).
 
@@ -693,6 +693,8 @@ Each instrument family exposes a synchronous helper that returns the names you c
 
 An audio buffer sampler. Pass a `buffers` object with the files to be load:
 
+#### Buffers mode
+
 ```js
 import { Sampler } from "smplr";
 
@@ -709,6 +711,37 @@ And then use the name of the buffer as note name:
 sampler.start({ note: "kick" });
 ```
 
+#### Advanced mode
+
+For advanced use cases (per-region pitch/velocity/round-robin, SFZ-like multi-sample instruments, runtime swaps), pass a `SmplrPreset` directly:
+
+```ts
+import { Sampler, type SmplrPreset } from "smplr";
+
+const kitA: SmplrPreset = {
+  samples: { baseUrl: "https://cdn.example.com/", formats: ["ogg"] },
+  groups: [
+    {
+      regions: [
+        { sample: "kick", keyRange: [60, 60], pitch: 60 },
+        { sample: "snare", keyRange: [62, 62], pitch: 62 },
+      ],
+    },
+  ],
+};
+
+const sampler = Sampler(new AudioContext(), { preset: kitA });
+await sampler.ready;
+sampler.start({ note: 60 });
+
+// Swap content at runtime
+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.
+
+`sampler.reload(input)` accepts either shape (flat buffers record or full `SmplrPreset`), regardless of which mode was used at construction.
+
 ### Soundfont
 
 A Soundfont player. By default it loads audio from Benjamin Gleitzman's package of

package/dist/index.d.mts

@@ -114,7 +114,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,7 +190,7 @@ 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
@@ -209,7 +209,7 @@ 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>>;
@@ -324,7 +324,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 +429,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
@@ -793,14 +793,14 @@ 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 {
@@ -820,26 +820,40 @@ 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;
+    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 +862,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>;
 
@@ -904,10 +925,10 @@ declare const Soundfont: InstrumentFactory<Partial<SoundfontConfig & {
 /** 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[];
@@ -945,8 +966,8 @@ type Soundfont2Options = {
     volume?: 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 = {
@@ -967,7 +988,7 @@ 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;
@@ -988,7 +1009,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 +1018,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 +1031,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 { 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 };

package/dist/index.d.ts

@@ -114,7 +114,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,7 +190,7 @@ 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
@@ -209,7 +209,7 @@ 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>>;
@@ -324,7 +324,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 +429,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
@@ -793,14 +793,14 @@ 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 {
@@ -820,26 +820,40 @@ 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;
+    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 +862,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>;
 
@@ -904,10 +925,10 @@ declare const Soundfont: InstrumentFactory<Partial<SoundfontConfig & {
 /** 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[];
@@ -945,8 +966,8 @@ type Soundfont2Options = {
     volume?: 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 = {
@@ -967,7 +988,7 @@ 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;
@@ -988,7 +1009,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 +1018,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 +1031,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 { 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 };