Configuration

Configuration File

Location: ~/.resonon/config.toml

Paths that begin with ~ are expanded to the user’s home directory.

Top-level Options

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

[audio] Section

Option	Type	Default	Description
output_device	string	system default	Preferred audio output device name
input_device	string	—	Preferred audio input device name (simple form)
sample_rate	integer	device default	Preferred sample rate in Hz
master_channels	array of integers	[0, 1]	Master output channel indices (e.g. [0, 1] for stereo, [0] for mono)
recording_offset_ms	float	0	Global recording latency compensation in ms (trims front of all recordings)
multicore	boolean	false	Render audio across multiple CPU cores. Off by default — the serial path is faster for light projects and average machines. Enable for dense projects on strong machines. Overridden by --multicore and the RESONON_PARALLEL env var.

[audio.input] Section

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

Option	Type	Description
device	string	Input device name (overrides audio.input_device)
channels	table	Named channel mappings — each key maps a name to an array of channel indices

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

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

[midi] Section

Option	Type	Default	Description
output_port	string	—	Default MIDI output port name (partial match supported)
input_port	string	—	Default MIDI input port name

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

Define named MIDI ports for multi-port routing. Each entry requires both fields.

[[midi.outputs]]

Field	Type	Required	Description
alias	string	yes	Name used in code to reference this port
port	string	yes	System MIDI port name (partial match supported)

[[midi.inputs]]

Field	Type	Required	Description
alias	string	yes	Name used in code to reference this port
port	string	yes	System MIDI port name (partial match supported)

[plugins] Section

Control which plugin format (CLAP or VST3) is preferred when both are available.

Option	Type	Default	Description
default_format	"clap" or "vst3"	"clap"	Global default format preference

[plugins.prefer]

Per-plugin format overrides. Keys are plugin display names (case-insensitive), values are "clap" or "vst3".

[plugins]
default_format = "clap"

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

When Effect() or Instrument() loads a plugin, it tries the preferred format first and falls back to the other if not found.

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]

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

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

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

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

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

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

[[midi.inputs]]
alias = "pads"
port = "Akai MPD218"

[plugins]
default_format = "clap"

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

CLI Reference

Main Command

resonon [OPTIONS] [FILE] [COMMAND]

Arguments

Argument	Description
[FILE]	Resonon file to run

Options

Option	Description
-m, --midi-port <NAME>	MIDI port name (partial match supported)
--list-ports	List available MIDI ports and exit
--no-midi	Disable MIDI output
--multicore[=<BOOL>]	Enable multicore (parallel) audio rendering. Bare --multicore or --multicore=true turns it on; --multicore=false off; omit to use the config file / default (off)
-h, --help	Print help
-V, --version	Print version

resonon server

Start the WebSocket server for remote code execution and TUI views.

Option	Default	Description
--server-port <PORT>	5555	WebSocket server port
--server-host <HOST>	0.0.0.0	WebSocket server host address
--server-name <NAME>	hostname	Custom server name for discovery

resonon server --server-port 6000 --server-name "studio"

resonon view <NAME>

Launch a TUI view connected to a running server. Available views: console, midi_monitor, mixer, routing.

Option	Default	Description
<NAME>	—	View name (required)
--port <PORT>	—	Server port (omit for auto-discovery)
--host <HOST>	—	Server host (omit for auto-discovery)
--midi-port <NAME>	—	MIDI input port filter for midi_monitor view (partial match)

resonon view mixer --host 10.0.0.5 --port 5555

resonon version

Manage installed Resonon versions. Versions are stored in ~/.resonon/versions/.

Subcommand	Description
list (default)	List installed versions
current	Print the currently active version
switch <VERSION>	Switch to a different installed version

resonon version list
resonon version current
resonon version switch v0.2.0

resonon pkg

Manage Resonon packages (libraries and kits).

Subcommand	Description
install <SOURCE>	Install a package from a git source (e.g. gh:user/repo)
list	List installed packages
inspect <NAME>	Inspect a package’s exports

resonon pkg install gh:user/my-lib
resonon pkg list
resonon pkg inspect my-lib

resonon plugin

Manage CLAP audio plugins.

Subcommand	Description
scan	Scan CLAP directories and update the plugin cache
list	List discovered CLAP plugins from the cache

resonon plugin scan
resonon plugin list

Environment Variables

Variable	Description
RESONON_HOME	Override the default ~/.resonon/ home directory
RESONON_MIDI_PORT	Default MIDI port name
RESONON_STDLIB_PATH	Override stdlib directory (advanced, for custom installations)
RESONON_PARALLEL	Override the multicore setting (1 = on, anything else = off / kill-switch). Takes precedence over --multicore and the config file
RESONON_SPIN_BUDGET	Worker spin budget before parking (advanced tuning knob)
RESONON_WORKERS	Fixed worker count, bypassing the derived live cap (benchmarking knob)

MIDI Port Resolution Order

The MIDI port is resolved in this order (first match wins):

1. CLI flag (-m, --midi-port)
2. Environment variable (RESONON_MIDI_PORT)
3. Config file ([midi] output_port)

Multicore Resolution Order

Multicore (parallel rendering) is resolved in this order (first match wins):

1. Environment variable (RESONON_PARALLEL) — override / kill-switch
2. CLI flag (--multicore)
3. Config file ([audio] multicore)
4. Default (off — the serial path)

In the VSCode extension this is the Multicore support setting (resonon.audio.multicore), passed to the spawned server as --multicore.

Startup Sequence

1. Initialize logging
2. Migrate legacy config/data to ~/.resonon/ (first run only)
3. Extract embedded CLAP plugins
4. Parse CLI arguments
5. Handle subcommands (view, version, pkg, plugin) — these exit early without MIDI/audio
6. Handle --list-ports — prints available ports and exits
7. Load ~/.resonon/config.toml
8. Initialize audio engine with configured output device
9. Connect MIDI ports (default port + named [[midi.outputs]] entries)
10. Start WebSocket server (if server subcommand) or proceed to step 10
11. Execute the specified file

Directory Structure

All Resonon data lives under ~/.resonon/ (or $RESONON_HOME if set). On Windows this is %USERPROFILE%\.resonon\.

Path	Description
~/.resonon/config.toml	Configuration file
~/.resonon/lib/	Default user library directory
~/.resonon/kits/	Default user kit directory (bundled kits extracted here)
~/.resonon/versions/	Installed versions directory
~/.resonon/versions/current	Symlink to the active version
~/.resonon/plugins/	Embedded CLAP plugins
~/.resonon/cache/clap-cache.json	CLAP plugin scan cache
~/.resonon/cache/vst3-cache.json	VST3 plugin scan cache

System plugin directories (searched for third-party CLAP/VST3 plugins):

Path	Platform
/Library/Audio/Plug-Ins/CLAP/	macOS
~/Library/Audio/Plug-Ins/CLAP/	macOS
~/.clap/	macOS, Linux
C:\Program Files\Common Files\CLAP\	Windows
/usr/lib/clap/, /usr/local/lib/clap/	Linux

See Also

• Package Management — Library and kit installation
• DAW Setup — Connecting Resonon to your DAW
• Plugins — CLAP plugin usage
• Troubleshooting — Common issues and solutions
• Audio Input — Live audio input configuration