uvi-script
Musical event scripting with Lua
Asynchronous Operations

Overview

uvi-script provides asynchronous operations to prevent blocking the real-time audio thread when performing file I/O, loading samples, or other time-consuming tasks.

All asynchronous operations run on background threads and communicate their results back to the script thread safely, ensuring real-time audio processing is never interrupted.

Common Patterns

Callback Pattern

Async functions take a completion callback as their last argument. It is optional everywhere except in createMidiFile, which raises an error without one. This is the recommended pattern for most use cases:

browseForFile("open", "Select file", "", "*.wav", function(task)
if task.success then
print("Selected: " .. task.result)
else
print("Operation cancelled or failed")
end
end)
function browseForFile(mode, title, initialFileOrDirectory, filePatterns, callback)
launch a file chooser to select a file to open or save
Definition api.lua:33

The callback receives an AsyncTask object with the following properties:

  • task.success - Boolean indicating if the operation succeeded
  • task.finished - Boolean indicating completion status

Operation-specific results are exposed through dedicated properties:

loadData and loadTextData are different: their callback receives the loaded data directly (a Lua table or a string), not a task object — see Custom Data I/O below.

Polling Pattern

Alternatively, you can poll the task status in a loop. This is useful when you need to perform other work while waiting:

function onInit()
local task = purge(Program.layers[1])
-- Continue doing other work while the purge happens
while not task.finished do
print("Purging samples...")
wait(100) -- Check every 100ms
end
print("Purge complete!")
end
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
function purge(target, callback)
purge an/several element(s)/oscillator(s) from its/their content in order to release memory.
Definition api.lua:440
void onInit()
initial callback, called once if the script was successfully analyzed.
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39

Polling needs the task handle. Most async functions return it whether or not a callback is given, but loadSample returns nil when called without a callback — pass one (even an empty function) if you need to observe completion.

Polling only works where wait can actually suspend execution: inside an event callback, onInit, or a thread started with spawn / run. At the top level of the script, or in a widget's changed callback, wait() returns immediately and the loop spins without ever letting the task complete — use the callback pattern there instead.

Note
wait counts audio time — samples rendered — not wall-clock time. In an offline render running faster than real time, wait(100) passes in a fraction of 100 ms, so the loop above sees the task finish at a point in the audio that depends on how fast the machine did the work. That is fine for a progress readout, but never use a wait as a delay that "gives the load time", and do not make what the script plays depend on when a task finished if the result has to render the same way twice.

Available Async Operations

File Dialogs

Use browseForFile to let users select files without blocking audio:

-- Open file dialog
browseForFile("open", "Select Audio File", "", "*.wav;*.aif", function(task)
if task.success then
local filepath = task.result
print("User selected: " .. filepath)
end
end)
-- Save file dialog
browseForFile("save", "Save Preset", "MyPreset", "*.preset", function(task)
if task.success then
saveData(presetData, task.result)
end
end)
function saveData(data, path, callback)
save data to file.
Definition api.lua:261

Sample Management

Loading and purging samples can take time. Use async operations to avoid audio glitches:

function onInit()
-- Purge samples from a layer
local task = purge(Program.layers[1])
-- Optionally wait for completion (see the polling pattern above)
while not task.finished do
wait(50)
end
print("Layer purged successfully")
end
A layer of sounds.
Definition Engine.cpp:367
table layers
Layer list for this Program (1-indexed, use #Program.layers to get the count)
Definition Engine.cpp:359

purge and unpurge work on the sample-based oscillators under the node they are given. A MultiSample ignores them — it purges a layer of zones at a time with its own calls, and the program-load sequence decides where those belong; see Program load and warm-up.

State Management

Save and restore the entire ScriptProcessor state, including widget values and custom data stored via onSave / onLoad :

  • saveState — serialize the processor state to a file
  • loadState — restore processor state from a file
-- Let the user pick a destination, then save state
browseForFile("save", "Save State", "MyState", "*.state", function(task)
if task.success then
saveState(task.result, function(t)
if t.success then print("State saved") end
end)
end
end)
-- Restore state from a user-selected file
browseForFile("open", "Load State", "", "*.state", function(task)
if task.success then
loadState(task.result, function(t)
if t.success then print("State restored") end
end)
end
end)
function saveState(path, callback)
save state to file.
Definition api.lua:133
function loadState(path, callback)
load state from file.
Definition api.lua:118

Custom Data I/O

Save and load arbitrary data to and from files:

JSON encoding does not support cyclic references or userdata values. Only plain Lua types (numbers, strings, booleans, and nested tables) are serialized.

Warning
A table that mixes array entries and string keys is written as a JSON object, so its integer keys come back as strings: {1, 2, name = "x"} reloads with data["1"], and data[1] is nil. Keep arrays and maps in separate tables, e.g. {notes = {1, 2}, name = "x"}. The same applies to onSave / onLoad.

The save callbacks receive a task object (check task.success). The load callbacks receive the loaded data directly: a decoded Lua table for loadData, a plain string for loadTextData. If the file cannot be read, the load callback is simply not invoked.

-- Save a preset table as JSON
local preset = {name = "Warm Pad", cutoff = 800, resonance = 0.6}
saveData(preset, "/path/to/preset.json", function(task)
if task.success then print("Preset saved") end
end)
-- Load it back: the callback receives the decoded table
loadData("/path/to/preset.json", function(data)
print("Loaded preset: " .. data.name)
end)
-- Save raw text
saveTextData("some config line\nanother line", "/path/to/config.txt", function(task)
if task.success then print("Text saved") end
end)
-- Load raw text: the callback receives the file contents as a string
loadTextData("/path/to/config.txt", function(text)
print("Contents: " .. text)
end)
function saveTextData(data, path, callback)
save string to file.
Definition api.lua:190
function loadTextData(path, callback)
load string from file.
Definition api.lua:225
function loadData(path, callback)
load data from file.
Definition api.lua:163

When polling instead of passing a callback, nothing is decoded on your behalf: the returned task (an AsyncDataLoadTask) exposes the raw file contents through its data property — a string, or nil if the file could not be read. For files written by saveData, decode the JSON yourself with the uvi.json module, which provides decode and encode:

local json = require('uvi.json')
function onInit()
local task = loadData("/path/to/preset.json")
while not task.finished do
wait(50)
end
if type(task.data) == "string" then
local preset = json.decode(task.data)
print("Loaded preset: " .. preset.name)
end
end

Sample Loading

Load audio files into oscillators and configure their playback parameters:

  • loadSample — load an audio file into an oscillator
  • setPlaybackOptions — set start, end, loop points, and direction (units are in samples; loopType: 0=None, 1=Forward, 2=Alternate, 3=OneShot)
  • unpurge — reload previously purged samples
Note
None of these target a MultiSample, which loads a whole sample set from a mapping file and purges it a layer at a time — see MultiSample (SampleMappingOscillator).
local osc = Program.layers[1].keygroups[1].oscillators[1]
-- Load a sample and configure loop points
loadSample(osc, "/path/to/kick.wav", function(task)
if task.success then
-- Set playback: start=0, end=44100, loop Forward from 1000 to 40000, forward
setPlaybackOptions(osc, 0, 44100, 1, 1000, 40000, true, function(t)
if t.success then print("Playback configured") end
end)
end
end)
-- Reload purged samples
unpurge(osc, function(task)
if task.success then print("Samples reloaded") end
end)
function setPlaybackOptions(oscillator, start, end_, loopType, loopStart, loopEnd, playForward, callback)
set playback options inside the oscillator
Definition api.lua:104
function loadSample(oscillator, path, callback)
load a sample inside the oscillator
Definition api.lua:79
function unpurge(target, callback)
unpurge an/several element(s)/oscillator(s) content in order to load their memory.
Definition api.lua:474

Oscillator Introspection

After loading a sample, you can query the oscillator for metadata:

local osc = Program.layers[1].keygroups[1].oscillators[1]
-- Sample information (available on sample-based oscillators)
local info = osc.sampleInfo
if info then
print("Name:", info.name)
print("Duration:", info.duration, "ms")
print("Sample rate:", info.samplerate, "Hz")
print("Channels:", info.channels)
end
-- Slice information (LoopLab oscillators; numSlices is 0 on any other oscillator)
if osc.numSlices > 0 then
for i = 1, osc.numSlices do
local slice = osc:getSliceInfo(i)
print("Slice", i, "start:", slice.start, "ms", "duration:", slice.duration, "ms")
end
end

See Oscillator for the full list of properties including purged, looplabInfo, and numSlices.

MIDI File Operations

Load, create, and save MIDI files:

The task passed to the callback exposes the sequence through its midi property. Events are accessed per track with getNumEventsForTrack and getEvent (both 1-indexed).

-- Load a MIDI file and iterate the events of its first track
loadMidi("/path/to/pattern.mid", function(task)
if task.success then
local seq = task.midi
for i = 1, seq:getNumEventsForTrack(1) do
local event = seq:getEvent(1, i)
print("Event " .. i .. ": type=" .. event.type
.. " byte1=" .. event.byte1)
end
end
end)
-- Create an empty MIDI sequence (2 tracks, up to 256 events per track), then save
createMidiFile(2, 256, function(task)
if task.success then
local seq = task.midi
saveMidi(seq, "/path/to/output.mid", function(t)
if t.success then print("MIDI file saved") end
end)
end
end)
function createMidiFile(maxNumTracks, maxNumEvents, callback)
create a midi file asynchronously
Definition api.lua:350
function loadMidi(path, callback)
load a midi file asynchronously
Definition api.lua:334
function saveMidi(midifile, path, callback)
save a midi file asynchronously
Definition api.lua:375

Impulse Response Loading

Load impulse response files into a IReverb effect:

local reverb = Program.inserts[1] -- a SampledReverb effect
loadImpulse(reverb, "/path/to/hall.wav", function(task)
if task.success then print("IR loaded") end
end)
table inserts
all InsertEffect for this node
Definition Engine.cpp:355
SampledReverb.
Definition Engine.cpp:306
function loadImpulse(reverb, path, callback)
load an impulse response inside the reverb.
Definition api.lua:406

Insert Effect Chains

Edit the insert chain of any node that has inserts (Synth, Part, Program, Layer, Keygroup, AuxEffect):

  • insertEffect — insert a new effect of a given type, at a slot or at the end
  • removeEffect — remove the effect at a slot
  • moveEffect — move an effect to another slot, keeping its settings and audio state

These are methods of the node and take their callback as the last argument. The chain changes after the call returns: read inserts again in the callback.

Program:insertEffect("SparkVerb", nil, function(task) -- nil slot: append
if task.success then
Program:moveEffect(#Program.inserts, 1) -- and put it first
end
end)
Program & Program
convenience global pointing to the parent Program element
Definition Engine.cpp:702

File Paths

Functions that read a file resolve a relative path by trying, in order: the path as given, the folder of the script file, the folder of the program (preset), the folder of the multi, and the folder the program was originally loaded from. loadSample and loadImpulse also look in the Samples folder of the program's sound bank. require searches the same script and program folders for a .lua file of that name, so a script can be split into modules kept beside it.

Functions that write a file (saveData, saveTextData, saveState, saveMidi) do not resolve relative paths: the path is used as given. Pass an absolute path, typically one returned by browseForFile.

Thread Safety

Background Execution
All async operations execute on background threads, completely separate from the real-time audio thread. This ensures audio processing is never interrupted.
Callback Execution
The completion callback is run by the script's own scheduler, on the audio thread, like every other script callback. That makes it safe to access script variables and call uvi-script API functions — and subject to the same real-time rules as onNote — keep it short, and never block in it.
Data Sharing
The arguments and results of an async operation are copied between threads, so you never need locks in the script. That does not order the operation with the rest of the engine: a query made while an operation is in flight can still report the previous state. For instance, right after unpurgeZones returns, getLoadingStatus can still read 1 until the worker picks the request up, and a note played then lands on zones that are not loaded yet. Wait for the completion callback before relying on the result.

Best Practices

Check Success Status
Always verify the operation succeeded before using results:
browseForFile("open", "Select file", "", "*.*", function(task)
if task.success then
-- Safe to use task.result
print("File: " .. task.result)
else
-- User cancelled or error occurred
print("No file selected")
end
end)
See also
Async, AsyncTask, browseForFile, purge
spawn, wait, onSave, onLoad, Porting from Kontakt (KSP)