kit.toml

A kit.toml controls how a kit’s samples are mapped and played. Every section is optional — with no kit.toml, resonon auto-detects WAV files in the directory.

Every path a kit.toml names must be relative, must live under samples/, and must not climb out of the kit with ... Loading a kit that breaks this is an error that names every offending path.

[kit] — metadata

Field	Type	Default	Description
name	String	Directory name	Display name for the kit.
author	String	—	Kit author.
mode	String	"oneshot"	Playback mode: "oneshot" or "melodic".
default_sample	String	Sole sample	Initial sample for SamplerMelodic; required when ambiguous.

Oneshot plays each sample at a fixed pitch — standard for drums. Melodic repitches samples relative to each sample’s root note — use it for tonal instruments.

[defaults] — bulk note mappings

Map sample names to notes in one place instead of repeating note in every entry. Values are note names ("C2", "F#3") or MIDI numbers (36, 42):

[defaults]
bd = "C2"
sd = "D2"
hh = "F#2"

[samples] — per-sample settings

Each key defines a sample:

Field	Type	Default	Description
files	Array of strings	—	WAV paths under samples/ in the kit directory. Multiple files enable round-robin.
note	String or number	Auto-assigned	MIDI note that triggers this sample ("C2" or 36).
root	String or number	—	Root pitch for melodic mode ("C4" or 60).
choke_group	Number	—	Samples sharing a group cut each other off.
velocity	Number	1.0	Default velocity (0.0–1.0).
loop_start	Number	—	Loop start, normalized (0.0–1.0).
loop_end	Number	—	Loop end, normalized (0.0–1.0).

A drum kit with a choke group (the open and closed hats cut each other):

[kit]
name = "Lo-Fi Drums"

[samples]
bd = { files = ["samples/kick.wav"] }
sd = { files = ["samples/snare.wav"], note = "D2" }
hh = { files = ["samples/hihat_closed.wav"], note = "F#2", choke_group = 1 }
hh_open = { files = ["samples/hihat_open.wav"], note = "A#2", choke_group = 1 }

Multiple files per sample give automatic round-robin variation:

[samples]
sd = { files = ["samples/snare_1.wav", "samples/snare_2.wav", "samples/snare_3.wav"], note = "D2" }

A melodic kit repitches relative to each root; use loop points for sustaining sounds:

[kit]
name = "Tape Piano"
mode = "melodic"
default_sample = "piano"

[samples]
piano = { files = ["samples/piano_c4.wav"], root = "C4" }
pad = { files = ["samples/pad_c3.wav"], root = "C3", loop_start = 0.1, loop_end = 0.95 }

SamplerMelodic(Kit("Tape Piano")) loads piano immediately. A melodic kit with exactly one sample may omit default_sample; a kit with several samples must declare it. Each selectable melodic sample names exactly one file—multiple files are round-robin material for the drum sampler. The selected file and its root must be valid when the device is constructed, so broken presets fail with an error instead of producing a silent instrument.

Note Resolution

When a sample has no explicit note, resonon resolves it in order:

1. Explicit note in the [samples] entry.
2. A [defaults] mapping.
3. The GM drum mapping below (by sample name).
4. Sequential assignment from C2 (MIDI 36).

Name	Aliases	Note
bd	kick, bass	C2 (36)
sd	snare	D2 (38)
rs	rim, rimshot	C#2 (37)
hh	hihat, hat, ch	F#2 (42)
hh_open	hihat_open, oh	A#2 (46)
cp	clap	D#2 (39)
lt	tom, tom_low	A2 (45)
mt	tom_mid	B2 (47)
ht	tom_high, tom_hi	D3 (50)
crash	cy	C#3 (49)
ride	—	D#3 (51)
cb	cowbell	G#3 (56)
ma	maracas	A#4 (70)
cl	clave	D#5 (75)
lc	conga_low	E4 (64)
mc	conga_mid	D#4 (63)
hc	conga_high	D4 (62)

With no kit.toml, each .wav becomes a sample named after its filename, notes come from the table above (or sequentially from C2), and the mode defaults to oneshot — so a minimal kit is just a folder of WAV files.