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

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 through its output and its 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

A track in the audio engine for sample playback and routing. Construct with AudioTrack("name"). The name is the track’s identity: asking for a name that already has a live track hands that track back, so re-running a track’s setup reconciles it in place instead of making a second track. The setters return the track, so a whole channel strip is one builder chain.

Instruments

instrument

fn instrument(instrument: Instrument or Sampler or SamplerMelodic) -> AudioTrack

Sets the instrument on this track. The declarative front door for the instrument; reconciles the live graph. Re-attaching one of the same identity preserves the live instance — its parameter edits, modulation and sounding voices survive; a plugin matches by type, a sampler by kit, a dsp instrument by definition (an edited body is crossfaded in). A different identity replaces the instrument outright. Read the attached instrument back with loaded_instrument.

Parameters:

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

Returns: AudioTrack — the track, for chaining

loaded_instrument

fn loaded_instrument() -> Instrument or Sampler or SamplerMelodic

Returns the instrument currently attached to this track.

Returns: Instrument | Sampler | SamplerMelodic — the attached instrument, or NUL if the track has none

remove_instrument

fn remove_instrument() -> AudioTrack

Detaches the instrument from this track, leaving it with none. The outgoing instance rings out (its tail is not cut); a no-op if the track has no instrument. Effect chain and routing are untouched.

Returns: AudioTrack — the track, for chaining

Effects

fx

fn fx(effects: Array) -> AudioTrack

Declaratively sets the whole effect chain, reconciling the live graph. The chain is made to match the given list exactly — inserting new slots, removing absent ones, and reordering to match. Re-running is idempotent. Slot identity is the effect’s name (its required leading constructor argument): a kept slot preserves its live instance, so its params and running modulation survive; constructor args only seed brand-new slots. Names must be unique. Passing an empty array clears the chain. A kept slot costs nothing to re-declare: the chain is planned against the live graph first, so no plugin is loaded and no dsp effect compiled for a slot that is being preserved. Editing a dsp effect body is handled without losing the slot — the recompiled graph is crossfaded into the live instance, so the edit is audible while the slot’s parameter values, modulation and sidechain connections carry over. An edit that changes the parameter set has nowhere to carry them, so it rebuilds the slot.

Parameters:

effects (Array) — the effects, in the desired chain order

Returns: AudioTrack — the track, for chaining

effects

fn effects() -> Array

Returns an array of all effects in chain order.

Returns: Array — the effects in chain order

effect

fn effect(name: String) -> Effect

Returns a modulatable handle to an effect by its slot name.

Parameters:

name (String) — slot name of the effect

Returns: Effect — the effect with that slot name

Mixing

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

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

out

fn out(destination: AudioTrack or Master) -> AudioTrack

Sets this track’s single exclusive output route (declarative >>). Replaces the output edge so the track’s dry signal goes to the destination at unity. Aux sends made via send_to are independent and untouched. Re-running is idempotent.

Parameters:

destination (AudioTrack | Master) — the output destination

Returns: AudioTrack — the track, for chaining

send_to

fn send_to(destination: AudioTrack, amount: Number) -> AudioTrack

Adds a parallel aux send to the given destination, leaving the output edge untouched. If the destination is already the track’s exclusive output (see out), this sets that output edge’s level instead — which is how you build a crossfade, by giving the wet and dry legs complementary amounts.

Parameters:

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

Returns: AudioTrack — the track, for chaining

send

fn send(destination: AudioTrack) -> SendParam

Returns a modulatable handle to an existing send’s level. The send must already exist (created via send_to). Supports .set(amount) and << signal, symmetric to effect(name).param(name).

Parameters:

destination (AudioTrack) — the send destination

Returns: SendParam — a modulatable handle to the send level

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

reset_routing

fn reset_routing() -> AudioTrack

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

Returns: AudioTrack — the track, for chaining

Recording & input

input

fn input(channel: Number, right: Number?) -> AudioTrack

Sets the hardware input channels for monitoring and recording. Channels are indices into the current input device, counting from 0, the same way audio_output_channels counts. Pass one for mono, two for a stereo pair. Choose the device itself with audio_input; with none chosen, the first call opens the system default input. A channel the device does not have is an error, not silence.

Examples:

vocals.input(0) records channel 0 as mono;
drums.input(2, 3) records channels 2 and 3 as stereo.

Parameters:

channel (Number) — mono channel, or the left channel of a stereo pair
right (Number) — right channel (optional)

Returns: AudioTrack — the track, for chaining

delay

fn delay(ms: Number) -> AudioTrack

Sets this track’s output delay, to line it up with outboard gear. Use it when the track runs out through a hardware effect or an amp and back: delay the output by that device’s round-trip time and the PDC system nudges every other track to keep the mix aligned. Recordings made on this track shift to match. Not modulatable — setting it re-plans the graph’s latency compensation, so it is a calibration, not an automation target. Read it back with delay_ms.

Parameters:

ms (Number) — output delay in milliseconds; must not be negative

Returns: AudioTrack — the track, for chaining

delay_ms

fn delay_ms() -> Number

Returns this track’s output delay in milliseconds, as set by delay.

Returns: Number — the output delay in milliseconds; 0 on a track that has none

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

fn disarm() -> AudioTrack

Disarms the track, stopping recording.

Returns: AudioTrack — the track, for chaining

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

is_armed

fn is_armed() -> Boolean

Returns true if this track is armed for recording.

Returns: Boolean — true when the track is armed

is_recording

fn is_recording() -> Boolean

Returns true if this track is currently capturing audio. Arming alone is not enough: an armed track starts capturing at RECORD, or, when punch points are set, at its punch-in cycle and no later than its punch-out. STOP leaves the track armed but no longer capturing.

Returns: Boolean — true when the track is recording

take

fn take() -> AudioClip

Collects one recorded pass as an AudioClip. Every pass is kept, so a track that was recorded twice hands them back in the order they were performed: oldest first, one per call.

Returns: AudioClip — the oldest pass not yet collected, or NUL if none is waiting

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

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

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

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

fn clear_punch() -> AudioTrack

Clears all punch points from this track.

Returns: AudioTrack — the track, for chaining

is_punched

fn is_punched() -> Boolean

Returns true if this track has punch points configured.

Returns: Boolean — true if punch points are configured

Expression

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

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

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

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

delete

fn delete() -> NUL

Deletes the track and releases its resources.

Returns: NUL — nothing

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.

fx

fn fx(effects: Array) -> Master

Parameters:

effects (Array) — the effects, in the desired chain order

Returns: Master — the master bus, for chaining

effects

fn effects() -> Array

Returns an array of all effects in chain order.

Returns: Array — the effects in chain order

effect

fn effect(name: String) -> Effect

Returns a modulatable handle to an effect by its slot name.

Parameters:

name (String) — slot name of the effect

Returns: Effect — the effect with that slot name

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

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

Parameter list and parameter-reference types.

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

EffectParam

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

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

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

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

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

get

fn get() -> Number

Gets the current value of this parameter.

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

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

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

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

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

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

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

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

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

fn length() -> Number

Returns the number of parameters.

Returns: Number — the parameter count

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

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

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

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

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

Plugin type classes and loaders.

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

Effect

An audio effect processor.

Unified type wrapping three backends:

Built-in DSP — described by constructors like Delay("echo"), Lowpass("lp"), or dsp effect blocks. Processing runs as compiled bytecode.
CLAP plugin — named by Effect("slot", "name") when a CLAP bundle is found.
VST3 plugin — named by Effect("slot", "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.

An effect is a symbolic handle. A constructor describes one; track.fx(#[...]) is what builds it. Before placement the parameter writers (param_set, param_set_norm, load_state, set_program) record what they were asked to do and apply it to the instance the track builds; the readers (param, param_get, params, programs, save_state, connect_input, backend, the GUI methods) need an instance and say so. After placement every method works on the effect live in that slot, re-resolved on each call — so a handle kept across a re-execute never points at a replaced instance.

Every effect carries a slot name — its required first constructor argument. When a track’s chain is set with fx([...]), effects are identified by slot name, so re-running with the same name preserves that slot in-place rather than duplicating it — this makes re-execution idempotent.

let room = Effect("room", "ValhallaRoom");
room.param_set("Mix", 0.3);      // seeds the slot; the fx() line below builds it
let delay = Delay("echo", 0.25, 0.5);
drums.fx(#[room, delay]);

Constructor

fn Effect(name: String, plugin: 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) — slot name (identity in a track’s effect chain)
plugin (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

name

fn name() -> String

Returns the slot name of this effect.

The slot name is the effect’s required first constructor argument.

Backends: all.

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

Returns: String — the effect’s slot name

backend

fn backend() -> String

Returns the plugin backend type (“CLAP”, “VST3”, or “dsp”).

Returns: String — the backend type

Parameters

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("delay", 0.25, 0.5);
drums.fx(#[d]);           // place it first — reading needs an instance
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

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("delay", 0.25, 0.5);
drums.fx(#[d]);            // place it first — reading needs an instance
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

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("delay").param_set("Time", 0.8).param_set("Feedback", 0.3);  // seeds a new slot
drums.effect("delay").param_set("Time", 0.4);                       // edits the live one

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

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

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.

drums.fx(#[fx]);      // place it first — reading needs an instance
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

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

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

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", "Diva");
lead.fx(#[fx]);  // place it first — reading needs an instance
fx.programs();   // => #["Init", "Juno Saw", "Warm Pad", ...]

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

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", "Diva");
fx.set_program(2);  // recorded now, applied to the instance fx() builds
lead.fx(#[fx]);

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

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).

drums.effect("delay").supports_gui();   // => false, for a built-in DSP effect
drums.effect("room").supports_gui();    // => true, for a placed plugin

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

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("room", "ValhallaRoom");
drums.fx(#[fx]);      // place it first — the GUI needs an instance
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

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

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("comp", "TDR Kotelnikov");
bass.fx(#[comp]);                            // place first: the port lives on the slot
comp.connect_input("sidechain", kick_track);

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

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

An instrument is a symbolic handle. A constructor describes one; track.instrument(...) is what builds it. Before placement the parameter writers (param_set, param_set_norm, load_state, set_program) record what they were asked to do and apply it to the instance the track builds; the readers (param, param_get, params, programs, save_state, the GUI methods) need an instance and say so. After placement every method works on the instrument live on that track, re-resolved on each call — so a handle kept across a re-execute never points at a replaced instance.

Constructor

fn Instrument(name: String, plugin_id: String = NUL) -> Instrument

Describes an instrument plugin (CLAP or VST3). Loading happens when a track places it.

The plugin name is resolved against the installed bundles immediately, so a typo fails here — but nothing is opened: track.instrument(...) is what loads and activates the plugin, and a re-execute that keeps the live instrument loads nothing at all. 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

name

fn name() -> String

Returns the instrument name — as written before placement, as the live instrument reports it after.

Returns: String — the instrument name

backend

fn backend() -> String

Returns the plugin backend type (“CLAP”, “VST3”, or “dsp”).

Returns: String — the backend type

Parameters

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

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

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

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

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.

lead.instrument(inst);  // place it first — reading needs an instance
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

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

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

fn programs() -> Array

Returns the list of plugin program names.

Returns: Array — the program names as Strings

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

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

fn show_gui() -> NUL

Opens the plugin GUI window.

Returns: NUL — nothing

hide_gui

fn hide_gui() -> NUL

Closes the plugin GUI window.

Returns: NUL — nothing

PluginList

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

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

fn length() -> Number

Returns the number of plugins.

Returns: Number — the plugin count

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

plugin_rescan

fn plugin_rescan(path: String) -> PluginList

Re-opens one plugin bundle, whatever the plugin cache already says about it. plugin_scan(force: true) narrowed to a single bundle: the way back for a plugin skipped after a failed scan, without re-opening everything else. Errors if the bundle is missing, is not a .clap or .vst3 directory, or fails to open again.

Parameters:

path (String) — the bundle to re-open (~ and $VAR are expanded)

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

plugin_scan

fn plugin_scan(force: Boolean = false) -> PluginList

Scans CLAP and VST3 plugin directories, updates the plugin cache, and returns a PluginList with keys: name, id, vendor, format. Only bundles that changed on disk are opened, so a rescan after installing one plugin costs one bundle. Forcing re-opens everything, including bundles skipped by an earlier failure.

Parameters:

force (Boolean) — re-open every bundle, even unchanged and previously skipped ones

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

Audio clips

The AudioClip type: a reference into a sample.

An AudioClip is what track.take() hands back, and it is Live’s model of a clip: it names the audio that was captured, a start marker inside it, and — for a take — where on the transport it was performed. Latency compensation moves the marker, so a clip presents the take from the moment you asked to record; the sample behind it keeps every frame it captured.

AudioClip

A reference into recorded audio: marker, length and transport position. Provides methods to inspect the clip and save it out to a WAV file.

save

fn save(path: String) -> AudioClip

Saves the clip to a WAV file.

Writes the clip, not the whole sample: an export begins where the clip begins.

Parameters:

path (String) — output file path

Returns: AudioClip — this, for method chaining

duration

fn duration() -> Number

Returns the duration of the clip in seconds.

Returns: Number — the duration in seconds

samples

fn samples() -> Number

Returns the total number of samples in the clip.

Returns: Number — the total sample count

sample_rate

fn sample_rate() -> Number

Returns the sample rate of the clip’s audio.

Returns: Number — the sample rate in Hz

position

fn position() -> Number

Returns where the clip sits on the transport, in seconds.

A take arrives placed at the moment it was performed, corrected by the measured round trip. NUL for a clip that was never placed.

Returns: Number — the transport position in seconds, or NUL

left

fn left() -> Array

Returns the left channel as an array of sample values.

Returns: Array — the left-channel sample values

right

fn right() -> Array

Returns the right channel as an array of sample values.

Returns: Array — the right-channel sample values

mono

fn mono() -> Array

Returns a mono mixdown as an array of sample values.

Returns: Array — the mono mixdown sample values

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

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

note

fn note() -> Number

Returns the MIDI note number.

Returns: Number — the MIDI note number

velocity

fn velocity() -> Number

Returns the velocity (0-127).

Returns: Number — the velocity (0-127)

channel

fn channel() -> Number

Returns the MIDI channel.

Returns: Number — the MIDI channel

start

fn start() -> Number

Returns the start time in cycles.

Returns: Number — the start time in cycles

duration

fn duration() -> Number

Returns the duration in cycles.

Returns: Number — the duration in cycles

end

fn end() -> Number

Returns the end time (start + duration).

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

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

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

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

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

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

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

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

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

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

AudioTrack

fn AudioTrack(name: String = NUL) -> AudioTrack

Creates an audio track, optionally named.

The name is the track’s identity: asking for a name that already has a live track returns that track, with its instrument, effect chain, fader and sends intact. Re-executing the line therefore re-attaches instead of building a second track — the same rule that lets an effect’s slot name preserve its slot. Two tracks need two names.

Example:

AudioTrack(), AudioTrack("drums")

Parameters:

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

Returns: AudioTrack — the track with that name, created if it does not exist yet

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). What it lays down is the base layer, so masks written on top of the result survive a later whole-lane rewrite.

Parameters:

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

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

audio_buffer_size

fn audio_buffer_size() -> Number

The number of frames the audio device delivers per callback.

The device’s own answer, read back from the audio callback — not what was asked for, which is [audio] buffer_size in ~/.resonon/preferences.toml. Same value as audio_latency()["buffer_frames"].

Returns: Number — block size in frames

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_input_devices

fn audio_input_devices() -> Array

Lists the devices this machine can record from. The names [audio] input is written in, and the channel counts .input() indexes into. sample_rates is what the microphone or interface reports it can run at — a diagnostic, not a setting: the session runs at one rate, chosen for the devices that will be open, so this is what explains an input that cannot join rather than a rate to pick.

Returns: Array — dicts with keys: name, channels, sample_rate, sample_rates (Array), buffer_frames (Dict with min/max, or NUL), is_default

audio_latency

fn audio_latency() -> Dict

Returns a dict with audio latency information.

output_ms, input_ms and monitor_ms are measured from the devices’ own timestamps, so they include the device latency and safety offset that a buffer-size calculation misses. monitor_ms is the whole monitoring path — the input device plus the output device, with nothing in between — and is absent until a monitored signal has actually been read.

record_compensation_ms is the whole of what a recorded take is corrected by: the round trip it went through, the graph’s compensation, and the recording_offset() residual on top. It is applied automatically; the take keeps every frame it captured either way.

Returns: Dict — keys: sample_rate, buffer_frames, buffer_ms, pdc_samples, pdc_ms, output_ms, input_ms, device_ms, record_compensation_ms, record_compensation_frames, monitor_ms (only once measured)

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

audio_output_devices

fn audio_output_devices() -> Array

Lists the devices this machine can play through. The names [audio] output is written in. sample_rates and buffer_frames are what [audio] sample_rate and [audio] buffer_size will be accepted for that device, so what to write in ~/.resonon/preferences.toml is something you can read rather than something you find by guessing wrong.

Returns: Array — dicts with keys: name, channels, sample_rate, sample_rates (Array), buffer_frames (Dict with min/max, or NUL), is_default

audio_sample_rate

fn audio_sample_rate() -> Number

The sample rate the audio output is running at, in Hz.

What the device is doing, which is not always what was asked for: set it with [audio] sample_rate in ~/.resonon/preferences.toml, and a rate the device will not run at is reported at startup and not applied.

Returns: Number — sample rate in Hz

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

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

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: <project>/renders/{name}_{datetime}/export.mid, or a custom path (relative to the project)

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

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

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

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

fn recording_offset() -> Number

Returns the recording latency residual in milliseconds.

The round trip a take was recorded through is measured and corrected automatically. This is the correction on top of that measurement, for a rig whose reported latency is not quite its real one: positive says the take arrived even later and starts it further in, negative starts it later. Usually zero. A fact about the rig rather than the piece, so it is [audio] recording_offset_ms in ~/.resonon/preferences.toml.

Compensation moves where a take begins; it never deletes what was captured.

Returns: Number — the current residual in milliseconds

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: <project>/renders/{name}_{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

fn render_master(cycles: Number) -> NUL

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

Parameters:

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

Returns: NUL — nothing; writes the WAV file

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

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

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

fn scope_clear() -> NUL

Removes all signals from the scope view.

Example:

scope_clear()

Returns: NUL — nothing

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

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. A section also carries automation lanes (sec[track].volume << curve, sec[track].get_effect("filt").param("cutoff") << curve) and a visual lane: sec[screen] << visual puts that visual on screen for the section’s whole span, so sequencing sections with arrange cuts the picture on section boundaries (a section without one renders black). .at(start, dur) positions any of them — notes, automation, visuals — within the lane instead of covering the whole section, so per-lane overrides coexist with the structure arrange laid down. A section’s length is a whole number of cycles, but a position inside it is not: .at(2.5, 1.25) places between the lines, the same rule on every lane kind. Every lane is a stack of layers: base (what section/arrange laid down, or a bare sec[track] << clip) with named layers above it, main by default. Later wins — the entry underneath is MASKED, not cut, and resumes in its own phase when the mask ends, so an override reaching across a section boundary plays through it. A write upserts by start, so editing a .at line and re-executing reshapes that one mask instead of stacking duplicates, and .clear() lifts a mask to bring back exactly what was underneath. An edit to a playing section’s automation or screen lane lands live — no second play(), no rewind.

Parameters:

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

Returns: Section — a section accepting per-track lanes; index it with a track value (or with screen for the visual lane)

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

fn timeline(length: Number) -> Timeline

Creates a mutable timeline builder for placing patterns along a lane. A timeline is a single lane, so it carries the same layer surface a section’s lanes do: .layer(name), .mute(), .layers(#[..]), .clear(). The length is a whole number of cycles — the ruler — but .at(..) is not bound to it: start and duration may be any position, so .at(2.5, 1.25) means exactly that. The grid is what you snap to, not what you are limited to, which is what lets recorded material sit where it was performed.

Parameters:

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

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