![]() |
uvi-script
Musical event scripting with Lua
|
| 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 | |
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:
| 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 -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:
In these cases pass an explicit duration, or use 0 and releaseVoice().
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:
| 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 |
Example:
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.
| 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.
id. playNote() with a duration handles the release for you.| e | event to be sent |
| delta | (optional) delay in ms to be applied to the event default to 0 |
| function releaseVoice | ( | voiceId | ) |
release a specific voice by sending it a note off message
| voiceId | the id of the voice to be released |
Example: