Event Callbacks

Functions
void	onInit ()
	initial callback that is called just after the script initialisation if the script was successfully analyzed.
void	onLoad (table data)
	callback that is called when restoring a ScriptProcessor state if custom data has been saved.
table	onSave ()
	callback that is called when saving the ScriptProcessor state.
void	onEvent (table e)
	event callback that will receive all incoming events if defined.
void	onNote (table e)
	event callback that will receive all incoming note-on events if defined.
void	onRelease (table e)
	event callback executed whenever a note off message is received.
void	onProgramChange (table e)
	event callback that will receive all incoming program-change events if defined.
void	onController (table e)
	event callback that will receive all incoming control-change events when defined.
void	onPitchBend (table e)
	event callback that will receive all incoming pitch-bend events if defined.
void	onAfterTouch (table e)
	event callback that will receive all incoming channel after-touch events if defined.
void	onPolyAfterTouch (table e)
	event callback that will receive all incoming polyphonic after-touch events if defined.
void	onTransport (bool playing)
	event callback that is called when the host transport bar state changes.

Detailed Description

Event-driven callback functions that define your script's behavior.

Event callbacks are functions you define that are automatically called when specific events are received by the ScriptProcessor. The default behavior (if you don't define a callback) is to forward incoming events unchanged to the output.

Threading Model:

Each callback executes as an independent cooperative micro-thread (Lua coroutine) with its own environment. Unlike traditional OS threads, callbacks cannot be interrupted unless they explicitly yield using wait, waitBeat, or waitForRelease. During suspension, other callbacks can start or resume in parallel.

Available Callbacks:

• onInit - Called once when script loads
• onNote - Called for each note-on event
• onRelease - Called for each note-off event
• onController - Called for MIDI continuous controller changes
• onPitchBend - Called for pitch bend events
• onPolyAfterTouch - Called for polyphonic aftertouch
• onAfterTouch - Called for channel aftertouch
• onProgramChange - Called for program change events
• onEvent - Master callback for all events (overrides others)

Transport:

• onTransport - Called when host transport state changes (play/stop)

State Management:

• onSave - Called when saving script state
• onLoad - Called when loading saved state

Note

Use local variables within callbacks for per-note state. Global variables are shared across all callbacks.

See also

Threading and Timing, Events, spawn, wait

Function Documentation

onAfterTouch()

void onAfterTouch

(

table

e

)

event callback that will receive all incoming channel after-touch events if defined.

AfterTouch to pitch Example:

noteids = {}
 
function onNote(e)
  noteids[e.note] = postEvent(e)
end
 
function onAfterTouch(e)
  for note, id in pairs(noteids) do
    changeTune(id, e.value/127)
  end
end

Parameters

e	event table with the following fields: type event type equal to Event.AfterTouch value aftertouch value in [0;127] optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts

See also

onEvent, onNote, onRelease, onProgramChange, onController, onPitchBend, onPolyAfterTouch

onController()

void onController

(

table

e

)

event callback that will receive all incoming control-change events when defined.

Example:

function onController(e)
  print("CC:", e.controller, "Value:", e.value)
  postEvent(e) -- just forward event
end

Be aware that you need to forward MIDI CC using postEvent(e) if you want your users to be able to MIDI learn script parameters or use pre-programmed MIDI CC modulations.

Parameters

e

event table with the following fields: type event type equal to Event.ControlChange controller MIDI controller type in [0;127] value MIDI controller value in [0;127] optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts

See also

onEvent, onNote, onRelease, onProgramChange, onPitchBend, onAfterTouch, onPolyAfterTouch

onEvent()

void onEvent

(

table

e

)

event callback that will receive all incoming events if defined.

If this callback is defined it will take over the other more specialized callbacks like onNote, onRelease. All incoming events are tables with at least the type field defined.

Parameters

e	event table, see other callbacks for the different kind of table fields

Example:

function onEvent(e)
  print(e)
  postEvent(e) -- forward event
end

See also

onNote, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

onInit()

void onInit

(

)

initial callback that is called just after the script initialisation if the script was successfully analyzed.

This the place to start a background process that doesn't require external input like algorithmic event generation.

Note

Don't try to create User Interface widgets here, widget creation functions are disabled right after the main script chunk.

Example:

-- chromatic scale
function onInit()
 local velocity = 100
  for i=0,11 do
     local note = 60 + i
     local id = playNote(note, velocity, 0) -- manual release
     waitBeat(0.5) -- 8th notes
     releaseVoice(id)
  end
end

initial callback that is called just after the script initialisation if the script was successfully analyzed.

Hierarchical IR menu with userReady guard

A hierarchical Menu (path-based entries grouped by "/") that loads an impulse response into a SampledReverb insert. The menu's selection is persisted with the preset, so the user's chosen IR survives a save / load round-trip.

Why this example shows the userReady flag:

When a preset loads, the engine restores every persistent widget to its saved value. For widgets whose .changed callback performs an expensive side effect (here loadImpulse, which hits the disk), we must not let that callback fire during the restore — the IR is already in the patch.

The standard guard:

• declare a flag userReady = false at script load,
• flip it to true in onInit (which fires AFTER preset state has been fully restored),
• have any side-effecting .changed early-return when the flag is false.

With the guard in place, only real user clicks trigger loadImpulse. The same pattern protects any expensive .changed side effect: loadSample, network calls, rebuilding a big lookup, etc. See Chorder for the alternative pattern when the menu writes into other widgets and you want the menu non-persistent.

@demonstrates onInit, Menu, Label, loadImpulse, hierarchical menu, userReady guard

onLoad()

void onLoad

(

table

data

)

callback that is called when restoring a ScriptProcessor state if custom data has been saved.

This is called just after the script initialisation and after restoring widgets values when the processing hasn't started yet.

Parameters

data	a lua value as saved by your onSave function

Example:

local customData = {1, 2, 3, a=1, b="text", c=true, d = {"another table"}}
 
function onSave()
  return customData
end
 
function onLoad(data)
  customData = data
end

See also

onSave

onNote()

void onNote

(

table

e

)

event callback that will receive all incoming note-on events if defined.

Example:

function onNote(e)
  print("Note:", e.note, "Velocity:", e.velocity)
  local id = playNote(e.note, e.velocity, -1) -- auto release
end

Parameters

e

event table with the following fields: type event type equal to Event.NoteOn note MIDI note number in [0;127] velocity MIDI note velocity in [1;127] id voice ID that will be affected to the Voice once triggered optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts optional layer in range [1, number of layers], useful to route events to Layers optional vol linear gain in range [0.0, 1.0], default value is 1.0 optional pan panoramic value in range [-1.0, 1.0], default value is 0.0 optional tune detuning in relative semitones, default value is 0.0. This is a floating point value: use 0.01 for detuning of 1 cents optional slice slice index for slice oscillators optional oscIndex oscillator index within the keygroup

See also

onEvent, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

onPitchBend()

void onPitchBend

(

table

e

)

event callback that will receive all incoming pitch-bend events if defined.

Example:

noteids = {}
 
function onNote(e)
  local id = postEvent(e)
  noteids[id] = true
end
 
function onRelease(e)
  noteids[e.id] = nil
end
 
function onPitchBend(e)
  for id, _ in pairs(noteids) do
    changeTune(id, e.bend)
  end
end

Parameters

e	event table with the following fields: type event type equal to Event.PitchBend bend bend value scaled to [-1.0; 1.0] optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts

See also

onEvent, onNote, onRelease, onProgramChange, onController, onAfterTouch, onPolyAfterTouch

onPolyAfterTouch()

void onPolyAfterTouch

(

table

e

)

event callback that will receive all incoming polyphonic after-touch events if defined.

Example:

noteids = {}
 
function onNote(e)
  noteids[e.note] = postEvent(e)
end
 
function onPolyAfterTouch(e)
  if noteids[e.note] then
    changeTune(noteids[e.note], e.value/127)
  end
end

Parameters

e

event table with the following fields: type event type equal to Event.PolyAfterTouch note MIDI note number in [0;127] value aftertouch value in [0;127] optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts

See also

onEvent, onNote, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch

onProgramChange()

void onProgramChange

(

table

e

)

event callback that will receive all incoming program-change events if defined.

Program Change to MIDI channel Example:

local channel = 0
function onNote(e)
  e.channel = channel
  postEvent(e)
end
 
function onRelease(e)
  e.channel = channel
  postEvent(e)
end
 
function onProgramChange(e)
  channel = math.min(e.channel, e.program)
end

Parameters

e	event table with the following fields: type event type equal to Event.ProgramChange program program change value in [0;127] optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts

See also

onEvent, onNote, onRelease, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

onRelease()

void onRelease

(

table

e

)

event callback executed whenever a note off message is received.

Release trigger Example:

function onRelease(e)
  print("noteoff", e.note, e.velocity)
  postEvent(e) -- forward original event
  local id = playNote(e.note, 64, 0, 100)
end

Parameters

e

event table with the following fields: type event type equal to Event.NoteOff note MIDI note number in [0;127] velocity MIDI note velocity in [0;127] id voice ID that will be affected to the Voice once triggered optional channel MIDI channel in [1;16], only useful to route events to Parts optional input MIDI input in [0,3], only useful to route events to Parts optional layer in range [1, number of layers], useful to route events to Layers optional vol linear gain in range [0.0, 1.0], default value is 1.0 optional pan panoramic value in range [-1.0, 1.0], default value is 0.0 optional tune detuning in relative semitones, default value is 0.0. This is a floating point value: use 0.01 for detuning of 1 cents optional slice slice index for slice oscillators optional oscIndex oscillator index within the keygroup

See also

onEvent, onNote, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

onSave()

table onSave

(

)

callback that is called when saving the ScriptProcessor state.

This is the place where you can save additional data if you need to. Supported lua types are number, boolean, strings and (nested) tables without (cyclic) references.

Returns

the lua object that you want to save

Example:

local customData = {1, 2, 3, a=1, b="text", c=true, d = {"another table"}}
 
function onSave()
  return customData
end
 
function onLoad(data)
  customData = data
end

See also

onLoad

callback that is called when saving the ScriptProcessor state.

Chord Harmonizer with Presets

Generates chords by playing up to 6 simultaneous notes with configurable pitch shifts and velocity scaling. Ships with several named presets (Major, Fifth, Jazz, Debusian, etc.) selectable from a Menu widget.

Worth studying: the preset Menu pattern. The Shift / Velocity knobs are left .persistent = true (default) so the engine round-trips their values across save / load. The preset Menu itself is .persistent = false so the engine does NOT restore it via the normal path — that would fire its .changed callback during the restore and overwrite the just-restored knob values. We round-trip the menu's visual selection ourselves with setValue(index, false) in onLoad, where the second arg false tells the widget NOT to fire .changed. The user's last-picked preset name is shown again, the knobs keep their tweaks, and no side effect re-fires.

@demonstrates playNote, Knob, Menu, onSave, onLoad, .persistent, setValue notify flag

onTransport()

void onTransport

(

bool

playing

)

event callback that is called when the host transport bar state changes.

Parameters

playing

boolean flag that tells whether the transport bar is in playing state

Example:

function onTransport(playing)
  if playing then
    print("Transport started")
  else
    print("Transport stopped")
  end
end

See also

onInit