Troubleshooting

MIDI Issues

Octave Numbers Don’t Match

Resonon uses scientific pitch notation (C4 = MIDI 60). Ableton Live and some other DAWs display this as C3. This is a display convention difference — the MIDI note numbers are correct.

Resonon	MIDI Note	Ableton Display
C4	60	C3
A4	69	A3
C5	72	C4

No Sound

1. Check MIDI track Monitor is set to In
2. Verify MIDI From shows your port
3. Confirm Track input is enabled in DAW preferences
4. Check an instrument is loaded on the track
5. Verify Resonon is connected: midi_connected();

Port Not Found

1. Run resonon --list-ports to see available ports
2. Verify virtual MIDI is set up (IAC Driver, loopMIDI, etc.)
3. Check the port name matches (partial names work)

Hanging Notes

If notes get stuck:

1. In Resonon: type PAUSE;
2. In Ableton: double-click Stop button (sends all-notes-off)
3. Restart Resonon (exits cleanly, sends note-offs)

Latency

For lowest latency:

• Use a dedicated virtual MIDI port
• Reduce DAW buffer size
• Close other audio applications

Headless Mode

Run without MIDI for testing or development:

resonon --no-midi script.non

The << operator silently does nothing in headless mode. Useful for:

• Testing pattern logic without DAW
• CI/CD pipelines
• Syntax checking

Audio Engine Issues

No Audio Output

No audio output device found

1. Check your system audio output is enabled and a device is selected
2. On macOS, open Audio MIDI Setup and verify an output device is active
3. On Linux, check PulseAudio (pactl info) or PipeWire (wpctl status) is running
4. Close other applications that may have exclusive access to the audio device

Stream Errors

Stream config error: … / Failed to build stream: … / Failed to start stream: …

1. Close other audio applications (DAWs, browsers playing audio)
2. Check your audio device supports the requested sample rate
3. Try a different audio output device
4. Restart Resonon after changing audio hardware

Sample Rate Mismatch

Input sample rate (X) must match output sample rate (Y)

When using audio input, the input and output devices must use the same sample rate.

1. Open your system audio settings
2. Set both input and output devices to the same rate (typically 44100 or 48000)
3. On macOS, use Audio MIDI Setup to verify both rates match

Buffer Size and Latency

If audio crackles or has high latency:

1. Reduce your system audio buffer size (256 or 512 samples is a good starting point)
2. Close other audio applications
3. On macOS, some audio interfaces let you set buffer size in Audio MIDI Setup

Sample and Kit Issues

Sample Not Found

Sample file ‘X’ not found. Searched: [cwd, …]

1. Check the file path — relative paths resolve from your script’s directory
2. Verify the file exists at the expected location
3. Check kit_paths in your configuration if loading from a kit directory
4. Only WAV files are supported — convert other formats first

Failed to Load Sample

Failed to load sample: …

The file was found but couldn’t be read as audio.

1. Re-export as standard PCM WAV (16-bit or 24-bit integer)
2. Compressed formats (MP3, OGG, FLAC) and 32-bit float WAV are not supported
3. Verify the file isn’t corrupted — try playing it in another application

Kit Loading Issues

Failed to load kit ‘X’ into sampler plugin

1. Check kit.toml syntax — a missing comma or bracket will cause a parse failure
2. Verify all sample paths in kit.toml point to existing WAV files
3. Without a kit.toml, WAV files in the kit directory are assigned sequential notes starting from C2

Missing Root Note

Melodic samplers need a root note to pitch samples correctly.

1. Provide the root note explicitly: sampler("piano.wav", root: 60)
2. Or define it in kit.toml under the sample entry
3. Without a root note, the sampler cannot transpose correctly

Plugin Issues

Plugin Not Found

1. Run plugin_scan() first — this scans CLAP directories and builds the plugin cache
2. Check plugin_list() to see what was found
3. Verify your .clap file is in a standard search path:
   • macOS: /Library/Audio/Plug-Ins/CLAP, ~/Library/Audio/Plug-Ins/CLAP, ~/.clap
   • Linux: /usr/lib/clap, /usr/local/lib/clap, ~/.clap
   • Windows: C:\Program Files\Common Files\CLAP
4. Bundled plugins (e.g., the built-in sampler) don’t need scanning — they’re always available

Plugin Won’t Load

If a plugin is listed but fails to load:

1. Verify the plugin architecture matches Resonon’s (e.g., arm64 vs x86_64 on macOS)
2. Check the .clap file isn’t corrupted — re-download or reinstall the plugin
3. Some plugins have dependencies on system libraries — check the plugin vendor’s documentation

Plugin GUI Not Available

Plugin does not support the CLAP GUI extension

Not all CLAP plugins provide a GUI. Bundled plugins (like the built-in sampler) have no GUI.

1. Use .params() to list all plugin parameters
2. Use .set_param(name, value) to control parameters programmatically
3. If a third-party plugin should have a GUI, verify you have the latest version

No Plugin Cache

No plugin cache. Run plugin_scan() first.

The plugin system caches scan results for fast lookups. If the cache doesn’t exist:

1. Run plugin_scan() to scan all CLAP search paths
2. After scanning, plugin_list() will show available plugins
3. You only need to rescan when you install or remove plugins

Common Language Errors

Undefined Function or Method

Undefined function ‘X’

1. Check spelling — function names are case-sensitive
2. Audio effect constructors are part of the prelude and available globally (e.g., Delay, Reverb)
3. Check the functions reference for the correct name

Missing Import

Most “undefined” errors for user modules are caused by a missing use statement. Built-in audio effects (Delay, Reverb, Lowpass, etc.) are part of the prelude and do not require any import.

Type Errors

Expected X, got Y

1. Check argument types — passing a string where a number is expected is common
2. MIDI note values should be integers (e.g., 60, not "60")
3. Pattern values and literal values sometimes need explicit conversion

Argument Count Mismatch

‘X’ expects N arguments, got M

Check the functions reference for the correct signature. Common cases:

• Forgot a required argument
• Passed extra arguments to a method

Index Out of Bounds

Index out of bounds: index N is out of range for length M

Arrays are 0-indexed. An array of length 3 has valid indices 0, 1, 2.

1. Check your index value — use .len() to verify array length
2. For cyclic access, use modulo: arr[i % arr.len()]

Signal and Modulation Gotchas

Zipper Noise

Stepped or abruptly changing signals can cause audible clicks (“zipper noise”) in audio parameters.

Add .smooth(ms) to the signal to apply a one-pole lowpass filter:

lfo.smooth(10)  // 5–20 ms is typical

Pattern and Timing Issues

Events Dropped After Nudge

Events shifted outside the [0, 1) cycle boundary by .nudge() are filtered out. If events seem to disappear:

1. Reduce the nudge offset magnitude
2. Keep offsets well within the cycle range (e.g., ±0.1)

Swing Affects Odd Events Only

This is standard swing behavior — even-indexed events stay on the grid, odd-indexed events shift forward. Swing is sugar for .nudge([0, amount]).

For per-event timing control, use .nudge() with a custom offset pattern instead.

Server Issues

Cannot Connect

1. Verify server is running: resonon server
2. Check port isn’t in use: lsof -i :5555
3. Verify firewall allows connections
4. Try explicit host: resonon server --server-host 127.0.0.1

No Output in VSCode

1. Ensure code uses PRINT or PUT for output
2. Check Output panel in VSCode (select “RESONON”)
3. Verify connection is established (status bar shows connected)

Errors Not Showing

1. Ensure you’re connected to server
2. Check Problems panel in VSCode
3. Try running resonon server with a fresh start

Server Won’t Start

1. Check if port is already in use
2. Try a different port: resonon server --server-port 5556
3. Check for permission issues (binding to 0.0.0.0)

See Also

• DAW Setup — Virtual MIDI and DAW configuration
• VSCode Extension — Server and extension setup
• Samplers — Sample loading, kits, and root notes
• Effects — Audio effect chains and routing
• Plugins — CLAP plugin scanning, loading, and parameters
• Signals & Automation — Signal types, smoothing, and modulation
• Microtiming — Nudge, swing, and humanize
• Audio Input — Live audio input configuration
• Configuration — Kit paths, audio settings, and project config