Sampler Reference

The .dspreset is parsed by a self-contained XML reader rather than DOMParser, so the same import runs in the browser and under `node --test` with no DOM. The parse is pure: text in, regions out. It never throws on instrument text, and anything it does not speak is counted in `ignored` with malformed values collected in `warnings`, so a lossy import is visible rather than silent.

Each authored `<group>` becomes its own sampler program, and the programs stack. This is the one deliberate divergence from a naive merge: Decent Sampler plays every matching sample simultaneously, while a program resolves one region per velocity cell, so merging the bundled instrument's soft and bright groups would rotate between them instead of letting velocity choose. The importer flags the ambiguous case, and building per group avoids it entirely.

Region payloads are generic, which is what makes the loader boring. The importer produces regions whose payload is a path reference; the playback layer maps that payload to a decoded AudioBuffer and keeps every other field (key range, velocity layer, tuning, gain, loop points) exactly as imported. Nothing re-derives the map from the audio.

Selection runs on key first, then velocity, then round robin. A region whose explicit key range contains the note wins outright; regions without one compete by nearest root and are repitched, bounded by a maximum stretch. If every region is velocity-ranged and none contains the strike, the note is silent by policy. Legible silence beats the wrong sound, the same rule the zone map uses for out-of-reach keys.

The keybed is drawn from the same parse the audio comes from. Colour washes are the instrument's `<keyboard>` ranges converted from hex ARGB, and the muted keys are the program's own playable range, so a key that looks unmapped is unmapped. Feeding the UI from the program rather than from a second hand-written table is what keeps the two from disagreeing.

The published package carries both Aurora Keys and Pocket Kit as content-addressed instrument documents plus all 17 immutable audio assets. A generic host selects the document from the instrument parameter, verifies and decodes only its declared assets, then prepares either the instant TypeScript preview or the optimized sampler bank; switching instruments tears down the old bank before installing the new one.