smplr 0.24.0 → 0.25.0

package/README.md

@@ -4,7 +4,7 @@
 
 > `smplr` is a collection of sampled instruments for Web Audio API ready to be used with no setup required.
 
-Examples:
+## Quick start
 
 **Play a note from a General MIDI soundfont:**
 
@@ -57,17 +57,13 @@ wav.downloadWav("arpeggio.wav");
 
 See demo: https://danigb.github.io/smplr/
 
-`smplr` is approaching 1.0. The 0.22.0 release lands the final batch of pre-1.0 API work — every documented `new X(ctx, opts)` keeps working, and the documented surface is intended to ship unchanged into 1.0. The formal stability commitment lands once the narrow `loader`/`scheduler` public interfaces sibling ticket is in (see [CHANGELOG](https://github.com/danigb/smplr/blob/main/CHANGELOG.md)).
-
-> **Upgrading from an earlier 0.x?** No code changes are required — every documented `new X(ctx, opts)` keeps working. New code should drop the `new` (`X(ctx, opts)`) and prefer `await x.ready` over `await x.load`.
-
 #### Library goals
 
 - No setup: specifically, all samples are online, so no need for a server.
 - Easy to use: everything should be intuitive for non-experienced developers
 - Decent sounding: uses high quality open source samples. For better or worse, it is sample based 🤷
 
-## Setup
+## Installation
 
 You can install the library with a package manager or use it directly by importing from the browser.
 
@@ -105,17 +101,35 @@ You can import directly from the browser. For example:
 
 The package needs to be served as a URL from a service like [unpkg](https://unpkg.com) or similar.
 
-> To author your own instrument or publish a third-party package, see the [Defining an instrument](./AUTHORING.md) guide.
+## Available instruments
 
-## Documentation
+`smplr` ships eleven instruments out of the box. Pick one and jump to its section in the [Instrument reference](#instrument-reference) for setup details.
 
-### Defining an instrument
+| 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                 | —                             |
 
-`smplr` ships ten instruments out of the box — `SplendidGrandPiano`, `Soundfont`, `DrumMachine`, `ElectricPiano`, `Mallet`, `Mellotron`, `Smolken`, `Versilian`, `Sampler`, `Soundfont2`. If none of them fit your use case, you can author your own with the `Instrument` builder and the `Smplr` interface.
+`*` `getVersilianInstruments` is async because the catalog is fetched from the network on first call (cached thereafter).
 
-See **[Defining an instrument](./AUTHORING.md)** for the full authoring guide — sync and async examples, third-party package layout, and how to use `Smplr` as a TypeScript type for generic helpers.
+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).
+
+## 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).
 
-### Create and load an instrument
+### Create and load
 
 Every smplr instrument is a factory function: call it with an `AudioContext` and an options object to get back an instance.
 
@@ -127,29 +141,18 @@ const piano = SplendidGrandPiano(context, { decayTime: 0.5 });
 const marimba = Soundfont(context, { instrument: "marimba" });
 ```
 
-> **Compatibility note:** All factories also support the `new` keyword — `new SplendidGrandPiano(context)` produces the same instance as `SplendidGrandPiano(context)`. Code from earlier `smplr` versions keeps working unchanged. Editors will mark the `new` form as `@deprecated` to nudge new code toward the call form; both remain supported throughout the 1.x line.
-
 #### Wait for audio loading
 
-You can start playing notes as soon as one audio is loaded. But if you want to wait for all of them, you can use the `load` property that returns a promise:
-
-```js
-piano.load.then(() => {
-  // now the piano is fully loaded
-});
-```
+You can start playing notes as soon as one sample is loaded. To wait for all of them, await either:
 
-Since the promise returns the instrument instance, you can create and wait in a single line:
+- `piano.ready` — resolves to `void` (preferred for new code).
+- `piano.load` — resolves to the instrument itself, so you can create and await in one line:
 
 ```js
 const piano = await SplendidGrandPiano(context).load;
 ```
 
-The pre-1.0 `new`-prefixed form continues to work — `const piano = await new SplendidGrandPiano(context).load` resolves to the same instrument. This is the documented backward-compat path for code from earlier `smplr` versions.
-
-> **New in 1.0:** prefer `await piano.ready` for new code. It resolves to `void` (not the instrument) and won't be removed — `.load` is kept as a deprecated alias for compatibility.
-
-⚠️ In versions lower than 0.8.0 a `loaded()` function was exposed instead.
+> Upgrading from older versions? See [MIGRATE.md](./MIGRATE.md).
 
 #### Load progress
 
@@ -168,7 +171,7 @@ console.log(piano.loadProgress); // { loaded: 12, total: 48 }
 
 `total` is known before loading starts, so you can display a determinate progress bar.
 
-#### Shared configuration options
+### Shared configuration options
 
 All instruments share some configuration options, passed as the second argument to the factory. Every field is optional:
 
@@ -177,52 +180,14 @@ All instruments share some configuration options, passed as the second argument
 - `pan`: stereo pan, -1 (full left) to +1 (full right). 0 by default.
 - `destination`: the `AudioNode` the instrument writes to. `AudioContext.destination` by default.
 - `volumeToGain`: a function to map MIDI volume to a linear gain. Uses the MIDI standard curve by default.
-- `storage`: a [storage backend](#cache-requests) used to fetch sample buffers. `HttpStorage` by default.
+- `storage`: a [storage backend](#caching-samples) used to fetch sample buffers. `HttpStorage` by default.
 - `loader`: a shared `SampleLoader` instance. Pass the same loader to multiple instruments to cache buffers across them (see [Buffer reuse](#buffer-reuse)).
 - `scheduler`: a shared `Scheduler` instance. Construct your own to tune scheduling — for example, `Scheduler(context, { lookaheadMs: 100, intervalMs: 25 })` — or omit to get a per-instrument default.
 - `onLoadProgress`: a function called after each sample buffer is decoded. Receives `{ loaded, total }` where `total` is the full count known before loading starts.
 - `onStart`: called when a note is dispatched to the audio engine. Receives the started note. See ⚠️ note under [Events](#events) on timing precision.
 - `onEnded`: called when each voice's audio node ends. Receives the started note.
 
-#### Usage with standardized-audio-context
-
-This package should be compatible with [standardized-audio-context](https://github.com/chrisguttandin/standardized-audio-context):
-
-```js
-import { AudioContext } from "standardized-audio-context";
-
-const context = new AudioContext();
-const piano = SplendidGrandPiano(context);
-```
-
-However, if you are using Typescript, you might need to "force cast" the types:
-
-```ts
-import { Soundfont } from "smplr";
-import { AudioContext as StandardizedAudioContext } from "standardized-audio-context";
-
-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:
-
-```ts
-import {
-  AudioWorkletNode,
-  IAudioContext,
-  AudioContext as StandardizedAudioContext,
-} from "standardized-audio-context";
-
-window.AudioWorkletNode = AudioWorkletNode as any;
-const context = new StandardizedAudioContext() as unknown as AudioContext;
-
-// ... rest of the code
-```
-
-See [standardized-audio-context issue #897](https://github.com/chrisguttandin/standardized-audio-context/issues/897) for background on why the cast is required.
-
-### Play
+### Play notes
 
 #### Start and stop notes
 
@@ -289,7 +254,9 @@ sampler.start({
 
 If `loop` is true but `loopStart` or `loopEnd` are not specified, 0 and total duration will be used by default, respectively.
 
-#### Change volume
+### Output
+
+#### Volume
 
 Instrument `output` attribute represents the main output of the instrument. The `output.volume` getter/setter accepts a number where 0 means no volume, and 127 is max volume without amplification:
 
@@ -298,8 +265,6 @@ piano.output.volume = 80;
 piano.output.volume; // => 80
 ```
 
-`output.setVolume(n)` is kept as a deprecated alias and continues to work.
-
 ⚠️ `volume` is global to the instrument, but `velocity` is specific for each note.
 
 #### Pan, detune, and reverse
@@ -330,20 +295,28 @@ piano.setCC(64, 0); // sustain pedal off
 
 Unset CCs default to `0` (matches MIDI's "undefined controller defaults to 0" convention).
 
-#### Disposing
+### Effects
 
-When you're done with an instrument, call `dispose()` to stop all voices, tear down the audio graph, and stop the scheduler. The instance must not be used after this call.
+#### Reverb
+
+A packaged version of the [DattorroReverbNode](https://github.com/khoin/DattorroReverbNode) algorithmic reverb is included.
+
+Use `output.addEffect(name, effect, mix)` to connect an effect using a send bus:
 
 ```js
-useEffect(() => {
-  const piano = SplendidGrandPiano(context);
-  return () => piano.dispose();
-}, []);
+import { Reverb, SplendidGrandPiano } from "smplr";
+const reverb = Reverb(context);
+const piano = SplendidGrandPiano(context, { volume });
+piano.output.addEffect("reverb", reverb, 0.2);
 ```
 
-`disconnect()` is kept as a deprecated alias and continues to work.
+To change the mix level, use `output.setEffectMix(name, mix)`:
 
-#### Events
+```js
+piano.output.setEffectMix("reverb", 0.5);
+```
+
+### Events
 
 Two events are supported `onStart` and `onEnded`. Both callbacks will receive as parameter started note.
 
@@ -374,30 +347,18 @@ Global callbacks will be invoked regardless of whether local events are defined.
 
 ⚠️ The invocation time of `onStart` is not exact: it fires slightly before the audio actually starts, by up to the scheduler's lookahead window (200ms by default; configurable via the `scheduler` option — see [Shared configuration options](#shared-configuration-options)).
 
-### Effects
+### Dispose
 
-#### Reverb
-
-A packaged version of the [DattorroReverbNode](https://github.com/khoin/DattorroReverbNode) algorithmic reverb is included.
-
-Use `output.addEffect(name, effect, mix)` to connect an effect using a send bus:
-
-```js
-import { Reverb, SplendidGrandPiano } from "smplr";
-const reverb = Reverb(context);
-const piano = SplendidGrandPiano(context, { volume });
-piano.output.addEffect("reverb", reverb, 0.2);
-```
-
-To change the mix level, use `output.setEffectMix(name, mix)`:
+When you're done with an instrument, call `dispose()` to stop all voices, tear down the audio graph, and stop the scheduler. The instance must not be used after this call.
 
 ```js
-piano.output.setEffectMix("reverb", 0.5);
+useEffect(() => {
+  const piano = SplendidGrandPiano(context);
+  return () => piano.dispose();
+}, []);
 ```
 
-`output.sendEffect(name, mix)` is kept as a deprecated alias and continues to work.
-
-### Cache requests
+### Caching samples
 
 The default sample sets are hosted on GitHub Pages, which rate-limits requests per second. That can be a problem, especially in a development environment with hot reload (most React frameworks).
 
@@ -414,9 +375,47 @@ const piano = SplendidGrandPiano(context, { storage });
 
 ⚠️ `CacheStorage` is based on the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) and only works in secure environments that run over `https`. Check your framework's documentation for local-HTTPS setup — for example [next-dev-https](https://www.npmjs.com/package/next-dev-https) for Next.js or [vite-plugin-mkcert](https://github.com/liuweiGL/vite-plugin-mkcert) for Vite.
 
+### Using with standardized-audio-context
+
+This package should be compatible with [standardized-audio-context](https://github.com/chrisguttandin/standardized-audio-context):
+
+```js
+import { AudioContext } from "standardized-audio-context";
+
+const context = new AudioContext();
+const piano = SplendidGrandPiano(context);
+```
+
+However, if you are using Typescript, you might need to "force cast" the types:
+
+```ts
+import { Soundfont } from "smplr";
+import { AudioContext as StandardizedAudioContext } from "standardized-audio-context";
+
+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:
+
+```ts
+import {
+  AudioWorkletNode,
+  IAudioContext,
+  AudioContext as StandardizedAudioContext,
+} from "standardized-audio-context";
+
+window.AudioWorkletNode = AudioWorkletNode as any;
+const context = new StandardizedAudioContext() as unknown as AudioContext;
+
+// ... rest of the code
+```
+
+See [standardized-audio-context issue #897](https://github.com/chrisguttandin/standardized-audio-context/issues/897) for background on why the cast is required.
+
 ## Sequencer
 
-`Sequencer` schedules notes from one or more tracks against any smplr instrument with sample-accurate timing. Constructed as `Sequencer(context, opts)` (the `new Sequencer(...)` form also still works as a deprecated alias).
+`Sequencer` schedules notes from one or more tracks against any smplr instrument with sample-accurate timing.
 
 ```js
 import { Sequencer, SplendidGrandPiano, DrumMachine } from "smplr";
@@ -712,7 +711,7 @@ seq.on("patternChange", (idx) => ui.highlightPattern(idx));
 
 ---
 
-## Export Audio
+## Offline rendering
 
 Render audio offline (faster than real-time) and export it as a WAV file. Uses `OfflineAudioContext` under the hood.
 
@@ -791,23 +790,9 @@ This will download a WAV file you can attach to your issue or pull request.
 
 ---
 
-## Instruments
-
-### Available instruments
+## Instrument reference
 
-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[]>` |
-
-`getVersilianInstruments` is async because the catalog is fetched from the network on first call (cached thereafter).
+Detailed configuration for each bundled instrument. For the shared API (load, play, output, effects, events), see [Using an instrument](#using-an-instrument).
 
 ### Sampler
 
@@ -1025,6 +1010,61 @@ drums.start("kick"); // Play the first sample of the group
 drums.start("kick-1"); // Play this specific sample
 ```
 
+### DrumAbuse
+
+Sampled instrument for the [Synthabuse](https://www.youtube.com/watch?v=Ay-U9eYKmGA) drum-machine collection — 5 packs covering ~210 classic drum machines and synths. Samples hosted at `smpldsnds.github.io/drum-abuse-{pack}/`.
+
+Two source modes: load a single machine's full kit, or load a cross-machine instrument list from a pack.
+
+#### Machine mode
+
+```js
+import { DrumAbuse, getDrumAbuseMachineNames } from "smplr";
+
+const machines = getDrumAbuseMachineNames(); // ~210 machine ids
+
+const context = new AudioContext();
+const drums = DrumAbuse(context, {
+  source: { kind: "machine", machine: "roland-tr-808" },
+});
+await drums.load;
+
+drums.start({ note: "kick" });
+
+// Samples are grouped by instrument name, like DrumMachine:
+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
+```
+
+If a machine has more than one sample set, pass `set` to pick a specific one. Omit to load the first set.
+
+```js
+const drums = DrumAbuse(context, {
+  source: { kind: "machine", machine: "roland-tr-808", set: "kit-a" },
+});
+```
+
+#### Pack mode
+
+A pack is a cross-machine catalog of named instruments (e.g. all the kicks across `vol1`). Pass `source: { kind: "pack", pack, instrument }`:
+
+```js
+import {
+  DrumAbuse,
+  getDrumAbusePackNames,
+  getDrumAbuseMachinesForPack,
+} from "smplr";
+
+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" },
+});
+```
+
 ### Smolken double bass
 
 ```js
@@ -1055,7 +1095,7 @@ const versilian = Versilian(context, { instrument: instrumentNames[0] });
 
 ### Soundfont2
 
-Sampler capable of reading .sf2 files directly. Previously named `Soundfont2Sampler`; the old name remains as a deprecated alias.
+Sampler capable of reading .sf2 files directly.
 
 ```ts
 import { Soundfont2 } from "smplr";
@@ -1078,6 +1118,16 @@ 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.
+
+See **[Defining an instrument](./AUTHORING.md)** for the full authoring guide — sync and async examples, third-party package layout, and how to use `Smplr` as a TypeScript type for generic helpers.
+
+## Upgrading
+
+`smplr` is approaching 1.0; pre-1.0 APIs keep working as deprecated aliases. See [MIGRATE.md](./MIGRATE.md) for the full compatibility table and [CHANGELOG](https://github.com/danigb/smplr/blob/main/CHANGELOG.md) for per-release detail.
+
 ## License
 
 MIT License

package/dist/index.d.mts

@@ -478,6 +478,55 @@ type DrumMachine = ReturnType<typeof DrumMachine>;
  */
 declare function drumMachineToPreset(instrument: DrumMachineInstrument): SmplrPreset;
 
+declare const DRUM_ABUSE_PACKS: readonly ["vol1", "vol2", "vol3", "vol4", "vol5"];
+type DrumAbusePackId = (typeof DRUM_ABUSE_PACKS)[number];
+declare function getDrumAbuseMachineNames(): string[];
+declare function getDrumAbuseMachinesForPack(pack: DrumAbusePackId): readonly string[];
+declare function getDrumAbusePackNames(): readonly DrumAbusePackId[];
+declare function getDrumAbuseMachinePack(id: string): DrumAbusePackId | undefined;
+/** Build a full sample URL. Exported so external row-level Sampler use
+ * (e.g. the sequencer engine) can share the same URL convention. */
+declare function drumAbuseSampleUrl(pack: DrumAbusePackId, urlPath: string, fileNoExt: string, format?: string, baseUrl?: string): string;
+type DrumAbuseSource = {
+    kind: "machine";
+    machine: string;
+    set?: string;
+} | {
+    kind: "pack";
+    pack: DrumAbusePackId;
+    instrument: string;
+};
+type DrumAbuseConfig = {
+    source: DrumAbuseSource;
+    baseUrl: string;
+    storage: Storage;
+};
+type DrumAbuseOptions = Partial<DrumAbuseConfig & {
+    destination?: AudioNode;
+    volume?: number;
+    pan?: number;
+    velocity?: number;
+    onLoadProgress?: (progress: LoadProgress) => void;
+}>;
+type DrumAbuseExtras = {
+    readonly mode: "machine" | "pack";
+    getSampleNames(): string[];
+    getGroupNames(): string[];
+    getSampleNamesForGroup(groupName: string): string[];
+    getMachineId(): string | null;
+    getSetPath(): string | null;
+    getPackId(): DrumAbusePackId;
+    start(event: NoteEvent): StopFn;
+};
+declare const DrumAbuse: InstrumentFactory<Partial<DrumAbuseConfig & {
+    destination?: AudioNode;
+    volume?: number;
+    pan?: number;
+    velocity?: number;
+    onLoadProgress?: (progress: LoadProgress) => void;
+}>, DrumAbuseExtras>;
+type DrumAbuse = ReturnType<typeof DrumAbuse>;
+
 /**
  * The result of an offline render. Provides the raw AudioBuffer and
  * lazy WAV encoding / download convenience methods.
@@ -1224,4 +1273,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-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 };
+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 };

package/dist/index.d.ts

@@ -478,6 +478,55 @@ type DrumMachine = ReturnType<typeof DrumMachine>;
  */
 declare function drumMachineToPreset(instrument: DrumMachineInstrument): SmplrPreset;
 
+declare const DRUM_ABUSE_PACKS: readonly ["vol1", "vol2", "vol3", "vol4", "vol5"];
+type DrumAbusePackId = (typeof DRUM_ABUSE_PACKS)[number];
+declare function getDrumAbuseMachineNames(): string[];
+declare function getDrumAbuseMachinesForPack(pack: DrumAbusePackId): readonly string[];
+declare function getDrumAbusePackNames(): readonly DrumAbusePackId[];
+declare function getDrumAbuseMachinePack(id: string): DrumAbusePackId | undefined;
+/** Build a full sample URL. Exported so external row-level Sampler use
+ * (e.g. the sequencer engine) can share the same URL convention. */
+declare function drumAbuseSampleUrl(pack: DrumAbusePackId, urlPath: string, fileNoExt: string, format?: string, baseUrl?: string): string;
+type DrumAbuseSource = {
+    kind: "machine";
+    machine: string;
+    set?: string;
+} | {
+    kind: "pack";
+    pack: DrumAbusePackId;
+    instrument: string;
+};
+type DrumAbuseConfig = {
+    source: DrumAbuseSource;
+    baseUrl: string;
+    storage: Storage;
+};
+type DrumAbuseOptions = Partial<DrumAbuseConfig & {
+    destination?: AudioNode;
+    volume?: number;
+    pan?: number;
+    velocity?: number;
+    onLoadProgress?: (progress: LoadProgress) => void;
+}>;
+type DrumAbuseExtras = {
+    readonly mode: "machine" | "pack";
+    getSampleNames(): string[];
+    getGroupNames(): string[];
+    getSampleNamesForGroup(groupName: string): string[];
+    getMachineId(): string | null;
+    getSetPath(): string | null;
+    getPackId(): DrumAbusePackId;
+    start(event: NoteEvent): StopFn;
+};
+declare const DrumAbuse: InstrumentFactory<Partial<DrumAbuseConfig & {
+    destination?: AudioNode;
+    volume?: number;
+    pan?: number;
+    velocity?: number;
+    onLoadProgress?: (progress: LoadProgress) => void;
+}>, DrumAbuseExtras>;
+type DrumAbuse = ReturnType<typeof DrumAbuse>;
+
 /**
  * The result of an offline render. Provides the raw AudioBuffer and
  * lazy WAV encoding / download convenience methods.
@@ -1224,4 +1273,4 @@ declare const LAYERS: ({
     cutoff?: undefined;
 })[];
 
-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 };
+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 };