@maruaudio/dsp/voices/sampler-zone is a zone-mapped sampler over a host-loaded arena: selection by key range, velocity layer and keyswitch window; root-pitch, source-rate playback with fine tune and transpose; per-zone gain, constant-power pan and velocity response; velocity crossfades; a linear AR or optional AHDSR envelope; 12 ms choke fades; round robin; crossfaded loops; release-trigger and one-shot zones; reverse; a per-zone RBJ low-pass. Legato zones, ping-pong loops, other filter types and streaming are refused.
Parameters
samplerZoneApplyParam(state, lane, value), lanes 0..16, clamped as coded:
| Lane | Range | Default |
|---|---|---|
| 0 master level (applied by the caller per frame) | 0 to 1 | 0.8 |
| 1 / 2 amp attack / release | 0 to 10000 ms, every zone | 0 / 300 |
| 3 transpose / 4 bend range | −24 to 24 / 0 to 24 semitones | 0 / 2 |
| 5 / 6 mod-wheel / pressure level | −24 to 24 dB | 0 / 0 |
| 7 / 8 amp decay / sustain | 0 to 10000 ms / 0 to 1 | 0 / 1 |
| 9 / 10 / 11 filter cutoff / Q / env amount | 20 to 20000 Hz / 0.1 to 20 / ±8 oct | 20000 / 0.7071 / 0 |
| 12, 13, 15 filter attack, decay, release / 14 sustain / 16 velocity | 0 to 10000 ms / 0 to 1 / 0 to 1 | 0 |
The instrument filter engages below 20 kHz or with a non-zero amount; it refreshes every 16 voice frames.
Lifecycle
Capacities must be finite integers: arena size is nonnegative, while zone and voice counts are positive and no larger than their declared ceilings. Invalid requests throw before allocation. A zero-sized initial arena supports later installation of an adapter-owned sample resource. The adapter keeps that resource alive and clears the bank before refilling, shrinking or releasing it; resource changes and rendering are serialized.
createSamplerZoneState(arenaSamples, zones, voices) allocates at the caller's capacities (at most 1024 zones, 96 voices, 64 active by default) → the host fills state.arena and declares zones with samplerZoneSetZone (30 fields; returns a rejection code) → samplerZoneStartNote / …StopNote → per block samplerZoneUpdateFilterCoefficients, then samplerZoneRenderFrame(state, bus) per frame leaves the pre-master pair in bus. Clear voices, round robin or params keeps the zones; samplerZoneClearZones drops the bank. Optional entries add AHDSR, one-shot, A/B zone flips, glide, bend, wheel, pressure and sustain.
When to use it
Multisampled instruments and kits with splits, layers, keyswitches, alternate takes and loops.
Limits
- Stereo, sample tick; voices steal oldest-first by serial; zones may route to four buses.
- A voice never ends on a non-zero sample: releases under 3 ms are lengthened to 3 ms, unlooped regions fade over their last 3 ms, reclaimed voices leave through the 5 ms bus bridge; there is no attack floor.