smplr 0.24.0 → 0.26.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.
 
@@ -75,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,17 +101,33 @@ 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.
+Each names helper returns strings to pass as the factory's `instrument` option. `getVersilianInstruments` is async (the catalog is fetched once and cached).
 
-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.
+To build your own instrument, see [Defining your own instrument](#defining-your-own-instrument).
 
-### Create and load an instrument
+## Using an instrument
+
+The shared API below applies to every instrument. Instrument-specific options live in the [Instrument reference](#instrument-reference).
+
+### 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 +139,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:
+You can start playing notes as soon as one sample is loaded. To wait for all of them, await either:
 
-```js
-piano.load.then(() => {
-  // now the piano is fully loaded
-});
-```
-
-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 +169,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,62 +178,24 @@ 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
 
-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:
 
@@ -259,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;
@@ -289,7 +252,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 +263,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,24 +293,30 @@ 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);
+```
 
-Two events are supported `onStart` and `onEnded`. Both callbacks will receive as parameter started note.
+### Events
 
-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();
@@ -374,30 +343,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
-
-#### Reverb
-
-A packaged version of the [DattorroReverbNode](https://github.com/khoin/DattorroReverbNode) algorithmic reverb is included.
+### Dispose
 
-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 +371,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" });
+```
+
+If you use `Reverb` (or anything else that needs `AudioWorkletNode`), force the `standardized-audio-context` version:
+
+```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";
@@ -489,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.
 
@@ -664,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
 ]);
 ```
@@ -698,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));
@@ -712,7 +713,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,27 +792,13 @@ 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
 
-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
 
@@ -831,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:
 
@@ -858,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.
 
@@ -1025,6 +1012,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
@@ -1039,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 ⚠️
 
@@ -1055,7 +1097,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";
@@ -1076,7 +1118,15 @@ 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