Configuration

Resonon reads an optional config.toml at startup. Every setting has a sensible default, so the file is entirely optional — add it only to override defaults like your audio device or MIDI ports.

Location

~/.resonon/config.toml

Set the RESONON_HOME environment variable to relocate the whole ~/.resonon directory (config, libraries, kits, caches). Paths inside the file that begin with ~ expand to your home directory.

Top-Level Options

Option	Type	Default	Description
lib_paths	array of strings	./lib, ./dependencies, ~/.resonon/lib	Library search directories.
kit_paths	array of strings	./kits, ./dependencies/*/kits, ~/.resonon/kits	Sampler kit search directories.
cycle_time	float	—	Default cycle time in seconds.
viz_resolution	integer	—	Default viz resolution (characters per cycle).

When lib_paths / kit_paths are omitted, the defaults above apply. Setting either replaces the default list entirely.

[audio]

Option	Type	Default	Description
output_device	string	system default	Preferred output device name.
input_device	string	—	Preferred input device (simple form).
sample_rate	integer	device default	Preferred sample rate in Hz.
master_channels	array of integers	[0, 1]	Master output channel indices ([0, 1] stereo, [0] mono).
recording_offset_ms	float	—	Latency compensation: trims the front of recordings to align with playback.
multicore	boolean	false	Enable parallel audio rendering. Overridden by --multicore / RESONON_PARALLEL.
plugin_mod_stride	integer	16	Samples between external-plugin automation points. 1 = per-sample.

[audio.input]

Advanced input routing with named channel mappings. If set, input.device overrides the top-level input_device.

[audio.input]
device = "Focusrite Scarlett 2i2"

[audio.input.channels]
mic    = [0]      # mono — channel 0
vocals = [0, 1]   # stereo — channels 0 and 1
guitar = [2]

Each key under [audio.input.channels] maps a name to one or more channel indices (one = mono, two = stereo).

[midi]

Option	Type	Description
output_port	string	Default MIDI output port (partial match).
input_port	string	Default MIDI input port.

[[midi.outputs]] / [[midi.inputs]]

Named ports for multi-port routing. Each entry needs both fields; alias is the name you use in code.

[[midi.outputs]]
alias = "daw"
port  = "IAC Driver Resonon"

[[midi.outputs]]
alias = "synth"
port  = "Moog Sub37"

[[midi.inputs]]
alias = "kb"
port  = "Arturia KeyStep"

[plugins]

Option	Type	Default	Description
default_format	"clap" or "vst3"	"clap"	Preferred format when both are available.

[plugins.prefer]

Per-plugin overrides keyed by display name (case-insensitive):

[plugins]
default_format = "clap"

[plugins.prefer]
"Surge XT" = "vst3"
"Diva"     = "vst3"

When loading a plugin, Resonon tries the preferred format first and falls back to the other.

Complete Example

lib_paths = ["./lib", "~/.resonon/lib"]
kit_paths = ["./kits", "~/.resonon/kits"]

cycle_time = 1.0
viz_resolution = 80

[audio]
output_device = "BlackHole 16ch"
sample_rate = 48000
master_channels = [0, 1]
multicore = true

[audio.input]
device = "Focusrite Scarlett 2i2"

[audio.input.channels]
mic    = [0]
vocals = [0, 1]

[midi]
output_port = "IAC Driver Resonon"
input_port  = "Arturia KeyStep"

[[midi.outputs]]
alias = "daw"
port  = "IAC Driver Resonon"

[plugins]
default_format = "clap"

[plugins.prefer]
"Surge XT" = "vst3"

Directory Layout

Everything Resonon stores per-user lives under ~/.resonon (or $RESONON_HOME):

Path	Description
~/.resonon/config.toml	This configuration file.
~/.resonon/versions/	Installed Resonon versions.
~/.resonon/versions/current	The active version.
~/.resonon/lib/	User library directory.
~/.resonon/kits/	User sampler kit directory.
~/.resonon/plugins/	Embedded CLAP plugins cache.
~/.resonon/cache/clap-cache.json	CLAP plugin scan cache.
~/.resonon/cache/vst3-cache.json	VST3 plugin scan cache.

See Also

• CLI Reference — flags, subcommands, and environment variables
• Plugins — CLAP/VST3 plugin usage
• Recording & Input — live audio input configuration
• Troubleshooting — common issues and fixes