Skip to content
RESONON

std/audio

Always in scope — no import required.

Track routing, instrument and effect hosting, parameter access, recording, events, and the audio-engine functions.

Tracks & Master

Section titled “Tracks & Master”

Audio tracks and the master bus.

AudioTrack is the workhorse of the audio engine: it hosts an instrument, chains effects, sets level and pan, and routes signal onward via sends. Master is the global output bus (master) that every track feeds by default. Construct a track with AudioTrack("name"); the master bus is always present and reached through the global master.

AudioTrack

Section titled “AudioTrack”

A track in the audio engine for sample playback and routing. Construct with AudioTrack("name").

Instruments

Section titled “Instruments”
load_instrument
Section titled “load_instrument”
fn load_instrument(instrument: Instrument or Sampler or SamplerMelodic) -> AudioTrack

Attaches a sampler or instrument to this track.

Parameters:

  • instrument (Instrument | Sampler | SamplerMelodic) — the instrument to attach

Returns: AudioTrack — the track, for chaining

get_instrument
Section titled “get_instrument”
fn get_instrument()

Returns the instrument loaded on this track, or NUL if none.

Returns: Instrument — the loaded instrument, or NUL if none

Effects

Section titled “Effects”
load_effect
Section titled “load_effect”
fn load_effect(effect: Effect) -> AudioTrack

Loads an effect onto this track’s signal chain by slot name. If an effect with the same slot name already exists, it is replaced in-place.

Parameters:

  • effect (Effect) — the effect to load

Returns: AudioTrack — the track, for chaining

load_effects
Section titled “load_effects”
fn load_effects(effects: Array) -> AudioTrack

Loads multiple effects at once (each replaces by slot name).

Parameters:

  • effects (Array) — the effects to load

Returns: AudioTrack — the track, for chaining

effects
Section titled “effects”
fn effects() -> Array

Returns an array of all effects in chain order.

Returns: Array — the effects in chain order

get_effect
Section titled “get_effect”
fn get_effect(name: String) -> Effect

Gets an effect by its slot name.

Parameters:

  • name (String) — slot name of the effect

Returns: Effect — the effect with that slot name

swap_effects
Section titled “swap_effects”
fn swap_effects(i: Number, j: Number) -> AudioTrack

Swaps two effects in the chain by index.

Parameters:

  • i (Number) — first effect index
  • j (Number) — second effect index

Returns: AudioTrack — the track, for chaining

remove_effect
Section titled “remove_effect”
fn remove_effect(index: Number) -> Effect

Removes an effect from the chain by index.

Parameters:

  • index (Number) — position of the effect to remove

Returns: Effect — the removed effect

clear_effects
Section titled “clear_effects”
fn clear_effects() -> AudioTrack

Removes all effects from the chain.

Returns: AudioTrack — the track, for chaining

Mixing

Section titled “Mixing”
volume
Section titled “volume”
fn volume(value: Number) -> AudioTrack

Sets track volume.

Parameters:

  • value (Number) — volume in dB (0 = unity, -70 = mute, +6 = max boost)

Returns: AudioTrack — the track, for chaining

pan
Section titled “pan”
fn pan(value: Number) -> AudioTrack

Sets track pan.

Parameters:

  • value (Number) — pan position (-1.0 = hard left, 0.0 = center, 1.0 = hard right)

Returns: AudioTrack — the track, for chaining

Routing & sends

Section titled “Routing & sends”
send_to
Section titled “send_to”
fn send_to(destination: AudioTrack, amount: Number) -> AudioTrack

Adds a parallel aux send to the given destination.

Parameters:

  • destination (AudioTrack) — target track or bus
  • amount (Number) — send level (0.0-1.0)

Returns: AudioTrack — the track, for chaining

xsend_to
Section titled “xsend_to”
fn xsend_to(destination: AudioTrack, amount: Number) -> AudioTrack

Crossfade send: routes audio with energy conservation. wet = amount, dry (master) = 1.0 - amount.

Parameters:

  • destination (AudioTrack) — target track or bus
  • amount (Number) — crossfade amount (0.0-1.0)

Returns: AudioTrack — the track, for chaining

send
Section titled “send”
fn send(amount: Number)

Returns a SendModifier for use with the >> operator.

Parameters:

  • amount (Number) — send level (0.0-1.0)

Returns: SendModifier — a send modifier usable with >>

routing
Section titled “routing”
fn routing() -> NUL

Displays detailed routing info for this track. Shows instrument, effects, volume/pan, receives, and routes.

Returns: NUL — nothing; prints the routing

send_level
Section titled “send_level”
fn send_level(target: AudioTrack) -> Number

Returns the send level to the given destination track.

Parameters:

  • target (AudioTrack) — destination track

Returns: Number — the send level to target

reset_routing
Section titled “reset_routing”
fn reset_routing() -> AudioTrack

Resets all routing (sends, receives, input) on this track.

Returns: AudioTrack — the track, for chaining

Recording & input

Section titled “Recording & input”
input
Section titled “input”
fn input(source: String) -> AudioTrack

Sets the audio input source for monitoring and recording. Connects the named hardware input to this track. If no audio input stream is active, starts one automatically for the named device.

Parameters:

  • source (String) — input device or channel name (e.g. “MacBook Pro Microphone”)

Returns: AudioTrack — the track, for chaining

arm
Section titled “arm”
fn arm() -> AudioTrack

Arms the track for recording. The track must have an input source set via input() first.

Returns: AudioTrack — the track, for chaining

disarm
Section titled “disarm”
fn disarm() -> AudioTrack

Disarms the track, stopping recording.

Returns: AudioTrack — the track, for chaining

monitor
Section titled “monitor”
fn monitor(mode: String) -> AudioTrack

Sets the input monitoring mode.

Parameters:

  • mode (String) — “off” (no monitoring), “in” (always monitor), or “auto” (monitor when armed)

Returns: AudioTrack — the track, for chaining

take
Section titled “take”
fn take() -> RecordedAudio

Retrieves the most recent recording as a RecordedAudio value.

Returns: RecordedAudio — the latest recording, or NUL if none has been made

save
Section titled “save”
fn save(path: String) -> AudioTrack

Saves the track’s audio to a file.

Parameters:

  • path (String) — output file path

Returns: AudioTrack — the track, for chaining

Punch recording

Section titled “Punch recording”
punch
Section titled “punch”
fn punch(in_cycle: Number, out_cycle: Number) -> AudioTrack

Sets punch-in and punch-out points for time-bounded recording. Recording activates at in_cycle and deactivates at out_cycle.

Parameters:

  • in_cycle (Number) — cycle at which recording starts
  • out_cycle (Number) — cycle at which recording stops

Returns: AudioTrack — the track, for chaining

punch_in
Section titled “punch_in”
fn punch_in(cycle: Number) -> AudioTrack

Sets only the punch-in point. Recording starts at the given cycle and continues until manually stopped.

Parameters:

  • cycle (Number) — cycle at which recording starts

Returns: AudioTrack — the track, for chaining

punch_out
Section titled “punch_out”
fn punch_out(cycle: Number) -> AudioTrack

Sets only the punch-out point. Recording starts immediately with RECORD and stops at the given cycle.

Parameters:

  • cycle (Number) — cycle at which recording stops

Returns: AudioTrack — the track, for chaining

clear_punch
Section titled “clear_punch”
fn clear_punch() -> AudioTrack

Clears all punch points from this track.

Returns: AudioTrack — the track, for chaining

is_punched
Section titled “is_punched”
fn is_punched() -> Boolean

Returns true if this track has punch points configured.

Returns: Boolean — true if punch points are configured

Expression

Section titled “Expression”
velocity
Section titled “velocity”
fn velocity(vel: Number or Signal or Pattern) -> AudioTrack

Sets the velocity for notes played on this track.

Parameters:

  • vel (Number | Signal | Pattern) — velocity value, signal, or pattern

Returns: AudioTrack — the track, for chaining

tuning
Section titled “tuning”
fn tuning(bend_range: Number?) -> AudioTrack

Enable microtonal pitch bend output. Uses the MIDI default ±2 semitone range (works with any synth).

Example:

track.tuning(), track.tuning(48)

Parameters:

  • bend_range (Number) — pitch-bend range in semitones (optional; default ±2)

Returns: AudioTrack — the track, for chaining

mpe
Section titled “mpe”
fn mpe(range: Number?, zone_lo: Number?, zone_hi: Number?) -> AudioTrack

Enable MPE (per-note channel allocation) for polyphonic microtonal output.

Example:

track.mpe(), track.mpe(24), track.mpe(48, 2, 9)

Parameters:

  • range (Number) — pitch-bend range in semitones (optional, defaults to 48)
  • zone_lo (Number) — low member channel (optional, defaults to 2)
  • zone_hi (Number) — high member channel (optional, defaults to 16)

Returns: AudioTrack — the track, for chaining

key
Section titled “key”
fn key(scale: Key or String or Scale, root: Note or Number?) -> AudioTrack

Set a track-level key for degree resolution and auto-quantization. Degrees (^1, ^2, …) resolve from this key without .in_key(), and absolute notes are quantized to the nearest scale tone. Pass a Key value, or a scale name/Scale with a root note.

Example:

track.key(Key(C4, "major")) or track.key("major", C4)

Parameters:

  • scale (Key | String | Scale) — a Key value, or a scale name/Scale value
  • root (Note | Number) — root note (e.g. C4 or a MIDI number); omit when passing a Key

Returns: AudioTrack — the track, for chaining

Lifecycle

Section titled “Lifecycle”
delete
Section titled “delete”
fn delete() -> NUL

Deletes the track and releases its resources.

Returns: NUL — nothing

Master

Section titled “Master”

The master output bus. Always present, cannot be deleted. Has its own effect chain and fader (volume/pan). Access via the global master variable.

load_effect

Section titled “load_effect”
fn load_effect(effect: Effect) -> Master

Loads an effect onto the master bus by slot name. If an effect with the same slot name already exists, it is replaced in-place.

Parameters:

  • effect (Effect) — the effect to load

Returns: Master — the master bus, for chaining

load_effects

Section titled “load_effects”
fn load_effects(effects: Array) -> Master

Loads multiple effects at once (each replaces by slot name).

Parameters:

  • effects (Array) — the effects to load

Returns: Master — the master bus, for chaining

effects

Section titled “effects”
fn effects() -> Array

Returns an array of all effects in chain order.

Returns: Array — the effects in chain order

get_effect

Section titled “get_effect”
fn get_effect(name: String) -> Effect

Gets an effect by its slot name.

Parameters:

  • name (String) — slot name of the effect

Returns: Effect — the effect with that slot name

swap_effects

Section titled “swap_effects”
fn swap_effects(i: Number, j: Number) -> Master

Swaps two effects in the chain by index.

Parameters:

  • i (Number) — first effect index
  • j (Number) — second effect index

Returns: Master — the master bus, for chaining

remove_effect

Section titled “remove_effect”
fn remove_effect(index: Number) -> Effect

Removes an effect from the chain by index.

Parameters:

  • index (Number) — position of the effect to remove

Returns: Effect — the removed effect

clear_effects

Section titled “clear_effects”
fn clear_effects() -> Master

Removes all effects from the chain.

Returns: Master — the master bus, for chaining

volume

Section titled “volume”
fn volume(value: Number) -> Master

Sets master volume. Clears any existing volume modulation.

Parameters:

  • value (Number) — volume in dB (0 = unity, -70 = mute, +6 = max boost)

Returns: Master — the master bus, for chaining

pan

Section titled “pan”
fn pan(value: Number) -> Master

Sets master pan. Clears any existing pan modulation.

Parameters:

  • value (Number) — pan position (-1.0 = hard left, 0.0 = center, 1.0 = hard right)

Returns: Master — the master bus, for chaining

Parameters

Section titled “Parameters”

Parameter list and parameter-reference types.

Wrap .params() output and reference individual plugin, track, and master parameters for reading and automation.

EffectParam

Section titled “EffectParam”

A reference to a single effect parameter, obtained via .param("name"). Supports .get(), .set(), .set_norm() and modulation via <<.

get

Section titled “get”
fn get() -> Number

Gets the current value of this parameter.

delay.param("Time").get();  // => 0.25

Returns: Number — the current value in the parameter’s native range

set

Section titled “set”
fn set(args: unknown) -> EffectParam

Sets this parameter’s value.

Accepts a Number (static set), Signal (modulation), or breakpoint arrays (automation lane).

delay.param("Time").set(0.5);
delay.param("Time").set(Sine(4).range(0.1, 0.8));
delay.param("Time").set(#[0, 200], #[4, 4000]);

Parameters:

  • value... — Number, Signal, or variadic [beat, value] breakpoint arrays

Returns: EffectParam — this reference, for chaining

set_norm

Section titled “set_norm”
fn set_norm(value: Number) -> EffectParam

Sets this parameter using a normalized [0,1] value.

delay.param("Time").set_norm(0.5);

Parameters:

  • value (Number) — 0.0 = minimum, 1.0 = maximum

Returns: EffectParam — this reference, for chaining

InstrumentParam

Section titled “InstrumentParam”

A reference to a single instrument parameter, obtained via .param("name"). Supports .get(), .set(), .set_norm() and modulation via <<.

get

Section titled “get”
fn get() -> Number

Gets the current value of this parameter.

Returns: Number — the current value in the parameter’s native range

set

Section titled “set”
fn set(args: unknown) -> InstrumentParam

Sets this parameter’s value.

Accepts a Number (static set), Signal (modulation), or breakpoint arrays (automation lane).

Parameters:

  • value... — Number, Signal, or variadic [beat, value] breakpoint arrays

Returns: InstrumentParam — this reference, for chaining

set_norm

Section titled “set_norm”
fn set_norm(value: Number) -> InstrumentParam

Sets this parameter using a normalized [0,1] value.

Parameters:

  • value (Number) — 0.0 = minimum, 1.0 = maximum

Returns: InstrumentParam — this reference, for chaining

MasterParam

Section titled “MasterParam”

A reference to the master bus fader parameter, obtained via master.volume or master.pan. Supports .get(), .set(), .set_norm() and modulation via <<.

get

Section titled “get”
fn get() -> Number

Gets the current master fader value.

master.volume.get();  // => 0.0
master.pan.get();     // => 0.0

Returns: Number — volume in dB (0 = unity, -70 = mute), or pan (-1.0 to 1.0)

set

Section titled “set”
fn set(args: unknown) -> MasterParam

Sets this master fader’s value.

Accepts a Number (static set), Signal (modulation), Pattern (converted to modulation signal), or breakpoint arrays (automation lane).

master.volume.set(-6);
master.pan.set(Sine(2).range(-0.5, 0.5));
master.volume.set(#[0, -12], #[4, 0]);

Parameters:

  • value... — Number, Signal, Pattern, or variadic [beat, value] breakpoint arrays

Returns: MasterParam — this reference, for chaining

set_norm

Section titled “set_norm”
fn set_norm(value: Number) -> MasterParam

Sets this master fader using a normalized [0,1] value.

Volume: 0.0 = -70 dB (mute), 1.0 = +6 dB (max boost). Pan: 0.0 = hard left, 0.5 = center, 1.0 = hard right.

master.volume.set_norm(0.5);

Parameters:

  • value (Number) — 0.0 = minimum, 1.0 = maximum

Returns: MasterParam — this reference, for chaining

ParamList

Section titled “ParamList”

Wraps an array of parameter dicts from .params(). Prints as an aligned table; provides .data for programmatic access.

filter

Section titled “filter”
fn filter(name: String) -> ParamList

Filters parameters by name substring, returns a new ParamList.

Parameters:

  • name (String) — substring to match against parameter names

Returns: ParamList — a new list of the matching parameters

length

Section titled “length”
fn length() -> Number

Returns the number of parameters.

Returns: Number — the parameter count

get

Section titled “get”
fn get(index: Number) -> Dict

Returns the parameter dict at the given index.

Parameters:

  • index (Number) — zero-based position

Returns: Dict — the parameter entry at index

TrackParam

Section titled “TrackParam”

A reference to an audio track’s fader parameter, obtained via track.volume or track.pan. Supports .get(), .set(), .set_norm() and modulation via <<.

get

Section titled “get”
fn get() -> Number

Gets the current fader value.

track.volume.get();  // => 0.0
track.pan.get();     // => 0.0

Returns: Number — volume in dB (0 = unity, -70 = mute), or pan (-1.0 to 1.0)

set

Section titled “set”
fn set(args: unknown) -> TrackParam

Sets this fader’s value.

Accepts a Number (static set), Signal (modulation), Pattern (converted to modulation signal), or breakpoint arrays (automation lane).

track.volume.set(-6);
track.pan.set(Sine(2).range(-0.5, 0.5));
track.volume.set(#[0, -12], #[4, 0]);

Parameters:

  • value... — Number, Signal, Pattern, or variadic [beat, value] breakpoint arrays

Returns: TrackParam — this reference, for chaining

set_norm

Section titled “set_norm”
fn set_norm(value: Number) -> TrackParam

Sets this fader using a normalized [0,1] value.

Volume: 0.0 = -70 dB (mute), 1.0 = +6 dB (max boost). Pan: 0.0 = hard left, 0.5 = center, 1.0 = hard right.

track.volume.set_norm(0.5);

Parameters:

  • value (Number) — 0.0 = minimum, 1.0 = maximum

Returns: TrackParam — this reference, for chaining

Plugins

Section titled “Plugins”

Plugin type classes and loaders.

Wrap plugin parameter access and scan results; load CLAP and VST3 plugins as instruments or effects.

Effect

Section titled “Effect”

An audio effect processor.

Unified type wrapping three backends:

  • Built-in DSP — created via constructors like Delay(), Lowpass(), or dsp effect blocks. Processing runs as compiled bytecode.
  • CLAP plugin — loaded via Effect("name") when a CLAP bundle is found.
  • VST3 plugin — loaded via Effect("name") when a VST3 bundle is found (or when CLAP is unavailable and VST3 is).

All backends support parameter access, state save/load, and can be loaded onto audio tracks and the master bus. GUI and program methods are backend-specific and emit warnings when called on unsupported backends.

Effects carry a slot name (set via set_name() or assigned automatically from the plugin name). When loaded onto a track with load_effect(), effects with the same slot name replace each other in-place rather than accumulating — this makes re-execution idempotent.

let fx = Effect("ValhallaRoom");
fx.param_set("Mix", 0.3);
drums.load_effect(fx);


let delay = Delay(0.25, 0.5);
drums.load_effect(delay);

Constructor

Section titled “Constructor”
fn Effect(name: String, plugin_id: String = NUL) -> Effect

Loads an effect plugin (CLAP or VST3). Searches CLAP plugins first, then VST3. File extensions are added automatically.

Parameters:

  • name (String) — plugin name or full path (e.g. “Valhalla Room”)
  • plugin_id (String) — plugin ID, auto-detected if only one plugin in bundle (optional)

Returns: Effect — the loaded effect plugin

Identity

Section titled “Identity”
name
Section titled “name”
fn name() -> String

Returns the slot name of this effect.

For external plugins this defaults to the plugin’s display name. For built-in effects it defaults to the constructor name (e.g. “Delay”). Can be changed with set_name().

Backends: all.

Delay().name();            // => "Delay"
Effect("ValhallaRoom").name();  // => "ValhallaRoom"

Returns: String — the effect’s slot name

set_name
Section titled “set_name”
fn set_name(name: String) -> Effect

Sets the slot name used for idempotent loading.

When an effect is loaded onto a track or master with load_effect(), the slot name determines identity: effects with the same slot name replace each other in-place (preserving chain position) rather than accumulating. This makes re-execution idempotent.

Backends: all.

Delay(0.25).set_name("echo");
drums.load_effect(Delay(0.5).set_name("echo"));  // replaces, not duplicates

Parameters:

  • name (String) — the new slot name

Returns: Effect — a new Effect value with the updated slot name

backend
Section titled “backend”
fn backend() -> String

Returns the plugin backend type (“CLAP”, “VST3”, or “built-in”).

Returns: String — the backend type

Parameters

Section titled “Parameters”
param
Section titled “param”
fn param(name: String) -> EffectParam

Returns a parameter reference for the named parameter.

Uses fuzzy case-insensitive matching: exact path first, then substring match on path and display name. Use .get(), .set(), .set_norm() on the returned reference, or pipe it with << for modulation.

Backends: all.

let d = Delay(0.25, 0.5);
d.param("Time").get();    // => 0.25
d.param("Time").set(0.5); // set to 0.5
d.param("Time") << Sine(2).range(0.1, 0.8);

Parameters:

  • name (String) — parameter name (e.g. “Room”, “Mix”, “Cutoff”)

Returns: EffectParam — a parameter reference with .get(), .set(), .set_norm() methods Errors: RuntimeError — if no parameter matches or match is ambiguous

param_get
Section titled “param_get”
fn param_get(name: String) -> Number

Gets the current value of a parameter by name (shorthand).

Equivalent to .param(name).get(). Returns the value in the parameter’s native range (not normalized).

Backends: all.

let d = Delay(0.25, 0.5);
d.param_get("Time");       // => 0.25
d.param_get("Feedback");   // => 0.5

Parameters:

  • name (String) — parameter name (e.g. “Room”, “Mix”, “Cutoff”)

Returns: Number — the current parameter value in its native range Errors: RuntimeError — if no parameter with the given name exists

param_set
Section titled “param_set”
fn param_set(name: String, value: Number) -> Effect

Sets a parameter value by name in its native range.

The value is clamped to the parameter’s declared range. For normalized [0,1] input use param_set_norm() instead.

Backends: all.

Delay().param_set("Time", 0.8).param_set("Feedback", 0.3);

Parameters:

  • name (String) — parameter name (e.g. “Room”, “Mix”)
  • value (Number) — new value in the parameter’s native range

Returns: Effect — this, for method chaining Errors: RuntimeError — if no parameter with the given name exists

param_set_norm
Section titled “param_set_norm”
fn param_set_norm(name: String, value: Number) -> Effect

Sets a parameter value using a normalized [0,1] input.

The normalized value is mapped to the parameter’s native range: actual = min + normalized * (max - min).

Backends: all.

fx.param_set_norm("Mix", 0.5);  // set Mix to midpoint of its range

Parameters:

  • name (String) — parameter name (e.g. “Room”, “Mix”)
  • value (Number) — normalized value (0.0 = minimum, 1.0 = maximum)

Returns: Effect — this, for method chaining Errors: RuntimeError — if no parameter with the given name exists

params
Section titled “params”
fn params(filter: String?) -> ParamList

Returns a ParamList of all effect parameters.

Prints as a formatted table (headed by the effect name and backend) with columns Parameter, Value, Range, Default. Use .data for the raw array of dicts; each entry has name, value, min, max, default, group, path, and step.

Backends: all.

fx.params();          // all parameters
fx.params("freq");    // only parameters containing "freq"
fx.params().data;     // raw array of parameter dicts

Parameters:

  • filter (String) — only include parameters whose name contains this substring (optional)

Returns: ParamList — parameter data (columns: Parameter, Value, Range, Default)

Presets & state

Section titled “Presets & state”
save_state
Section titled “save_state”
fn save_state(path: String) -> Effect

Saves the effect’s state to a preset file.

For CLAP/VST3 plugins, saves the full binary plugin state (includes all internal state beyond just parameter values). For built-in DSP effects, saves parameter values only.

The file format is a Resonon preset file (.preset extension recommended).

Backends: all.

fx.save_state("presets/warm_reverb.preset");

Parameters:

  • path (String) — file path for the preset

Returns: Effect — this, for method chaining

load_state
Section titled “load_state”
fn load_state(path: String) -> Effect

Loads a preset file into the effect.

Restores the effect’s state from a file previously created by save_state(). The preset’s plugin name must match this effect’s plugin name.

Backends: all.

fx.load_state("presets/warm_reverb.preset");

Parameters:

  • path (String) — file path of the preset to load

Returns: Effect — this, for method chaining Errors: RuntimeError — if the file doesn’t exist or the plugin name mismatches

programs
Section titled “programs”
fn programs() -> Array

Lists all program/preset names built into the plugin.

Only VST3 plugins expose factory programs. For CLAP and built-in DSP effects, prints a warning and returns an empty array.

Backends: VST3. Warns on CLAP, DSP.

let fx = Effect("Diva");
fx.programs();  // => #["Init", "Juno Saw", "Warm Pad", ...]

Returns: Array — array of program name strings, e.g. #["Init", "Warm", "Bright"]

set_program
Section titled “set_program”
fn set_program(index: Number) -> Effect

Selects a factory program/preset by index.

Only VST3 plugins support program selection. For CLAP and built-in DSP effects, prints a warning and returns the effect unchanged.

Backends: VST3. Warns on CLAP, DSP.

let fx = Effect("Diva");
fx.set_program(2);  // select the third factory preset

Parameters:

  • index (Number) — zero-based program index

Returns: Effect — this, for method chaining Errors: RuntimeError — if the index is out of range (VST3 only)

GUI

Section titled “GUI”
supports_gui
Section titled “supports_gui”
fn supports_gui() -> Boolean

Returns whether this effect supports a graphical user interface.

Built-in DSP effects always return false. CLAP and VST3 plugins return true if the plugin provides a GUI.

Backends: all (DSP always returns false).

Delay().supports_gui();           // => false
Effect("ValhallaRoom").supports_gui();  // => true

Returns: Boolean — true if show_gui() will open a window

show_gui
Section titled “show_gui”
fn show_gui() -> NUL

Opens the plugin GUI window.

For CLAP/VST3 plugins with GUI support, opens the plugin’s native editor window. For built-in DSP effects, prints a warning and returns NUL (no error).

Backends: CLAP, VST3. Warns on DSP.

let fx = Effect("ValhallaRoom");
fx.show_gui();

Returns: NUL Errors: RuntimeError — if the plugin does not support GUI (CLAP/VST3 only) RuntimeError — if running in headless mode

hide_gui
Section titled “hide_gui”
fn hide_gui() -> NUL

Closes the plugin GUI window.

For CLAP/VST3 plugins, closes the native editor window if open. For built-in DSP effects, prints a warning and returns NUL.

Backends: CLAP, VST3. Warns on DSP.

fx.hide_gui();

Returns: NUL

Routing

Section titled “Routing”
connect_input
Section titled “connect_input”
fn connect_input(name: String, source: AudioTrack) -> Effect

Connects a named sidechain input port to a source audio track.

Some effects (e.g. compressors) have sidechain input ports that accept audio from another track. This method sets up that routing in the audio graph. The source track must be processed before the effect’s track (enforced by topological sort).

Backends: CLAP, VST3 (DSP effects typically have no sidechain ports).

let comp = Effect("TDR Kotelnikov");
comp.connect_input("sidechain", kick_track);
bass.load_effect(comp);

Parameters:

  • name (String) — the sidechain input port name (e.g. “sidechain”)
  • source (AudioTrack) — the track whose output feeds this port

Returns: Effect — this, for method chaining Errors: RuntimeError — if the effect has no port with the given name

Instrument

Section titled “Instrument”

Type class for Instrument values — wraps .params() in ParamList.

Constructor

Section titled “Constructor”
fn Instrument(name: String, plugin_id: String = NUL) -> Instrument

Loads an instrument plugin (CLAP or VST3). Searches CLAP plugins first, then VST3. File extensions are added automatically.

Parameters:

  • name (String) — plugin name or full path (e.g. “Surge XT”)
  • plugin_id (String) — plugin ID, auto-detected if only one plugin in bundle (optional)

Returns: Instrument — the loaded instrument plugin

Identity

Section titled “Identity”
name
Section titled “name”
fn name() -> String

Returns the instrument name.

Returns: String — the instrument name

backend
Section titled “backend”
fn backend() -> String

Returns the plugin backend type (“CLAP”, “VST3”, or “built-in”).

Returns: String — the backend type

set_name
Section titled “set_name”
fn set_name(name: String) -> Instrument

Renames the instrument’s slot name.

Parameters:

  • name (String) — new slot name

Returns: Instrument — a new instrument with the updated name

Parameters

Section titled “Parameters”
param
Section titled “param”
fn param(name: String) -> InstrumentParam

Returns a parameter reference by name.

Parameters:

  • name (String) — parameter name (e.g. “Cutoff”, “Mix”, “gain”)

Returns: InstrumentParam — a parameter reference with .get(), .set(), .set_norm()

param_get
Section titled “param_get”
fn param_get(name: String) -> Number

Gets a parameter value by name (shorthand for .param(name).get()).

Parameters:

  • name (String) — parameter name (e.g. “Cutoff”, “Mix”, “gain”)

Returns: Number — the current parameter value

param_set
Section titled “param_set”
fn param_set(name: String, value: Number) -> Instrument

Sets a parameter value by name.

Parameters:

  • name (String) — parameter name (e.g. “Cutoff”, “Mix”)
  • value (Number) — new value in the parameter’s native range

Returns: Instrument — the instrument, for chaining

param_set_norm
Section titled “param_set_norm”
fn param_set_norm(name: String, value: Number) -> Instrument

Sets a parameter value using a normalized [0,1] input.

Parameters:

  • name (String) — parameter name (e.g. “Cutoff”, “Mix”)
  • value (Number) — normalized value (0.0 to 1.0)

Returns: Instrument — the instrument, for chaining

params
Section titled “params”
fn params(filter: String?) -> ParamList

Returns a ParamList of all instrument parameters.

Prints as a formatted table (headed by the instrument name and backend) with columns Parameter, Value, Range, Default. Use .data for the raw array of dicts; each entry has name, value, min, max, default, group, path, and step.

Backends: all.

inst.params();          // all parameters
inst.params("freq");    // only parameters containing "freq"
inst.params().data;     // raw array of parameter dicts

Parameters:

  • filter (String) — only include parameters whose name contains this substring (optional)

Returns: ParamList — parameter data (columns: Parameter, Value, Range, Default)

Presets & state

Section titled “Presets & state”
save_state
Section titled “save_state”
fn save_state(path: String) -> Instrument

Saves the plugin state to a preset file.

Parameters:

  • path (String) — file path for the preset

Returns: Instrument — the instrument, for chaining

load_state
Section titled “load_state”
fn load_state(path: String) -> Instrument

Loads a preset file into the plugin.

Parameters:

  • path (String) — file path of the preset to load

Returns: Instrument — the instrument, for chaining

programs
Section titled “programs”
fn programs() -> Array

Returns the list of plugin program names.

Returns: Array — the program names as Strings

set_program
Section titled “set_program”
fn set_program(index: Number) -> Instrument

Switches to a program by index.

Parameters:

  • index (Number) — program index

Returns: Instrument — the instrument, for chaining

GUI

Section titled “GUI”
supports_gui
Section titled “supports_gui”
fn supports_gui() -> Boolean

Returns true if the plugin supports a GUI window.

Returns: Boolean — true if a GUI window is supported

show_gui
Section titled “show_gui”
fn show_gui() -> NUL

Opens the plugin GUI window.

Returns: NUL — nothing

hide_gui
Section titled “hide_gui”
fn hide_gui() -> NUL

Closes the plugin GUI window.

Returns: NUL — nothing

PluginList

Section titled “PluginList”

Wraps an array of plugin dicts from plugin_scan(). Prints as an aligned table; provides .data for programmatic access.

filter

Section titled “filter”
fn filter(name: String) -> PluginList

Filters plugins by name substring, returns a new PluginList.

Parameters:

  • name (String) — substring to match against plugin names

Returns: PluginList — a new list of the matching plugins

length

Section titled “length”
fn length() -> Number

Returns the number of plugins.

Returns: Number — the plugin count

get

Section titled “get”
fn get(index: Number) -> Dict

Returns the plugin dict at the given index.

Parameters:

  • index (Number) — zero-based position

Returns: Dict — the plugin entry at index

Recording

Section titled “Recording”

The RecordedAudio type: captured audio.

RecordedAudio holds the audio captured by audio_record(). Use it to inspect the take — its duration and sample data — and to save it out to a WAV file.

RecordedAudio

Section titled “RecordedAudio”

Captured audio data from audio_record(). Provides methods to inspect and save recorded audio.

save

Section titled “save”
fn save(path: String) -> RecordedAudio

Saves the recording to a WAV file.

Parameters:

  • path (String) — output file path

Returns: RecordedAudio — this, for method chaining

duration

Section titled “duration”
fn duration() -> Number

Returns the duration of the recording in seconds.

Returns: Number — the duration in seconds

samples

Section titled “samples”
fn samples() -> Number

Returns the total number of samples in the recording.

Returns: Number — the total sample count

sample_rate

Section titled “sample_rate”
fn sample_rate() -> Number

Returns the sample rate of the recording.

Returns: Number — the sample rate in Hz

left

Section titled “left”
fn left() -> Array

Returns the left channel as an array of sample values.

Returns: Array — the left-channel sample values

Section titled “right”
fn right() -> Array

Returns the right channel as an array of sample values.

Returns: Array — the right-channel sample values

mono

Section titled “mono”
fn mono() -> Array

Returns a mono mixdown as an array of sample values.

Returns: Array — the mono mixdown sample values

Events

Section titled “Events”

The Event type: one note from a pattern.

An Event is a single MIDI event — note, velocity, channel, and timing — yielded when a pattern is iterated or queried. Read its fields to inspect or react to what a pattern will play.

Event

Section titled “Event”

A single MIDI event with note, velocity, timing, and channel. Obtained from pattern iterators or event queries.

note

Section titled “note”
fn note() -> Number

Returns the MIDI note number.

Returns: Number — the MIDI note number

velocity

Section titled “velocity”
fn velocity() -> Number

Returns the velocity (0-127).

Returns: Number — the velocity (0-127)

channel

Section titled “channel”
fn channel() -> Number

Returns the MIDI channel.

Returns: Number — the MIDI channel

start

Section titled “start”
fn start() -> Number

Returns the start time in cycles.

Returns: Number — the start time in cycles

duration

Section titled “duration”
fn duration() -> Number

Returns the duration in cycles.

Returns: Number — the duration in cycles

end

Section titled “end”
fn end() -> Number

Returns the end time (start + duration).

Returns: Number — the end time in cycles (start + duration)

transpose

Section titled “transpose”
fn transpose(semitones: Number) -> Event

Returns a new event transposed by the given number of semitones.

Parameters:

  • semitones (Number) — semitone offset (positive = up, negative = down)

Returns: Event — a new transposed event

detune

Section titled “detune”
fn detune(cents: Number) -> Event

Returns a new event detuned by the given number of cents (100 = one semitone).

Parameters:

  • cents (Number) — cent offset (positive = up, negative = down)

Returns: Event — a new detuned event

ratio

Section titled “ratio”
fn ratio(ratio: Number) -> Event

Returns a new event with its note’s frequency scaled by the given ratio. Multiplying frequency by ratio adds 12*log2(ratio) semitones; ratio must be > 0.

Parameters:

  • ratio (Number) — frequency ratio (must be > 0)

Returns: Event — a new event with the scaled note

Notes

Section titled “Notes”

The Note type: a single pitched value.

A Note is a MIDI pitch in semitones (fractional for microtonal pitches). These methods are discoverable aliases for the pitch arithmetic also expressible with the +/* operators, mirroring the equivalents on Event.

Note

Section titled “Note”

A single MIDI pitch in semitones, fractional for microtonal values.

transpose

Section titled “transpose”
fn transpose(semitones: Number) -> Note

Returns a new note transposed by the given number of semitones. Fractional semitones are preserved.

Parameters:

  • semitones (Number) — semitone offset (positive = up, negative = down)

Returns: Note — a new transposed note

detune

Section titled “detune”
fn detune(cents: Number) -> Note

Returns a new note detuned by the given number of cents (100 = one semitone).

Parameters:

  • cents (Number) — cent offset (positive = up, negative = down)

Returns: Note — a new detuned note

ratio

Section titled “ratio”
fn ratio(ratio: Number) -> Note

Returns a new note with its frequency scaled by the given ratio. Multiplying frequency by ratio adds 12*log2(ratio) semitones; ratio must be > 0.

Parameters:

  • ratio (Number) — frequency ratio (must be > 0)

Returns: Note — a new note scaled by the ratio

Audio I/O

Section titled “Audio I/O”

Audio engine functions: track/timeline construction, rendering, tempo, recording, device routing, project metadata, and scope visualization.

AudioTrack

Section titled “AudioTrack”
fn AudioTrack(name: String = NUL) -> AudioTrack

Creates an audio track for sample playback, optionally named.

Example:

AudioTrack(), AudioTrack("drums")

Parameters:

  • name (String) — track name (optional; omit for an unnamed track)

Returns: AudioTrack — a new track, routable with << and >>

arrange

Section titled “arrange”
fn arrange(...sections) -> Timeline

Sequences clips and arrangements back-to-back into one Timeline. Each clip pattern occupies one cycle; each Timeline element contributes its own length. Repeat an element with elem * n or elem.repeat(n).

Parameters:

  • sections (Array) — clips and/or arrangements to play in order

Returns: Timeline — a new arrangement; length is the sum of element lengths

audio_cpu_load

Section titled “audio_cpu_load”
fn audio_cpu_load() -> Dict

Returns a dict with audio CPU load information.

Returns: Dict — keys: load (EMA-smoothed 0.0-1.0), peak (peak since last drain 0.0-1.0)

audio_devices

Section titled “audio_devices”
fn audio_devices() -> Array

Lists all audio output devices.

Returns: Array — dicts with keys: name, input_channels, output_channels, sample_rate, is_default

audio_latency

Section titled “audio_latency”
fn audio_latency() -> Dict

Returns a dict with audio latency information.

Returns: Dict — keys: sample_rate, buffer_frames, buffer_ms, pdc_samples, pdc_ms

audio_output

Section titled “audio_output”
fn audio_output(name: String) -> NUL

Switches the audio output to the named device. Uses exact match first, then substring fallback.

Example:

audio_output("Scarlett") switches to a Scarlett interface.

Parameters:

  • name (String) — output device name (or a substring of it)

Returns: NUL — nothing

audio_output_channels

Section titled “audio_output_channels”
fn audio_output_channels(channel: Number) -> NUL
fn audio_output_channels(left: Number, right: Number) -> NUL
fn audio_output_channels(track: AudioTrack, channel: Number) -> NUL
fn audio_output_channels(track: AudioTrack, left: Number, right: Number) -> NUL

Routes a track to stereo hardware channels.

Example:

audio_output_channels(drums, 2, 3)

Parameters:

  • track (AudioTrack) — track to route
  • left (Number) — left output channel index
  • right (Number) — right output channel index

Returns: NUL — nothing

list_snapshots

Section titled “list_snapshots”
fn list_snapshots() -> Array

Lists the save_project() snapshots retained under .history/, newest first. Feed an entry’s index or name back into load_project() to restore it.

Returns: Array — of dicts { index, name, count }; count is the number of plugin presets in that snapshot. Empty when nothing has been saved yet.

load_project

Section titled “load_project”
fn load_project(snapshot = NUL) -> NUL

Restores plugin GUI state previously written by save_project(). Run after the script has rebuilt the session. Plugins whose identity no longer matches the saved preset are skipped with a warning; orphaned presets are reported. With no argument, restores the current flat state. Pass a snapshot selector to restore a .history/ snapshot instead: a Number index (0 = most recent, 1 = next older, …) for quick undo, or the exact snapshot name string from list_snapshots(). Restoring a snapshot is non-destructive — it only applies state to loaded plugins; the current files are untouched until the next save_project().

Parameters:

  • snapshot — NUL for current state, Number index, or snapshot name String

Returns: NUL — nothing; applies state to loaded plugins

midi_export

Section titled “midi_export”
fn midi_export(first: Pattern, second: Number or String = NUL, third: String = NUL) -> String

Exports a pattern to a Standard MIDI File (.mid). Output path: renders/{project}/{datetime}/export.mid (auto) or custom path

Parameters:

  • first (Pattern) — the pattern to export (requires cycles)
  • second (Number | String) — cycles, or output path (optional)
  • third (String) — output path (optional)

Returns: String — the path of the written MIDI file

plugin_scan

Section titled “plugin_scan”
fn plugin_scan() -> PluginList

Scans CLAP and VST3 plugin directories, updates the plugin cache, and returns a PluginList with keys: name, id, vendor, format.

Returns: PluginList — the scanned plugins (keys: name, id, vendor, format)

project_artist

Section titled “project_artist”
fn project_artist(artist: String) -> NUL

Sets the project artist name. Used in render metadata.

Parameters:

  • artist (String) — artist name

Returns: NUL — nothing

project_bpm

Section titled “project_bpm”
fn project_bpm(bpm: Number, beats_per_cycle: Number = NUL) -> NUL

Sets the project BPM and updates the audio engine tempo. Equivalent to setbpm() but also sets project metadata.

Parameters:

  • bpm (Number) — beats per minute (positive)
  • beats_per_cycle (Number) — beats in one cycle (optional)

Returns: NUL — nothing

project_title

Section titled “project_title”
fn project_title(title: String) -> NUL

Sets the project title. Used in render output paths and metadata.

Parameters:

  • title (String) — project title

Returns: NUL — nothing

recording_offset

Section titled “recording_offset”
fn recording_offset(ms: Number = NUL) -> Number

Set or get the global recording latency compensation offset in milliseconds.

When recording while playing back, the recorded audio is shifted forward by the round-trip I/O latency. This function trims the front of all recordings to compensate. Call with no argument to read the current offset, or with ms to set it.

Parameters:

  • ms (Number) — offset in milliseconds (optional; omit to read the current value)

Returns: Number — the current offset value (after setting, when ms is given)

render

Section titled “render”
fn render(target: AudioTrack or Master or Screen or Array or Number, cycles: Number = NUL) -> NUL

Renders audio and/or the routed visual offline for the given number of cycles. The target selects what is written: a track/bus → its WAV, master → master.wav, screen → a PNG frame sequence (frames/frame_00000.png …) of the visual routed with v >> screen. An array combines them (#[master, screen] = a synced master.wav + PNG export; #[drums, screen] = drums.wav + frames). screen always bounces the master internally so audio-reactive visuals see real meters/FFT, even when no WAV is written. With one argument, renders the master output for that many cycles. Byte-reproducible on a given GPU. Output path: renders/{project}/{datetime}/.

Example:

render(8), render(drums, 8), render(screen, 8), render(#[master, screen], 8)

Parameters:

  • target (AudioTrack | Master | Screen | Array | Number) — what to render, OR (when cycles is omitted) the number of cycles to render the master for
  • cycles (Number) — number of cycles to render (optional; omit to render the master for target cycles)

Returns: NUL — nothing; writes the WAV file(s) and/or PNG frames

render_master

Section titled “render_master”
fn render_master(cycles: Number) -> NUL

Renders the master output to a WAV file. Mixes all tracks through the audio graph. Output path: renders/{project}/{datetime}/master.wav

Parameters:

  • cycles (Number) — number of cycles to render (>= 1)

Returns: NUL — nothing; writes the WAV file

routing

Section titled “routing”
fn routing(...tracks) -> NUL

Displays the current audio routing graph. With no arguments, shows all tracks and routing chains. With track arguments, shows detailed per-track routing info.

Parameters:

  • tracks (Array) — variadic AudioTrack values (zero or more)

Returns: NUL — nothing; prints the routing graph

save_project

Section titled “save_project”
fn save_project() -> NUL

Saves the GUI state of every loaded VST3/CLAP plugin to a folder beside the script (<script>.resonon-state/), one preset file per plugin. Only plugin GUI parameter/binary state is saved; tracks, routing, and built-in DSP are reproduced by re-running the script.

Returns: NUL — nothing; writes preset files

scope

Section titled “scope”
fn scope(signal: Signal, label: String = "") -> NUL

Registers a signal for visualization in the scope TUI view.

Example:

scope(Sine(2)) or scope(lfo, "tempo LFO")

Parameters:

  • signal (Signal) — the signal to visualize
  • label (String) — display label (optional; defaults to the signal description)

Returns: NUL — nothing

scope_clear

Section titled “scope_clear”
fn scope_clear() -> NUL

Removes all signals from the scope view.

Example:

scope_clear()

Returns: NUL — nothing

scope_remove

Section titled “scope_remove”
fn scope_remove(signal: Signal) -> NUL

Removes a signal from the scope view.

Example:

lfo = Sine(2); scope(lfo); scope_remove(lfo)

Parameters:

  • signal (Signal) — the signal to remove (must be the same instance passed to scope())

Returns: NUL — nothing

section

Section titled “section”
fn section(length: Number) -> Section

Creates a multi-track section: lanes keyed by track, assigned with sec[track] << clip (whole lane) or sec[track].at(start, dur) << clip.

Parameters:

  • length (Number) — section length in cycles (must be > 0)

Returns: Section — a section accepting per-track lanes; index it with a track value

setbpm

Section titled “setbpm”
fn setbpm(bpm: Number, beats_per_cycle: Number = NUL) -> NUL

Sets the global tempo. Formula: cps = bpm / 60 / beats_per_cycle

Parameters:

  • bpm (Number) — beats per minute (positive)
  • beats_per_cycle (Number) — beats in one cycle (optional)

Returns: NUL — nothing

timeline

Section titled “timeline”
fn timeline(length: Number) -> Timeline

Creates a mutable timeline builder for placing patterns at cycle offsets.

Parameters:

  • length (Number) — timeline length in cycles (must be > 0)

Returns: Timeline — a timeline accepting entries via .at(start, duration) << pattern