uvi-script
Musical event scripting with Lua
Event Callbacks

Functions

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.
 

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 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:

State Management:

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:

local noteids = {}
function onNote(e)
noteids[e.note] = postEvent(e)
end
function onRelease(e)
noteids[e.note] = nil -- stop retuning released voices
end
function onAfterTouch(e)
for note, id in pairs(noteids) do
changeTune(id, e.value/127)
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
eevent 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:

function onController(e)
print("CC:", e.controller, "Value:", e.value)
postEvent(e) -- just forward event
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
eevent 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()

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
eevent table, see other callbacks for the different kind of table fields

Example:

function onEvent(e)
print(e)
postEvent(e) -- forward event
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()

void 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:

  1. the program's MultiSample oscillators load the mappings it names; their samples may still be arriving when the steps below run,
  2. the main script chunk runs (widgets are created),
  3. the saved widget and parameter values are restored,
  4. onLoad is called if custom data has been saved,
  5. 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
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
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
dataa lua value as saved by your onSave function

Example:

local customData = {notes = {60, 64, 67}, name = "text", enabled = true}
function onSave()
return customData
end
function onLoad(data)
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()

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
eevent 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 = {}
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
void onPitchBend(table e)
event callback that will receive all incoming pitch-bend events if defined.
Parameters
eevent 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 = {}
function onNote(e)
noteids[e.note] = postEvent(e)
end
function onRelease(e)
noteids[e.note] = nil
end
function onPolyAfterTouch(e)
if noteids[e.note] then
changeTune(noteids[e.note], e.value/127)
end
end
void onPolyAfterTouch(table e)
event callback that will receive all incoming polyphonic after-touch events if defined.
Parameters
eevent 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
function onNote(e)
e.channel = channel
end
function onRelease(e)
e.channel = channel
end
function onProgramChange(e)
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
eevent 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:

function onRelease(e)
print("noteoff", e.note, e.velocity)
postEvent(e) -- forward original event
local id = playNote(e.note, 64, 100) -- release trigger, 100 ms long
end
Parameters
eevent 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()

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.

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}
function onSave()
return customData
end
function onLoad(data)
customData = data
end
See also
onLoad

◆ onTransport()

void onTransport ( bool playing)

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

Parameters
playingboolean 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
void onTransport(bool playing)
event callback that is called when the host transport bar state changes.
See also
onInit