|
| void | onInit () |
| | initial callback, called once 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.
|
| |
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 event callback (onInit, onNote, onRelease, onTransport, ...) 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. onSave and onLoad are the exception: they are plain synchronous calls, not coroutines, so wait has no effect in them.
Available Callbacks:
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
◆ onAfterTouch()
| void onAfterTouch |
( |
table | e | ) |
|
event callback that will receive all incoming channel after-touch events if defined.
AfterTouch to pitch Example:
local noteids = {}
end
noteids[e.note] = nil -- stop retuning released voices
end
for note, id in pairs(noteids) do
end
end
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 onAfterTouch(table e)
event callback that will receive all incoming channel after-touch events if defined.
function postEvent(e, delta)
send a script event back to the script engine event queue.
Definition api.lua:959
function changeTune(voiceId, shift, relative, immediate)
change the tuning of a specific voice in (fractional) semitones.
Definition api.lua:567
- 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 (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
|
- 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:
print("CC:", e.controller, "Value:", e.value)
end
void onController(table e)
event callback that will receive all incoming control-change events when defined.
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 (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
|
- See also
- onEvent, onNote, onRelease, onProgramChange, onPitchBend, onAfterTouch, onPolyAfterTouch
◆ onEvent()
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:
print(e)
end
void onEvent(table e)
event callback that will receive all incoming events if defined.
- See also
- onNote, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch
◆ onInit()
initial callback, called once if the script was successfully analyzed.
onInit is not called synchronously at the end of the main script chunk: it is spawned as a thread (see spawn) that starts on the first processed audio block. When a preset is loaded the order is:
- the program's MultiSample oscillators load the mappings it names; their samples may still be arriving when the steps below run,
- the main script chunk runs (widgets are created),
- the saved widget and parameter values are restored,
- onLoad is called if custom data has been saved,
- onInit starts on the first audio block.
onTransport can also be called before onInit: the transport state is checked at the beginning of the audio block, before pending threads are resumed.
This is the place to start a background process that doesn't require external input like algorithmic event generation.
- Note
- Nothing holds notes back until onInit has finished or until samples are loaded, and wait counts rendered audio, not wall-clock time. Do not load the program's own content from here, and do not wait "for loading" — see Program load and warm-up for where mapping loads and unpurges belong.
-
Don't try to create User Interface widgets here, widget creation functions are disabled right after the main script chunk.
Example:
-- chromatic scale
local velocity = 100
for i=0,11 do
local note = 60 + i
local
id =
playNote(note, velocity, 0) -- manual release
end
end
void onInit()
initial callback, called once if the script was successfully analyzed.
function releaseVoice(voiceId)
release a specific voice by sending it a note off message
Definition api.lua:1179
function playNote(note, vel, duration, layer, channel, input, vol, pan, tune, slice, oscIndex, dim1, dim2)
helper function to generate a note event.
Definition api.lua:1089
function waitBeat(beat)
Suspend execution for a tempo-synchronized duration in beats.
Definition conversions.lua:142
◆ onLoad()
| void onLoad |
( |
table | data | ) |
|
callback that is called when restoring a ScriptProcessor state if custom data has been saved.
This is called after the main script chunk has run and after the widget values have been restored. When the script is loaded together with its saved state (preset load), this happens before onInit has started.
- Note
- onLoad is a plain synchronous call, not a thread: wait and waitForRelease have no effect in it. It is usually called from the message thread, where functions that need the audio context such as getTempo(), getBeatDuration() and therefore waitBeat raise an error. Only restore your script state here; do not post or play events.
- Parameters
-
| data | a lua value as saved by your onSave function |
Example:
local customData = {notes = {60, 64, 67}, name = "text", enabled = true}
return customData
end
customData = data
end
table onSave()
callback that is called when saving the ScriptProcessor state.
void onLoad(table data)
callback that is called when restoring a ScriptProcessor state if custom data has been saved.
- See also
- onSave
◆ onNote()
event callback that will receive all incoming note-on events if defined.
Example:
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 given to the voice this note-on triggers when forwarded with postEvent()
- optional
channel MIDI channel in [1;16], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
- 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 1-based slice index for slice oscillators, the same base postEvent() and playNote() expect: the event can be forwarded as is
- optional
oscIndex 0-based oscillator index within the keygroup
- optional
dim1, dim2 zone dispatch coordinates for a MultiSample, absent on regular MIDI notes. See MultiSample (SampleMappingOscillator)
|
- 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:
local noteids = {}
noteids[id] = true
end
noteids[e.id] = nil
end
for id, _ in pairs(noteids) do
end
end
void onPitchBend(table e)
event callback that will receive all incoming pitch-bend events if defined.
- 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 (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
|
- 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:
local noteids = {}
end
noteids[e.note] = nil
end
if noteids[e.note] then
end
end
void onPolyAfterTouch(table e)
event callback that will receive all incoming polyphonic after-touch events if defined.
- 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 (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
|
- 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
e.channel = channel
end
e.channel = channel
end
channel = math.min(e.program + 1, 16) -- program 0 routes to channel 1
end
void onProgramChange(table e)
event callback that will receive all incoming program-change events if defined.
- 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 (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
|
- 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:
print("noteoff", e.note, e.velocity)
local
id =
playNote(e.note, 64, 100) -- release trigger, 100 ms
long
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 of the voice started by the matching note-on (the oldest one still held with the same note, channel and input)
- optional
channel MIDI channel in [1;16], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
- optional
input MIDI input in [1;4], only useful to route events to Parts (omitted for omni; postEvent() also accepts 0 as omni)
- 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
oscIndex 0-based oscillator index within the keygroup
|
- See also
- onEvent, onNote, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch
◆ onSave()
callback that is called when saving the ScriptProcessor state.
This is the place where you can save additional data if you need to.
- Note
- onSave is a plain synchronous call, not a thread: wait and waitForRelease have no effect in it. It is usually called from the message thread, where functions that need the audio context such as getTempo(), getBeatDuration() and therefore waitBeat raise an error. Only return the data to save; do not post or play events. Supported lua types are number, boolean, strings and (nested) tables without (cyclic) references. The data is stored as JSON. A table that mixes array entries and string keys is saved as an object, so its integer keys come back as strings:
{1, 2, name = "x"} reloads with data["1"], while data[1] is nil and #data is 0. Keep arrays and maps in separate tables, e.g. {notes = {1, 2}, name = "x"}.
- Returns
- the lua object that you want to save
Example:
local customData = {notes = {60, 64, 67}, name = "text", enabled = true}
return customData
end
customData = data
end
- See also
- onLoad
◆ 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:
if playing then
print("Transport started")
else
print("Transport stopped")
end
end
void onTransport(bool playing)
event callback that is called when the host transport bar state changes.
- See also
- onInit