Preferences

This machine’s preferences live in one file, read before any code runs:

~/.resonon/preferences.toml

Every key is optional. With no file, resonon uses the system default devices at their own sample rate and block size. resonon setup writes the file interactively, and reload_preferences() puts a change in force in a running session. Why these settings are data about the machine rather than calls in a piece: The Machine and the Piece.

[audio]
output              = "Focusrite Scarlett 2i2"
input               = "Focusrite Scarlett 2i2"
sample_rate         = 48000
buffer_size         = 256
recording_offset_ms = 2.5

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

[[midi.outputs]]
alias      = "synth"
port       = "Moog Sub 37"
optional   = true
trim_ms    = -2.5
send_clock = true

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

[folders]
kits    = ["~/Music/kits", "/Volumes/Audio/Samples/kits"]
plugins = ["/Volumes/Audio/Plugins"]

[display]
viz_resolution = 48

A key nothing reads, or a value this machine cannot honour, is named at startup and dropped, and the rest of the file is applied. A file that does not parse applies nothing, and says so.

[audio]

Key	Type	Default	What it is
output	String	The system default	Output device, by name. Exact match first, then substring: "Scarlett" finds "Focusrite Scarlett 2i2". Not connected means nothing plays until it is, never a substitute device.
input	String	The system default	Input device, matched the same way. Opened at startup. Not connected means capture stays closed; playback is unaffected.
sample_rate	Whole number	A rate input and output can both run	The whole session’s sample rate in Hz. A rate the device cannot run is named and dropped. Set, it stands: an input that cannot join it is refused.
buffer_size	Whole number	The device’s	Buffer size in frames per block. resonon reports the size the device actually settled on, and says so if it differs.
recording_offset_ms	Number	0	Signed correction in milliseconds on top of the round trip a recorded take is already compensated by. ±500 ms at most.

While a take is recording, reload_preferences() leaves the whole [audio] section alone and says so.

[[midi.outputs]] and [[midi.inputs]]

One entry per port, opened in file order before the first bar of every session.

Outputs

Key	Type	Default	What it is
alias	String	Required	The name pieces use for the port.
port	String	Required	The name the system gives the port.
optional	Boolean	false	The device is not always plugged in: its absence is expected rather than reported as a problem.
trim_ms	Number	0	Moves the port’s notes and clock by this many milliseconds, on top of the automatic alignment. Positive is later.
clock_trim_ms	Number	0	Milliseconds added to clock and transport messages only.
send_clock	Boolean	false	The port receives MIDI clock while set_midi_clock_send(true) is on.

Inputs

Key	Type	Default	What it is
alias	String	Required	The name pieces use for the port.
port	String	Required	The name the system gives the port.
optional	Boolean	false	The device is not always plugged in: its absence is expected rather than reported as a problem.

• A trim is kept to the microsecond and must be within ±500 ms. One further out is named, left at zero, and the port still opens. On an input, the output-only keys are named as keys nothing reads.
• A port whose device is absent keeps its alias. A track pointed at it stays valid, and its events are counted and reported against it by name. reload_preferences() tries an absent device again.
• Moving an alias to another port and reloading closes the old device first, even when the new one is not plugged in.
• Under resonon --no-midi every entry is a reservation: nothing is opened and nothing is sent.

resonon --list-ports prints a paste-ready entry per attached device. Per-port trims in use: Align Hardware with the Mix.

[folders]

Key	Type	Default	What it is
kits	Array of strings	[]	Kit folders, searched after the project’s own. See Home & Search Paths.
plugins	Array of strings	[]	CLAP and VST3 plugin folders, searched as well as the standard ones.

Entries must be absolute. Only a leading ~ or ~/ is expanded, to your home directory (~user is not). An entry naming an environment variable, or a relative one, is reported and left out of the search. A folder that is not there, such as an unmounted drive, is kept. resonon config kits add / remove / list and resonon config plugins … edit these lists without opening the file.

[display]

Key	Type	Default	What it is
viz_resolution	Whole number	24	How wide viz() draws one cycle, in characters (8–64). Pick a multiple of the subdivision you are looking at: 24 shows sixteenths in 4/4, 30 shows triplets.