Lua API Reference

Lua scripting is a fully supported alternative to NeuroScript for advanced MIDI transformations.

When to Use Lua

Choose Lua when you need:

• Complex control structures — for/while loops, procedural logic, tables
• Imperative style — step-by-step procedural programming
• Familiar syntax — standard programming language (not domain-specific)

Choose NeuroScript when:

• Sharing presets — NeuroScript is the canonical export/import format
• Simple transforms — declarative, musician-friendly syntax
• Visual editing — UI compiles to NeuroScript

Complementary Languages

Both Lua and NeuroScript access the same MIDI state, clock, BPM, and transport. You can mix both in different routes.

Security: Lua runs in a restricted sandbox (deterministic libs only). Logging functions like console.log(...) are no-ops in the Lua sandbox.

Event Structure

event = {
  type = "noteOn",  -- or "noteOff", "cc", etc.
  channel = 0,      -- 0-15
  data1 = 60,       -- 0-127
  data2 = 100,      -- 0-127
  timestamp = 1234567890
}

Neurode MIDI Library

The neurode table provides high-level MIDI operations:

-- Create MIDI events
neurode.note(pitch, velocity, channel)     -- Create note-on event
neurode.cc(controller, value, channel)     -- Create CC event
neurode.programChange(program, channel)    -- Create PC event

-- Call pre-compiled NeuroScript functions
neurode.callScript("transpose", event, 12) -- Transpose up an octave
neurode.callScript("velocityScale", event, 0.8)

-- Scheduling
neurode.scheduleAt(time_ms, event)         -- Schedule event in milliseconds
neurode.scheduleAtBeat("1/8", event)       -- Schedule at next eighth note

-- Transport information
local bpm = neurode.getBPM()               -- Current tempo
local playing = neurode.isPlaying()        -- Transport state

-- Utility functions
MIDI.noteName(60)        -- "C4"
MIDI.noteNumber("C#3")   -- 49
MIDI.clamp(value)        -- Clamp to 0-127

Pre-compiled NeuroScript Functions:

• transpose — Shift notes by semitones
• velocityScale — Multiply velocity by factor
• channelMap — Remap MIDI channel
• More functions available through the NeuroScript API (see Neuroscript Reference)

Context Store

context.set(scope, key, value)
local value = context.get(scope, key)
context.delete(scope, key)
local keys = context.keys(scope)

-- There is no context.has(...); use get(...) ~= nil.
local exists = (context.get(scope, key) ~= nil)

Scopes: "local", "graph", "global"

Scheduling & Output Tags

Your script can schedule an event to emit in the future by returning an event table with one of the supported schedule fields:

-- Schedule by milliseconds
event.afterMs = 120

-- Or schedule by note fraction (e.g. eighth note)
event.after = "1/8"
-- event.afterNumerator = 1
-- event.afterDenominator = 8

-- Optional: tag for downstream routing
event.outputTag = 3
-- event.tag = 3

return event

Examples

See the Lua examples in the app’s Script Engine “Examples” menu for complete examples.

Next Steps

• Event Model — Deep dive into events