Configuration

Configuration File

Location: ~/.config/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", "~/.config/resonon/lib"]	Library search directories
kit_paths	array of strings	["./kits", "~/.config/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)

[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",
    "~/.config/resonon/lib",
]

kit_paths = [
    "./kits",
    "~/.config/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 (omit for REPL)

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
-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 /usr/local/resonon/.

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

resonon version list
resonon version current
sudo 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_MIDI_PORT	Default MIDI port name

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)

Startup Sequence

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

Directory Structure

Path	Platform	Description
~/.config/resonon/config.toml	all	Configuration file
~/.config/resonon/lib/	all	Default user library directory
~/.config/resonon/kits/	all	Default user kit directory
/usr/local/resonon/	all	Installed versions directory
/usr/local/resonon/current	all	Symlink to the active version
~/Library/Application Support/resonon/plugins/	macOS	Embedded CLAP plugins cache
~/.local/share/resonon/plugins/	Linux	Embedded CLAP plugins cache
%LOCALAPPDATA%\resonon\plugins\	Windows	Embedded CLAP plugins cache
~/Library/Application Support/resonon/clap-cache.json	macOS	CLAP plugin scan cache
~/.local/share/resonon/clap-cache.json	Linux	CLAP plugin scan cache
/Library/Audio/Plug-Ins/CLAP/	macOS	System CLAP plugin directory
~/Library/Audio/Plug-Ins/CLAP/	macOS	User CLAP plugin directory
~/.clap/	macOS, Linux	User CLAP plugin directory
C:\Program Files\Common Files\CLAP\	Windows	System CLAP plugin directory
C:\Program Files (x86)\Common Files\CLAP\	Windows	System CLAP plugin directory (32-bit)
/usr/lib/clap/	Linux	System CLAP plugin directory
/usr/local/lib/clap/	Linux	Local CLAP plugin directory

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