# Resonon > Resonon is a programming language for musical live-coding, algorithmic composition and sound > design. This is its compact reference for coding agents: the language, the mini-notation, and > every standard-library function with its signature and a one-line description. `resonon reference` prints this reference for the installed version. The full manual is at [resonon.org/docs](https://resonon.org/docs/); a function's full documentation is in the [standard library reference](https://resonon.org/docs/reference/stdlib/), or printed by `show(name)`. The commands for working on a project from a shell are `resonon check`, `resonon run` and `resonon analyze`. `resonon --help` lists a command's options, and the [CLI reference](https://resonon.org/docs/reference/setup/01-cli/) lists every command. How to check, render and measure a piece is in [Work with Coding Agents](https://resonon.org/docs/how-to/running/11-work-with-coding-agents/). ## Language Source files end in `.non`. A project is a directory with a `resonon.toml`; its piece is `src/main.non`. Statements end with `;`. - **Values.** Number (one type: `5 == 5.0`), String (`"text"`, format string `f"{x}"`), Boolean, `NUL` (no value), Note (`C4` is MIDI 60, `F#3`, `Bb2`), Pattern (`[C4 E4]`), Array (`#[1, 2]`), Dict (`#{"key": 1}`), Tuple (`(1, "a")`), function (`fn(x) { return x * 2; }`). Arrays, dicts and class instances are shared on assignment. - **Strict types.** Conditions, `&&`, `||` and `!` take Booleans only; mixing types in an operator is an error. `+` with a String on one side concatenates. `C4 + 2` transposes a note. - **Names.** `let x = 1;` declares, `x = 2;` assigns, `let (a, b) = (1, 2);` destructures. A name has one `fn`, `class`, `interface`, `enum` or `dsp` definition per file, written at the top level. - **Types.** Types are optional; an unannotated binding stays dynamic. `Array`, `Dict` and `Iterator` are the builtin generics. Array and dict checks inspect contents without converting elements; iterator checks do not consume values. `Any` accepts every value. - **Functions.** `fn name(a, b = 1, ...rest) -> Type { … }`; the last expression is returned when there is no `return`. Named arguments use `:` (`f(b: 2)`). Type annotations are checked where a value crosses them: arguments, returns, `let x: T` and its writes, class fields. `T?` is T or NUL; a parameter that defaults to NUL is written `x: T? = NUL`. - **Control flow.** `if c { … } else { … }` (an expression when both branches are blocks), `loop`, `do N { … }`, `for x in source { … }`, `break`, `continue`, `match x { 1 => …, _ => … }`, `assert c, "message";`. - **Classes and enums.** `class P { let x; fn new(x) { this.x = x; } fn m() { … } }`, constructed as `P(1)`; no inheritance. `enum Style { staccato, legato }`, read as `Style.legato`. - **Conversions.** `fn from(n: Number) -> Hz { … }` in a class converts a value of another type where a `Hz` is asked for: `let h: Hz = 440;`. It is never called directly. A MIDI number is a `Note` this way: `chord(60, "maj")`, `let n: Note = 60.5`. Nothing inside an Array converts. - **Interfaces.** `interface Shape { fn area() -> Number; fn twice() -> Number { … } }`: a method ending in `;` is required, one with a body is a default. `class Sq implements Shape { … }` defines the required methods; its values fit a `Shape` annotation. - **Modules.** `use "std/effects" { Delay, Reverb };` imports names; `use "std/visuals" as gfx;` imports a module, read as `gfx.Noise(…)`; `use "./drums";` loads a file of the project. Names in the prelude are always in scope. - **Output and routing.** `track << pattern;` plays a pattern on a track; `param << value_or_signal;` sets or modulates a parameter. `a >> b` routes track `a`'s output to `b` (`master` by default). - **Transport.** `PLAY;`, `PAUSE;`, `STOP;`, `RESET;` and `SEEK` are statements. - **Comments.** `// line`, `/* block */`, `/// documents the definition below`, `//! documents the file`. ```resonon /// Doubles a number. fn double(x) { x * 2 } let notes = #[C4, E4, G4]; let up = notes.map(fn(n) { return n + 12; }); let label = if up[0] == C5 { "octave up" } else { "other" }; match up.length() { 3 => print(f"{label}: {up}"), _ => print("other length"), } assert double(21) == 42; ``` ## Idioms A drum beat on an audio track, with an effect chain and an LFO on the filter cutoff: ```resonon use "std/instruments" { Sampler, Kit }; use "std/effects" { Lowpass, Delay }; use "std/signals" { Sine }; let drums = AudioTrack("drums"); drums.set_instrument(Sampler(Kit("CR-78"))); drums << [bd [sd bd] bd sd, hh*8]; let filter = Lowpass("lowpass", 800); drums.set_effects(#[filter, Delay("delay", 0.25, 0.4)]); filter.parameter("Cutoff") << Sine(1).range_exp(400, 4000); PLAY; ``` A melody in a key, transformed, with chords on a second track: ```resonon use "std/instruments" { SamplerMelodic, Kit }; let lead = AudioTrack("lead"); lead.set_instrument(SamplerMelodic(Kit("keys"))); lead << [^1 ^3 ^5 ^8].in_key(Key(A3, "minor")).fast(2); let keys = AudioTrack("keys"); keys.set_instrument(SamplerMelodic(Kit("keys"))); keys << ; keys.set_volume(-6); // dB PLAY; ``` MIDI to an external synth or DAW, one track per channel: ```resonon let bass = MidiTrack("bass").set_velocity(90); bass >> MidiOutput("synth", 2); bass << [C2 _ C2 G1]; PLAY; ``` A custom effect written in a `dsp` block (experimental): ```resonon use "std/instruments" { Sampler, Kit }; dsp effect Gain { param level: 1.0 range(0, 2); fn process(left, right) -> (out_l, out_r) { return (left * level, right * level); } } let drums = AudioTrack("drums"); drums.set_instrument(Sampler(Kit("CR-78"))); drums << [bd sd bd sd]; drums.set_effects(#[Gain("gain")]); PLAY; ``` A song arranged from sections: ```resonon use "std/instruments" { Sampler, Kit }; let drums = AudioTrack("drums"); drums.set_instrument(Sampler(Kit("CR-78"))); let verse = section(8); verse[drums] << [bd bd sd bd]; let chorus = verse.clone(); chorus[drums] << [bd sd bd sd]; let song = arrange(#[verse * 2, chorus]); song.play(); ``` A visual operator graph: ```resonon use "std/visuals" as gfx; let field = gfx.Noise("field"); field.parameter("period") << 2.0; let soft = gfx.Blur("soft"); soft.parameter("size") << 16.0; field >> soft >> screen; PLAY; ``` Reading what a pattern plays, as text, without listening: ```resonon let melody = [C4 [E4 G4] ]; print(melody.describe()); print(to_json(notes(melody, 2))); ``` ## Mini-notation grammar Every token that can go inside pattern brackets. The examples below are fragments; a pattern goes to a track like this: ```resonon use "std/instruments" { Sampler, Kit }; let drums = AudioTrack("drums"); drums.set_instrument(Sampler(Kit("TR-808"))); drums << [bd , ch*8, <_ oh>]; PLAY; ``` ### Structure How elements are grouped and how time is divided. | Token | Name | Meaning | | ------------ | ----------------- | ----------------------------------------------------------------------- | | `[ … ]` | Sequence | Elements share the slot, each gets `slot / count`. Nest to subdivide. | | `,` | Parallel groups | Split a bracket into simultaneous voices, each on its own time grid. | | `< … >` | Alternation | One element per cycle, chosen by `cycle % count`; fills the whole slot. | | `{ … }` | Polymetric | Steps per cycle = length of the first group (or `1` for a single group).| | `{ … }%n` | Polymetric ÷ n | Force `n` steps per cycle regardless of group length. | | `_` | Rest | A silent slot. | ```resonon parse-only let sequence = [C4 D4 E4]; // three slots, 1/3 cycle each let nested = [[C4 D4] E4]; // C4,D4 in the first half; E4 in the second let parallel = [C4 D4, E4 F4 G4]; // two voices, 2-against-3 let alt = ; // C4, then D4, then E4 — one per cycle let poly = {C4 D4 C4 E4}%3; // three steps per cycle, phasing over four let with_rest = [C4 _ E4 _]; // notes on slots 1 and 3 ``` A pattern nested in a slot plays exactly what it plays on its own, fitted into the slot. A pattern inside `< … >` advances one cycle each time its turn comes round, so every element of an inner alternation gets played: ```resonon parse-only let turns = < E4>; // C4 E4 D4 E4, then repeats ``` ### Modifiers Postfix timing shorthand on a single element. **At most one per element.** | Token | Name | Effect | Example | Equivalent | | ----- | --------- | --------------------------------------------------- | ----------- | -------------- | | `*n` | Fast | Play `n` times **within** the slot (speeds up) | `bd*2` | `[bd bd]` | | `/n` | Slow | Stretch the element over `n` cycles in the slot | `[C4 D4]/2` | spans 2 cycles | | `@n` | Weight | Take an `n×` share of the cycle (plays once, longer)| `bd@2 sd` | bd 2/3, sd 1/3 | | `!n` | Replicate | Expand into `n` separate slots at normal speed | `bd!3` | `bd bd bd` | ```resonon parse-only let fast = [bd sd*2]; // sd plays twice inside its half let slow = [/2 E4]; // the alternation advances every 2 cycles let weighted = [C4@3 D4]; // long C4, quick D4 let replicate = [bd!4]; // same as [bd bd bd bd] ``` `*n`, `/n`, and `@n` accept decimals (`*1.5`, `@2.5`). `*n` and `/n` take 0.0001 to 10000, the range of `.fast()` and `.slow()`; `@n` must be greater than 0 (`_` is a rest); `!n` takes integers only. ### Decorations Postfixes that shape *what* an element plays. These combine with each other and with a modifier. | Token | Name | Meaning | | ------------- | -------------- | ------------------------------------------------------------------- | | `^v` | Velocity | Strike velocity `1`–`127`, e.g. `C4^120`; `^0` plays at `1`. | | `(k,n)` | Euclidean | `k` pulses spread over `n` steps. | | `(k,n,r)` | Euclidean + rot| As above, rotated left by `r` steps, modulo `n`. | | `Root:Quality`| Chord | A chord, e.g. `C4:maj7`; add `~i` for inversion `i` (`C4:maj7~1`), `~-i` to invert downwards (`C4:maj~-1`). | | `^N` | Scale degree | Degree `N` of the current scale/key (see [Write in a Key](https://resonon.org/docs/how-to/patterns/08-write-in-a-key/)). | | `^N:Quality` | Degree chord | A chord built on scale degree `N`, with an optional `~i`. | | `^N:` | Diatonic chord | The key's own triad on degree `N`; `^N:~i` inverts it. | | `^bN`, `^#N` | Altered degree | Degree `N` a semitone lower or higher, e.g. `^b3`, `^#4`, `^b-2`. As a chord root it names its quality: `^b6:maj`. | | `.method(…)` | Sample method | Shape one sample hit; chains, e.g. `bd.vel(0.8).pan(0.5)`. | ```resonon parse-only let accented = [C4^120 C4^60 C4^60 C4^60]; // accent on beat 1 let euclid = [bd(3,8) sd(5,8,2)]; // euclidean kick + rotated snare let chords = [D4:min7 G4:7 C4:maj7~1]; // ii–V–I, last chord inverted let degrees = [^1 ^3 ^5 ^3]; // arpeggio over the current scale let diatonic = [^1: ^4: ^5:~1]; // the key's triads, the last inverted let borrowed = [^1: ^b6:maj ^b7:maj ^1:]; // bVI and bVII, borrowed from the parallel minor let lower = [c4 e4:min~-1]; // lower case; E minor inverted downwards let shaped = [bd.gain(1.2) sd.pitch(-5).pan(0.5)]; ``` ### Combining Order When several postfixes attach to one element they appear in a fixed order: ```txt element velocity euclid modifier C4 ^80 (3,8) *2 ``` So `C4^80(3,8)*2` is valid; reordering the postfixes is not. ### Element Types What can sit in a slot: | Kind | Examples | Notes | | ----------- | --------------------------------- | -------------------------------------------------- | | Note | `C4`, `F#3`, `Bb-1`, `g9` | Scientific pitch; octaves `-1`–`9` (C4 = MIDI 60). Upper or lower case inside a pattern; upper case only outside one. | | Number | `60`, `-5`, `0.5` | Raw values for numeric patterns and automation. | | Sample | `bd`, `sd`, `hh` | Kit sample names; accept `.method(…)` postfixes. | | Chord | `C4:maj`, `a3:min7` | See the [chord qualities](https://resonon.org/docs/reference/patterns/03-scales-chords-intervals/#chord-qualities). Only inside a pattern; outside one, use `chord()`. | | Scale degree| `^1`, `^-3`, `^b3`, `^5:min`, `^2:`| Resolved against the active scale/key. | | Rest | `_` | Silence for one slot. | ### Polymetric Groups `{ … }` gives every element one step. `%n` sets the steps per cycle; without it, a group has as many steps per cycle as its first voice has elements, or `1` for a group with one voice. A voice of `L` elements over `N` steps runs at `N / L` passes per cycle, and wraps when the two don't divide. | Pattern | Steps/cycle | Voice lengths | Passes/cycle | | ------------------- | ----------- | ------------- | ---------------- | | `{C4 D4 E4}` | 1 | 3 | 1/3 | | `{C4 D4 E4}%3` | 3 | 3 | 1 — as `[C4 D4 E4]` | | `{C4 D4 E4}%6` | 6 | 3 | 2 | | `{C4 E4 G4, F4 A4}` | 3 | 3, 2 | 1, 3/2 | Voices in `{ … }` share one grid of steps; voices in `[ … , … ]` each divide the cycle by their own length. ### Euclidean Rhythms `(k,n)` spreads `k` hits over `n` steps as evenly as possible, inside the element's slot; the element sounds on the hits and rests on the other steps. `(k,n,r)` rotates the result left by `r` steps, modulo `n`. Like every modifier and decoration, `(k,n)` belongs to an element inside brackets: write `[(5,16)]`, not `(5,16)`. Outside brackets the same rhythm is the method `.euclid(5,16)`. | Rotation | `(3,8,r)` | Hit steps | | -------- | ----------------- | --------- | | 0 | `x . . x . . x .` | 0, 3, 6 | | 2 | `. x . . x . x .` | 1, 4, 6 | | 3 | `x . . x . x . .` | 0, 3, 5 | Traditional cells written this way: | Pattern | Hits | Name | | -------- | --------------------------------- | ---------- | | `(3,4)` | `x x x .` | Cumbia | | `(3,8)` | `x . . x . . x .` | Tresillo | | `(5,8)` | `x . x x . x x .` | Cinquillo | | `(5,16)` | `x . . x . . x . . x . . x . . .` | Bossa nova | | `(7,16)` | `x . . x . x . x . . x . x . x .` | Samba | ### See Also - [Your First Groove](https://resonon.org/docs/tutorials/patterns/02-your-first-groove/) — the same syntax, step by step - [Polymeter & Euclidean Rhythm](https://resonon.org/docs/explanation/patterns/04-polymeter-and-euclidean-rhythm/) — phasing meters and euclidean rhythms - [Pattern methods](https://resonon.org/docs/reference/stdlib/patterns/) — `.fast()`, `.slow()`, `.reverse()` and the rest of the method API - [Scales, Chords & Intervals](https://resonon.org/docs/reference/patterns/03-scales-chords-intervals/) — chord qualities and scale names ## Standard library Each entry is a signature and the first sentence of its documentation. A class lists its constructor, its conversion and its methods under it. ### std/core **Always in scope** — no import required. #### Array - class `Array` implements `Clone` — Ordered collection of values. - `fn length() -> Number` — Returns the number of elements. - `fn push(value: Any) -> Array` — Adds an element to the end of the array. - `fn pop() -> Any` — Removes and returns the last element. - `fn get(index: Number) -> Any` — Returns the element at the given index. - `fn slice(start: Number, end: Number) -> Array` — Returns a subarray from start (inclusive) to end (exclusive). - `fn concat(other: Array) -> Array` — Returns a new array with elements from both arrays. - `fn reverse() -> Array` — Returns a new array with elements in reverse order. - `fn contains(value: Any) -> Boolean` — Returns true if the array contains the given value. - `fn map(func: Function) -> Array` — Applies a function to each element, returns a new array. - `fn filter(func: Function) -> Array` — Returns a new array with only elements satisfying the predicate. - `fn reduce(func: Function, initial: Any) -> Any` — Reduces the array to a single value. - `fn iter() -> Iterator` — Returns an iterator over the array elements. - `fn concat(array1: Array, array2: Array) -> Array` — Concatenates two arrays. - `fn filter(array: Array, func: Function) -> Array` — Selects elements from an array that satisfy a predicate. - `fn fold(array: Array, initial: Any, func: Function) -> Any` — Reduces an array to a single value using an accumulator function. - `fn length(array: Array) -> Number` — Returns the number of elements in an array. - `fn map(array: Array, func: Function) -> Array` — Transforms each element of an array using a function. - `fn range(start_or_end: Number, end: Number? = NUL) -> Array` — Generates an array of sequential numbers. - `fn slice(array: Array, start: Number, end: Number) -> Array` — Extracts a subarray from start index to end index. #### String - class `String` — Text value with Unicode support. - `fn length() -> Number` — Returns the character count (Unicode-aware). - `fn uppercase() -> String` — Returns the string converted to uppercase. - `fn lowercase() -> String` — Returns the string converted to lowercase. - `fn substring(start: Number, end: Number) -> String` — Returns a substring from start to end (Unicode-aware). - `fn split(delimiter: String) -> Array` — Splits the string by a delimiter, returns an array of strings. - `fn contains(needle: String) -> Boolean` — Returns true if the string contains the given substring. - `fn trim() -> String` — Returns the string with leading and trailing whitespace removed. - `fn replace(old: String, new: String) -> String` — Returns the string with all occurrences of old replaced with new. - `fn starts_with(prefix: String) -> Boolean` — Returns true if the string starts with the given prefix. - `fn ends_with(suffix: String) -> Boolean` — Returns true if the string ends with the given suffix. - `fn repeat(n: Number) -> String` — Returns a new string by repeating this string n times. - `fn iter() -> Iterator` — Returns an iterator over the characters. #### Dict - class `Dict` implements `Clone` — Key-value mapping with String or Number keys. - `fn get(key: String | Number) -> Any` — Returns the value for the given key, or NUL if not found. - `fn set(key: String | Number, value: Any) -> Dict` — Sets a key-value pair in place. - `fn remove(key: String | Number) -> Any` — Removes a key in place. - `fn keys() -> Array` — Returns an Array of all keys. - `fn values() -> Array` — Returns an Array of all values. - `fn length() -> Number` — Returns the number of entries. - `fn contains_key(key: String | Number) -> Boolean` — Returns true if the dict contains the given key. - `fn entries() -> Array>` — Returns an Array of [key, value] pairs. - `fn merge(other: Dict) -> Dict` — Returns a new dict with entries from both dicts merged. - `fn map(func: Function) -> Dict` — Transforms values using a function. - `fn filter(func: Function) -> Dict` — Filters entries by predicate. - `fn reduce(func: Function, initial: Any) -> Any` — Reduces entries to a single value. - `fn iter() -> Iterator` — Returns an Iterator over the keys. #### Iterator - class `Iterator` — Lazy sequence of values with chainable transformations. - `fn next() -> Any` — Returns the next value, or `NUL` if exhausted. - `fn take(n: Number) -> Iterator` — Returns a lazy iterator yielding the first n elements. - `fn collect() -> Array` — Collects all remaining elements into an array. - `fn skip(n: Number) -> Iterator` — Returns a lazy iterator that skips the first n elements. - `fn count() -> Number` — Counts remaining elements (consumes the iterator). - `fn step_by(step: Number) -> Iterator` — Returns a lazy iterator yielding every nth element. - `fn enumerate() -> Iterator` — Returns a lazy iterator yielding [index, value] pairs. - `fn first() -> Any` — Returns the first element, or `NUL` if empty. - `fn last() -> Any` — Returns the last element, or `NUL` if empty. - `fn map(func: Function) -> Iterator` — Returns a lazy iterator applying a function to each element. - `fn filter(func: Function) -> Iterator` — Returns a lazy iterator yielding the elements that match the predicate. - `fn find(func: Function) -> Any` — Returns the first element matching the predicate, or `NUL`. - `fn any(func: Function) -> Boolean` — Returns true if any element matches the predicate. - `fn all(func: Function) -> Boolean` — Returns true if all elements match the predicate. - `fn fold(initial: Any, func: Function) -> Any` — Folds the iterator to a single value. - `fn zip(other: Iterator) -> Iterator` — Zips this iterator with another, yielding [a, b] pairs. - `fn chain(other: Iterator) -> Iterator` — Chains another iterator after this one. - `fn flatten() -> Array` — Flattens nested arrays into a single array. #### Tuple - class `Tuple` implements `Clone` — Fixed-size, immutable, ordered group of values. - `fn length() -> Number` — Returns the number of elements. - `fn get(index: Number) -> Any` — Returns the element at the given index, like `t[index]`. #### Clone - interface `Clone` — A value that can make an independent copy of itself with `.clone()`. - `fn clone() -> Self` — Returns an independent copy: a change to the copy is not seen through the original, nor the other way round. #### Utilities - `fn clock() -> Number` — Returns time in nanoseconds from an arbitrary reference point. - `fn hostname() -> String` — Returns this machine's hostname. - `fn load_file(path: String) -> String` — Reads a text file and returns its contents as a String. - `fn print(value: Any, newline: Boolean = true) -> NUL` — Writes a value to the output, followed by a newline. - `fn put(value: Any) -> NUL` — Writes a value to the output with no trailing newline. - `fn reload_ext(name: String) -> NUL` — Reloads a native extension from disk. - `fn reload_preferences() -> NUL` — Re-reads `~/.resonon/preferences.toml` and applies whatever changed. - `fn show(value: Any = NUL) -> NUL` — Displays detailed information about a value. - `fn sleep(seconds: Number) -> NUL` — Lets the piece play for the given number of seconds before the next statement runs. - `fn to_json(value: Boolean | Number | String | Array | Tuple | Dict?) -> String` — Returns the JSON text of a value, on one line. - `fn type(value: Any = NUL) -> String` — Returns the type name of a value as a string. #### Math - `fn abs(x: Number) -> Number` — Absolute value. - `fn ceil(x: Number) -> Number` — Smallest integer greater than or equal to the value. - `fn clamp(x: Number, lo: Number, hi: Number) -> Number` — Constrains a value to the inclusive range [lo, hi]. - `fn cos(x: Number) -> Number` — Cosine of an angle in radians. - `fn exp(x: Number) -> Number` — Exponential function (e raised to the power x). - `fn floor(x: Number) -> Number` — Largest integer less than or equal to the value. - `fn fract(x: Number) -> Number` — Fractional part of the value (the part after the decimal point). - `fn ftom(freq: Number) -> Number` — Converts a frequency in Hz to a MIDI note number. - `fn lerp(a: Number, b: Number, t: Number) -> Number` — Linearly interpolates between two values. - `fn log(x: Number) -> Number` — Natural logarithm (base e). - `fn log10(x: Number) -> Number` — Base-10 logarithm. - `fn log2(x: Number) -> Number` — Base-2 logarithm. - `fn max(a: Number, b: Number) -> Number` — Larger of two numbers. - `fn min(a: Number, b: Number) -> Number` — Smaller of two numbers. - `fn mtof(note: Number) -> Number` — Converts a MIDI note number to frequency in Hz. - `fn pow(base: Number, exponent: Number) -> Number` — Raises a base to a power. - `fn round(value: Number, places: Number = 0) -> Number` — Rounds a number to the given number of decimal places. - `fn sin(x: Number) -> Number` — Sine of an angle in radians. - `fn sqrt(x: Number) -> Number` — Square root. - `fn tan(x: Number) -> Number` — Tangent of an angle in radians. - `fn tanh(x: Number) -> Number` — Hyperbolic tangent. #### Durations - class `Duration` — A length of time in the unit it was written in: cycles, beats or seconds. - `fn dotted() -> Duration` — Returns the duration half again as long: a dotted note value. - `fn triplet() -> Duration` — Returns the duration two thirds as long: a triplet note value, three in the space of two. - `fn beats(n: Number) -> Duration` — A duration in beats. - `fn cycles(n: Number) -> Duration` — A duration in cycles. - `fn ms(n: Number) -> Duration` — A duration in milliseconds. - `fn note(num: Number, den: Number) -> Duration` — A note value: `num / den` of a whole note, which is four beats. - `fn seconds(n: Number) -> Duration` — A duration in seconds. ### std/audio **Always in scope** — no import required. #### Tracks & Master - class `AudioTrack` — A track in the audio engine for sample playback and routing. - `fn set_instrument(instrument: Instrument) -> AudioTrack` — Sets the instrument on this track. - `fn instrument() -> Instrument?` — Returns the instrument currently attached to this track. - `fn remove_instrument() -> AudioTrack` — Detaches the instrument from this track, leaving it with none. - `fn set_effects(effects: Array) -> AudioTrack` — Declaratively sets the whole effect chain, reconciling the live graph. - `fn effects() -> Array` — Returns an array of all effects in chain order. - `fn effect(name: String) -> Effect` — Returns a modulatable handle to an effect by its slot name. - `fn set_send(destination: AudioTrack | Master, amount: Number | Signal | Pattern) -> AudioTrack` — Adds a parallel aux send to the given destination, leaving the output edge untouched. - `fn send(destination: AudioTrack | Master) -> SendParam` — Returns a modulatable handle to an existing send's level. - `fn delete() -> NUL` — Deletes the track and releases its resources. - `fn routing_report() -> NUL` — Displays detailed routing info for this track. - `fn set_volume(value: Number) -> AudioTrack` — Sets track volume. - `fn set_pan(value: Number) -> AudioTrack` — Sets track pan. - `fn mute() -> AudioTrack` — Mutes the track, like Live's Track Activator. - `fn unmute() -> AudioTrack` — Unmutes the track. - `fn is_muted() -> Boolean` — Returns whether the track is muted. - `fn solo() -> AudioTrack` — Solos the track, and only this track: every other solo is released, as a plain click on Live's Solo button. - `fn add_solo() -> AudioTrack` — Adds the track to the soloed tracks and keeps the others soloed, as a Cmd-click on Live's Solo button. - `fn unsolo() -> AudioTrack` — Releases the track's solo. - `fn is_soloed() -> Boolean` — Returns whether the track is soloed. - `fn set_input(channel: Number, right: Number? = NUL) -> AudioTrack` — Sets the hardware input channels for monitoring and recording. - `fn set_delay(ms: Number) -> AudioTrack` — Sets this track's output delay, to line it up with outboard gear. - `fn delay() -> Number` — Returns this track's output delay in milliseconds, as set by `set_delay`. - `fn arm() -> AudioTrack` — Arms the track for recording. - `fn disarm() -> AudioTrack` — Disarms the track, stopping recording. - `fn set_monitor(mode: Monitor) -> AudioTrack` — Sets the input monitoring mode. - `fn is_armed() -> Boolean` — Returns true if this track is armed for recording. - `fn is_recording() -> Boolean` — Returns true if this track is currently capturing audio. - `fn take() -> AudioClip?` — Collects one recorded pass as an AudioClip. - `fn reset_routing() -> AudioTrack` — Resets the track's routing: output back to master, every send removed. - `fn save(path: String) -> AudioTrack` — Saves the track's audio to a file. - `fn punch(in_cycle: Number, out_cycle: Number) -> AudioTrack` — Sets punch-in and punch-out points for time-bounded recording. - `fn punch_in(cycle: Number) -> AudioTrack` — Sets only the punch-in point. - `fn punch_out(cycle: Number) -> AudioTrack` — Sets only the punch-out point. - `fn clear_punch() -> AudioTrack` — Clears all punch points from this track. - `fn is_punched() -> Boolean` — Returns true if this track has punch points configured. - `fn set_velocity(vel: Number | Signal | Pattern) -> AudioTrack` — Sets the velocity for notes played on this track. - `fn set_tuning(bend_range: Number? = NUL) -> AudioTrack` — Enable microtonal pitch bend output. - `fn set_mpe(range: Number? = NUL, zone_lo: Number? = NUL, zone_hi: Number? = NUL) -> AudioTrack` — Enable MPE (per-note channel allocation) for polyphonic microtonal output. - `fn set_key(scale: Key | String | Scale, root: Note? = NUL) -> AudioTrack` — Set a track-level key for degree resolution and auto-quantization. - class `Master` — The master output bus. - `fn set_effects(effects: Array) -> Master` — Declaratively sets the whole effect chain, reconciling the live graph. - `fn effects() -> Array` — Returns an array of all effects in chain order. - `fn effect(name: String) -> Effect` — Returns a modulatable handle to an effect by its slot name. - `fn set_volume(value: Number) -> Master` — Sets master volume. - `fn set_pan(value: Number) -> Master` — Sets master pan. - class `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)`). - `fn smooth(attack_ms: Number, release_ms: Number? = NUL) -> MeterFeed` — Smooths the level so it glides instead of strobing. - `fn range(min: Number, max: Number) -> MeterFeed` — Maps the 0-to-1 level linearly onto [min, max]. - class `Nowhere` — Nowhere: a track's output that goes nowhere. - class `SpectrumFeed` — A live spectrum from a track or the master (`track.fft`), bound to a shader texture with `<<`. - `fn smooth(attack_ms: Number, release_ms: Number? = NUL) -> SpectrumFeed` — Smooths every bin so the spectrum glides between analysis frames. - `fn band(low_hz: Number, high_hz: Number) -> MeterFeed` — Reduces a frequency band to a single level. - enum `Monitor` { off, input, auto } — When a track's input is heard: Live's Monitor In / Auto / Off. #### Parameters - class `Bezier` — An automation segment shaped as a cubic Bezier curve, as CSS's `cubic-bezier()`. - class `EffectParam` implements `Parameter` — A parameter of an effect, obtained via `effect.parameter("name")`. - class `InstrumentParam` implements `Parameter` — A parameter of an instrument, obtained via `instrument.parameter("name")`. - class `MasterParam` implements `Parameter` — The master bus fader, `master.volume` (in dB) or `master.pan`. - class `ParamList` — Wraps an array of parameter dicts from `.parameters()`. - `fn filter(name: String) -> ParamList` — Filters parameters by name substring, case-insensitive; returns a new ParamList. - `fn length() -> Number` — Returns the number of parameters. - `fn get(index: Number) -> Dict` — Returns the parameter dict at the given index. - interface `Parameter` — A parameter a musician sets, modulates and automates: an effect's or an instrument's, a track's or the master's fader, a send's level. - `fn get() -> Number` — Gets the parameter's current value. - `fn set(values: Number | Signal | Pattern | Array) -> Parameter` — Sets the parameter's value. - `fn set_norm(value: Number) -> Parameter` — Sets the parameter by a fraction of its range. - class `SendParam` implements `Parameter` — The level of one send, from `track.send(destination)`: 0.0 to 1.0. - class `TrackParam` implements `Parameter` — An audio track's fader, `track.volume` (in dB: 0 = unity, -70 = mute, +6 the most) or `track.pan` (-1.0 = hard left, 1.0 = hard right). - enum `Curve` { linear, step, exp, smooth, ease_in, ease_out, ease_in_out, ease } — The shape of an automation segment, from its breakpoint to the next one. #### Plugins - class `DspInstrument` implements `Instrument` — An instrument a `dsp instrument` definition makes: `Pad()` for `dsp instrument Pad { ... - `fn set_parameter(name: String, value: Number) -> DspInstrument` — Sets a parameter value by name. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList of the instrument's parameters, headed by its name. - class `Effect` — An audio effect processor. - `fn Effect(name: String, plugin: String, plugin_id: String? = NUL) -> Effect` — Loads an effect plugin (CLAP or VST3). - `fn name() -> String` — Returns the slot name of this effect. - `fn parameter(name: String) -> EffectParam` — Returns a parameter reference for the named parameter. - `fn set_parameter(name: String, value: Number) -> Effect` — Sets a parameter value by name in its native range. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList of all effect parameters. - `fn supports_gui() -> Boolean` — Returns whether this effect supports a graphical user interface. - `fn show_gui() -> NUL` — Opens the plugin GUI window. - `fn hide_gui() -> NUL` — Closes the plugin GUI window. - `fn save_state(path: String) -> Effect` — Saves the effect's state to a preset file. - `fn load_state(path: String) -> Effect` — Loads a preset file into the effect. - `fn connect_input(name: String, source: AudioTrack) -> Effect` — Connects a named sidechain input port to a source audio track. - `fn programs() -> Array` — Lists all program/preset names built into the plugin. - `fn set_program(index: Number) -> Effect` — Selects a factory program/preset by index. - `fn backend() -> String` — Returns the plugin backend type ("CLAP", "VST3", or "dsp"). - interface `Instrument` — An instrument: what a track plays its notes through. - `fn name() -> String` — Returns the instrument's name: a plugin's as written before placement and as the live instrument reports it after, a `dsp instrument`'s definition name, a sampler's kit name. - `fn parameter(name: String) -> InstrumentParam` — Returns a parameter reference by name. - `fn set_parameter(name: String, value: Number) -> Instrument` — Sets a parameter value by name. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList of the instrument's parameters. - class `PluginInstrument` implements `Instrument` — A plugin instrument, CLAP or VST3, from `Instrument("Surge XT")`. - `fn set_parameter(name: String, value: Number) -> PluginInstrument` — Sets a parameter value by name. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList of all instrument parameters. - `fn backend() -> String` — Returns the plugin format ("CLAP" or "VST3"). - `fn supports_gui() -> Boolean` — Returns true if the plugin supports a GUI window. - `fn show_gui() -> NUL` — Opens the plugin GUI window. - `fn hide_gui() -> NUL` — Closes the plugin GUI window. - `fn save_state(path: String) -> PluginInstrument` — Saves the plugin state to a preset file. - `fn load_state(path: String) -> PluginInstrument` — Loads a preset file into the plugin. - `fn programs() -> Array` — Returns the list of plugin program names. - `fn set_program(index: Number) -> PluginInstrument` — Switches to a program by index. - class `PluginList` — Wraps an array of plugin dicts from `plugin_scan()`. - `fn filter(name: String) -> PluginList` — Filters plugins by name substring, returns a new PluginList. - `fn length() -> Number` — Returns the number of plugins. - `fn get(index: Number) -> Dict` — Returns the plugin dict at the given index. - `fn Instrument(name: String, plugin_id: String? = NUL) -> PluginInstrument` — Describes an instrument plugin (CLAP or VST3). - `fn plugin_rescan(path: String) -> PluginList` — Re-opens one plugin bundle, whatever the plugin cache already says about it. - `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. #### Audio clips - class `AudioClip` — A reference into recorded audio: marker, length and arrangement position. - `fn save(path: String) -> AudioClip` — Saves the clip to a WAV file. - `fn duration() -> Number` — Returns the duration of the clip in seconds. - `fn samples() -> Number` — Returns the total number of samples in the clip. - `fn sample_rate() -> Number` — Returns the sample rate of the clip's audio. - `fn position() -> Number?` — Returns where the clip sits in the arrangement, in cycles. - `fn left() -> Array` — Returns the left channel as an array of sample values. - `fn right() -> Array` — Returns the right channel as an array of sample values. - `fn mono() -> Array` — Returns a mono mixdown as an array of sample values. #### Events - class `Event` — A single note with pitch, velocity, and timing. - `fn note() -> Number` — Returns the MIDI note number. - `fn velocity() -> Number` — Returns the velocity the note plays at (1-127). - `fn start() -> Number` — Returns the start time in cycles. - `fn duration() -> Number` — Returns the duration in cycles. - `fn end() -> Number` — Returns the end time (start + duration). - `fn transpose(semitones: Number) -> Event` — Returns a new event transposed by the given number of semitones. - `fn detune(cents: Number) -> Event` — Returns a new event detuned by the given number of cents (100 = one semitone). - `fn ratio(ratio: Number) -> Event` — Returns a new event with its note's frequency scaled by the given ratio. #### Notes - class `Note` — A single MIDI pitch in semitones, fractional for microtonal values. - converts: `fn from(n: Number) -> Note` — A MIDI note number is a Note wherever a Note is asked for: `chord(60, "maj")`, `let n: Note = 60.5`. - `fn transpose(semitones: Number) -> Note` — Returns a new note transposed by the given number of semitones. - `fn detune(cents: Number) -> Note` — Returns a new note detuned by the given number of cents (100 = one semitone). - `fn ratio(ratio: Number) -> Note` — Returns a new note with its frequency scaled by the given ratio. #### Audio I/O - class `Output` — Output: hardware output channels of the audio device, a destination for `>>`. - `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. - `fn AudioTrack(name: String) -> AudioTrack` — Creates an audio track with the given name. - `fn arrange(sections: Array) -> Timeline | Section` — Sequences clips and arrangements back-to-back into one Timeline, or sections into one Section. - `fn audio_buffer_size() -> Number` — The number of frames the audio device delivers per callback. - `fn audio_cpu_load() -> Dict` — Returns a dict with audio CPU load information. - `fn audio_input_devices() -> Array>` — Lists the devices this machine can record from. - `fn audio_latency() -> Dict` — Returns a dict with audio latency information. - `fn audio_output_devices() -> Array>` — Lists the devices this machine can play through. - `fn audio_sample_rate() -> Number` — The sample rate the audio output is running at, in Hz. - `fn list_snapshots() -> Array>` — Lists the `save_project()` snapshots retained under `.history/`, newest first. - `fn load_project(snapshot: Number | String? = NUL) -> NUL` — Restores plugin GUI state previously written by `save_project()`. - `fn midi_export(source: Pattern | Timeline | MidiTrack | Array, cycles: Number, path: String? = NUL) -> String` — Exports a pattern, timeline, MIDI track or array of MIDI tracks to a Standard MIDI File (.mid). - `fn notes(source: Pattern | Timeline | MidiTrack | Array, cycles: Number, start_cycle: Number? = NUL) -> Array>` — Lists the notes a pattern, timeline, MIDI track or array of MIDI tracks plays, as data. - `fn recording_offset() -> Number` — Returns the recording latency residual in milliseconds. - `fn render(target: AudioTrack | Master | Screen | Array | Number, cycles: Number? = NUL) -> NUL` — Renders audio and/or the routed visual offline for the given number of cycles. - `fn render_master(cycles: Number) -> NUL` — Renders the master output to a WAV file. - `fn routing_report(...tracks: AudioTrack) -> NUL` — Displays the current audio routing graph. - `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. - `fn scope(signal: Signal, label: String = "") -> NUL` — Registers a signal for visualization in the scope TUI view. - `fn scope_clear() -> NUL` — Removes all signals from the scope view. - `fn scope_remove(signal: Signal) -> NUL` — Removes a signal from the scope view. - `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`. - `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. - `fn set_project_artist(artist: String) -> NUL` — Sets the project artist name. - `fn set_project_title(title: String) -> NUL` — Sets the project title. - `fn timeline(length: Number) -> Timeline` — Creates a mutable timeline builder for placing patterns along a lane. #### Timelines - class `LaneLayer` — One named layer of a lane, from `.layer(name)` on any lane. - `fn at(start: Number, duration: Number) -> TimelineSlot | SectionParam | SectionVisual` — Addresses a span of this layer for a `<<` write. - `fn mute() -> LaneLayer` — Silences the whole layer without destroying it. - `fn unmute() -> LaneLayer` — Brings a muted layer back. - `fn clear() -> LaneLayer` — Drops every entry on this layer. - class `Timeline` implements `Clone` — A single lane of patterns placed at positions along it. - `fn at(start: Number, duration: Number) -> TimelineSlot` — Addresses a span of the timeline for a `<<` write. - `fn length() -> Number` — Returns the timeline length. - `fn entry_count() -> Number` — Returns how many entries have been written, on every layer. - `fn entries() -> Array>` — Returns the entries as written — the base first, then each layer — not the flattened result. - `fn repeat(n: Number) -> Timeline` — Returns a new timeline holding `n` back-to-back copies of this one; the receiver is untouched. - `fn layer(name: String) -> LaneLayer` — Addresses one named layer. - `fn layers() -> Array>` — Returns the layer stack, bottom-to-top (`base` first). - `fn set_layer_order(names: Array) -> Timeline` — Restacks the layers above `base`, bottom-to-top. - `fn clear() -> Timeline` — Drops every layer above `base`, leaving what `arrange` laid down. - `fn clear_all() -> Timeline` — Empties the timeline: every layer, `base` included. - class `TimelineSlot` — A span of a note lane, from `.at(start, duration)`. - `fn clear() -> TimelineSlot` — Drops the entry that starts at this slot's start on this slot's layer, bringing back what it was masking. #### Sections - class `Section` implements `Clone` — A multi-track arrangement: one lane per track, plus automation and screen lanes. - `fn length() -> Number` — Returns the section length. - `fn track_count() -> Number` — Returns how many tracks have a note lane. - `fn tracks() -> Array` — Returns the tracks that have a note lane. - `fn repeat(n: Number) -> Section` — Returns a new section holding `n` back-to-back copies of this one; the receiver is untouched. - `fn play() -> Section` — Binds every lane — notes, automation, screen — and plays from the top. - class `SectionEffect` — An effect on a section lane's track, from `sec[track].effect(name)`. - `fn parameter(name: String) -> SectionParam` — Addresses one of the effect's parameters as an automation lane. - class `SectionLane` — A track's note lane in a section, from `sec[track]`. - `fn at(start: Number, duration: Number) -> TimelineSlot` — Addresses a span of the lane for a `<<` write. - `fn entry_count() -> Number` — Returns how many entries have been written, on every layer. - `fn entries() -> Array>` — Returns the entries as written — the base first, then each layer — not the flattened result. - `fn effect(name: String) -> SectionEffect` — Addresses an effect on this lane's track, by slot name, for automation. - `fn layer(name: String) -> LaneLayer` — Addresses one named layer. - `fn layers() -> Array>` — Returns the layer stack, bottom-to-top (`base` first). - `fn set_layer_order(names: Array) -> SectionLane` — Restacks the layers above `base`, bottom-to-top. - `fn clear() -> SectionLane` — Drops every layer above `base`, leaving what the section laid down. - `fn clear_all() -> SectionLane` — Empties the lane: every layer, `base` included. - class `SectionParam` — An automation lane in a section, from `sec[track].volume`, `.pan`, or `sec[track].effect(name).parameter(name)`. - `fn at(start: Number, duration: Number) -> SectionParam` — Narrows the next `<<` write to a span of the lane. - `fn entry_count() -> Number` — Returns how many curves have been written, on every layer. - `fn entries() -> Array>` — Returns the curves as written — the base first, then each layer — not the flattened result. - `fn layer(name: String) -> LaneLayer` — Addresses one named layer. - `fn layers() -> Array>` — Returns the layer stack, bottom-to-top (`base` first). - `fn set_layer_order(names: Array) -> SectionParam` — Restacks the layers above `base`, bottom-to-top. - `fn clear() -> SectionParam` — Drops every layer above `base` — or, after `.at(start, duration)`, just the curve that starts there. - `fn clear_all() -> SectionParam` — Empties the lane: every layer, `base` included. - class `SectionVisual` *(experimental)* — The screen lane of a section, from `sec[screen]`. - `fn at(start: Number, duration: Number) -> SectionVisual` — Narrows the next `<<` write to a span of the lane. - `fn entry_count() -> Number` — Returns how many visuals have been written, on every layer. - `fn entries() -> Array>` — Returns the visuals as written — the base first, then each layer — not the flattened result. - `fn layer(name: String) -> LaneLayer` — Addresses one named layer. - `fn layers() -> Array>` — Returns the layer stack, bottom-to-top (`base` first). - `fn set_layer_order(names: Array) -> SectionVisual` — Restacks the layers above `base`, bottom-to-top. - `fn clear() -> SectionVisual` — Drops every layer above `base` — or, after `.at(start, duration)`, just the visual that starts there. - `fn clear_all() -> SectionVisual` — Empties the lane: every layer, `base` included. ### std/patterns **Always in scope** — no import required. - interface `Pattern` — A MIDI note pattern for sequencing. - `fn query(cycle: Number) -> Note | Number | Rest | Array | Pattern?` — Returns what the pattern plays in one cycle. - `fn fast(factor: Number | Pattern) -> Pattern` — Speeds up the pattern by the given factor. - `fn slow(factor: Number | Pattern) -> Pattern` — Slows down the pattern by the given factor. - `fn transpose(semitones: Number | Pattern) -> Pattern` — Transposes all notes by the given number of semitones. - `fn reverse() -> Pattern` — Reverses the pattern playback order. - `fn rotate(steps: Number) -> Pattern` — Rotates the pattern by the given number of steps. - `fn stack(other: Pattern | Note | Array) -> Pattern` — Stacks this pattern with another (polyphonic layering). - `fn concat(other: Pattern | Note | Array) -> Pattern` — Concatenates this pattern with another sequentially. - `fn degrade(probability: Number | Pattern) -> Pattern` — Randomly removes events with the given probability. - `fn describe() -> String` — Returns a string description of the pattern structure. - `fn length() -> Number` — Returns the number of events in cycle 0. - `fn iter() -> Iterator` — Returns an infinite iterator over pattern events. - `fn map(func: Function) -> Pattern` — Transforms each event using a function. - `fn map_with_timing(func: Function) -> Pattern` — Transforms events with timing information. - `fn at(index: Number) -> Pattern` — Returns the element at the given index (for indexable patterns). - `fn euclid(hits: Number, steps: Number, rotation: Number? = NUL) -> Pattern` — Applies a Euclidean rhythm to the pattern. - `fn nudge(offsets: Number | Array | Pattern) -> Pattern` — Shifts individual events by per-event offsets. - `fn swing(amount: Number | Pattern, grid: Number) -> Pattern` — Delays every second slot of a grid, like a drum machine's swing: whatever plays on the off-beat 8th or 16th plays late, and what plays on the beat stays. - `fn humanize(amount: Number | Pattern) -> Pattern` — Adds slight random timing variations for human feel. - `fn kind() -> String` — Returns the concrete pattern kind ("Sequence", "Stack", "Fast", etc.). - `fn elements() -> Array` — Returns sub-patterns as an array. - `fn in_key(key: Key) -> Pattern` — Resolves degree elements (^N, ^N:quality) to MIDI notes using a Key. - `fn quantize(key: Key) -> Pattern` — Snaps all MIDI pitches to the nearest tone in the key's scale. - `fn Alternating(...elements: Pattern | Note | Array) -> Pattern` — Creates an alternating pattern (one element per cycle). - `fn Sequence(...notes: Pattern | Note | Array) -> Pattern` — Creates a sequential pattern that plays notes one after another. - `fn Stack(...notes: Pattern | Note | Array) -> Pattern` — Creates a stacked/layered pattern (chord). - `fn euclid(hits: Number, steps: Number, pattern: Pattern | Note | Array, rotation: Number? = NUL) -> Pattern` — Creates a Euclidean rhythm pattern. - `fn viz(pattern: Pattern | Note | Array, cycles: Number? = NUL, start_cycle: Number? = NUL) -> NUL` — Displays an ASCII visualization of a pattern. ### std/midi **Always in scope** — no import required. - class `CcOutput` — A MIDI track's CC lane, from `track.cc(number)`. - `fn set_send_rate(hz: Number) -> CcOutput` — Set the CC send rate in Hz (default 30). - class `MidiOutput` — MidiOutput: a MIDI output port and channel, a destination for `>>` — Live's "MIDI To". - `fn MidiOutput(alias: String, channel: Number? = NUL) -> MidiOutput` — A MIDI output port and channel, as a destination for `>>` — Live's "MIDI To". - class `MidiTrack` — A MIDI track: plays patterns and CC to a hardware or virtual MIDI port. - `fn MidiTrack(name: String) -> MidiTrack` — Creates a MIDI track with the given name. - `fn set_input(alias: String, channel: Number? = NUL) -> MidiTrack` — Set the MIDI input port and optional channel. - `fn set_monitor(mode: Monitor) -> MidiTrack` — Set the monitor mode: whether what is played on the input passes through to the output. - `fn set_velocity(vel: Number | Signal | Pattern) -> MidiTrack` — Set the default velocity for this track. - `fn cc(cc_number: Number) -> CcOutput` — Get a CC output handle for the given controller number. - `fn set_tuning(bend_range: Number? = NUL) -> MidiTrack` — Enable microtonal pitch bend output. - `fn set_mpe(range: Number? = NUL, zone_lo: Number? = NUL, zone_hi: Number? = NUL) -> MidiTrack` — Enable MPE (per-note channel allocation) for polyphonic microtonal output. - `fn set_key(scale: Key | String | Scale, root: Note? = NUL) -> MidiTrack` — Set a track-level key for degree resolution and auto-quantization. - `fn mute() -> MidiTrack` — Mutes the track, like Live's Track Activator: its notes and CC stop at once, and the notes it holds get their note-offs. - `fn unmute() -> MidiTrack` — Unmutes the track. - `fn is_muted() -> Boolean` — Returns whether the track is muted. - `fn solo() -> MidiTrack` — Solos the track, and only this track: every other solo is released and every other track — audio and MIDI — falls silent, as a plain click on Live's Solo button. - `fn add_solo() -> MidiTrack` — Adds the track to the soloed tracks and keeps the others soloed, as a Cmd-click on Live's Solo button. - `fn unsolo() -> MidiTrack` — Releases the track's solo. - `fn is_soloed() -> Boolean` — Returns whether the track is soloed. - enum `MidiLatency` { auto, manual } — How outgoing MIDI is aligned with the audio output. - `fn midi_clock_report() -> NUL` — Print MIDI clock status: source, BPM, transport state, and PLL diagnostics. - `fn midi_connected() -> Dict` — Checks the current MIDI connection status. - `fn midi_disconnect(alias: String) -> NUL` — Disconnects a MIDI output port. - `fn midi_input_disconnect(alias: String) -> NUL` — Disconnects a MIDI input port by alias. - `fn midi_input_ports() -> Array` — Lists all available MIDI input ports. - `fn midi_latency_report() -> NUL` — Print the MIDI output alignment report. - `fn midi_port_clock(alias: String) -> Boolean` — Returns whether a MIDI output port is opted in to receiving clock. - `fn midi_port_clock_trim(alias: String) -> Number` — Returns a MIDI output port's clock-only trim in milliseconds. - `fn midi_port_trim(alias: String) -> Number` — Returns a MIDI output port's timing trim in milliseconds. - `fn midi_ports() -> Array` — Lists all available MIDI output ports. - `fn midi_routing_report() -> NUL` — Displays the current MIDI routing: connected output/input ports and active slots. - `fn midi_trace_report() -> NUL` — Print the MIDI timing trace: clock tick spacing, note dispatch, phase errors. - `fn set_midi_clock_send(enabled: Boolean) -> NUL` — Enable/disable MIDI clock output (master mode). - `fn set_midi_clock_source(alias: String? = NUL) -> NUL` — Sets where the tempo and transport come from: an external MIDI clock on an input port (follower mode), or resonon's own clock. - `fn set_midi_latency(mode: MidiLatency) -> NUL` — Sets how outgoing MIDI is aligned with the audio output. - `fn set_midi_trace(on: Boolean) -> NUL` — Start or stop the MIDI timing trace. ### std/theory **Always in scope** — no import required. - class `Key` — A Key — a Scale rooted at a note, for scale-relative composition. - `fn Key(root: Note, name: String | Scale) -> Key` — Creates a Key value for scale-relative composition. - `fn degree(n: Number) -> Note` — Returns the Note at the given scale degree. - `fn chord(deg: Number, quality: String | Number? = NUL, inv: Number? = NUL) -> Array` — Returns a chord (array of Notes) built on the given scale degree. - `fn chord7(deg: Number, inv: Number? = NUL) -> Array` — Returns a diatonic 7th chord (4 Notes) on the given scale degree. - `fn notes() -> Array` — Returns one octave of the key's scale as an array of Notes (rooted). - `fn quantize(note: Note) -> Note` — Snaps a note to the nearest tone in this key's scale. - `fn transpose(semitones: Number) -> Key` — Returns a new Key with the root shifted by the given semitones. - class `Scale` — A musical scale — a rootless, ordered set of pitch intervals. - `fn Scale(arg: String | Array, period: Number? = NUL) -> Scale` — Creates a Scale value, optionally with a custom period. - `fn name() -> String` — Returns the scale's name. - `fn intervals() -> Array` — Returns the interval array (semitones from root). - `fn period() -> Number` — Returns the period in semitones (12 for a standard octave). - `fn length() -> Number` — Returns the number of scale degrees. - `fn mode(n: Number) -> Scale` — Returns a new Scale rotated to the nth mode (1-indexed). - `fn contains(semitones: Number) -> Boolean` — Returns true if the scale contains the given interval (in semitones). - `fn chord(root: Note, name: String, inversion: Number? = NUL) -> Array` — Returns an array of Notes forming a chord, optionally inverted. - `fn chord_names() -> Array` — Returns an array of all available chord names. - `fn interval(note: Note, name: String) -> Note` — Returns a single Note at the given interval above the input note. - `fn load_scala(name: String) -> Scale` — Load a Scala (.scl) tuning file and return a Scale value. - `fn scale_names() -> Array` — Returns an array of all available scale names. ### std/effects **Import:** `use "std/effects";` #### Filters - `fn Allpass(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates an allpass filter effect (SVF topology). - `fn Bandpass(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates a bandpass filter effect (SVF topology). - `fn Highpass(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates a highpass filter effect (SVF topology). - `fn Lowpass(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates a lowpass filter effect (SVF topology). - `fn Notch(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates a notch (band-reject) filter effect (SVF topology). - `fn Peak(name: String, cutoff: Number? = NUL, resonance: Number? = NUL) -> Effect` — Creates a peak (bell) filter effect (SVF topology). #### Delay - `fn Delay(name: String, time: Number? = NUL, feedback: Number? = NUL) -> Effect` — Creates a delay effect with feedback. #### Reverb - `fn PlateReverb(name: String, size: Number? = NUL, damping: Number? = NUL, diffusion: Number? = NUL, predelay: Number? = NUL, mix: Number? = NUL) -> Effect` — Creates a plate reverb effect (Dattorro algorithm). - `fn Reverb(name: String, room: Number? = NUL, damp: Number? = NUL, width: Number? = NUL, mix: Number? = NUL) -> Effect` — Creates a reverb effect (Freeverb algorithm). #### Distortion - `fn Distortion(name: String, drive: Number? = NUL, tone: Number? = NUL) -> Effect` — Creates a distortion effect (asymmetrical/transistor-style clipping). - `fn Overdrive(name: String, drive: Number? = NUL, tone: Number? = NUL) -> Effect` — Creates an overdrive effect (symmetrical/tube-style tanh clipping). ### std/instruments **Import:** `use "std/instruments";` #### Samples - class `Kit` — A drum kit's metadata: its samples, the notes they sit on and their files. - `fn Kit(kit_name: String? = NUL) -> Kit` — Loads kit metadata (samples, notes, files) without creating a plugin. - `fn samples() -> Array` — Returns the kit's sample names. - `fn sample_info() -> Array>` — Returns each sample with its note and file, sorted by note. - `fn name() -> String` — Returns the kit's display name. - `fn mode() -> String` — Returns how the kit plays: "oneshot" or "melodic". - `fn author() -> String` — Returns the kit's author. - `fn Sample(path: String) -> AudioClip` — Loads a WAV file as an audio clip. #### Drum Sampler - class `DrumSample` — A reference to a single drum sample slot. - `fn parameter(name: String) -> InstrumentParam` — Returns a parameter reference for this slot. - `fn set_parameter(name: String, value: Number) -> DrumSample` — Sets a parameter value by name. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList with this slot's parameters. - `fn set_envelope(attack_ms: Number, decay_ms: Number, sustain: Number, release_ms: Number) -> DrumSample` — Sets the ADSR envelope for this sample. - `fn name() -> String` — Returns the sample name. - `fn note() -> Number` — Returns the MIDI note number for this sample. - class `Sampler` implements `Instrument` — A CLAP drum sampler plugin with per-sample note mapping. - `fn Sampler(kit: Kit? = NUL) -> Sampler` — Creates a drum sampler instrument. - `fn samples() -> Array` — Returns an array of loaded sample names. - `fn sample_info() -> Array>` — Returns an array of [name, note, file] for each sample. - `fn note(name: String) -> Number` — Returns the MIDI note number for the given sample name. - `fn set_note(name: String, new_note: Note) -> Sampler` — Moves a sound to a different trigger note. - `fn parameter(name: String) -> InstrumentParam` — Returns a parameter reference by raw path. - `fn set_parameter(name: String, value: Number) -> Sampler` — Sets a parameter value by raw path. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList with all sampler parameters. - `fn sample(name: String) -> AudioClip` — Gets the audio behind a kit sound, as a clip. - `fn set_choke_group(group: Number, samples: Array) -> Sampler` — Assigns samples to a choke group. - `fn load_kit(kit: Kit) -> Sampler` — Loads a kit into the sampler. - `fn slot(name_or_note: String | Note) -> DrumSample` — Returns a reference to a drum sample slot. #### Melodic Sampler - class `SamplerMelodic` implements `Instrument` — A CLAP melodic sampler plugin with pitch-shifting. - `fn SamplerMelodic(kit: Kit? = NUL) -> SamplerMelodic` — Creates a melodic sampler. - `fn load_sample(name: String, root_note: Note? = NUL) -> SamplerMelodic` — Loads a sample from the kit directory. - `fn set_envelope(attack_ms: Number, decay_ms: Number, sustain: Number, release_ms: Number) -> SamplerMelodic` — Sets the ADSR envelope for the current sample. - `fn set_root(note: Note) -> SamplerMelodic` — Overrides the root note for the current sample. - `fn samples() -> Array` — Returns an array of loaded sample names. - `fn sample_info() -> Array>` — Returns an array of [name, root, file] for each sample, with root `NUL` if unset. - `fn root(name: String) -> Number` — Returns the root note for the given sample, or `NUL` if unset. - `fn set_parameter(name: String, value: Number) -> SamplerMelodic` — Sets a parameter value by name. - `fn parameters(filter: String? = NUL) -> ParamList` — Returns a ParamList with all sampler parameters. - `fn sample(name: String) -> AudioClip` — Gets the audio behind a kit sound, as a clip. - `fn load_kit(kit: Kit) -> SamplerMelodic` — Loads a kit into the sampler. - `fn set_loop(start_secs: Number, end_secs: Number) -> SamplerMelodic` — Sets the loop region in seconds. - `fn set_loop_normalized(start: Number, end: Number) -> SamplerMelodic` — Sets the loop region using normalized [0,1] positions. ### std/signals **Import:** `use "std/signals";` - class `Signal` implements `Clone` — A continuous control signal for modulation. - `fn range(min: Number | Signal, max: Number | Signal) -> Signal` — Maps the signal output to a linear range [min, max]. - `fn range_exp(min: Number | Signal, max: Number | Signal) -> Signal` — Maps the signal output to an exponential range [min, max]. - `fn set_retrigger(period: Duration) -> Signal` — Resets the signal's phase every `period`. - `fn set_timebase(unit: Duration) -> Signal` — Sets the unit the signal counts time in: an oscillator's rate is periods per unit, and automation breakpoint times are in units. - `fn smooth(time_ms: Number | Signal) -> Signal` — Applies one-pole lowpass smoothing to the signal. - `fn continuous() -> Signal` — Opt out of bind-time re-anchoring. - `fn at(time: Number, value: Number, curve: Curve | Bezier = Curve.linear) -> Signal` — Adds a breakpoint to an automation signal (builder pattern). - `fn set_parameter(name: String, value: Number) -> Signal` — Sets a named parameter on the signal. - `fn Cc(cc_number: Number, channel: Number? = NUL) -> Signal` — Creates a MIDI CC input signal (0 to 1 output). - `fn Cc_learn() -> Signal` — MIDI learn: waits for a CC knob/fader to be moved, then returns a Signal bound to that CC channel and number. - `fn Perlin(freq: Number | Signal = 1) -> Signal` — Unipolar Perlin noise signal (0 to 1). - `fn Ramp(start: Signal | Number = 0.0, end: Signal | Number = 1.0, duration: Signal | Number = 1.0) -> Signal` — Linear ramp signal — rises from `start` to `end` over `duration` units of its timebase (cycles by default), then clamps at both ends. - `fn Rand(freq: Number | Signal = 1) -> Signal` — Unipolar random sample-and-hold signal (0 to 1). - `fn Saw(freq: Number | Signal = 1) -> Signal` — Unipolar sawtooth signal (0 to 1). - `fn Saw2(freq: Number | Signal = 1) -> Signal` — Bipolar sawtooth signal (-1 to 1). - `fn Sine(freq: Number | Signal = 1) -> Signal` — Unipolar sine wave signal (0 to 1). - `fn Sine2(freq: Number | Signal = 1) -> Signal` — Bipolar sine wave signal (-1 to 1). - `fn Square(freq: Number | Signal = 1) -> Signal` — Unipolar square wave signal (0 or 1). - `fn Square2(freq: Number | Signal = 1) -> Signal` — Bipolar square wave signal (-1 or 1). - `fn Time(rate: Number | Signal = 1) -> Signal` — Elapsed time in units of the timebase, times `rate`: the phase the other oscillators wrap, left unwrapped, so it keeps rising until a retrigger. - `fn Tri(freq: Number | Signal = 1) -> Signal` — Unipolar triangle wave signal (0 to 1). - `fn Tri2(freq: Number | Signal = 1) -> Signal` — Bipolar triangle wave signal (-1 to 1). - `fn automation(...breakpoints: Array) -> Signal` — Creates an automation signal with breakpoint-based modulation. - `fn hz_to_periods(frequency: Number) -> Number` — Converts a frequency in Hertz to periods per cycle at the current tempo. - `fn sec_to_periods(period: Number) -> Number` — Converts a period in seconds to periods per cycle at the current tempo. - `fn signal(pattern: Pattern | Note | Array) -> Signal` — Creates a signal from a pattern, or from an array played as one cycle's sequence. - `fn signal_ramp(start: Number, end: Number, duration: Number? = NUL) -> Signal` — Creates a linear ramp signal that clamps at its endpoints. ### std/random **Import:** `use "std/random";` - `fn choose(seed: Number, array: Array) -> Any` — Deterministic element selection from an array. - `fn choose_true(array: Array) -> Any` — True random element selection from an array, drawn from the operating system's entropy. - `fn choose_weighted(seed: Number, array: Array, weights: Array) -> Any` — Deterministic weighted element selection from an array. - `fn rand(seed: Number) -> Number` — Deterministic random number from a seed. - `fn rand_true() -> Number` — True random number, drawn from the operating system's entropy. ### std/generative **Import:** `use "std/generative";` #### Cycle Callbacks - `fn off_cycle() -> NUL` — Clear all per-cycle callbacks registered via on_cycle(). - `fn on_cycle(callback: Function) -> NUL` — Register a per-cycle callback that runs on the interpreter thread. - `fn prime_cycles() -> NUL` — Fire cycle callbacks once, for the cycle the playhead is on, so the pattern that plays next is ready before it is needed. #### Streams & Markov - `fn markov(num_states: Number, transitions: Array>, initial: Number) -> Pattern` — Creates a Markov chain pattern with cycle-seeded transitions. - `fn stream(initial: Note | Number | Array | Pattern, next_fn: Function) -> Pattern` — Creates a stateful stream pattern from an initial value and a next function. ### std/visuals *(experimental)* **Import:** `use "std/visuals";` - class `Screen` — The display output sink. - `fn set_quality(n: Number) -> Screen` — Sets the supersampling (SSAA) quality — the internal render resolution as a multiple of the composition size (default 1, one sample per pixel). - `fn resolution(w: Number, h: Number) -> Screen` — Sets the composition size in pixels (default 1920 × 1080). - `fn show_window() -> Screen` — Opens the native live-rendering window for the routed visual, rendered on the GPU in-process from the routed graph and transport (audio meter feeds read as zero for now). - `fn snap(path: String) -> Screen` — Renders the routed visual off-screen on the GPU and writes it to a PNG at the given path. - class `Visual` — A node in the GPU visual graph: a built-in operator (`Noise`, `Blur`, `Displace`, …) or a compiled shader (`Visual(name, source)`). - `fn Visual(name: String, source: String) -> Visual` — Compiles a fragment-shader source string into a Visual. - `fn parameter(name: String) -> VisualParam` — Binds a uniform to a signal or value (`v.parameter("period") << sig`), or wires a texture input slot with a node (`c.parameter("b") << node` on Composite, `d.parameter("by") << field` on Displace, `l.parameter("table") << ramp` on Lookup). - `fn reset() -> Visual` — Clears the operator's render state on the next frame — TouchDesigner's Reset pulse. - class `VisualParam` — A reference to a visual operator's parameter, produced by `node.parameter("name")` and consumed by `<<` (`v.parameter("period") << sig`). - enum `BlurExtend` { hold, repeat, mirror } — What a `Blur` sees beyond the image edges: TD's Blur Extend menu. - enum `BlurMethod` { horizontal_and_vertical, horizontal, vertical } — The axes a `Blur` blurs along: TD's Blur Method menu. - enum `BlurType` { catmull_rom, gaussian, box, bartlett, sinc, hanning, blackman } — The kernel shape of a `Blur`: TD's Blur Type menu. - enum `Extend` { hold, zero, repeat, mirror } — What is read beyond the image edges: TD's Extend menu. - enum `LookupChannel` { luminance, red, green, blue, alpha, rgb_average, rgba_average, rgb_maximum, rgba_maximum, rgba_independent } — How a `Lookup` index colour picks from the table: TD's Lookup Index Channel menu. - enum `Operand` { add, difference, maximum, minimum, multiply, over, screen, subtract, subtractive } — How a `Composite` combines its inputs A and B: TD's Composite Operation menu. - enum `RampExtend` { hold, black, zero, repeat, mirror } — What a `Ramp` draws below 0: TD's Ramp Extend Left menu. - enum `RampExtendRight` { same_as_left, hold, black, zero, repeat, mirror } — What a `Ramp` draws above 1: TD's Ramp Extend Right menu. - enum `RampFit` { fill, fit_horizontal, fit_vertical, fit_best } — How a radial or circular `Ramp` fits a non-square image: TD's Ramp Fit Aspect menu. - enum `RampInterp` { step, linear, ease_in_ease_out, hermite } — The curve between the keys of a `Ramp`: TD's Ramp Interpolate Notches menu. - enum `RampType` { vertical, horizontal, radial, circular } — The shape of a `Ramp`: TD's Ramp Type menu. - enum `RgbOutput` { multiply_alpha, new_alpha } — The colour an `RgbKey` draws: TD's RGB Key RGB Output menu. - enum `Unit` { pixels, fraction, fraction_aspect } — The unit of a distance on an image: TouchDesigner's Pixels, Fraction and Fraction Aspect. - `fn Blur(name: String) -> Visual` — A blur visual: TouchDesigner's Blur TOP. - `fn Composite(name: String) -> Visual` — A composite visual: TouchDesigner's Composite TOP. - `fn Displace(name: String) -> Visual` — A displace visual: TouchDesigner's Displace TOP. - `fn Edge(name: String) -> Visual` — An edge visual: TouchDesigner's Edge TOP. - `fn Lookup(name: String) -> Visual` — A lookup visual: TouchDesigner's Lookup TOP. - `fn LumaLevel(name: String) -> Visual` — A luma-level visual: TouchDesigner's Luma Level TOP. - `fn Noise(name: String) -> Visual` — A noise generator: TouchDesigner's Noise TOP with type Simplex 3D, monochrome, aspect corrected, alpha one. - `fn Ramp(name: String) -> Visual` — A ramp visual: TouchDesigner's Ramp TOP. - `fn RgbKey(name: String) -> Visual` — An RGB-key visual: TouchDesigner's RGB Key TOP. - `fn Slope(name: String) -> Visual` — A slope visual: TouchDesigner's Slope TOP. - `fn Transform(name: String) -> Visual` — A transform visual: a TouchDesigner-style Transform TOP that translates, rotates and scales its primary input (set via `src >> Transform("…")`) about a pivot. - `fn feedback(seed: Visual, build: Function) -> Visual` — Builds a feedback group: TouchDesigner's Feedback TOP, with the group output as its Target TOP. - `fn load_shader(name: String, path: String) -> Visual` — Loads a fragment shader from an external .glsl file and compiles it. ### DSP Builtins *(experimental)* **Availability:** inside `dsp { }` blocks. - `BEAT_EDGE: Number` — Single-sample trigger pulse (1.0) at the start of each beat, 0.0 otherwise. - `BEAT_PHASE: Number` — Sawtooth phase ramping 0.0→1.0 across each beat (fract(CYCLES * BPC)). - `BPC: Number` — Beats per cycle — number of beats spanning one transport cycle (default 4.0). - `CPS: Number` — Cycles per second — tempo-derived frequency (e.g. 120 BPM = 2.0 CPS). - `CYCLE: Number` — The song's current whole cycle number (0, 1, 2, …), taken at the first sample of each block. - `CYCLES: Number` — Local position in cycles since the signal's anchor. - `CYCLE_EDGE: Number` — Single-sample trigger pulse (1.0) at the start of each transport cycle, 0.0 otherwise. - `CYCLE_PHASE: Number` — Sawtooth phase ramping 0.0→1.0 across each transport cycle (fract(CYCLES)). - `INV_SR: Number` — Inverse sample rate (1.0 / SR). - `PI: Number` — Pi (3.14159...) - `POSITION: Number` — Local position since the signal's anchor, counted in its timebase: cycles unless `.set_timebase()` sets another unit. - `SR: Number` — Current sample rate in Hz. - `TIME: Number` — Local time in seconds since the signal's anchor. - `TWOPI: Number` — Two pi / tau (6.28318...). - `abs(x) -> Number` — Absolute value. - `aftertouch(channel) -> Number` — Read MIDI channel aftertouch, normalized to 0.0–1.0. - `cc(cc_num, channel) -> Number` — Read a MIDI CC value, normalized to 0.0–1.0. - `ceil(x) -> Number` — Round up to the nearest integer. - `clamp(value, min, max) -> Number` — Clamp a value to a range. - `cos(x) -> Number` — Cosine function. - `delay(input, time) -> Number` — Integer sample delay (circular buffer, max 1 second). - `delay_interp(input, time) -> Number` — Fractional delay with linear interpolation (max 1 second). - `exp(x) -> Number` — Exponential function (e^x). - `floor(x) -> Number` — Round down to the nearest integer. - `fract(x) -> Number` — Fractional part (x - floor(x)). - `ftom(freq) -> Number` — Frequency in Hz to MIDI note number. - `lerp(a, b, t) -> Number` — Linear interpolation between two values. - `log(x) -> Number` — Natural logarithm (ln). - `log10(x) -> Number` — Base-10 logarithm. - `log2(x) -> Number` — Base-2 logarithm. - `max(a, b) -> Number` — Maximum of two values. - `min(a, b) -> Number` — Minimum of two values. - `mtof(midi) -> Number` — MIDI note number to frequency in Hz. - `noise() -> Number` — White noise generator. - `onepole(input, coeff) -> Number` — One-pole lowpass filter. - `pitchbend(channel) -> Number` — Read MIDI pitch bend, normalized to -1.0–1.0. - `pow(base, exp) -> Number` — Raise base to exponent. - `round(x) -> Number` — Round to the nearest integer. - `sample_hold(input, trigger) -> Number` — Sample and hold — captures input on rising edge of trigger. - `sin(x) -> Number` — Sine function. - `sqrt(x) -> Number` — Square root. - `svf_allpass(input, cutoff, resonance) -> Number` — State variable filter — allpass. - `svf_bp(input, cutoff, resonance) -> Number` — State variable filter — bandpass. - `svf_hp(input, cutoff, resonance) -> Number` — State variable filter — highpass. - `svf_lp(input, cutoff, resonance) -> Number` — State variable filter — lowpass (Zavalishin topology-preserving transform). - `svf_notch(input, cutoff, resonance) -> Number` — State variable filter — notch (band-reject). - `svf_peak(input, cutoff, resonance) -> Number` — State variable filter — peak (bell). - `tan(x) -> Number` — Tangent function. - `tanh(x) -> Number` — Hyperbolic tangent — useful for soft clipping.