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. >> selects an output: drums >> bus, drums >> Output(2, 3), drums >> nowhere, master >> Output(2, 3).

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

set_instrument

fn set_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 instrument().

Parameters:

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

Returns: AudioTrack — the track, for chaining

instrument

fn 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 fades out over 10 ms rather than clicking; a no-op if the track has no instrument. Effect chain and routing are untouched.

Returns: AudioTrack — the track, for chaining

Effects

set_effects

fn set_effects(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. Slot identity is the effect’s name (its required leading constructor argument): a kept slot preserves its live instance, so its running modulation survives. Constructor args are parameter writes: a freshly executed Lowpass("lp", 12000) sets the kept slot’s cutoff, as it would a new one’s — the last write executed wins. Args left out write nothing, and re-placing a bound handle writes nothing either, so a value tweaked since survives. 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

set_volume

fn set_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

set_pan

fn set_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

set_send

fn set_send(destination: AudioTrack or Master, amount: Number or Signal or Pattern) -> 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 >>), 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 | Master) — target track, bus or the master
amount (Number | Signal | Pattern) — send level (0.0-1.0), or a signal or pattern that moves it

Returns: AudioTrack — the track, for chaining

send

fn send(destination: AudioTrack or Master) -> SendParam

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

Parameters:

destination (AudioTrack | Master) — the send destination

Returns: SendParam — a modulatable handle to the send level

routing_report

fn routing_report() -> 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 the track’s routing: output back to master, every send removed.

Returns: AudioTrack — the track, for chaining

Recording & input

set_input

fn set_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 Output 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.set_input(0) records channel 0 as mono;
drums.set_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

set_delay

fn set_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.

Parameters:

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

Returns: AudioTrack — the track, for chaining

delay

fn delay() -> Number

Returns this track’s output delay in milliseconds, as set by set_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 set_input() first.

Returns: AudioTrack — the track, for chaining

disarm

fn disarm() -> AudioTrack

Disarms the track, stopping recording.

Returns: AudioTrack — the track, for chaining

set_monitor

fn set_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

set_velocity

fn set_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

set_tuning

fn set_tuning(bend_range: Number?) -> AudioTrack

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

Example:

track.set_tuning(), track.set_tuning(48)

Parameters:

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

Returns: AudioTrack — the track, for chaining

set_mpe

fn set_mpe(range: Number?, zone_lo: Number?, zone_hi: Number?) -> AudioTrack

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

Example:

track.set_mpe(), track.set_mpe(24), track.set_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

set_key

fn set_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.set_key(Key(C4, "major")) or track.set_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. The name is freed: AudioTrack(name) afterwards builds a new track. A deleted track no longer counts toward the track limit, even while a variable holds it. Tracks that output to it now output to nowhere (Sends Only; see The Audio Graph), sends to it are removed and sidechain inputs it fed are unwired; a warning names each track affected. A take it was recording is discarded.

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.

set_effects

fn set_effects(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

set_volume

fn set_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

set_pan

fn set_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

MeterFeed

A live level from a track or the master: track.rms, track.peak, or a band of a spectrum (master.fft.band(lo, hi)). Bind it to a visual parameter with <<; the raw level runs from 0 to 1.

smooth

fn smooth(attack_ms: Number, release_ms: Number?) -> MeterFeed

Smooths the level so it glides instead of strobing. With one time the rise and the fall are equal; give two for a separate release.

Parameters:

attack_ms (Number) — rise time in milliseconds (>= 0)
release_ms (Number) — fall time in milliseconds (>= 0; omit to match attack)

Returns: MeterFeed — a new feed with that smoothing

range

fn range(min: Number, max: Number) -> MeterFeed

Maps the 0-to-1 level linearly onto [min, max].

Parameters:

min (Number) — value at a level of 0
max (Number) — value at a level of 1

Returns: MeterFeed — a new feed with that range

Nowhere

Nowhere: a track’s output that goes nowhere. nowhere is a global, like master. It can only end a >> chain, and only a track’s output can be nowhere: master’s is always hardware. On an audio track it is Live’s “Sends Only”: drums >> nowhere takes the track out of the mix while its sends keep feeding their returns, so a reverb or parallel bus hears it fully wet. drums >> master puts it back in the mix at unity. On a MIDI track it is Live’s “No Output”, where a new MIDI track starts: bass >> nowhere stops it sending.

SpectrumFeed

A live spectrum from a track or the master (track.fft), bound to a shader texture with <<.

smooth

fn smooth(attack_ms: Number, release_ms: Number?) -> SpectrumFeed

Smooths every bin so the spectrum glides between analysis frames. With one time the rise and the fall are equal; give two for a separate release.

Parameters:

attack_ms (Number) — rise time in milliseconds (>= 0)
release_ms (Number) — fall time in milliseconds (>= 0; omit to match attack)

Returns: SpectrumFeed — a new feed with that smoothing

band

fn band(low_hz: Number, high_hz: Number) -> MeterFeed

Reduces a frequency band to a single level. It reads the unsmoothed spectrum, so smooth the result, not the spectrum.

Parameters:

low_hz (Number) — bottom of the band in Hz (>= 0)
high_hz (Number) — top of the band in Hz (above low_hz)

Returns: MeterFeed — the band’s level, from 0 to 1

Parameters

Parameter list and parameter-reference types.

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

EffectParam

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

get

fn get() -> Number

Gets the current value of this parameter.

delay.parameter("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.parameter("Time").set(0.5);
delay.parameter("Time").set(Sine(4).range(0.1, 0.8));
delay.parameter("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.parameter("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 .parameter("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 .parameters(). 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

SendParam

A reference to one send’s level, obtained via track.send(destination). Supports .set() and modulation via <<.

set

fn set(amount: Number or Signal or Pattern) -> SendParam

Sets the send level: a static amount, or a Signal or Pattern that modulates it.

Parameters:

amount (Number | Signal | Pattern) — the level, from 0.0 to 1.0

Returns: SendParam — this, for method chaining

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.set_effects(#[...]) is what builds it. Before placement the parameter writers (set_parameter, load_state, set_program) record what they were asked to do and write it to the slot when the track places the effect — a new slot or one the chain kept; the readers (parameter, parameters, 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 set_effects(#[...]), effects are identified by slot name, so re-running with the same name preserves that slot in-place rather than duplicating it. The recorded writes still land: re-running Lowpass("lp", 12000) sets the kept slot’s cutoff — the last write executed wins.

let room = Effect("room", "ValhallaRoom");
room.set_parameter("Mix", 0.3);      // recorded; the set_effects() line below writes it
let delay = Delay("echo", 0.25, 0.5);
drums.set_effects(#[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

parameter

fn parameter(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.set_effects(#[d]);           // place it first — reading needs an instance
d.parameter("Time").get();    // => 0.25
d.parameter("Time").set(0.5); // set to 0.5
d.parameter("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

set_parameter

fn set_parameter(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 parameter(name).set_norm() instead.

Backends: all.

Delay("delay").set_parameter("Time", 0.8).set_parameter("Feedback", 0.3);  // written when placed
drums.effect("delay").set_parameter("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

parameters

fn parameters(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.set_effects(#[fx]);             // place it first — reading needs an instance
print(fx.parameters());          // all parameters
print(fx.parameters("freq"));    // only parameters containing "freq"
let rows = fx.parameters().data; // raw array of parameter dicts

Parameters:

filter (String) — only include parameters whose name contains this substring, case-insensitive (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.set_effects(#[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 set_effects() builds
lead.set_effects(#[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.set_effects(#[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).

The port name is the effect’s own, matched exactly: a plugin’s is the name it gives its input bus (MCompressor and TDR Molot GE say “Sidechain”, Shadow Hills “Stereo Aux In”, FETish “Aux”), a dsp effect’s is the name of its extra input. To find it, connect any name — the error lists the ports the effect has.

Backends: CLAP, VST3, and dsp effect blocks that declare a second input.

let comp = Effect("comp", "TDR Molot GE");
bass.set_effects(#[comp]);                            // place first: the port lives on the slot
comp.connect_input("Sidechain", kick_track);

Parameters:

name (String) — the sidechain input port name, as the effect reports it
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; lists the ports it has

Instrument

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

An instrument is a symbolic handle. A constructor describes one; track.set_instrument(...) is what builds it. Before placement the parameter writers (set_parameter, load_state, set_program) record what they were asked to do and apply it to the instance the track builds; the readers (parameter, parameters, 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.set_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

parameter

fn parameter(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()

set_parameter

fn set_parameter(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

parameters

fn parameters(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.set_instrument(inst);         // place it first — reading needs an instance
print(inst.parameters());          // all parameters
print(inst.parameters("freq"));    // only parameters containing "freq"
let rows = inst.parameters().data; // raw array of parameter dicts

Parameters:

filter (String) — only include parameters whose name contains this substring, case-insensitive (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. The preset’s plugin name must match this instrument’s plugin name.

Parameters:

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

Returns: Instrument — the instrument, for chaining Errors: RuntimeError — if the file doesn’t exist or the plugin name mismatches

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. Matching is case-insensitive.

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 in the arrangement 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 arrangement 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 in the arrangement, in cycles.

A take arrives placed at the cycle its recording pass began on — the position seek and .at() take — with the measured round trip already corrected inside the clip. NUL for a clip that was never placed.

Returns: Number — the arrangement position in cycles, 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.

Output

Output: hardware output channels of the audio device, a destination for >>. Made by Output(left, right); it can only end a >> chain.

Constructor

fn Output(left: Number, right: Number = NUL) -> Output

Hardware output channels of the audio device, as a destination for >> — a track’s output, or master’s. Channels count from 0, the same way set_input() counts. One channel folds the stereo signal to mono at -3 dB; two are a stereo pair. A channel the device does not have is an error when the output is selected; after a switch to a smaller device, a pair with one channel left folds onto it the same way, and one with none is silent.

Example:

drums >> Output(2, 3), master >> Output(0, 1)

Parameters:

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

Returns: Output — the channels, to route to with >>

AudioTrack

fn AudioTrack(name: String) -> AudioTrack

Creates an audio track with the given name.

Every track has a name; there is no unnamed track. 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("drums")

Parameters:

name (String) — the track’s name and identity (not empty)

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

arrange

fn arrange(...sections) -> Timeline or Section

Sequences clips and arrangements back-to-back into one Timeline, or sections into one Section. Each clip pattern occupies one cycle; each Timeline or Section 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, arrangements or sections to play in order

Returns: Timeline | Section — a Section when any element is a section (play it with .play()), else a Timeline; 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 .set_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_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(source: Pattern or Timeline or MidiTrack or Array, cycles: Number, path: String = NUL) -> String

Exports a pattern, timeline, MIDI track or array of MIDI tracks to a Standard MIDI File (.mid). Writes notes (pitch, velocity, channel, length), CC lanes, pitch bend and MPE setup (for .set_tuning() and .set_mpe() tracks), tempo and track names — not program changes or SysEx. A pattern or timeline is written as a single-track file (type 0); tracks as a multi-track file (type 1) with a tempo track first. The resolution is 480 ticks per quarter note, and a cycle is written as 4 beats (1920 ticks) at the session’s cycle rate, so the timing is right in seconds but a piece with another number of beats per cycle shows a different bar length in a DAW. Every note is at least one tick long. Output path: <project>/renders/{name}_{datetime}/export.mid (a single track is named after the track), or a custom path (relative to the project)

Parameters:

source (Pattern | Timeline | MidiTrack | Array) — what to export; an array holds MidiTracks
cycles (Number) — number of cycles to export (>= 1)
path (String) — output path

Returns: String — the path of the written MIDI file

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. A track’s WAV is the track as it sounds in the mix, post-fader: the rest of the project keeps playing behind it, so its sidechains are keyed, and it lines up with master.wav. With one argument, renders the master output for that many cycles. Starts at cycle 0, whatever the play head is doing, and pauses live output while it runs. 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_report

fn routing_report(...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 the project’s plugin-state/ folder, 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].effect("filt").parameter("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)

set_bpm

fn set_bpm(bpm: Number, beats_per_cycle: Number = NUL) -> NUL

Sets the tempo, and records it as the project’s tempo in render metadata. Formula: cps = bpm / 60 / beats_per_cycle. Ignored while following an external MIDI clock (set_midi_clock_source).

Parameters:

bpm (Number) — beats per minute (positive)
beats_per_cycle (Number) — beats in one cycle (optional, 4 when omitted)

Returns: NUL — nothing

set_project_artist

fn set_project_artist(artist: String) -> NUL

Sets the project artist name. Used in render metadata.

Parameters:

artist (String) — artist name

Returns: NUL — nothing

set_project_title

fn set_project_title(title: String) -> NUL

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

Parameters:

title (String) — project title

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(), .set_layer_order(#[..]), .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

Timelines

The timeline types: a single lane of patterns placed along it.

A Timeline comes from timeline(length) or arrange(...). Every lane — a timeline, or one of a section’s lanes — is a stack of layers: base at the bottom, main where a plain .at() lands, and any named layer above.

LaneLayer

One named layer of a lane, from .layer(name) on any lane. << replaces the layer’s contents; .at(start, duration) << ... masks a span.

at

fn at(start: Number, duration: Number) -> TimelineSlot or SectionParam or SectionVisual

Addresses a span of this layer for a << write.

Parameters:

start (Number) — where the span begins, in cycles (>= 0, before the end)
duration (Number) — how long it lasts, in cycles (> 0)

Returns: TimelineSlot | SectionParam | SectionVisual — a handle to the span, of the lane’s own kind

mute

fn mute() -> LaneLayer

Silences the whole layer without destroying it.

Returns: LaneLayer — this, for method chaining

unmute

fn unmute() -> LaneLayer

Brings a muted layer back.

Returns: LaneLayer — this, for method chaining

clear

fn clear() -> LaneLayer

Drops every entry on this layer.

Returns: LaneLayer — this, for method chaining

Timeline

A single lane of patterns placed at positions along it. Assign with t.at(start, duration) << pattern; a later write masks the entries underneath for its span rather than cutting them.

at

fn at(start: Number, duration: Number) -> TimelineSlot

Addresses a span of the timeline for a << write. Neither value is rounded to the ruler: .at(2.5, 1.25) means exactly that.

Parameters:

start (Number) — where the span begins, in cycles (>= 0, before the end)
duration (Number) — how long it lasts, in cycles (> 0)

Returns: TimelineSlot — a slot that takes a pattern via <<

length

fn length() -> Number

Returns the timeline length.

Returns: Number — the length in cycles

entry_count

fn entry_count() -> Number

Returns how many entries have been written, on every layer.

Returns: Number — the entry count

entries

fn entries() -> Array

Returns the entries as written — the base first, then each layer — not the flattened result. masked is true for an entry hidden outright.

Returns: Array — one {start, duration, layer, masked} dict per entry

repeat

fn repeat(n: Number) -> Timeline

Returns a new timeline holding n back-to-back copies of this one; the receiver is untouched. t * n does the same.

Parameters:

n (Number) — number of copies (> 0)

Returns: Timeline — a new, independent timeline n times as long

layer

fn layer(name: String) -> LaneLayer

Addresses one named layer. Creates nothing: the first write through the handle creates the layer.

Parameters:

name (String) — the layer name

Returns: LaneLayer — a handle to that layer

layers

fn layers() -> Array

Returns the layer stack, bottom-to-top (base first).

Returns: Array — one {name, entry_count, muted} dict per layer

set_layer_order

fn set_layer_order(names: Array) -> Timeline

Restacks the layers above base, bottom-to-top. Layers left out keep their relative order and end up on top. Every name must exist; re-running the line changes nothing.

Parameters:

names (Array) — layer names, bottom-to-top (base may not be listed)

Returns: Timeline — this, for method chaining

clear

fn clear() -> Timeline

Drops every layer above base, leaving what arrange laid down.

Returns: Timeline — this, for method chaining

clear_all

fn clear_all() -> Timeline

Empties the timeline: every layer, base included.

Returns: Timeline — this, for method chaining

TimelineSlot

A span of a note lane, from .at(start, duration). Takes a pattern via <<.

clear

fn clear() -> TimelineSlot

Drops the entry that starts at this slot’s start on this slot’s layer, bringing back what it was masking. A start nothing occupies is a no-op.

Returns: TimelineSlot — this, for method chaining

Sections

The section types: a multi-track arrangement and the lanes inside it.

A Section comes from section(length). Index it with a track for that track’s note lane (sec[drums]), reach a parameter’s automation lane through it (sec[drums].volume, sec[drums].effect("filt").parameter("cutoff")), or index it with screen for the visual lane. Every lane has the same layer surface a Timeline has.

Section

A multi-track arrangement: one lane per track, plus automation and screen lanes.

length

fn length() -> Number

Returns the section length.

Returns: Number — the length in cycles

track_count

fn track_count() -> Number

Returns how many tracks have a note lane.

Returns: Number — the lane count

tracks

fn tracks() -> Array

Returns the tracks that have a note lane.

Returns: Array — one track id per lane

repeat

fn repeat(n: Number) -> Section

Returns a new section holding n back-to-back copies of this one; the receiver is untouched.

Parameters:

n (Number) — number of copies (> 0)

Returns: Section — a new, independent section n times as long

play

fn play() -> Section

Binds every lane — notes, automation, screen — and plays from the top. Re-running it replays. A track with no instrument is skipped.

Returns: Section — this, for method chaining

SectionEffect

An effect on a section lane’s track, from sec[track].effect(name).

parameter

fn parameter(name: String) -> SectionParam

Addresses one of the effect’s parameters as an automation lane.

Parameters:

name (String) — the parameter name

Returns: SectionParam — the automation lane for that parameter

SectionLane

A track’s note lane in a section, from sec[track]. << replaces the base; .at(start, duration) << ... masks a span.

at

fn at(start: Number, duration: Number) -> TimelineSlot

Addresses a span of the lane for a << write.

Parameters:

start (Number) — where the span begins, in cycles (>= 0, before the end)
duration (Number) — how long it lasts, in cycles (> 0)

Returns: TimelineSlot — a slot that takes a pattern via <<

entry_count

fn entry_count() -> Number

Returns how many entries have been written, on every layer.

Returns: Number — the entry count

entries

fn entries() -> Array

Returns the entries as written — the base first, then each layer — not the flattened result. masked is true for an entry hidden outright.

Returns: Array — one {start, duration, layer, masked} dict per entry

effect

fn effect(name: String) -> SectionEffect

Addresses an effect on this lane’s track, by slot name, for automation. The slot must exist on the track now.

Parameters:

name (String) — slot name of the effect

Returns: SectionEffect — a handle whose .parameter(name) is an automation lane

layer

fn layer(name: String) -> LaneLayer

Addresses one named layer. Creates nothing: the first write through the handle creates the layer.

Parameters:

name (String) — the layer name

Returns: LaneLayer — a handle to that layer

layers

fn layers() -> Array

Returns the layer stack, bottom-to-top (base first).

Returns: Array — one {name, entry_count, muted} dict per layer

set_layer_order

fn set_layer_order(names: Array) -> SectionLane

Restacks the layers above base, bottom-to-top. Layers left out keep their relative order and end up on top. Every name must exist; re-running the line changes nothing.

Parameters:

names (Array) — layer names, bottom-to-top (base may not be listed)

Returns: SectionLane — this, for method chaining

clear

fn clear() -> SectionLane

Drops every layer above base, leaving what the section laid down.

Returns: SectionLane — this, for method chaining

clear_all

fn clear_all() -> SectionLane

Empties the lane: every layer, base included.

Returns: SectionLane — this, for method chaining

SectionParam

An automation lane in a section, from sec[track].volume, .pan, or sec[track].effect(name).parameter(name). Takes a value or a curve via <<.

at

fn at(start: Number, duration: Number) -> SectionParam

Narrows the next << write to a span of the lane.

Parameters:

start (Number) — where the span begins, in cycles (>= 0, before the end)
duration (Number) — how long it lasts, in cycles (> 0)

Returns: SectionParam — the same lane, addressing that span

entry_count

fn entry_count() -> Number

Returns how many curves have been written, on every layer.

Returns: Number — the entry count

entries

fn entries() -> Array

Returns the curves as written — the base first, then each layer — not the flattened result. masked is true for an entry hidden outright.

Returns: Array — one {start, duration, layer, masked} dict per entry

layer

fn layer(name: String) -> LaneLayer

Addresses one named layer. Creates nothing: the first write through the handle creates the layer.

Parameters:

name (String) — the layer name

Returns: LaneLayer — a handle to that layer

layers

fn layers() -> Array

Returns the layer stack, bottom-to-top (base first).

Returns: Array — one {name, entry_count, muted} dict per layer

set_layer_order

fn set_layer_order(names: Array) -> SectionParam

Restacks the layers above base, bottom-to-top. Layers left out keep their relative order and end up on top. Every name must exist; re-running the line changes nothing.

Parameters:

names (Array) — layer names, bottom-to-top (base may not be listed)

Returns: SectionParam — this, for method chaining

clear

fn clear() -> SectionParam

Drops every layer above base — or, after .at(start, duration), just the curve that starts there.

Returns: SectionParam — this, for method chaining

clear_all

fn clear_all() -> SectionParam

Empties the lane: every layer, base included. On a playing section the automation stops.

Returns: SectionParam — this, for method chaining

SectionVisual

Experimental — Visuals are experimental; expect breaking changes to the screen lane.

The screen lane of a section, from sec[screen]. Takes a visual via <<.

at

fn at(start: Number, duration: Number) -> SectionVisual

Narrows the next << write to a span of the lane.

Parameters:

start (Number) — where the span begins, in cycles (>= 0, before the end)
duration (Number) — how long it lasts, in cycles (> 0)

Returns: SectionVisual — the same lane, addressing that span

entry_count

fn entry_count() -> Number

Returns how many visuals have been written, on every layer.

Returns: Number — the entry count

entries

fn entries() -> Array

Returns the visuals as written — the base first, then each layer — not the flattened result. masked is true for an entry hidden outright.

Returns: Array — one {start, duration, layer, masked} dict per entry

layer

fn layer(name: String) -> LaneLayer

Addresses one named layer. Creates nothing: the first write through the handle creates the layer.

Parameters:

name (String) — the layer name

Returns: LaneLayer — a handle to that layer

layers

fn layers() -> Array

Returns the layer stack, bottom-to-top (base first).

Returns: Array — one {name, entry_count, muted} dict per layer

set_layer_order

fn set_layer_order(names: Array) -> SectionVisual

Restacks the layers above base, bottom-to-top. Layers left out keep their relative order and end up on top. Every name must exist; re-running the line changes nothing.

Parameters:

names (Array) — layer names, bottom-to-top (base may not be listed)

Returns: SectionVisual — this, for method chaining

clear

fn clear() -> SectionVisual

Drops every layer above base — or, after .at(start, duration), just the visual that starts there.

Returns: SectionVisual — this, for method chaining

clear_all

fn clear_all() -> SectionVisual

Empties the lane: every layer, base included. On a playing section this blanks the screen.

Returns: SectionVisual — this, for method chaining