API Quick Reference

A condensed reference of all uvi-script functions, organized by category. For detailed explanations and examples, follow the links to the relevant guide or module page.

Event Callbacks

Callback	Description
onInit()	Called once after script loads
onNote(e)	Note-on event
onRelease(e)	Note-off event
onController(e)	MIDI CC event
onPitchBend(e)	Pitch bend event
onAfterTouch(e)	Channel aftertouch
onPolyAfterTouch(e)	Polyphonic aftertouch
onProgramChange(e)	Program change event
onEvent(e)	Master callback (overrides all above)
onTransport(playing)	Host transport start/stop
onSave()	State serialization
onLoad(data)	State restoration

Guide: Event Callbacks

Events & Notes

Function	Description
postEvent(e, delta)	Send event to engine queue
playNote(note, vel, duration, layer, ...)	Create and play a note
releaseVoice(id)	Release a playing voice

Guide: Events

Voice Manipulation

Function	Description
changeTune(id, semitones, relative, immediate)	Modify pitch
changeVolume(id, gain, relative, immediate)	Modify volume (linear)
changeVolumedB(id, dB, relative, immediate)	Modify volume (dB)
changePan(id, pan, relative, immediate)	Modify pan position
setSampleOffset(id, ms)	Set sample playback position
fadein(id, duration, reset, layer)	Fade voice in
fadeout(id, duration, kill, reset, layer)	Fade voice out
fade(id, target, duration, layer)	Fade to target volume
fade2(id, start, target, duration, layer)	Fade with explicit start
sendScriptModulation(id, value, ramp, voiceId)	Script modulation source
sendScriptModulation2(id, start, target, ramp, voiceId)	Script modulation ramp

Guide: Voice Manipulation

Time & Threading

Function	Description
wait(ms)	Suspend thread for milliseconds
waitBeat(beats)	Suspend thread for musical beats
waitForRelease()	Suspend until note is released
spawn(fn, ...)	Launch thread (deferred start)
run(fn, ...)	Launch thread (immediate start)
isNoteHeld()	Check if triggering note is held

Guide: Threading and Timing

Musical Context

Function	Returns
getTime()	Script engine time in ms
getTempo()	Tempo in BPM
getBeatTime()	Host transport beat position
getRunningBeatTime()	Internal monotonic beat position
getBarDuration()	Bar duration in ms
getBeatDuration()	Beat duration in ms
getSamplingRate()	Sample rate in Hz
getTimeSignature()	Numerator, denominator
getNoteDuration(note)	Time since note-on in ms
getCC(cc)	Last CC value for given number
isKeyDown(note)	True if note is held
isOctaveKeyDown(note)	True if any octave of note is held

Guide: Threading and Timing (Musical Context Queries section)

Conversions

Function	Description
beat2ms(beats)	Musical beats → milliseconds
ms2beat(ms)	Milliseconds → musical beats
ms2samples(ms)	Milliseconds → sample count
samples2ms(samples)	Sample count → milliseconds

MIDI Generation

Function	Description
controlChange(cc, val, ch, inp)	Send CC message
programChange(val, ch, inp)	Send program change
pitchBend(bend, ch, inp)	Send pitch bend [-1;1]
afterTouch(val, ch, inp)	Send channel aftertouch
polyAfterTouch(val, note, ch, inp)	Send poly aftertouch
postMidiEvent(event)	Send raw MidiEvent

Guide: MIDI Event Generation

Async Operations

Function	Description
browseForFile(mode, title, init, patterns, cb)	File open/save dialog
loadSample(osc, path, cb)	Load sample into oscillator
setPlaybackOptions(osc, start, end, loop, ..., cb)	Configure playback
purge(element, cb)	Unload samples from memory
unpurge(element, cb)	Reload purged samples
saveState(path, cb)	Save full script state
loadState(path, cb)	Restore script state
saveData(data, path, cb)	Save Lua table as JSON
loadData(path, cb)	Load JSON as Lua table
saveTextData(text, path, cb)	Save raw text
loadTextData(path, cb)	Load raw text
loadMidi(path, cb)	Load MIDI file
createMidiFile(tracks, fmt, ppq, cb)	Create empty MIDI
saveMidi(midi, path, cb)	Save MIDI file
loadImpulse(reverb, path, cb)	Load impulse response

Guide: Asynchronous Operations

User Interface

Function	Description
setSize(w, h)	Set script UI dimensions
setHeight(h)	Set script UI height
setBackground(path)	Set background image
setBackgroundColour(colour)	Set background colour
makePerformanceView()	Show UI in performance view
setKeyColour(note, colour)	Colorize keyboard key
resetKeyColour(note)	Reset keyboard key colour
moveControl(widget, col, row)	Snap widget to grid cell

Widgets: Knob, Slider, Button, OnOffButton, NumBox, Menu, MultiStateButton, Label, Image, SVG, Panel, Viewport, Table, XY, AudioMeter, WaveView, FileSelector, DnDArea

Guide: User Interface

Engine Access

Navigate the synthesis hierarchy: Synth → Part → Program → Layer → Keygroup → Oscillator

Property / Method	Description
setParameter(param, value)	Set element parameter
getParameter(param)	Get element parameter
hasParameter(param)	Check parameter existence
Program.layers	Layer list (1-indexed)
Layer.keygroups	Keygroup list
Keygroup.oscillators	Oscillator list
findLayer(name)	Find layer by name

See also: Engine, Elements & Parameters

Quick Start Examples

Playing a Note

function onNote(e)
    local id = postEvent(e)  -- Forward the event and get voice ID
end

Waiting and Timing

function onNote(e)
    playNote(60, 100, 500)  -- Play C4 immediately
    wait(250)               -- Wait 250ms
    playNote(64, 100, 500)  -- Play E4
end

Spawning Background Tasks

function onNote(e)
    postEvent(e)
    spawn(function()
        local chord = {0, 4, 7, 12} -- major triad + octave
        for _, interval in ipairs(chord) do
            playNote(e.note + interval, e.velocity, 200)
            waitBeat(0.5)  -- half a beat between each note
        end
    end)
end

Creating UI Widgets

local cutoff = Knob{"Cutoff", 20000, 20, 20000, mapper = Mapper.Exponential, unit = Unit.Hertz}
cutoff.changed = function(self)
    Program.layers[1].keygroups[1].inserts[1]:setParameter("Freq", self.value)
end
cutoff:changed()
setSize(720, 60)
makePerformanceView()

Voice Manipulation

function onNote(e)
    local id = postEvent(e)
    changeTune(id, 0.05)       -- detune by 5 cents
    changeVolume(id, 0.8)      -- set volume to 80%
    fadein(id, 200)            -- fade in over 200ms
end

MIDI Event Generation

function onNote(e)
    postEvent(e)
    controlChange(1, 100)      -- send mod wheel CC
    pitchBend(0.5)             -- bend up halfway
end

Async File Operations

browseForFile("open", "Select Sample", "", "*.wav;*.aif", function(task)
    if task.success then
        loadSample(Program.layers[1].keygroups[1].oscillators[1], task.result)
    end
end)