uvi-script
Musical event scripting with Lua
Events
function postEvent (e, delta)
 send a script event back to the script engine event queue.
 
function playNote (note, vel, duration, layer, channel, input, vol, pan, tune, slice, oscIndex, dim1, dim2)
 helper function to generate a note event.
 
function releaseVoice (voiceId)
 release a specific voice by sending it a note off message
 

Detailed Description

Event structure and event manipulation functions.

Events represent musical messages (notes, controllers, etc.) flowing through the system. This group provides functions to create, modify, post, and inspect events.

Event Structure:

Events are Lua tables with fields like:

Key Functions:

See also
Event Callbacks, Voice Manipulation

Function Documentation

◆ playNote()

function playNote ( note ,
vel ,
duration ,
layer ,
channel ,
input ,
vol ,
pan ,
tune ,
slice ,
oscIndex ,
dim1 ,
dim2  )

helper function to generate a note event.

  • if duration is greater than 0 the voice will be released after the given duration
  • if duration is -1 the voice will be released when the note that created this callback is depressed (the NoteOff of the event onNote() was called with), even if the callback returned before. This depends on where playNote is called from:

    • from a callback that was not started by an event (onInit(), onTransport(), async task callbacks...) the voice is released immediately, so nothing is heard for more than an instant
    • from a callback started by another event type (onController(), onRelease()...) or from a function launched with spawn() or run(), the voice is never released automatically
    • from a widget callback it raises an error

    In these cases pass an explicit duration, or use 0 and releaseVoice().

  • if duration is 0 only the note-on is sent: release has to be done manually using releaseVoice and the returned id

playNote also accepts a single table in place of the positional arguments. Fields can be given by name (note, velocity, duration, layer, channel, input, vol, pan, tune, slice, oscIndex, dim1, dim2) or by numeric index following the positional order (playNote{60, 100} is playNote(60, 100)). Omitted fields take the same default values as the positional form. This avoids writing a run of nil placeholders when the fields you need are far apart in the positional list:

-- equivalent to playNote(60, 100, -1, nil, nil, nil, nil, nil, nil, nil, 2)
playNote{note=60, oscIndex=2}
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
Parameters
note(optional) the note number in the range [0;127], default is 0
vel(optional) the note velocity in the range [1;127], default is 100 (velocity in the table form)
duration(optional) duration of the note in milliseconds, default is -1
layer(optional) target layer index in the range [1;Program.layers] or a table of layer indices (e.g. {1, 3}), default to nil: all layers
channel(optional) default to nil: all channels
input(optional) default to nil: all inputs
vol(optional) initial linear gain, default to 1
pan(optional) initial pan in the range [-1;1], default to 0
tune(optional) initial tuning in fractional semitones, default to 0
slice(optional) 1-based sliceId to trigger when targeting the slice oscillator (see postEvent())
oscIndex(optional) 0-based index of the only oscillator to trigger within the keygroup, overriding the keygroup trigger rules. An index past the last oscillator triggers none, silently
dim1(optional) logical layer to dispatch to on a MultiSample, default to nil: layer 0
dim2(optional) round-robin variant to dispatch to on a MultiSample, default to nil: the oscillator's round-robin policy chooses
Returns
the voice id that will be created by this note-on event

Example:

function onNote(e)
local id = playNote(e.note+12, e.velocity) -- harmonize note
end
void onNote(table e)
event callback that will receive all incoming note-on events if defined.
function postEvent(e, delta)
send a script event back to the script engine event queue.
Definition api.lua:959

dim1 / dim2 only mean something to a MultiSample, and are ignored when slice is set: a slice trigger takes its own path through the engine.

playNote{note=60, velocity=100, dim1=2} -- note-on on the third logical layer
See also
postEvent, releaseVoice, Keyswitch, MultiSampleIntro

◆ postEvent()

function postEvent ( e ,
delta  )

send a script event back to the script engine event queue.

The event's layer field can be a single index or a table of indices (e.g. {1, 3}) to target multiple layers at once. When a table is provided, a separate event is dispatched for each layer.

The event's channel field must be in [0;16] and input in [0;4]: 1-16 (resp. 1-4) target a specific MIDI channel (resp. input), while 0 means omni and is equivalent to omitting the field.

The event's slice field is 1-based (1 is the first slice, 0 or nil means no slice), like the one carried by the NoteOn events received in onNote()/onEvent(), so a received slice event can be re-posted as is.

Warning
a NoteOn posted by hand is never released automatically: release it with releaseVoice() and the returned id, or post a NoteOff carrying the same id. playNote() with a duration handles the release for you.
Parameters
eevent to be sent
delta(optional) delay in ms to be applied to the event default to 0
Returns
the event's voice id if it carries one (always assigned for Event.NoteOn events), nil otherwise
local id = postEvent({type=Event.NoteOn, note=60, velocity=100})
Event types.
Definition Engine.cpp:905
See also
playNote, releaseVoice

◆ releaseVoice()

function releaseVoice ( voiceId )

release a specific voice by sending it a note off message

Parameters
voiceIdthe id of the voice to be released
Returns
true if there was a voice to release with the given id

Example:

local id = playNote(note,vel)
wait(20)
function releaseVoice(voiceId)
release a specific voice by sending it a note off message
Definition api.lua:1179
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39
See also
postEvent, playNote