Event callbacks are functions called when different types of events are received by the ScriptProcessor. More...

Functions
function	onAfterTouch (e)
	event callback that will receive all incoming channel after-touch events if defined. More...

function	onController (e)
	event callback that will receive all incoming control-change events when defined. More...

function	onEvent (e)
	event callback that will receive all incoming events if defined. More...

function	onInit ()
	initial callback that is called just after the script initialisation if the script was successfully analyzed. More...

function	onLoad (data)
	callback that is called when restoring a ScriptProcessor state if custom data has been saved. More...

function	onNote (e)
	event callback that will receive all incoming note-on events if defined. More...

function	onPitchBend (e)
	event callback that will receive all incoming pitch-bend events if defined. More...

function	onPolyAfterTouch (e)
	event callback that will receive all incoming polyphonic after-touch events if defined. More...

function	onProgramChange (e)
	event callback that will receive all incoming program-change events if defined. More...

function	onRelease (e)
	event callback executed whenever a note off message is received. More...

function	onSave ()
	callback that is called when saving the ScriptProcessor state. More...

function	onTransport (playing)
	event callback that is called when the host transport bar state changes. More...

Detailed Description

Event callbacks are functions called when different types of events are received by the ScriptProcessor.

The default behaviour (if you don't write your own) is to forward the incoming event to the output of the ScriptProcessor. You can customize the default behaviour by writing your own function.

Each callback act as a different thread of execution with its own environment but, unlike threads in traditional Operating Systems, a callback cannot be interrupted unless you ask for it. They can be paused for some specific amount of time (sample-accurate) using the wait function. During that time, other callbacks can be started or resumed in parallel.

You can start new callbacks if you need to using the spawn function.

Function Documentation

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

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

Example:

function onInit()
 local velocity = 100
  for i=0,11 do 
     local note = 60 + i
     local id = playNote(note, velocity, 0) 
     waitBeat(0.5) 
     releaseVoice(id)
  end
end

function onLoad ( 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

Example2:

local a,b,c
function onSave()
  return {a,b,c}
end
function onLoad(data)
  a = data[1]
  b = data[2]
  c = data[3]
end

Example3:

local a,b,c
function onSave()
  local data = {}
  data.a = a
  data.b = b
  data.c = c
  return data
end
function onLoad(data)
  a = data.a
  b = data.b
  c = data.c
end

See Also: onSave

function 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

Example2:

local a,b,c
function onSave()
  return {a,b,c}
end
function onLoad(data)
  a = data[1]
  b = data[2]
  c = data[3]
end

Example3:

local a,b,c
function onSave()
  local data = {}
  data.a = a
  data.b = b
  data.c = c
  return data
end
function onLoad(data)
  a = data.a
  b = data.b
  c = data.c
end

See Also: onLoad

function onEvent ( 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) 
end

See Also: onNote, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

function onNote ( 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) 
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 void 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

See Also: onEvent, onRelease, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

Examples:: Chorder.lua, Ensemble.lua, InvertPitch.lua, Keyswitch.lua, legato.lua, monoBassLine.lua, portamento.lua, quarterTone.lua, TimbreShifting.lua, tremolo.lua, Unison.lua, and vibrato.lua.

function onRelease ( 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) 
  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 void 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

See Also: onEvent, onNote, onProgramChange, onController, onPitchBend, onAfterTouch, onPolyAfterTouch

Examples:: Chorder.lua, Ensemble.lua, InvertPitch.lua, Keyswitch.lua, legato.lua, monoBassLine.lua, portamento.lua, quarterTone.lua, TimbreShifting.lua, and Unison.lua.

function onProgramChange ( e )

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

Parameters

e	event table with the following fields type, program

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

function onController ( e )

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

Parameters

e	event table with the following fields: type, controller, value

Example:

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

function onPitchBend ( e )

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

Example:

ids = {}
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(ids) 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

function onAfterTouch ( e )

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

AfterTouch to pitch Example:

nodeids = {}
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

function onPolyAfterTouch ( 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.AfterTouch
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

function onTransport ( 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

Functions

Detailed Description

Function Documentation