KODA Scripting Reference

Introduction

This reference complements the KODA Scripting Manual. If you're new to KODA scripting, read the manual first. Then use this reference as a lookup when writing instrument behavior. Find the type you're working with in the sidebar, scroll to its function list, and copy what you need.

Conventions used in this reference

Getting by name vs. by index

• By name — More robust. If you reorder articulations, variations, or other parts of the instrument, scripts keep working because they reference the parts by what they're called, not where they sit.
• By index — Less typing, and natural inside for loops where you'd iterate over every articulation, mic, etc. Index access skips the string lookup, but breaks if you reorder.

// By name — survives reordering
Articulation soft = getArticulation("Soft");
Mic close = getMic("Close");

event initialize() { setLogEnabled(true); }   // Without this, debug.log() output is silent

// By index — concise in loops
for(int i = 0; i < getNumArticulations(); i++)
{
    Articulation art = getArticulation(i);
    debug.log(art.getName());
}

Note vs NoteData

Two related but distinct types describe a note at different points in its life:

• NoteData — a template for a note before it plays. Carries pitch, velocity, envelope, timing, and routing. KODA hands one to your noteOn handler describing each incoming MIDI note. You can modify it freely, build new ones via createNoteData(), and trigger them with start() or startNote().
• Note — a handle to a note that's currently playing. You get one back from startNote(). Use it to modulate or stop the playing note: change its tuning, gain, pan, or trigger its release.

The typical flow is configure → start → modify:

event noteOn(NoteData note)         // receive a NoteData template…
{
    note.setAttack(0.05f);              // pre-configure before it plays

    Articulation art = getCurrentArticulation();
    Note playing = art.startNote(note);  // …trigger it, get back a Note handle…

    playing.setGain(0.8f);               // …modify the playing note
}

Once startNote() has fired, changes to the original NoteData have no effect on the playing note — they only describe the template. To affect a sounding note, always use its Note handle.

Two ways to call a function: with a dot or without

Examples in this reference use dot syntax because it's the more common style in the Cmajor standard library and KODA codebase. If you prefer a procedural style — passing the object as the first argument — that form works everywhere too.

Using Parameter to skip using .getValue() (Overload Convenience)

Many setter functions that take a primitive (float, int, or bool) also accept a Parameter directly, saving you a .getValue() / .getIntValue() / .getBoolValue() call. The Parameter overload exists wherever you see a Tip line in a function's description.

// Both of these set the articulation's gain from a Parameter:

art.setGain(myGainParam.getValue());    // Explicit unwrap
art.setGain(myGainParam);               // Parameter overload — same result, less typing

For non-setter contexts (arithmetic, comparisons, stream output, passing to functions without a Parameter overload) you'll always need an explicit .getValue():

// ✗ Won't compile
if(myParam > 0.5f)
console <- myParam;

// ✓ Works
if(myParam.getValue() > 0.5f)
console <- myParam.getValue();

Built-in Parameters

Every KODA instrument always carries these eight Parameters. They're created automatically — you don't need to add them in Figma — and you can react to them from a script with the standard event <ParameterName>(Parameter parameter) handler pattern without any extra UI setup. The default CC mappings follow the MIDI standard, and the user can remap any of them to a different CC in KODA's CONTROL tab.

All share a range of 0.0–1.0; default 0.0, except where noted.

Default CCs are just that — defaults. If the user maps Dynamics to CC 11 in the CONTROL tab, the Parameter will respond to CC 11 instead of CC 1 going forward; nothing in your script needs to change. From a script perspective, you always address these by name — getParameter("Dynamics"), event Dynamics(Parameter parameter) — and the CC number is just an input-routing detail handled outside your code.

Built-in helpers

Generic utility functions that don't belong to any specific type. Always in scope.

Cmajor patterns you'll see

A few Cmajor language conventions that aren't part of the KODA API but show up regularly in scripts.

Safe array indexing with wrap<N>

When you index a fixed-size array with a plain int, the Cmajor compiler rejects the access unless the index is guaranteed to be in bounds. The standard fix is to cast the index via wrap<N>, which wraps the value modulo N so it's always valid for an array of size N.

float[8] table = (0.0f, 0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f);

int i = someIndex;
float v = table[wrap<8>(i)];   // safe: i wraps into [0, 8)

You'll see this most often in event process() when stepping through a precomputed table — for example, looking up an entry in a vibrato LFO waveform.

Function calls on a returned value

Dot syntax (obj.foo()) is shorthand for the free function call foo(obj). When obj is the value returned by another call (a temporary), the Cmajor compiler can sometimes fail to resolve the dot-syntax call. The fix is to assign the temporary to a named variable first.

// ✗ May fail to compile
Note n = getArticulation("Straight").startNote(note);

// ✓ Assign first, then call
Articulation art = getArticulation("Straight");
Note n = art.startNote(note);

Instrument (Global)

This is your script's top-level entry point into the instrument. Everything you've built in the KODA app — the Articulations, Variations, Groups, Parameters, Modulators, Mics, and Buses — is reachable from here, alongside instrument-wide controls (volume, tuning, MIDI input filters) and host-supplied info (BPM, play state, time signature, sample rate, elapsed time).

When calling setInstrumentGainDecibels(-6.0f) or setInstrumentTuning(2.0f), you're setting the same values as the instrument-wide volume and tuning controls in the KODA app's GUI.

These are always in scope. Call them from anywhere in your script — no setup, no object to fetch.

Example: Log notes only when the transport is playing

event initialize() { setLogEnabled(true); }   // Without this, debug.log() output is silent

// Triggered every time the user plays a note
event noteOn(NoteData note)
{
    // Skip if the host transport isn't running (no DAW playback)
    if(getIsPlaying())
    {
        // PPQ = pulses per quarter note — the host's current playback position
        debug.log("Note played at PPQ:", getppqPosition());
    }
}

Logging

AVG Hierarchy Section

This is where the AVG (Articulation / Variation / Group) hierarchy you've built in the KODA app becomes reachable from your script. Use these to grab a handle to whichever Articulation, Variation, or Group you want to act on.

Parameters & Modulators

The Parameters you've defined in Figma and the Modulators wired up in the KODA app's Modulators panel become reachable from your script here. Use these to grab a handle to the Parameter or Modulator you want to read, set, or react to.

Mics

The mic mixer you've configured in the KODA app becomes reachable from your script here. Use these to grab a handle to a specific Mic so you can adjust its gain, pan, solo, or mute from your script.

Convolution IRs

The impulse-response .wav files in the library's IR Samples folder — the same list the Convolution effect shows in its own dropdown — are reachable from your script here. Use these to autopopulate a front-end menu of IRs: the index matches Convolution::File, so a menu item's value can route straight to setInsertParameter(slot, Convolution::File, index).

Example: Autopopulate a menu with the library's IRs

// Build a front-end dropdown from the library's "IR Samples" folder.
Component createConvolutionMenu(string name)
{
    Component menu = getComponent(name);
    menu.clearItems();
    menu.addItem("None", -1);   // -1 clears the IR (pass-through)

    for (int i = 0; i < getNumConvolutionFiles(); i++)
        menu.addItem(getConvolutionFileName(i), i);

    menu.setMenuSelection(-1);   // start on "None"
    return menu;
}

// The menu value maps directly to the Convolution insert's File parameter.
// (assumes a Convolution insert at slot 0 of the master bus)
event mnuConvolution(Parameter parameter)
{
    Bus master = getMasterBus();
    master.setInsertParameter(0, Convolution::File, parameter.getValue());
}

Instrument output

The instrument-wide volume and tuning controls in the KODA app are exposed here. Use these to adjust the global gain or tuning from a script.

MIDI input control

Filter or block specific kinds of incoming MIDI messages at the instrument level.

Instrument runtime state

Read-only queries about what your instrument is doing right now.

Transport state

Read-only queries about the host's current transport state and audio configuration. Note: although you access this from the instrument, the data is being passed in from the host DAW.

System & environment

Read-only info about the host environment and machine.

Time elapsed & beats

Time since the script started running, and helpers for sample-counts until the next beat or bar. Reach for the samples version for sample-accurate scheduling (it combines naturally with getBeat(), getNextBeat(), and getBlockSize()); reach for the seconds version for logging or human-readable duration checks.

Note length helpers

Length of musical note durations in samples, based on the host BPM (and time signature for bars). Useful for scheduling delays and lengths in rhythmic units.

Example: Enable logging on initialize

// Runs once when the script first compiles
event initialize()
{
    // Logging is disabled by default — enable it for the rest of the session
    setLogEnabled(true);

    // Print useful host info to the debug console
    debug.log("Sample rate:", getSampleRate());
    debug.log("BPM:", getBPM());
}

Parameter

The Parameters you've created in Figma — knobs, sliders, buttons, etc. — become reachable from your script here. Use these to grab a handle to whichever Parameter you want to read, set, or react to.

• Access a parameter inside its specific callback: event <ParameterName>(Parameter parameter)
• Or a generic callback that fires when any parameter changes: event parameterUpdated(Parameter parameter)
• Or, for use outside the callback, create a global Parameter via getParameter("Name").

Parameter p_gain = getParameter("Gain");
float currentGain = p_gain.getValue();

Reading values

When two function names are stacked in a single row, they're equivalent — they call the same underlying code. Pick whichever name reads more naturally in your script.

Range & identity

Setting values

Reacting to parameter changes

To run code when a Parameter's value changes, write a named event handler — the handler's name matches the Parameter's name (the string passed to getParameter). KODA dispatches each change to its own handler automatically; there's no central dispatch function to write.

The event runs once per change, with the new value already on the parameter. Read it with parameter.getValue() / parameter.getIntValue() / parameter.getBoolValue(), or pass the parameter directly to any setter that accepts a Parameter overload (see Parameter Convenience).

// Fires whenever InstrumentVolume changes (built-in, MIDI CC 7 by default)
event InstrumentVolume(Parameter parameter)
{
    // Push the new value into the current articulation's gain
    Articulation art = getCurrentArticulation();
    art.setGain(parameter);   // Parameter overload — see Articulation reference
}

Articulation, Variation & Group

Every KODA instrument's samples are organised into a three-level container hierarchy:

• Articulation — the top-level grouping, typically a name for a playing style ("Sustain", "Staccato", "Pizzicato"). Switching articulations via the keyswitch UI changes which Articulation plays, as well as the elements contained within.
• Variation — a mid-level container inside an Articulation. Used for things like dynamic layers (pp / mf / ff), vibrato vs. non-vibrato, or alternate takes.
• Group — the bottom-level container inside a Variation. Where the actual sample mappings live. The level you'd reach to manipulate the insert FX chain attached to those samples.

All three containers share most of the same functions — identity / state, gain / pan, tuning / transposition, sample loading, note triggering, and per-container parameters — so they're documented together below. Three subsections at the end cover the per-type extras: navigating a parent's children (Articulation, Variation) and the insert FX chain (Group).

Get a handle via getCurrentArticulation(), getArticulation(), articulation.getVariation(), variation.getGroup(), or articulation.getGroup() (which jumps from Articulation directly to Group, using whichever Variation is currently active).

Example: Log which articulation handled each note

event initialize() { setLogEnabled(true); }   // Without this, debug.log() output is silent

// Fires every time a note is played
event noteOn(NoteData note)
{
    // Reach into the currently-active articulation and log its name
    Articulation art = getCurrentArticulation();
    debug.log("Note routed to articulation:", art.getName());
}

Example: Mute the current articulation when the host stops

// Fires whenever the host transport stops
event transportStopped()
{
    // Reach into the currently-active Articulation
    Articulation art = getCurrentArticulation();

    // Silence it and stop any tails still playing
    art.setGain(0.0f);
    art.stopAllNotes();
}

Identity & state

Gain & pan

Tuning & transposition

Tuning shifts the pitch of a sample. Transposition offsets the position of the note to trigger a different sample.

Sample loading/purging

Load or purge this container's samples from memory. Useful for templating instruments that hold many articulations but only need a few in memory at once.

Keyboard highlight

Overlay this container's playable range — the exact set of MIDI notes covered by every zone beneath it (across all child Variations and Groups) — on the GUI piano, tinted with a chosen Colour. Handy for showing the user which keys an Articulation, Variation, or Group responds to, e.g. when a menu switches the active Variation.

Playing notes

Trigger and stop notes scoped to this container. Notes started on an Articulation flow through its active Variation (and that Variation's active Group); notes started on a Variation flow through its active Group; notes started on a Group play that Group's samples directly.

Parameters & properties

Each container can carry its own set of named parameters (numeric values) and properties (typed values) defined alongside it in the instrument. Use these to attach per-container settings without polluting the global parameter list.

Variations & active variation Articulation only

Access an Articulation's child Variations, and control which Variation new notes route to.

Example: Crossfade between vibrato and non-vibrato

// Fires whenever Vibrato changes (built-in, MIDI CC 2 by default)
// (assumes the current articulation has Variations named "NoVibrato" and "Vibrato")
event Vibrato(Parameter parameter)
{
    Articulation art = getCurrentArticulation();
    Variation noVib = art.getVariation("NoVibrato");
    Variation vib   = art.getVariation("Vibrato");

    float blend = parameter.getValue();

    // 0.0 = full NoVibrato, 1.0 = full Vibrato, in-between = blended
    noVib.setGain(1.0f - blend);
    vib.setGain(blend);
}

Example: Trigger a release-tail Variation when a note is released

// Fires when the user lifts a key
// (assumes the current articulation has a Variation named "ReleaseTail")
event noteOff(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Variation tail = art.getVariation("ReleaseTail");

    // Trigger the tail sample through the ReleaseTail Variation directly,
    // bypassing the Articulation's active-Variation routing
    tail.startNote(note);
}

Groups & active group Variation only

Access a Variation's child Groups, and control which Group new notes route to.

Insert FX Group only

Each Group can host a chain of insert FX (compressor, EQ, reverb, etc.) defined in the instrument. These functions let you modulate individual insert parameters or bypass entire inserts at runtime.

Example: Darken soft notes with a velocity-driven filter cutoff

// Fires every time a note is played
event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Group group = art.getGroup(0);

    // Lower-velocity notes get a lower cutoff (darker tone, mimicking a softer note)
    // (assumes insert slot 0 is a filter with cutoff frequency as parameter 1)
    float cutoffHz = 200.0f + note.getVelocity() * 19800.0f;
    group.setInsertParameter(0, 1, cutoffHz);
}

Example: Bypass a reverb with a UI button

// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as a reverb-bypass toggle for portable testing.
// (assumes a reverb at insert slot 1 of the current articulation's group)
event SustainPedal(Parameter parameter)
{
    Articulation art = getCurrentArticulation();
    Group group = art.getGroup(0);

    // Pedal pressed = bypass on, pedal released = bypass off
    group.setInsertBypassed(1, parameter.getBoolValue());
}

NoteData

A NoteData describes a note before it plays — its pitch, velocity, envelope, timing, and which articulation / variation / group / mic / bus it routes through. KODA hands one to your noteOn and noteOff handlers describing each incoming MIDI note, and you can also build your own by calling createNoteData() on an Articulation, Variation, or Group.

Once a NoteData is configured, trigger it with noteData.start() to play it through its current routing (see Triggering below). A NoteData is just a value — changing it after the note has started has no effect on the playing note (use the returned Note handle for that).

Example: Add an octave-up echo to every note

event noteOn(NoteData incoming)
{
    Articulation art = getCurrentArticulation();

    // Build a copy of the incoming note, an octave higher, half as loud,
    // delayed by 200 ms — KODA still triggers the original note normally
    NoteData echo = art.createNoteData();
    echo.setNoteNumber(incoming.getNoteNumber() + 12);
    echo.setVelocity(incoming.getVelocity() * 0.5f);

    art.startNote(echo);
}

Pitch & velocity

Set or read the note's pitch (note number, tuning offsets, transposition) and velocity. Velocity has two unit conventions exposed as separate function pairs — float (0.0–1.0) and MIDI integer (0–127) — that read and write the same underlying value.

Gain & pan

Delay, length & stretch

Control where in the sample to start playback (sample start), how long to delay before triggering, and how time-stretched it is.

Envelope

Override the note's envelope stages individually, or apply a whole envelope at once via setEnvelope(). Curve exponents take values in the range 0.5–2.0: 0.5 = convex (fast start, slow finish), 1.0 = linear, 2.0 = concave (slow start, fast finish).

Behavior flags

Routing

Direct the note through a specific articulation, variation, group, mic, or bus. The setTarget(...) overloads are the most ergonomic — they set the relevant indices in one call. For low-level control, use the individual index setters; indices of -1 mean "no override — use the engine's default routing".

Triggering

Convert a configured NoteData into a playing note. The note plays through the routing set on the NoteData (via setTarget(...) or inherited from the incoming noteOn event).

Example: Make soft notes longer and breathier

event initialize()
{
    // Disable default triggering so we can customise each note ourselves
    setIgnoreNoteOns(true);
}

event noteOn(NoteData note)
{
    if(note.getVelocity() < 0.4f)
    {
        // Slow swell, gentle release for soft notes (curve 2.0 = slow start / fast end)
        note.setAttack(0.5f, 2.0f);
        note.setRelease(2.0f, 2.0f);
    }

    // Use the routing already on the incoming note — no need to fetch the articulation
    note.start();
}

Note

A Note is a handle to a currently-playing note. You get one back from startNote() on an Articulation, Variation, or Group — and you use it to modify or stop that specific note while it's still sounding.

Every Note function returns a bool: true if the note was still active and the change was applied, false if the note had already finished. That return value lets you safely call functions on a Note without first checking isActive().

Example: Apply a longer release to every incoming note

event initialize()
{
    // Suppress KODA's default note triggering so we can start notes ourselves
    setIgnoreNoteOns(true);
}

event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Note playing = art.startNote(note);

    // Stretch the release out to 2 seconds with a slightly concave curve (slow start)
    playing.setRelease(2.0f, 1.5f);
}

Lifecycle

Per-note properties

Adjust gain, tuning, length, time-stretch, pan, and release on a single note while it's playing. Each function returns true if the change landed (the note was still active), false if the note had already finished.

Insert FX

Example: Vary release length by velocity

event initialize()
{
    setIgnoreNoteOns(true);
}

event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Note playing = art.startNote(note);

    // Soft notes ring out longer; loud notes cut off quickly
    if(note.getVelocity() < 0.4f)
        playing.setRelease(3.0f, 2.0f);    // slow, lingering fade
    else
        playing.setRelease(0.5f, 1.0f);    // short, linear fade
}

HeldNotes

A HeldNotes is a snapshot of every MIDI note the user is currently holding down — useful for chord recognition, arpeggiator-style logic, or any script behaviour that needs to know what's pressed at a given moment. Get one via the free function getHeldNotes(); for a quick single-note query, use isNoteHeld(int) instead.

HeldNotes stores up to 128 note numbers. The size member variable tells you how many are currently held.

Example: Detect chords by counting held notes

event initialize() { setLogEnabled(true); }   // Without this, debug.log() output is silent

event noteOn(NoteData note)
{
    HeldNotes held = getHeldNotes();

    if(held.size >= 3)
        debug.log("Chord detected, notes:", held.size);
}

Functions

Member Variables

Time-varying modulation

The script-side API has no built-in glide, fade, or ramp helpers for active notes — there's no glideTo(target, durationSec) or fadeOutOver(durationSec). Instead, you interpolate values yourself in event process() and call Note's per-note setters (setTuningSemitones, setGain, etc.) each audio block. This pattern is the canonical answer to "how do I make X change smoothly over time".

The process() event

event process() fires once per audio block (typical block size 64 samples ≈ 1.3 ms at 48 kHz). Use it to advance any time-varying state — pitch glides, fade-outs, scripted LFOs, parameter sweeps — and apply the result to active notes.

event process()
{
    // runs every block — keep work small and predictable
}

Block-delta seconds

To advance a real-time animation, you need to know how much wall-clock time has passed between block calls. Divide the block size (samples) by the sample rate:

event process()
{
    float blockSec = float(getBlockSize()) / float(getSampleRate());
    // blockSec ≈ 0.00133 at 48 kHz / 64-sample blocks

    // ... advance an elapsed-time counter, look up a position, etc.
}

Example: 30 ms pitch glide

Animate a Note's tuning offset linearly from a starting value down to zero over a fixed duration. The state lives at module level so it persists across block calls.

Note currentNote;
bool gliding;
float glideStartSemitones;
float glideElapsedSec;
const float kGlideDurationSec = 0.030f;

event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    currentNote = art.startNote(note);

    // Start the note one semitone below pitch and glide up to natural
    currentNote.setTuningSemitones(-1.0f);
    glideStartSemitones = -1.0f;
    glideElapsedSec = 0.0f;
    gliding = true;
}

event process()
{
    if(!gliding)
        return;

    float blockSec = float(getBlockSize()) / float(getSampleRate());
    glideElapsedSec += blockSec;

    float ratio = min(glideElapsedSec / kGlideDurationSec, 1.0f);
    currentNote.setTuningSemitones(glideStartSemitones * (1.0f - ratio));

    if(ratio >= 1.0f)
        gliding = false;
}

Combining modulators on the same note

Note setters are absolute — each call overwrites the property's current value. If two modulators want to influence the same property in the same block (e.g. a legato glide running alongside a vibrato LFO), accumulate their contributions and apply the total in a single call.

event process()
{
    float blockSec = float(getBlockSize()) / float(getSampleRate());

    float totalSemitones = 0.0f;

    if(gliding)
    {
        glideElapsedSec += blockSec;
        float ratio = min(glideElapsedSec / kGlideDurationSec, 1.0f);
        totalSemitones += glideStartSemitones * (1.0f - ratio);
        if(ratio >= 1.0f) gliding = false;
    }

    if(vibratoActive)
    {
        vibratoPhase += vibratoHz * blockSec;
        float v = sin(vibratoPhase * 2.0f * pi);
        totalSemitones += vibratoDepthSemitones * v;
    }

    currentNote.setTuningSemitones(totalSemitones);
}

Bus

A Bus is one of the audio routing destinations in your instrument — the master bus, a mic bus, or an FX bus. It's the level you'd reach to adjust output gain, route signal between buses, or toggle an insert FX on a shared FX chain rather than per-Group.

Get a Bus via the free functions getMasterBus() or getBus() (by name or 0-based index).

Example: Drive a reverb send from a UI knob

// Fires when Expression changes (built-in, MIDI CC 11 by default).
// Repurposed here as a reverb-send amount for portable testing.
// (assumes a reverb sitting on the first send bus)
event Expression(Parameter parameter)
{
    Bus master = getMasterBus();

    // Send a portion of the master bus's output to the first send bus (send index 0)
    master.setSendLevel(0, parameter);
}

Identity & state

Gain & pan

Bypass, solo & mute

Toggle the Bus's playback state. These mirror the bypass, solo, and mute buttons users see on each bus in the plugin's mixer.

Send levels

Each Bus can send a portion of its signal to the instrument's send buses (up to 8 of them). Use this to drive parallel effects like reverbs and delays.

Insert FX

Like Groups, each Bus can host a chain of insert FX defined in the instrument. These functions let you modulate individual insert parameters or bypass entire inserts at runtime.

Example: Bypass a reverb on the master bus

// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as a reverb-bypass toggle for portable testing.
// (assumes a reverb at insert slot 0 of the master bus)
event SustainPedal(Parameter parameter)
{
    Bus master = getMasterBus();

    // Pass the button state straight to the insert's bypass flag
    master.bypassInsert(0, parameter);
}

Output levels

Read a bus's current output meter. getLevels() returns a Levels snapshot, refreshed once per audio block — read it in event viewRefresh() or event process() to drive meters.

Levels

A read-only snapshot of a bus's output meter, returned by bus.getLevels(). Linear values are 0.0–1.0; decibel values are floored at −60 dB.

Mic

A Mic represents one of the microphone positions in your instrument — the same mics users see in the plugin's mic mixer. Mics are defined at the clip level: when you import samples, the Tokenizer identifies a "mic position" token in each filename (e.g. Close, Room, Overheads), and the unique set across all clips becomes the instrument's mic list. Each mic is surfaced as a routing object you can address by name or index.

Get a Mic via the free functions getMic(string name) or getMic(int index).

Example: Tie a mic's gain to a UI knob

// Fires when InstrumentVolume changes (built-in, MIDI CC 7 by default).
// Repurposed here as close-mic gain for portable testing.
// (assumes a mic named "Close" in the instrument)
event InstrumentVolume(Parameter parameter)
{
    Mic close = getMic("Close");

    // Pass the knob value straight to the mic's gain
    close.setGain(parameter);
}

Identity & state

Gain & pan

Solo, mute & enabled

These mirror the solo, mute, and enable buttons users see for each mic in the plugin's mic mixer.

Example: Toggle a mic on/off from a UI button

// Fires when SostenutoPedal changes (built-in, MIDI CC 66 by default).
// Repurposed here as a Room-mic on/off toggle for portable testing.
// (assumes a mic named "Room" in the instrument)
event SostenutoPedal(Parameter parameter)
{
    Mic room = getMic("Room");

    // Pass the button state straight to the mic's enabled flag
    room.setMicEnabled(parameter);
}

Modulator

A Modulator represents an LFO or envelope defined in your instrument — the same modulators users see attached to parameters in the plugin's modulation panel. From a script, you can adjust the modulator's shape (LFO frequency, waveform, depth) or envelope (attack, decay, sustain, release) at runtime, and enable or bypass it.

Get a Modulator via the free functions getModulator(string name) or getModulator(int index).

Example: Tie vibrato depth to the Mod Wheel

// Fires when Vibrato changes (built-in, MIDI CC 2 by default —
// the standard mod-wheel destination)
// (assumes a Modulator named "Vibrato" in the instrument)
event Vibrato(Parameter parameter)
{
    Modulator vibrato = getModulator("Vibrato");

    // 0.0 = no vibrato, 1.0 = full vibrato
    vibrato.setLFODepth(parameter);
}

Enable & bypass

LFO controls

These shape the LFO's behavior — rate, waveform, phase, depth, and whether the LFO runs globally (shared across all notes) or per-note (each note starts a fresh phase).

Envelope controls

These shape the envelope's pre-delay, attack-hold-decay-sustain-release stages, and their curve exponents.

Example: Switch LFO waveform from a UI dropdown

// Fires whenever CurrentArticulation changes (built-in, integer-valued).
// Each articulation index picks a different LFO shape — fine for testing,
// since articulation buttons naturally produce 0, 1, 2, 3 ...
//   0 = Sine, 1 = Triangle, 2 = Saw, 3 = Square
// (assumes a Modulator named "Tremolo" in the instrument)
event CurrentArticulation(Parameter parameter)
{
    Modulator tremolo = getModulator("Tremolo");

    tremolo.setLFOWaveform(parameter);
}

Crossfader

A Crossfader blends smoothly between two or more Articulations, Variations, or Groups based on a single 0.0–1.0 value. As you move that value, the Crossfader interpolates gain across its targets — useful for dynamics layers, blendable mic positions, vibrato amount, or anywhere you want a UI knob to feel like a continuous fader across discrete sample sets.

Each Crossfader is locked to a single target type. The available types are ArticulationCrossfader, VariationCrossfader, and GroupCrossfader. Construct one with the templated factory createCrossfader<Articulation>(), createCrossfader<Variation>(), or createCrossfader<Group>(). Declare the Crossfader at script scope (outside any event handler) so it persists across events.

Example: Crossfade three dynamic-layer Articulations from a UI knob

// Persistent Crossfader, set up once and updated on each knob change
ArticulationCrossfader dynamics;

// (assumes Articulations named "Soft", "Medium", "Hard" in the instrument)
event initialize()
{
    dynamics = createCrossfader<Articulation>();
    dynamics.addTarget(getArticulation("Soft"));
    dynamics.addTarget(getArticulation("Medium"));
    dynamics.addTarget(getArticulation("Hard"));
    dynamics.setEqualPowerCrossfade();   // constant perceived volume
}

event Dynamics(Parameter parameter)
{
    // 0.0 = full Soft, 0.5 = blend Medium/Hard, 1.0 = full Hard
    dynamics.set(parameter.getValue());
}

Construction & targets

Blending

Curve shape

Controls how gain transitions between adjacent targets. The exponent applies to both fading-out and fading-in halves: lowerGain = (1 - blend) ^ exponent, upperGain = blend ^ exponent.

Inspection

Example: Switch between linear and equal-power curves from a button

// (assumes the top-example setup is in place: the "dynamics" ArticulationCrossfader
//  declared at script scope and configured in initialize)
// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as an equal-power / linear curve toggle for portable testing.
event SustainPedal(Parameter parameter)
{
    if(parameter.getBoolValue())
        dynamics.setEqualPowerCrossfade();   // constant perceived volume
    else
        dynamics.setLinearCrossfade();       // constant gain sum
}

Component

A Component is a handle to a single GUI element from your instrument's UI — a knob, button, menu, label, panel, animation, etc. In Figma, components appear as layers marked in purple. From a script you can toggle its visibility, move it, set its value, bind it to a parameter, paint shapes on it, or drive its animation.

Get a Component via the free function getComponent(string controlID). The controlID is the name set on the element in Figma.

Example: Show or hide a panel from a UI button

// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as a panel visibility toggle for portable testing.
// (assumes a Component named "MixerPanel" in the instrument UI)
event SustainPedal(Parameter parameter)
{
    Component mixerPanel = getComponent("MixerPanel");

    mixerPanel.setVisible(parameter.getBoolValue());
}

Visibility & position

Value, text & state

Binding

Connect a Component to data sources at runtime: a UI parameter (so the component reflects and controls that parameter) or a panel variant (for Figma multi-variant panels).

Painting

Draw shapes, text, or images onto a Component at runtime. The vector shapes (Ellipse, Rectangle, Arc, Path) are drawn with fill(...) and stroke(...): each takes the shape plus a Colour or a Gradient. fill fills the shape; stroke outlines it (using the shape's strokeWidth / strokeThickness). They are separate operations — to both fill and outline a shape, call fill and then stroke. Image and Text are drawn with paint(...). Every function draws behind the Component's children; the matching ...Over(...) form draws in front of them.

Animation

For Components that hold animated content (e.g. Lottie or sprite-sheet animations from Figma), these functions control playback.

Example: Drive an animation with a toggle button

// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as an animation play/pause toggle for portable testing.
// (assumes an animated Component named "Spinner" in the instrument UI)
event SustainPedal(Parameter parameter)
{
    Component spinner = getComponent("Spinner");

    if(parameter.getBoolValue())
        spinner.start();
    else
        spinner.pause();
}

Bounds, rotation & scale

Position, orient and scale a Component after creation.

Text formatting

For Label, value-edit and text-edit Components.

Effects & sprites

Attach visual effects and sprite sheets to a Component.

Containers & event routing

Nest Components and route their input to script event handlers.

Menu & list items

For Menu and ListItemBox Components.

The viewRefresh() event

event viewRefresh() fires once per UI "frame" at a configurable rate (default 24 Hz). Use it to update painted UI and animated readouts.

event initialize()
{
    setViewRefreshRate(30);
}

// Update a numeric meter label from the master bus level, 30×/sec
event viewRefresh()
{
    Bus master = getMasterBus();
    Levels lv = master.getLevels();

    Component meter = getComponent("Meter");
    meter.setText(lv.getPeakDecibels(), 1);
}

Creating Widgets at Runtime

Beyond binding to widgets you laid out in Figma, a script can create widgets at runtime (e.g. in event initialize()). Each create function returns a Component handle you keep and drive like any other. Positions and sizes use a Bounds (x, y, width, height in pixels).

The name argument is the new Component's control ID (used later with getComponent).

event initialize()
{
    Component play = createButton("Play", Bounds(10.0f, 10.0f, 80.0f, 30.0f));
}

Colour

Colour is the strong ARGB colour type used across the paint API, replacing the raw int32 values used in earlier builds. It has a single member variable value (int32, packed 0xAARRGGBB), but you normally build colours with the colours:: constructors and read or derive them with the methods below rather than touching value directly.

Construction

The colours:: constructors are free functions that each return a Colour.

There are also named constants such as colours::white, colours::black, colours::red, colours::orange, colours::dodgerblue, and colours::transparent, along with the full CSS/JUCE colour-name set, each a const Colour.

Channels & HSB

Read individual channels as 8-bit integers or normalised floats, or pull out HSB components.

Transforms

Each transform returns an immutable copy; the original colour is unchanged.

// Build a base colour, then derive a translucent, brighter variant
Colour base    = colours::fromRGB(96, 192, 128);
Colour lighter = base.brighter(0.3);
Colour overlay = lighter.withAlpha(0.5);

Paint Primitives

Paint primitives are plain data structs that describe shapes, text, or images to draw onto a Component. The vector shapes (Ellipse, Rectangle, Arc, Path) carry only geometry — colour is supplied at draw time: construct the shape, set its member variables, then pass it to fill(shape, colour) / stroke(shape, colour) (or fillPath / strokePath for a Path), passing a Colour or a Gradient. Image and Text are drawn with paint(image) / paint(text).

Unlike most KODA types, paint primitives don't expose getters or setters — you read and write their member variables directly. All coordinates are in pixels relative to the Component's origin. All sizes are in pixels.

Point & Bounds

Lightweight position and size structs used as building blocks (notably inside Path).

Ellipse

An ellipse shape. Draw it with fill(ellipse, …) and/or stroke(ellipse, …), passing a Colour or a Gradient.

Rectangle

Same as Ellipse, plus a corner-radius member variable for rounded rectangles. Draw with fill(rectangle, …) / stroke(rectangle, …).

Arc

A circular arc swept between two angles. Useful for knob indicators, ring meters, and pie-style readouts. Draw with fill(arc, …) / stroke(arc, …).

Path

A multi-segment vector outline built from straight lines and Bézier curves. Unlike the other primitives you don't set point member variables directly — you build the path by calling its segment functions, then draw it with the Component's fillPath(path, colour|gradient) or strokePath(path, colour|gradient).

// Build a triangle and stroke it onto a Component named "Canvas"
Path tri;
tri.strokeThickness = 2.0f;
tri.startNewSubPath(10.0f, 10.0f);
tri.lineTo(90.0f, 10.0f);
tri.lineTo(50.0f, 80.0f);
tri.close();

Component c = getComponent("Canvas");
c.strokePath(tri, colours::fromHex(0xFFFFFFFF_L));

Gradient

A multi-stop colour gradient. Pass a Gradient in place of a Colour to any fill / stroke / fillPath / strokePath to fill or outline a shape with a gradient. Build it by setting the type and endpoints, then adding up to 16 colour stops with addStop(position, colour).

// Fill a rectangle with a vertical 3-stop linear gradient
Rectangle r;
r.x = 0.0f; r.y = 0.0f; r.width = 120.0f; r.height = 80.0f;

Gradient g;
g.type = GradientType::Linear;
g.x1 = 0.0f; g.y1 = 0.0f;     // top
g.x2 = 0.0f; g.y2 = 80.0f;    // bottom
g.addStop(0.0f, colours::dodgerblue);
g.addStop(0.5f, colours::white);
g.addStop(1.0f, colours::black);

Component c = getComponent("Canvas");
c.fill(r, g);

Image

Paints an image (looked up by name) into a rectangular region. The image must already be available to the instrument (typically exported alongside the Figma UI).

Text

Paints a string of text. Use for runtime-generated labels, value readouts, or status indicators where the text changes based on parameter values.

Font

A font spec for label-style widgets, passed to setFont() / setItemTextFont().

Effect

A visual effect added to a Component via addEffect().

Canvas

A Canvas records a list of paint actions you build once and then draw onto one or more Components with paint(Canvas) / paintOver(Canvas). Use it to avoid re-issuing the same paint calls per component. Declare one with Canvas myCanvas;.

// Build a canvas once, then draw it onto a component
Canvas myCanvas;

Rectangle r;
r.x = 0.0f;  r.y = 0.0f;  r.width = 64.0f;  r.height = 32.0f;
myCanvas.fill(r, colours::dodgerblue);

Component panel = getComponent("Panel");
panel.paint(myCanvas);

SpriteSheet

Describes a sprite sheet passed to setSprite() for animated Components.

MouseEvent

A MouseEvent is passed to your script when the user interacts with a Component that has a mouse event declared. You handle one by writing event <Name>(MouseEvent mouseEvent) { ... }, where <Name> matches the event name set on the Component in Figma. The event payload tells you where the mouse was (x, y), which modifier keys were held, and what kind of mouse action occurred.

Member Variables

Modifier-key helpers

Event-type helpers

KeyEvent

A KeyEvent is passed to your script when a keyboard key is pressed while a Component is focused. Handle one by writing event <Name>(KeyEvent keyEvent) { ... }, where <Name> matches the event name set in Figma.

Member Variables

Key helpers

Modifier-key helpers

GuiEvent

A GuiEvent is passed to your script when a GUI control with a declared GuiEvent fires — typically used by widgets to send arbitrary value-plus-identifier signals. Handle one by writing event <Name>(GuiEvent guiEvent) { ... }, where <Name> matches the event name declared in Figma.

Example: React to a menu selection

event initialize() { setLogEnabled(true); }   // Without this, debug.log() output is silent

event MenuChoice(GuiEvent guiEvent)
{
    debug.log("Menu item index:", guiEvent.getValue());
}

Member Variables

Functions

KeyRange

A KeyRange describes a span of MIDI notes with a name, colour, and tooltip — used to highlight regions of the GUI piano. Construct one directly by setting its member variables, then pass it to showKeyRange() to display it (or hideKeyRange() to remove it).

Example: Highlight the C4 octave on startup

event initialize()
{
    KeyRange octave4;
    octave4.startNote = 60;          // C4
    octave4.endNote = 71;            // B4
    octave4.name = "Octave 4";
    octave4.colour = colours::cornflowerblue;
    octave4.tooltip = "Middle C through B above";

    showKeyRange(octave4);
}

Member Variables

Functions

Highlight regions of the GUI piano and define the playable range.

Pattern

A Pattern is a queue of NoteData events with timing, transposition, and optional tempo-sync — use it to sequence playback. Build it once, then advance it from event process(), pulling out notes as they come due. Declare with Pattern mySeq;.

Building the queue

Playback

Inspection

Pattern mySeq;

event initialize()
{
    NoteData first;
    first.setNoteNumber(60);
    first.setDelayMS(0.0f);
    mySeq.addNote(first);

    NoteData second;
    second.setNoteNumber(64);
    second.setDelayMS(250.0f);
    mySeq.addNote(second);

    mySeq.setLooping(true);
    mySeq.start();
}

event process()
{
    NoteData n;
    while(mySeq.pop(n, getBlockSize()))
        n.start();
}

Saving & Restoring State

KODA can persist script state across sessions (and with the host project). Declare a struct State holding the values you want saved; KODA serializes it automatically when the host saves, and calls event loadState(State state) when restoring so you can read the values back. Keep State fields to plain values (float, int, bool).

The save side is automatic — you only declare struct State and (optionally) implement event loadState.

struct State
{
    float wetMix;
    int mode;
}

float currentWetMix = 0.5;
int currentMode = 0;

// Called when KODA restores saved state
event loadState(State state)
{
    currentWetMix = state.wetMix;
    currentMode = state.mode;
}