Builtin Functions

Free functions that are always in scope — no import required.

AudioTrack

fn AudioTrack() -> AudioTrack

Creates an unnamed audio track for sample playback.

Example:

AudioTrack()

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

audio_cpu_load

fn audio_cpu_load() -> Dict

Returns a dict with audio CPU load information.

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

audio_devices

fn audio_devices() -> Array

Lists all audio output devices.

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

audio_latency

fn audio_latency() -> Dict

Returns a dict with audio latency information.

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

audio_output

fn audio_output(name: String) -> NUL

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

Example:

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

Parameters:

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

Returns: NUL — nothing

audio_output_channels

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

clock

fn clock() -> Number

Returns time in nanoseconds from an arbitrary reference point. Useful for benchmarking and timing operations.

Returns: Number — nanoseconds from an arbitrary reference point

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_file

fn load_file(path: String) -> String

Reads a text file and returns its contents as a String. The path is resolved relative to the directory of the .non file being run (falling back to the working directory). Useful for keeping GLSL shaders in external files: gfx.Visual(load_file("shaders/plasma.glsl")).

Parameters:

• path (String) — file path, relative to the current .non file

Returns: String — the file contents (UTF-8)

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, third: String) -> String

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

Parameters:

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

Returns: String — the path of the written MIDI file

plugin_scan

fn plugin_scan() -> PluginList

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

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

project_artist

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

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

When recording while playing back, the recorded audio is shifted forward by the round-trip I/O latency. This function trims the front of all recordings to compensate.

Returns: Number — the current offset value in milliseconds

reload_ext

fn reload_ext(name: String) -> NUL

Reloads a native extension from disk. Fails if any objects from the extension still exist — drop them first.

Parameters:

• name (String) — extension name to reload

Returns: NUL — nothing

render

fn render(cycles: Number) -> NUL

Renders the master output to a WAV file for the given number of cycles. Output path: renders/{project}/{datetime}/{track_name}.wav

Example:

render(8)

Parameters:

• cycles (Number) — number of cycles to render

Returns: NUL — nothing; writes the WAV file

render_master

fn render_master(cycles: Number) -> NUL

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

Parameters:

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

Returns: NUL — nothing; writes the WAV file

render_with_visuals

fn render_with_visuals(cycles: Number) -> NUL

Renders the routed visual and master audio to a synced offline export. Bounces the master mix to master.wav and the visual routed with v >> screen to a PNG sequence (frames/frame_00000.png …), both from one fixed-dt frame clock so frame N’s shader sees frame N’s transport. Byte-reproducible on a given GPU. Requires a visual routed to screen. Output path: renders/{project}/{datetime}/ (master.wav + frames/)

Parameters:

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

Returns: NUL — nothing; writes the WAV file and PNG frames

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

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

show

fn show(value: any) -> NUL

Displays detailed information about a value. For modules: name, path, exports, and documentation. For functions: the full typed signature, parameter types, and doc comments. For other values: the runtime type and representation.

Parameters:

• value (Any) — any resonon value

Returns: NUL — nothing; prints the information

sleep

fn sleep(seconds: Number) -> NUL

Pauses execution for the given number of seconds.

Useful for timed recording, waiting for hardware, or scripted workflows.

Parameters:

• seconds (Number) — duration to sleep (e.g. 1.5 for 1500ms)

Returns: NUL — nothing

timeline

fn timeline(length: Number) -> Timeline

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

Parameters:

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

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

type

fn type(value: any) -> String

Returns the type name of a value as a string.

Parameters:

• value (Any) — any resonon value

Returns: String — the value’s type name