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

All async functions accept a callback that will be called upon completion. 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)

The callback receives an AsyncTask object with the following properties:

• task.success - Boolean indicating if the operation succeeded
• task.result - The result data (file path, loaded data, etc.)
• task.finished - Boolean indicating completion status

Polling Pattern

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

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!")

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)

Sample Management

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

-- Purge samples from a layer
local task = purge(Program.layers[1])
 
-- Optionally wait for completion
while not task.finished do
    wait(50)
end
print("Layer purged successfully")

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)

Custom Data I/O

Save and load arbitrary data to and from files:

• saveData / loadData — write and read Lua tables as JSON
• saveTextData / loadTextData — write and read raw text strings

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

-- 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
loadData("/path/to/preset.json", function(task)
    if task.success then
        local p = task.result
        print("Loaded preset: " .. p.name)
    end
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
loadTextData("/path/to/config.txt", function(task)
    if task.success then
        print("Contents: " .. task.result)
    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

local osc = Program.layers[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)

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 (available on Slice oscillators)
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:

• loadMidi — load a MIDI file into a MidiSequence
• createMidiFile — create an empty MIDI file (specify number of tracks, format, and PPQ)
• saveMidi — save a MidiSequence to disk

-- Load a MIDI file and iterate its events
loadMidi("/path/to/pattern.mid", function(task)
    if task.success then
        local seq = task.result
        for i, event in ipairs(seq.events) do
            print("Event " .. i .. ": type=" .. event.type
                  .. " note=" .. (event.note or ""))
        end
    end
end)
 
-- Create an empty Type-1 MIDI file at 480 PPQ with 2 tracks, then save
createMidiFile(2, 1, 480, function(task)
    if task.success then
        local seq = task.result
        saveMidi(seq, "/path/to/output.mid", function(t)
            if t.success then print("MIDI file saved") end
        end)
    end
end)

Impulse Response Loading

Load impulse response files into a IReverb effect:

• loadImpulse — load an IR audio file into a SampledReverb instance

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)

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 executed on the script's main thread, making it safe to access script variables and call uvi-script API functions.

Data Sharing

Data passed between threads is safely copied. You don't need to worry about race conditions or locks when using async operations.

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