Sampling and playback
Author sample instruments with prepared zones, loops, articulations and reusable playback.
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
- Author the sample mapping and include the source audio and its rights.
- Let the host load/decode resources and prepare the sample arena and tables.
- Validate and install a complete resource before using it for playback.
- Select zones on note events and read the prepared data during processing.
- Publish the project using its supported delivery path; see the shared .maru format.
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 for I/O, lifecycle, units and the category map.