# Sampling and playback

> Author sample instruments with prepared zones, loops, articulations and reusable playback.

Canonical: https://maru.audio/docs/dsp-sampling
Documentation index: https://maru.audio/llms.txt

Maru includes sampler authoring as well as reusable playback DSP. A sample
instrument combines recorded or imported audio with zones, tuning, velocity
layers, articulations, envelopes, presets and an interface. These contracts
let you build a playable instrument rather than a collection of disconnected
file players.

## From authored samples to the audio callback

1. Author the sample mapping and include the source audio and its rights.
2. Let the host load/decode resources and prepare the sample arena and tables.
3. Validate and install a complete resource before using it for playback.
4. Select zones on note events and read the prepared data during processing.
5. Publish the project using its supported delivery path; see the
   [shared .maru format](https://maru.audio/docs/maru-bundle.md).

File selection, decoding, downloads and streaming services belong outside the
realtime reader. The shared `.maru` direction brings sampler and other Processor
artifacts together; the bundle guide explains the current packaging boundary.

## Zone sampler capabilities

`voices/sampler-zone` combines key/velocity ranges, root tuning, source-rate
conversion, per-zone gain/pan, round robin, keyswitches, continuous loops with
crossfades, reverse reads and release-trigger zones. It also supports one-shots,
instrument amplitude envelopes, low-pass shaping, pitch bend, pressure,
mod wheel and sustain behavior through its prepared control contract.

Begin with `createSamplerZoneState`, prepare the arena and declare zones with
`samplerZoneSetZone`. `samplerZoneStartNote` and `samplerZoneStopNote` drive
selection; use the reader’s rendering entry points for your declared layout.
The zone setter rejects unsupported declarations. Streaming libraries,
ping-pong loops, legato-trigger zones and non-low-pass zone filters are outside
this reader’s accepted zone format; expressive legato glide is a separate
instrument behavior.

## Choose a reader or a complete voice

| Goal | Start with | What to prepare |
| --- | --- | --- |
| One oscillator table or one-shot | `tables/sample-reader` | Bounded mono samples and read range. |
| Fine-grained region/loop control | `tables/looped-region` | Loop bounds, reversal and crossfade run-up. |
| Mapped sample instrument | `voices/sampler-zone` | Zone table, sample arena, voice capacity and controls. |
| Morphing pad instrument | `voices/tetra-box` | Pad metadata and up to three prepared clips per pad. |
| Clip or stem transport | `processors/clip-player`, `processors/stem-player` | Prepared planar clips, transport and alignment. |
| Record/overdub loop | `tables/tape-loop` | Bounded recording storage and its fixed virtual-block behavior. |

Use the common velocity, keymap and round-robin helpers when composing a custom
reader. Keep instrument-level envelopes distinct from bank-authored zone data;
do not assume that every envelope field is consumed by every playback mode.
Test source/host rate differences, loop wraps, silent/missing zones, repeated
notes, release tails, choke groups and stealing. These are audible behaviors,
not merely file-format checks.

## Toolkit reference

Import paths below are suffixes of `maruaudio/dsp/`. Use the exported types
and setters in your installed version for complete signatures and defaults.

### Readers and sample voices

| Import suffix | Purpose | Selected API |
| --- | --- | --- |
| `tables/sample-reader` | Bounded mono sample-table reader serving cyclic wavetable playback and one-shot regions with linear interpolation. | `initSampleTableReader`, `sampleTableReaderTick` |
| `tables/looped-region` | Bounded sample-region reads with reversal, continuous-loop crossfades, linear interpolation and split integer/fraction cursor advancement. | `loopedRegionFrameAt`, `advanceLoopedCursor` |
| `tables/tape-loop` | Firmware-derived tape looper with first-pass recording, reverse/forward varispeed, overdub, scrub and reset fades over prepared storage. | `initTapeLoop`, `tapeLoopTick` |
| `voices/tetra-box` | Sixteen-pad sample voice with three-corner morphing, velocity/tuning, one-shots, voice policies and choke groups. Samples are prepared resources. | `createTetraBoxVoice`, `tetraBoxRenderFrame` |
| `voices/sampler-zone` | Zone sampler with key/velocity mapping, round robin, keyswitches, loops, reverse, release triggers, envelopes and low-pass filtering. | `createSamplerZoneState`, `samplerZoneRenderFrame` |
| `voices/round-robin` | Seeded cycle, random and random-cycle take selection, tracked independently for each group and key. | `createRoundRobinState`, `nextRoundRobinKeyTake` |
| `voices/serial-voice-pool` | Up to 64 voice slots: lowest free first, otherwise oldest by serial. The instrument retires stolen voices. | `freeOrOldestVoiceSlot` |
| `voices/keymap` | Key, velocity and keyswitch admission predicates for sample zones and articulations. | `keymapWindowAdmits`, `keyswitchWindowAdmits` |
| `voices/sampler-bus-slot` | Prepared sampler effect-bus table and macro-target encoding; the sampler Processor validates and dispatches it. | `samplerBusBlockFirst`, `samplerBusMacroTarget` |

Return to [DSP fundamentals](https://maru.audio/docs/dsp-fundamentals.md) for I/O, lifecycle,
units and the category map.