KODA Scripting Reference

Introduction

Conventions used in this reference

How instrument scripts start

Nearly every instrument script opens the same way: an event initialize() that runs once when the instrument loads, switching on logging and setting how much of KODA's automatic note handling you want to keep.

event initialize()
{
    setLogEnabled(true);          // Without this, debug.log() output is silent
    setIgnoreMidiNotes(false);    // Make sure incoming MIDI notes still play
}

• setLogEnabled(true) - logging is off by default, so debug.log() stays silent until you turn it on.
• setIgnoreMidiNotes(false) - KODA keeps triggering notes for you. Use this when the script only listens: logging, GUI work, or modulation.
• setIgnoreNoteOns(true) - KODA stops triggering notes so the script can start them itself with startNote(). setIgnoreMidiNotes(true) does the same for note-offs as well.

These flags live on the instrument, but the script owns them: every time a script loads or reloads, they reset to their defaults before initialize() runs, so the engine only keeps what the current version of the script actually sets. Remove a setIgnoreNoteOns(true) and reload - the engine goes back to handling note-ons. See MIDI input control for the full set.

bool ready;

event process()
{
    if(!ready)
    {
        buildDelayTables();   // sample rate and tempo are real by now
        ready = true;
    }
}

Everything that doesn't depend on timing still belongs in initialize(): logging, MIDI flags, building UI, reading parameters.

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");

// By index - concise in loops
event initialize()
{
    setLogEnabled(true);    // Without this, debug.log() output is silent

    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 stop the playing note, or change its tuning, gain, pan, or trigger its release.

The typical flow is configure (NoteData) → start (returns a Note) → modify (Note):

event initialize() { setIgnoreNoteOns(true); }

event noteOn(NoteData note)  // NoteData is a template for a note to be played
{
    note.setAttack(0.05f);   // Set attack before note 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 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 the built-in Dynamics Parameter:
event Dynamics(Parameter parameter)
{
    Articulation art = getCurrentArticulation();

    art.setGain(parameter.getValue());   // Explicit unwrap
    art.setGain(parameter);              // Parameter overload - same result, less typing
}

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

// ✗ Won't compile
if(parameter > 0.5f)

// ✓ Works
if(parameter.getValue() > 0.5f)

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. Their CC assignments are fixed. The CONTROL tab that will let users remap them is still to come.

Each has a range of 0.0-1.0 except where the table says otherwise. Note that the defaults are not all 0.0. Dynamics starts at 0.8, and BreathController starts at 1.0. If your script reads one of these before the user has touched it, that starting value is what you'll get. They appear in the order below in the app's Instrument Parameters table.

Don't write scripts around the CC numbers themselves. You always address these by name - getParameter("Dynamics"), event Dynamics(Parameter parameter) - and the CC is just an input-routing detail handled outside your code. Once user remapping arrives, a script written this way keeps working with no changes.

How to use the script examples in this reference

Script examples throughout this reference use built-in Parameters like Dynamics, Expression, and SustainPedal so they copy-paste into any instrument and run without you building UI first.

It does make a few examples impractical - bypassing a distortion with the sustain pedal isn't something you'd normally do. Replace the built-in Parameter with one of your own, the Parameter behind your knob or slider, and rename the handler to match:

• A button in place of SustainPedal
• A knob or slider in place of a continuous CC like Expression
• A menu in place of CurrentArticulation

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> or .at()

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 round so it's always valid for an array of size N.

.at(index) does the same job in fewer characters: it takes a plain int and wraps out-of-range values the same way. You can assign through it as well as read from it.

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

int i = 12;
float v = table[wrap<8>(i)];   // 12 wraps into [0, 8) as 4, so v is 0.4
float w = table.at(i);         // same element, so w is 0.4 too

The difference is cost. wrap<N> guarantees the index is in range as part of its type, so the compiler emits no check at all. .at() checks on every access. Either is fine for occasional lookups; prefer wrap<N> in code that runs every block.

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.

Fetching and calling need to be separate lines

Writing art.startNote(note) is shorthand for startNote(art, note), and the dot form needs a named variable on its left. So fetching something and calling a function on it need to be separate lines. Put both on one line and the compiler often can't work out which function you meant.

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

// ✓ Fetch on one line, call on the next
Articulation art = getArticulation("Straight");
Note n = art.startNote(note);

Names you declare share the script with KODA's

Your variables and functions live in the same namespace as every function in this reference. Short, common words - transpose, start, set - are often already taken, and the compiler reports the collision as "The name is already in use", pointing at your declaration. The fix is a more specific name: transposeSemitones instead of transpose.

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 setInstrumentVolume(-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 a note's position only when the transport is playing

event initialize()
{
    setLogEnabled(true);          // Without this, debug.log() output is silent
    setIgnoreMidiNotes(false);    // Make sure incoming MIDI notes still play
}

// 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())
    {
        // Quarter notes elapsed since the start of the timeline (e.g. 2.5 = halfway through beat 3)
        debug.log("Note played at PPQ:", getppqPosition());
    }
}

Logging

Group Structure Section

This is where the Group Structure (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

Your script can read the library's impulse-response .wav files - the same list the Convolution effect shows in its own dropdown - and use them to autopopulate a front-end menu of IRs. They live in the library's IR Samples folder. 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

(Three things have to be in place before this example will run: a Menu widget named mnuConvolution in your Figma UI, a Convolution insert in slot 0 of the master bus, and at least one .wav in the library's IR Samples folder.)

// Runs once when the instrument loads.
event initialize()
{
    createConvolutionMenu("mnuConvolution");   // must match the Menu widget's name
}

// 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);

    return menu;
}

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

Instrument output

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

MIDI input control

Filter or block specific kinds of incoming MIDI messages at the instrument level. These flags reset to their defaults whenever the script loads or reloads, then the script's initialize() re-asserts whatever it sets - so a call removed from the script never lingers in the engine.

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: Print the host's sample rate and tempo

initialize() runs before the first block of audio, so anything the host supplies - sample rate, BPM, time signature, transport position - is still 0 there. Read it from process() or noteOn() instead. The flag below keeps it to a single log line.

bool loggedHostInfo;

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

// Runs once per block of 64 samples, after the host has supplied its info
event process()
{
    if (!loggedHostInfo)
    {
        debug.log("Sample rate:", getSampleRate());
        debug.log("BPM:", getBPM());
        loggedHostInfo = true;
    }
}

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 expression = getParameter("Expression");   // Expression is a built-in parameter. Swap in your own.
float currentExpression = expression.getValue();

Reading values

(Where multiple functions are listed in the below tables, they do the same thing.)

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 must match the Parameter's name (the string passed to getParameter). KODA sends each change to its own handler automatically.

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

Example: Using the Expression parameter to control current articulation volume

event Expression(Parameter parameter)
{
    Articulation art = getCurrentArticulation();  // Get handle to current articulation
    art.setGain(parameter); // Set the volume of the articulation
}

Articulation, Variation & Group

Every KODA instrument's samples are organized 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).

You can use the structure however you like. That said, structuring your articulations in the Articulations section will give KODA automatic awareness of what articulations are available and what the user currently has selected, which lets you harness some automatic functionality for free. Similarly, placing your release tails on the Group level allows you to use built-in release tail trigger functionality.

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 received each note

event initialize()
{
    setLogEnabled(true);          // Without this, debug.log() output is silent
    setIgnoreMidiNotes(false);    // Make sure incoming MIDI notes still play
}

// 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: Alter current articulation volume/pan/tuning with sustain pedal

event initialize()
{
    setLogEnabled(true);          // Without this, debug.log() output is silent
    setIgnoreMidiNotes(false);    // Make sure incoming MIDI notes still play
}

// Fires whenever the sustain pedal moves (built-in, MIDI CC 64 by default)
event SustainPedal(Parameter parameter)
{
    Articulation art = getCurrentArticulation();

    if(parameter.isTrue())      // pedal down
    {
        art.setVolume(-6.0f);       // 6 dB below unity
        art.setPan(-0.5f);          // half left
        art.setTuningCents(50.0f);  // a quarter-tone sharp

        debug.log("Trimmed:", art.getName());
    }
    else                        // pedal up: back to normal
    {
        art.setVolume(0.0f);        // unity
        art.setPan(0.0f);           // centered
        art.setTuningCents(0.0f);   // no offset

        debug.log("Restored:", art.getName());
    }
}

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 mapped 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. This overlay is transient and independent of the articulation's own mapped-range bar (the DISPLAY checkbox in the KEY RANGES module, addressable from a script as the "Playable Range" name via hideKeyRange()).

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. Both are authored in the GROUP VARIABLES section of the Setup tab, where properties are labelled Constants. Use these to attach per-container settings without polluting the global parameter list - and see Using Constants (properties) and parameters to make templates for the pattern that builds on them.

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 "NonVibrato" and "Vibrato".)
event Vibrato(Parameter parameter)
{
    Articulation art = getCurrentArticulation();
    Variation nonVib = art.getVariation("NonVibrato");
    Variation vib   = art.getVariation("Vibrato");

    float blend = parameter.getValue();

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

Example: Manually trigger a release-tail Variation when a note is released

The script takes over note handling so it can decide which Variation sounds and when. Left to itself, KODA sends each note-on to every Variation in the articulation, so the tail would sound on the way down as well as the way up.

// (Assumes the current articulation has Variations named "Sustain" and "ReleaseTail".)

float[128] noteOnVelocity;   // remembers how hard each key was struck

event initialize() { setIgnoreMidiNotes(true); }   // Override automatic note handling so we can implement in script

event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Variation sus = art.getVariation("Sustain");

    noteOnVelocity.at(note.getNoteNumber()) = note.getVelocity();   // Stash it for the release tail
    sus.startNote(note);
}

// Fires when the user lifts a key
event noteOff(NoteData note)
{
    Articulation art = getCurrentArticulation();
    Variation sus = art.getVariation("Sustain");
    Variation tail = art.getVariation("ReleaseTail");

    sus.stopNote(note);   // Stop sustain manually

    // A note-off carries release velocity, so swap in the note-on velocity
    note.setVelocity(noteOnVelocity.at(note.getNoteNumber()));
    tail.startNote(note); // Trigger release tail manually
}

Because the script starts the note, it also has to stop it - nothing releases it otherwise. The noteOnVelocity array lives at module level so it persists between the two events, and .at() is used because a plain int index into a fixed-size array won't compile (see Cmajor patterns you'll see).

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

// (Assumes first insert of the Group is a Filter effect.)

event initialize() { setIgnoreMidiNotes(false); }   // Make sure incoming MIDI notes still play

// 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)
    float cutoffHz = 200.0f + note.getVelocity() * 10000.0f; // Adjust to taste, depending on the instrument
    group.setInsertParameter(0, Filter::Cutoff, cutoffHz);
}

Insert parameters are addressed by index, but each effect publishes named constants for its own - Filter::Cutoff, Filter::Resonance, and so on - which read better and survive an effect gaining parameters.

Example: Bypass a distortion with the sustain pedal

// Holding the sustain pedal bypasses the distortion on the group's FX insert.
// (Assumes a distortion in the first insert slot 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(0, 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).

Always blank a NoteData before you use it

A NoteData you declare yourself starts out full of zeros - zero volume, zero tuning - so it plays nothing, silently. Blanking it sets those values to "inherit from the Group" instead. Three ways to get a usable note:

Example: Build a note from scratch

// Holding the sustain pedal plays middle C on the current articulation.

Note playing;                       // Handle to the note, so we can stop it again

event SustainPedal(Parameter parameter)
{
    Articulation art = getCurrentArticulation();

    if(parameter.isTrue())          // Pedal down: build a note and play it
    {
        NoteData note;              // Build a note from scratch
        note.initialize();          // Blank it, or it plays silently
        note.setNoteNumber(60);     // Middle C
        note.setMidiVelocity(100);

        playing = art.startNote(note);
    }
    else                            // Pedal up: stop it
    {
        playing.stop();
    }
}

Example: Add an octave-up echo to every note

Note[128] echoes;   // One handle per MIDI note, so each echo can be stopped

event initialize() { setIgnoreMidiNotes(false); }   // Original note pressed by user is handled automatically

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

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

    echoes.at(incoming.getNoteNumber()) = art.startNote(echo); // Start echo manually and store note handle
}

// Fires when the user lifts a key
event noteOff(NoteData incoming)
{
    Note echo = echoes.at(incoming.getNoteNumber()); // Retrieve note handle
    echo.stop(); // End echo manually
}

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() { setIgnoreNoteOns(true); }  // Override automatic note-on handling

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() { setIgnoreNoteOns(true); }  // Override automatic note-on handling

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); }  // Override automatic note-on handling

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

    // Scale the release straight off velocity: harder hits ring out longer
    float releaseSeconds = note.getVelocity() * 3.0f;    // velocity is 0.0-1.0, so 0.0-3.0 seconds
    playing.setRelease(releaseSeconds, 1.0f);            // 1.0 = a 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 behavior 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

// Logs to the debug console when three or more notes are pressed at once.

event initialize()
{
    setLogEnabled(true);          // Without this, debug.log() output is silent
    setIgnoreMidiNotes(false);    // Make sure incoming MIDI notes still play
}

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 standard 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
}

Use process() for anything you can hear, and viewRefresh() for anything you can see. viewRefresh() fires at 12-60 Hz, far too slow to step a glide smoothly, and its frame timing isn't guaranteed, so you can't measure elapsed time from it. process() gives you both: a fast rate, and an exact time step you can calculate.

Block-delta seconds

To advance a glide, fade, or any other value that changes over time, you need to know how much 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: 200 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;                        // Handle to the note currently gliding
bool gliding;                            // True while a glide is in progress
float glideElapsedSec;                   // Seconds since this glide started
const float kGlideDurationSec = 0.2f;    // Glide length. Portamento usually sits around 0.1 - 0.3
const float kGlideSemitones = -1.0f;     // Glide distance. Negative starts below pitch, positive above

event initialize() { setIgnoreNoteOns(true); }  // The script plays the note, not KODA's default routing

event noteOn(NoteData note)
{
    Articulation art = getCurrentArticulation();
    currentNote = art.startNote(note);   // Keep the handle so we can retune the note while it sounds

    // Start off-pitch by kGlideSemitones, then glide up to natural pitch
    currentNote.setTuningSemitones(kGlideSemitones);
    glideElapsedSec = 0.0f;
    gliding = true;
}

event process()                          // Runs once per audio block
{
    if(!gliding)                         // Nothing to do between glides
        return;

    float blockSec = float(getBlockSize()) / float(getSampleRate());   // How much time one block covers
    glideElapsedSec += blockSec;

    float ratio = min(glideElapsedSec / kGlideDurationSec, 1.0f);      // 0.0 at the start, 1.0 when finished
    currentNote.setTuningSemitones(kGlideSemitones * (1.0f - ratio));  // Shrink the offset to zero as ratio rises

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

Combining glide and vibrato on the same note

The scripted glide and vibrato below are both intended to change the same note's tuning. The problem is that note setters are absolute, so each call replaces the last one. If the two wrote their own values, you'd hear only whichever ran last. The solution is to add their offsets into one total instead, and apply that in a single call.

Note currentNote;
bool gliding;
float glideElapsedSec;
bool vibratoActive;
float vibratoPhase;                          // Kept between blocks so the sine stays continuous
const float kGlideDurationSec = 0.2f;
const float kGlideSemitones = -1.0f;
const float kVibratoHz = 5.0f;               // Vibrato speed in cycles per second
const float kVibratoDepthSemitones = 0.15f;  // Roughly a 15 cent wobble either side

event initialize() { setIgnoreNoteOns(true); }  // The script plays the note, not KODA's default routing

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

    glideElapsedSec = 0.0f;                  // Start both modulators from scratch on every note
    gliding = true;
    vibratoPhase = 0.0f;
    vibratoActive = true;
}

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

    float totalSemitones = 0.0f;             // Each modulator adds its offset here

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

    if(vibratoActive)
    {
        // Phase counts whole cycles, so scale it by twoPi for sin().
        // twoPi is a Cmajor built-in constant, and a float64, so cast it to keep the math in float
        vibratoPhase += kVibratoHz * blockSec;
        totalSemitones += kVibratoDepthSemitones * sin(vibratoPhase * float(twoPi));
    }

    // One call carries both offsets
    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.

Buses are also how a signal becomes visible to the user. Each one can appear as a channel strip in the plugin's Mix tab with its own fader, pan, solo and mute buttons, and meters, so anything you want the user to mix has to live on a bus.

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

Example: Drive a reverb send from a MIDI controller

// 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 main = getBus("Main");   // The first bus in the mixer, called "Main" by default

    // Send a portion of that bus's output to the first send bus (send index 0)
    main.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 run from 0.0 (silence) to ~3.98 (+12 dB), with 1.0 at unity (0 dB). Decibel values are floored at -180 dB, so a silent bus reads exactly -180.

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 Signal (Mic) token in each filename (e.g. Close, Room, Overheads), and the unique set across all clips becomes the instrument's mic list. Each mic becomes an object you can address by name or index.

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

Mic functions cover level and position: gain, pan, solo, and mute. To enable or disable a mic entirely, bypass the Bus it's routed to, which drops the preloaded samples of every mic on that bus.

Example: Tie a mic's gain to a MIDI controller

// Fires when BreathController changes (built-in, MIDI CC 3 by default).
// Repurposed here as close-mic gain for portable testing. It starts at 1.0,
// so the mic sits at full gain until the controller is moved.
// (Assumes a mic named "Close" in the instrument.)
event BreathController(Parameter parameter)
{
    Mic close = getMic("Close");   // Rename this to any mic you want to control

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

Identity & state

Gain & pan

Solo & mute

These mirror the solo and mute buttons users see for each mic in the plugin's mic mixer. To enable or disable a mic, bypass its Bus - see the note at the top of this section.

Example: Toggle a mic on/off from a MIDI controller

// Fires when SustainPedal changes (built-in, MIDI CC 64 by default).
// Repurposed here as a Room-mic on/off toggle for portable testing.
event SustainPedal(Parameter parameter)
{
    Mic room = getMic("Room");   // Rename this to any mic you want to control

    // Pedal down silences the Room mic, pedal up brings it back
    room.setMute(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 a MIDI controller

// Dynamics controls modulator depth (built-in, MIDI CC 1 by default).
// (Assumes a Modulator named "Vibrato" in the instrument.)
event Dynamics(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 with the current articulation

// Switching the current articulation number also changes the LFO wave shape
// (in your own instrument, swap in the Parameter behind a menu widget)
// 0 = Sine, 1 = Triangle, 2 = Saw, 3 = Square, 4 = SampleHold, 5 = Drift
// (Assumes an LFO Modulator named "Tremolo" in the instrument.)
event CurrentArticulation(Parameter parameter)
{
    Modulator tremolo = getModulator("Tremolo");

    tremolo.setLFOWaveform(parameter);
}

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 a Figma project, components appear in the left panel 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 an on/off Parameter

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

Not every Component type can be painted on. Paint onto a plain Component (no type set) or a panel; buttons, sliders, labels and animations work too. A menu authored in Figma, a level meter, a table, and an XY pad draw themselves instead, and discard script paint silently - no error, nothing drawn.

Coordinates are measured from the Component's own top-left corner, in the same units as your Figma layout, so a drawing keeps its place and proportions as the plugin is resized. A script can't read a Component's size back, so the numbers you paint with have to match the size the Component has in Figma. Keeping that size in a constant at the top of the script, as below, saves hunting for stray numbers when the layout changes.

What you paint stays on the Component until you clear it. If you repaint every frame from viewRefresh(), call clearCanvas() first. Otherwise each frame's drawing piles on top of the last and the Component fills up with old artwork. The usual shape is clear, then draw:

Example: Vector-painted pulse that follows the master level

// A pulse that grows and shifts from green to red with the master bus level.
// (Assumes a plain component named "LevelGlow", 100 x 100 px in Figma.)

const float kSize = 100.0f;      // must match the component's size in Figma (square)
const float kFloorDb = -48.0f;   // the level that maps to the smallest circle
const float kFallRate = 0.15f;   // how fast the circle shrinks back: 0 = frozen, 1 = instant

float displayLevel;              // 0..1, kept between frames so the fall is smooth

event initialize()
{
    setViewRefreshRate(60);      // the fastest UI rate KODA allows
}

event viewRefresh()
{
    Bus master = getMasterBus();
    Levels levels = master.getLevels();

    // Work in decibels. Linear gain spends most of its range close to silence,
    float db = levels.getPeakDecibels();                          // -180 (silence) .. 0 (unity)
    float target = limit((db - kFloorDb) / -kFloorDb, 0.0f, 1.0f);   // -48..0 dB becomes 0..1

    // Meter ballistics: jump straight up to peaks, then ease back down
    if(target > displayLevel)
        displayLevel = target;
    else
        displayLevel = displayLevel + (target - displayLevel) * kFallRate;

    Component glow = getComponent("LevelGlow");
    glow.clearCanvas();          // wipe last frame, or the circles stack up

    // Centered circle, growing from 10% to 100% of the component's width
    float diameter = kSize * (0.1f + displayLevel * 0.9f);
    float inset = (kSize - diameter) * 0.5f;
    Ellipse disc = (inset, inset, diameter, diameter, 0.0f);      // last member is strokeWidth

    // Hue sweeps green -> yellow -> red as the level rises; alpha brightens with it
    float hue = 0.33f * (1.0f - displayLevel);   // 0.33 = green, 0.16 = yellow, 0.0 = red
    glow.fill(disc, getColourHSBA(hue, 0.9f, 1.0f, 0.25f + displayLevel * 0.75f));
}

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.

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

A Component made this way arrives with no artwork, so it is invisible until you give it one, either by attaching a sprite sheet with setSprite or by painting on it. It is also inert until you connect it to something: setParameter links a button to a Parameter, so clicking it drives that Parameter and your handler for it runs. The example below does both.

Example: Build a Play button in the script

// Draws a rectangular green button in the upper left of the GUI
// (Assumes a Parameter named "PlayToggle" in the instrument.)

const float kButtonWidth = 240.0f;
const float kButtonHeight = 80.0f;

Component playButton;      // kept at script scope so later events can repaint it

event initialize()
{
    playButton = createButton("Play", Bounds(10.0f, 10.0f, kButtonWidth, kButtonHeight));
    playButton.setParameter("PlayToggle");   // clicks now drive that Parameter
    paintButton(false);                     // draw the "off" look right away
}

// Fires whenever PlayToggle changes, including the click that changed it
event PlayToggle(Parameter parameter)
{
    paintButton(parameter.isTrue());
}

// Paint coordinates are local to the button, so they start at 0, 0
void paintButton(bool playing)
{
    playButton.clearCanvas();

    // Rectangle members are x, y, width, height, strokeWidth, cornerRadius
    Rectangle body = (0.0f, 0.0f, kButtonWidth, kButtonHeight, 0.0f, 6.0f);
    playButton.fill(body, playing ? colours::limegreen : colours::dimgrey);
}

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 change them with the functions 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 normalized 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.3f);
Colour overlay = lighter.withAlpha(0.5f);

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. A Rectangle or Ellipse is described by setting its member variables - x, y, width, height. A Path isn't: you build it by calling its segment functions, then draw it with the Component's fillPath(path, colour|gradient) or strokePath(path, colour|gradient).

Build and draw as many Paths as you like in one function. Each draw call carries that path's own points, so paths never interfere with one another, and calling fillPath and then strokePath on the same Path fills it and then outlines it.

Example: Paints a triangle onto a Component

// Paints a triangle onto a plain Component named "Canvas" (100 x 100 px in Figma).
event initialize()
{
    Path triangle;
    triangle.strokeThickness = 2.0f;
    triangle.startNewSubPath(10.0f, 10.0f);
    triangle.lineTo(90.0f, 10.0f);
    triangle.lineTo(50.0f, 80.0f);
    triangle.close();

    Component canvas = getComponent("Canvas");
    canvas.strokePath(triangle, colours::red);
}

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

Example: Paints a gradient-filled rectangle

// Fills a plain Component named "Canvas" (100 x 100 px in Figma) with a 3-stop linear gradient.
event initialize()
{
    Rectangle r = (0.0f, 0.0f, 100.0f, 100.0f, 0.0f, 0.0f);   // x, y, width, height, strokeWidth, cornerRadius

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

    Component canvas = getComponent("Canvas");
    canvas.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.

*** Not implemented yet. Painting a Text draws a placeholder and ignores every member below. For text that changes at runtime, use a Label Component and setText.

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

Example: Paints a prebuilt Canvas onto a Component

// Builds the artwork once, then draws it onto a plain Component named "Canvas" (100 x 100 px in Figma).
event initialize()
{
    Canvas artwork;

    Rectangle r = (0.0f, 0.0f, 100.0f, 100.0f, 0.0f, 0.0f);   // x, y, width, height, strokeWidth, cornerRadius
    artwork.fill(r, colours::dodgerblue);

    Component canvas = getComponent("Canvas");
    canvas.paint(artwork);
}

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 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 a value plus an identifier. Handle one by writing event <Name>(GuiEvent guiEvent) { ... }, where <Name> matches the event name declared in Figma.

Example: React to a menu selection

// Clears a menu, populates new items, and logs the selected item's value
// (Assumes a Menu named "MyMenu" in your kdui, with property "GuiEvent" set to "MenuChoice".)
event initialize()
{
    setLogEnabled(true);       // Without this, debug.log() output is silent

    Component menu = getComponent("MyMenu");
    menu.clearItems();          // drop the items defined in Figma first
    menu.addItem("Alpha", 100);
    menu.addItem("Beta", 250);
}

event MenuChoice(GuiEvent guiEvent)
{
    debug.log("Menu item value:", int(guiEvent.getValue()));   // 100 or 250, not 1 or 2
}

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. There are two kinds of range a script can work with:

• Script-drawn ranges - construct a KeyRange, then addKeyRange() draws it and removeKeyRange() / clearKeyRanges() take it down. These are transient overlays owned by the script (matched by name); they are cleared on every recompile and never saved with the instrument.
• Ranges authored in the KEY RANGES module (Setup page) - showKeyRange() / hideKeyRange() toggle the visibility of an existing range whose display name matches the KeyRange.name you pass (every match, at instrument and articulation scope). Only name is read; the other members are ignored. The per-articulation mapped range (the drawn-on-demand span of every note the articulation's zones cover) answers to the name "Playable Range", so a script can hide or show it the same way.

Example: Highlight keys C3 to B3 on startup

event initialize()
{
    KeyRange octave3;
    octave3.startNote = 60;          // C3
    octave3.endNote = 71;            // B3
    octave3.name = "Octave 3";
    octave3.colour = colours::cornflowerblue;
    octave3.tooltip = "Middle C through B above";

    addKeyRange(octave3);          // script-drawn overlay

    KeyRange mapped;
    mapped.name = "Playable Range";
    hideKeyRange(mapped);           // hide every articulation's mapped range
}

Member Variables

Functions

Highlight regions of the GUI piano. All of these are also available on the Keyboard struct returned by getKeyboard().

Pattern

A Pattern is a note sequencer that lives in your script: fill it with NoteData events placed at beat positions, give it a length in beats, and it plays them back - once, or looping. Everything about a Pattern is musical time: positions, the loop length, and note gates are all beats, converted to samples against the live host tempo as the notes fire. Tempo sync isn't a mode you enable - it's what a Pattern is. Change the DAW tempo mid-loop and the pattern follows, with no reference tempo to declare anywhere.

Declare Patterns at the top level of the script (they're big - see Large object scope), and give each one its per-block pulse by calling update() from event process(). That call is the one piece of wiring every Pattern needs.

The smallest useful Pattern is a one-note repeater - hold a key and it retriggers every beat:

Pattern repeater;

event initialize() { setIgnoreNoteOns(true); }

event noteOn (NoteData note)
{
    repeater.setTarget(getCurrentArticulation());   // route fired notes to the current articulation
    repeater.repeat(note, 1.0);                      // loop the held note every beat
}

event noteOff (NoteData note) { repeater.stop(); }

event process() { repeater.update(); }

Building

Add events with addNote() - each call copies the NoteData you pass in, so one NoteData variable can be reused to lay down every step (see the melody example below). A Pattern holds up to 1024 events; additions beyond that are silently ignored.

Playback

Example: A melody sequencer

One NoteData lays down every step, and the pattern re-keys itself to whatever key is held. Because positions and gates are beats, this is safe to build in initialize() and rescales to any host tempo:

Pattern melody;

const int kRoot = 60;   // the melody is written around middle C

event initialize()
{
    setIgnoreNoteOns(true);

    var art = getCurrentArticulation();
    NoteData step = art.createNoteData();   // a blank note, routed to this articulation
    step.setMidiVelocity(100);

    // note number            position (beats)  length (beats)
    step.setNoteNumber(60);  melody.addNote(step, 0, 0.5);
    step.setNoteNumber(64);  melody.addNote(step, 1, 0.5);
    step.setNoteNumber(67);  melody.addNote(step, 2, 0.5);
    step.setNoteNumber(64);  melody.addNote(step, 3, 0.5);

    melody.setLengthInBeats(4);
    melody.setLooping(true);
}

event noteOn (NoteData note)
{
    melody.setTransposition(note.getNoteNumber() - kRoot);   // play it in the held key
    melody.start();
}

event noteOff (NoteData note) { melody.stop(); }

event process() { melody.update(); }

Explicit note-off events are also possible for cases where an off shouldn't be tied to its own on: add a note with setIsNoteOff(true) at any beat before the pattern length and it fires as a note-off. For ordinary melodic gates, prefer the length argument - it stays correct across the loop wrap.

Saving & Restoring State

Advanced Topics

You can script KODA without anything in this section. These topics start to matter as scripts grow - more data, code you want to reuse across instruments, and the failure modes that only show up at scale. Each topic stands alone, so dip in as needed.

Passing by value vs reference

Assigning a value or passing it to a function makes a copy - structs and arrays included. Changes to the copy never reach the original, which is also why editing a NoteData after starting the note has no effect (see Note vs NoteData).

To let a function change what the caller passed in, mark the parameter with &:

// ✗ By value - boost() changes its own copy
event initialize() { setLogEnabled(true); }

void boost (float value) { value += 0.2f; }

event noteOn (NoteData note)
{
    float v = 0.5f;
    boost(v);
    debug.log("v", v);   // still 0.5
}

// ✓ By reference - boost() changes the caller's v
event initialize() { setLogEnabled(true); }

void boost (float& value) { value += 0.2f; }

event noteOn (NoteData note)
{
    float v = 0.5f;
    boost(v);
    debug.log("v", v);   // now 0.7
}

& works in one place only: parameters being passed into a function. A function cannot return a reference - returning always hands back a copy - and there are no reference variables. So a function that should give the caller a changed value either returns the copy for the caller to assign, or writes into a & parameter as above. Copying is fine for small values; for big ones, see the next topic.

Large object scope

Declare big arrays and structs at the top level of the script, not inside functions. Top-level variables live for the lifetime of the instrument and are shared by every function; function locals are copied around and limited in size. Pass a big object to your own helper with & so the helper works on it in place:

// A big lookup table: declared at the top level, filled in place through a & parameter
float[1024] table;                     // top level - lives with the instrument

void fill (float[1024]& t)             // & - fills the caller's table, no copy
{
    for (wrap<1024> i)
        t[i] = float(i) / 1023.0f;
}

event initialize()
{
    setLogEnabled(true);
    fill(table);
    debug.log("table.at(512)", table.at(512));   // 0.500489
}

Index lookup tables with wrap<N> or .at() as described in Cmajor patterns you'll see.

Generics (functions, namespaces)

A generic function is written once and works for every type you call it with - the compiler builds a version per type. Put <Type> after the name, then use Type as a placeholder. The built-in limit() works this way, which is why it accepts int and float alike.

// One generic function serving two types: int and float
event initialize() { setLogEnabled(true); }

Type highest<Type> (Type a, Type b)
{
    static_assert (Type.isPrimitive, "highest() needs a numeric type");
    return a > b ? a : b;
}

event noteOn (NoteData note)
{
    debug.log("int", highest(3, 7));                        // 7
    debug.log("float", highest(note.getVelocity(), 0.5f));   // at least 0.5
}

static_assert is a check that runs at compile time: if its condition is false, compilation stops and its message becomes the error. Here it's optional but worth the keystrokes - without it, calling the function with a type it can't handle fails with a confusing compiler error instead of your own message. Namespaces can be parameterised the same way - see the Cmajor language documentation.

Designing your own structs

A struct groups related values under one name, and every member variable starts at zero - there are no member initialisers, so a struct needs no constructor. If a member should start at some other value, set it in initialize(). Functions declared inside the struct refer to it as this, and calling them follows the same two spellings as everything else (see dot or no dot).

If you're coming from an OOP language, a struct is the closest thing to a class, with one big difference up front: there is no inheritance. A struct cannot extend another, so build bigger structs by composition - one struct as a member of the next. Otherwise the shape is familiar: member variables plus the functions that work on them, called with dot syntax. Two smaller differences: a struct is a plain value - assigning or passing one copies it (see Passing by value vs reference), where a class object in most languages is shared by reference - and there is no constructor, so every struct starts zeroed, every time.

// A struct that accumulates a running average across noteOn calls
struct VelocityStats
{
    float total;
    int   count;

    void  add (float v) { this.total += v; this.count++; }
    float average()     { return this.count == 0 ? 0.0f : this.total / float(this.count); }
}

VelocityStats stats;                    // top level, zero-initialised

event initialize() { setLogEnabled(true); }

event noteOn (NoteData note)
{
    stats.add(note.getVelocity());
    debug.log("average velocity", stats.average());
}

Name your struct anything except State - that name opts into the save and restore machinery described in Saving & Restoring State.

Using Constants (properties) and parameters to make templates

Constants let one script serve many instruments: instead of hard-coding numbers, the script reads named values authored per-instrument in the GROUP VARIABLES section of the Setup tab. The script side calls them properties - the property getters on Articulation, Variation, and Group read them by name. Despite the name, a Constant has nothing to do with the const keyword: it is constant from the script's point of view because only the instrument author can change it, and your script reads it into an ordinary variable.

A name that isn't authored on the instrument reads as "", 0, or false rather than erroring. That silence is what lets one script load everywhere, but it means a template should check and log its fallbacks, so an instrument builder can see what's missing. Read Constants once in initialize() and keep the values in top-level variables:

// Read a per-instrument Constant (property) with a logged fallback when it's missing
int transposeSemitones;                 // read once at startup

event initialize()
{
    setLogEnabled(true);

    Articulation art = getCurrentArticulation();

    if (art.getProperty("Transpose") == "")
        debug.log("No 'Transpose' Constant - using 0");

    transposeSemitones = art.getIntProperty("Transpose");
    debug.log("transposeSemitones", transposeSemitones);
}

Avoiding infinite loops

Everything your script does - noteOn, process, every event - runs inside KODA's audio engine, so a loop that never exits doesn't just stall the script, it freezes all of KODA. The compiler rejects loops it can prove never exit (a bare loop {} fails with "The function contains at least one infinite loop"), but it cannot catch a loop whose exit depends on a value that never arrives. Floats are the classic trap: stepping by 0.1f never lands exactly on 1.0f, so a != test stays true forever.

// ✗ Compiles cleanly, then freezes KODA on the first note
event noteOn (NoteData note)
{
    float t = 0.0f;
    while (t != 1.0f)      // never exactly 1.0
        t += 0.1f;
}

// ✓ Bounded by construction
event noteOn (NoteData note)
{
    float t = 0.0f;
    loop (10)               // runs exactly 10 times
        t += 0.1f;
}

Prefer loops that are bounded by construction: the counted loop (n) form, for loops with fixed bounds, and < comparisons rather than != when the condition involves a float.

Avoiding NaN

NaN - "not a number" - is what float maths produces when an operation has no answer, like 0.0f / 0.0f or the square root of a negative. It spreads: any arithmetic that touches a NaN yields NaN, and every comparison against NaN is false, so range checks and clamps wave it through, and a != loop condition holding a NaN never exits (see Avoiding infinite loops).

The place scripts usually meet one: timing functions inside initialize(), before any audio is flowing. getBlockTimeSeconds() divides two values that are still zero there and reads NaN. Guard with isnan() before a value like that reaches a setter:

// Where NaN shows up, and how to stop it before it reaches a setter
event initialize()
{
    setLogEnabled(true);
    debug.log("block time", getBlockTimeSeconds());   // logs nan - no audio yet
}

event noteOn (NoteData note)
{
    float64 blockTime = getBlockTimeSeconds();

    if (isnan(blockTime))
        return;                                       // never let NaN reach a setter

    debug.log("block time", blockTime);               // real value, e.g. 0.001333
}

An unguarded NaN fails silently: fed into setInstrumentGain, the instrument simply goes quiet - no error, no log message, just no sound until the script is fixed and the instrument reloaded. If a value could ever come from a division, check the denominator or check the result with isnan() (and isinf() for its cousin) before using it.