smplr 0.23.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:**
 
@@ -25,7 +25,7 @@ const context = new AudioContext();
 const piano = SplendidGrandPiano(context);
 const drums = DrumMachine(context, { instrument: "TR-808" });
 
-const seq = new Sequencer(context, { bpm: 110, loop: true });
+const seq = Sequencer(context, { bpm: 110, loop: true });
 seq.addTrack(piano, [
   { note: "C4", at: "1:1", duration: "4n" },
   { note: "E4", at: "1:2", duration: "4n" },
@@ -47,7 +47,7 @@ import { SplendidGrandPiano, Reverb, renderOffline } from "smplr";
 
 const wav = await renderOffline(async (context) => {
   const piano = await SplendidGrandPiano(context).load;
-  piano.output.addEffect("reverb", new Reverb(context), 0.3);
+  piano.output.addEffect("reverb", Reverb(context), 0.3);
   ["C4", "E4", "G4", "C5"].forEach((note, i) => {
     piano.start({ note, time: i * 0.4, duration: 0.4 });
   });
@@ -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`, `Soundfont2Sampler`. 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).
 
-### Create and load an 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
 
 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:
+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 +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, `new Scheduler(context, { lookaheadMs: 100, intervalMs: 25 })` — or omit to get a per-instrument default.
+- `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,10 +265,24 @@ 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
+
+Every instrument accepts a `pan` option at construction (`-1` = full left, `+1` = full right):
+
+```js
+const drums = DrumMachine(context, { instrument: "TR-808", pan: -0.5 });
+```
+
+Two universal setters mutate the playback defaults in place. They apply to notes scheduled **after** the call; in-flight notes are unaffected.
+
+```js
+sampler.setDetune(100); // semitone up (100 cents) for all future notes
+sampler.setReverse(true); // play samples reversed for all future notes
+sampler.setReverse(false); // back to forward playback
+```
+
 #### MIDI CC
 
 Set and read MIDI Control Change values on the instrument:
@@ -314,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
+
+#### Reverb
 
-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.
+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.
 
@@ -358,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
-
-#### 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 = new Reverb(context);
-const piano = SplendidGrandPiano(context, { volume });
-piano.output.addEffect("reverb", reverb, 0.2);
-```
+### Dispose
 
-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).
 
@@ -391,16 +368,54 @@ To cache samples in the browser, use a `CacheStorage` object:
 import { SplendidGrandPiano, CacheStorage } from "smplr";
 
 const context = new AudioContext();
-const storage = new CacheStorage();
+const storage = CacheStorage();
 // First time the instrument loads, will fetch the samples from http. Subsequent times from cache.
 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. Unlike instruments, it's a regular class — always constructed with `new Sequencer(context, opts)`.
+`Sequencer` schedules notes from one or more tracks against any smplr instrument with sample-accurate timing.
 
 ```js
 import { Sequencer, SplendidGrandPiano, DrumMachine } from "smplr";
@@ -409,7 +424,7 @@ const context = new AudioContext();
 const piano = SplendidGrandPiano(context);
 const drums = DrumMachine(context, { instrument: "TR-808" });
 
-const seq = new Sequencer(context, { bpm: 120, loop: true });
+const seq = Sequencer(context, { bpm: 120, loop: true });
 
 seq.addTrack(piano, [
   { note: "C4", at: "1:1", duration: "4n" },
@@ -446,19 +461,55 @@ Note positions and durations accept several formats:
 #### Constructor options
 
 ```js
-const seq = new Sequencer(context, {
+const seq = Sequencer(context, {
   bpm: 120, // default 120
   ppq: 480, // pulses per quarter note, default 480
-  timeSignature: 4, // beats per bar, default 4
+  timeSignature: 4, // accepts `4` (→ 4/4) or `{ numerator, denominator }`
   loop: false, // default false
   loopStart: 0, // loop start position (ticks or string)
   loopEnd: "2:1", // loop end position; defaults to end of longest track
   lookaheadMs: 200, // scheduling lookahead, default 200
   intervalMs: 50, // flush interval, default 50
   humanize: { timingMs: 10, velocity: 8 }, // optional randomisation
+  stepSize: "16n", // optional: emit "step" events at this interval
 });
 ```
 
+`timeSignature` accepts a plain number (interpreted as `{ numerator: n, denominator: 4 }`) or a full object such as `{ numerator: 7, denominator: 8 }` for 7/8 time. The `seq.timeSignature` getter always returns the `{ numerator, denominator }` form.
+
+#### Tracks
+
+```js
+seq.addTrack(piano, notes); // append a track
+seq.addTrack(drums, notes, { id: "drums", volume: 0.8 }); // with options
+seq.removeTrack(piano); // remove by instrument reference
+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.                                    |
+
+After `setPatterns` is called (see [Pattern chain](#pattern-chain-song-mode)), `addTrack` / `removeTrack` / `clearTracks` throw — the chain is owned by the patterns array.
+
+#### Track mixer
+
+```js
+seq.setTrackVolume("drums", 0.6);
+seq.muteTrack("drums");
+seq.unmuteTrack("drums");
+seq.soloTrack("lead");
+seq.unsoloTrack("lead");
+```
+
+Mixer methods operate on the **currently-playing pattern** (so per-pattern mute/solo state is automatic when using a pattern chain). Calls with an unknown id are no-ops.
+
 #### Playback
 
 ```js
@@ -481,12 +532,17 @@ seq.stopNote("intro-c", time); // stop at a scheduled time
 
 ```js
 seq.bpm = 140; // change BPM live, no glitch
-seq.timeSignature = 3; // change time signature
+seq.timeSignature = 3; // 3/4 (number → { numerator: 3, denominator: 4 })
+seq.timeSignature = { numerator: 7, denominator: 8 }; // 7/8
+
+seq.timeSignature; // → { numerator: 7, denominator: 8 }
 
 seq.position; // current position as "bar:beat:tick" string
 seq.position = "3:1"; // seek while playing or stopped
 ```
 
+The `"beat"` event fires once per denominator-defined note: 4/4 → 4 beats per bar, 6/8 → 6 beats per bar, etc.
+
 #### Loop
 
 ```js
@@ -531,12 +587,18 @@ seq.on("beat", (beat, time) => {
 seq.on("bar", (bar, time) => {
   ui.updateBar(bar);
 });
+seq.on("step", (stepIndex, time) => {
+  ui.flashStep(stepIndex); // only fires when `stepSize` is set in options
+});
 seq.on("loop", () => {
   console.log("looped");
 });
 seq.on("end", () => {
   console.log("done");
 });
+seq.on("patternChange", (patternIndex, time) => {
+  ui.highlightPattern(patternIndex); // fires when the chain advances
+});
 seq.on("start", () => {});
 seq.on("stop", () => {});
 seq.on("pause", () => {});
@@ -544,6 +606,9 @@ seq.on("pause", () => {});
 seq.off("beat", handler); // remove a listener
 ```
 
+The `"step"` event only fires when the sequencer was constructed with `stepSize` (e.g. `"16n"`).
+The `"patternChange"` event only fires when more than one pattern is in the chain.
+
 #### Note events
 
 `noteOn` and `noteOff` events fire when the instrument's `onStart` / `onEnded` callbacks are called, so they are driven by the actual audio playback — not by the scheduling lookahead.
@@ -581,7 +646,7 @@ seq.addTrack(piano, [
 Add subtle randomisation to timing and velocity for a more natural feel:
 
 ```js
-const seq = new Sequencer(context, {
+const seq = Sequencer(context, {
   bpm: 90,
   humanize: { timingMs: 12, velocity: 8 },
 });
@@ -590,9 +655,63 @@ const seq = new Sequencer(context, {
 - `timingMs`: maximum random offset in milliseconds (±). Default 0.
 - `velocity`: maximum random offset in MIDI velocity units (±). Default 0.
 
+Per-track humanize (passed to `addTrack`) overrides the global setting:
+
+```js
+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.       |
+| `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`.            |
+
+Example:
+
+```js
+seq.addTrack(drums, [
+  { note: "hat", at: "1:4", duration: "8n", ratchet: 4, ratchetVelocityDecay: 0.2 },
+  { note: "snare", at: "1:2", chance: 50 }, // fires 50% of the time
+]);
+```
+
+When `ratchet > 1`, each sub-note's `noteId` is suffixed with `#0`, `#1`, etc., so you can stop an individual sub-voice via `seq.stopNote("id#0")`.
+
+#### Pattern chain (song mode)
+
+For multi-pattern arrangements (intro → verse → chorus), use `setPatterns`:
+
+```js
+seq.setPatterns([
+  { tracks: [{ instrument: drums, notes: introNotes }], loopEnd: "1m" },
+  { tracks: [{ instrument: drums, notes: verseNotes }], loopEnd: "2m" },
+  { tracks: [{ instrument: drums, notes: chorusNotes }], loopEnd: "2m" },
+]);
+
+seq.chainOrder = [0, 1, 2, 1, 2]; // intro, verse, chorus, verse, chorus
+seq.loop = true;                  // loop the whole chain
+seq.start();
+
+seq.on("patternChange", (idx) => ui.highlightPattern(idx));
+```
+
+- Each pattern's `tracks` entries accept the same `AddTrackOptions` (`id`, `humanize`, `volume`, `muted`, `solo`) as `addTrack`.
+- `loopEnd` is per-pattern and defaults to the longest track in that pattern.
+- `chainOrder` defaults to `[0, 1, …, n-1]`. Setting it lets you repeat or reorder patterns without duplicating data.
+- With `loop: false` the chain plays once and emits `"end"`; with `loop: true` it cycles indefinitely and emits `"loop"` each time it wraps.
+- Track mixer methods (`muteTrack`, `setTrackVolume`, etc.) operate on the currently-playing pattern — `muteTrack("lead")` only affects the pattern that owns the `"lead"` track.
+
 ---
 
-## Export Audio
+## Offline rendering
 
 Render audio offline (faster than real-time) and export it as a WAV file. Uses `OfflineAudioContext` under the hood.
 
@@ -641,7 +760,7 @@ If you already have an instrument loaded, pass the same `SampleLoader` to avoid
 ```js
 import { SplendidGrandPiano, SampleLoader, renderOffline } from "smplr";
 
-const loader = new SampleLoader(audioContext);
+const loader = SampleLoader(audioContext);
 const piano = SplendidGrandPiano(audioContext, { loader });
 await piano.load;
 
@@ -671,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
 
@@ -905,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
@@ -933,16 +1093,16 @@ const context = new AudioContext();
 const versilian = Versilian(context, { instrument: instrumentNames[0] });
 ```
 
-### Soundfont2Sampler
+### Soundfont2
 
-Sampler capable of reading .sf2 files directly:
+Sampler capable of reading .sf2 files directly.
 
 ```ts
-import { Soundfont2Sampler } from "smplr";
+import { Soundfont2 } from "smplr";
 import { SoundFont2 } from "soundfont2";
 
 const context = new AudioContext();
-const sampler = Soundfont2Sampler(context, {
+const sampler = Soundfont2(context, {
   url: "https://smpldsnds.github.io/soundfonts/soundfonts/galaxy-electric-pianos.sf2",
   createSoundfont: (data) => new SoundFont2(data),
 });
@@ -958,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