uvi-script
Musical event scripting with Lua
Async

Classes

class  AsyncTask
 An Asynchronous task. More...
 
class  AsyncBrowseForFileTask
 An Asynchronous task that browses for a file on disk. More...
 
class  AsyncListFilesTask
 An Asynchronous task that lists the files of a folder. More...
 
class  AsyncMidiFileLoadTask
 An Asynchronous task that loads a MIDI file. More...
 
class  AsyncDataLoadTask
 An Asynchronous task that reads a file from disk. More...
 
class  AsyncDataSaveTask
 An Asynchronous task that writes a file to disk. More...
 

Functions

function browseForFile (mode, title, initialFileOrDirectory, filePatterns, callback)
 launch a file chooser to select a file to open or save
 
function loadSample (oscillator, path, callback)
 load a sample inside the oscillator
 
function setPlaybackOptions (oscillator, start, end_, loopType, loopStart, loopEnd, playForward, callback)
 set playback options inside the oscillator
 
function loadState (path, callback)
 load state from file.
 
function saveState (path, callback)
 save state to file.
 
function loadData (path, callback)
 load data from file.
 
function saveTextData (data, path, callback)
 save string to file.
 
function loadTextData (path, callback)
 load string from file.
 
function saveData (data, path, callback)
 save data to file.
 
function listFiles (path, patterns, recursive, callback)
 list the files of a folder.
 
function loadMidi (path, callback)
 load a midi file asynchronously
 
function createMidiFile (maxNumTracks, maxNumEvents, callback)
 create a midi file asynchronously
 
function saveMidi (midifile, path, callback)
 save a midi file asynchronously
 
function loadImpulse (reverb, path, callback)
 load an impulse response inside the reverb.
 
function purge (target, callback)
 purge an/several element(s)/oscillator(s) from its/their content in order to release memory.
 
function unpurge (target, callback)
 unpurge an/several element(s)/oscillator(s) content in order to load their memory.
 

Detailed Description

Asynchronous operations for non-blocking file I/O and long-running tasks.

Async operations run on background threads to avoid blocking the real-time audio thread. They return AsyncTask objects that can be polled for completion or accept callbacks for notification when the operation finishes.

Available Operations:

Task Management:

Usage Patterns:

See also
Asynchronous Operations, Engine

Function Documentation

◆ browseForFile()

function browseForFile ( mode ,
title ,
initialFileOrDirectory ,
filePatterns ,
callback  )

launch a file chooser to select a file to open or save

Parameters
modefile browsing mode ("open" or "save")
titlea text string to display in the dialog box to tell the user what's going on
initialFileOrDirectorythe file or directory that should be selected when the dialog box opens. If left empty the default location is OS-dependent. In "save" mode, a missing directory (or the missing parent directory of a proposed file name, i.e. a path with an extension) is created before the dialog opens; "open" mode ignores a path that does not exist
filePatternsa set of file patterns to specify which files can be selected - each pattern should be separated by a comma or semi-colon, e.g. "*" or "*.jpg;*.gif". An empty string means that all files are allowed
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncBrowseForFileTask

Example:

browseForFile("open", "choose file to open", "", "", function(task) print(task.result) end)
browseForFile("save", "save preset", getUserLocation("My Instrument", "My Company").."/Presets/My Preset.json", "*.json", function(task) print(task.result) end)
function browseForFile(mode, title, initialFileOrDirectory, filePatterns, callback)
launch a file chooser to select a file to open or save
Definition api.lua:33
string getUserLocation(string productName, string vendorName)
Per-product user folder, Documents/[vendorName]/[productName], for a sound bank to keep its user pres...

◆ createMidiFile()

function createMidiFile ( maxNumTracks ,
maxNumEvents ,
callback  )

create a midi file asynchronously

Parameters
maxNumTracksmaximum number of tracks, must be greater than 0
maxNumEventsmaximum number of events, must be greater than 0
callbackcallback function that will be called upon completion of the asynchronous task. Unlike the other asynchronous functions it is required: omitting it raises an error
Returns
an AsyncMidiFileLoadTask

◆ listFiles()

function listFiles ( path ,
patterns ,
recursive ,
callback  )

list the files of a folder.

The folder is read asynchronously, so the call never touches the disk on the audio thread; the callback receives the task. task.result is an array of entries {path = absolute path, name = file name, isDirectory = boolean, size = bytes, / modified = seconds since 1970-01-01 UTC}, sorted by path (byte order, so upper case sorts before lower case). Each read of task.result builds a new table: keep it in a local.

  • patterns uses the browseForFile syntax ("*.json", "*.lyr;*.arp", "*" for all files) and is matched against the file name, ignoring case. Folders are listed only when patterns is "" (the default): "" lists files and folders, "*" lists files only.
  • recursive also lists the content of the subfolders (folders reached through a symbolic link are listed but not entered). Hidden files and folders are skipped.
  • path is resolved like loadData: an absolute path, a path relative to the script, to the program or to the multi, or a path inside a sound bank ("$My Bank.ufs/..."). Inside a sound bank, modified is 0.
  • When the folder cannot be listed (missing, or a file), task.result is an empty table, task.success is false and task.error tells why; task.error is nil otherwise.
  • In an offline render (bounce), the callback is called at the start of the next block, at the same point of every render.
Parameters
pathfolder to list
patterns(optional) file patterns separated by ";" or ",", "" by default
recursive(optional) list subfolders too, false by default
callback(optional) function called with the task once the folder has been read
Returns
an AsyncListFilesTask

Example:

listFiles(getUserLocation("My Instrument").."/Presets", "*.json", false, function(task)
if task.error then print(task.error) return end
for _, entry in ipairs(task.result) do
print(entry.name, entry.size, entry.modified)
end
end)
function listFiles(path, patterns, recursive, callback)
list the files of a folder.
Definition api.lua:316

◆ loadData()

function loadData ( path ,
callback  )

load data from file.

The file content is decoded from JSON (see saveData) and the callback receives the decoded value, not the task. The callback is not called when the file is missing or cannot be read, and a file that is not valid JSON raises an error from the callback's thread. The returned task reports success as true even when the file could not be read, so do not use it to detect a missing file.

Parameters
pathpath to file
callback(optional) function called with the decoded data once the file has been read
Returns
an AsyncTask

Example:

browseForFile("open", "choose file to open", "", "", function(task)
loadData(task.result, function(data)
print(data)
end)
end)
function loadData(path, callback)
load data from file.
Definition api.lua:163

◆ loadImpulse()

function loadImpulse ( reverb ,
path ,
callback  )

load an impulse response inside the reverb.

Parameters
reverbthe sampled reverb or convolver element to load into
pathpath to impulse response file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

Example:

loadImpulse(Program.inserts[1], "IR/irsample.wav", function(task) print("done") print(task.success) end)
A Patch that represents a monotimbral instrument.
Definition Engine.cpp:350
table inserts
all InsertEffect for this node
Definition Engine.cpp:355
function loadImpulse(reverb, path, callback)
load an impulse response inside the reverb.
Definition api.lua:406

◆ loadMidi()

function loadMidi ( path ,
callback  )

load a midi file asynchronously

Parameters
pathpath to midi file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncMidiFileLoadTask

◆ loadSample()

function loadSample ( oscillator ,
path ,
callback  )

load a sample inside the oscillator

The callback is optional: when omitted, the async command skips the script-thread completion round-trip entirely and loadSample returns nil, so there is no task to poll. To observe completion, pass a callback: the returned task can then also be polled (task.finished).

Parameters
oscillatorthe sample-based or wavetable oscillator to load into
pathpath to sample file
callback(optional) callback function called upon completion of the asynchronous task
Returns
an AsyncTask when a callback is given, nil otherwise

Examples: a) with completion callback

loadSample(Program.layers[1].keygroups[1].oscillators[1], "samples/sample.wav",
function(task) print("done", task.success) end)
table layers
Layer list for this Program (1-indexed, use #Program.layers to get the count)
Definition Engine.cpp:359
function loadSample(oscillator, path, callback)
load a sample inside the oscillator
Definition api.lua:79

b) fire-and-forget (no callback, returns nil)

loadSample(Program.layers[1].keygroups[1].oscillators[1], "samples/sample.wav")

c) polling (a callback is required to get a task back)

local task = loadSample(Program.layers[1].keygroups[1].oscillators[1], "samples/sample.wav",
function() end)
while not task.finished do
wait(50)
end
print("done", task.success)
function wait(ms)
suspend the current thread callback execution for the given number of milliseconds.
Definition wrapper.lua:39

◆ loadState()

function loadState ( path ,
callback  )

load state from file.

Parameters
pathpath to file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

◆ loadTextData()

function loadTextData ( path ,
callback  )

load string from file.

The callback receives the raw file content as a string, not the task. It is not called when the file is missing or cannot be read. The returned task reports success as true even when the file could not be read.

Parameters
pathpath to file
callback(optional) function called with the file content once the file has been read
Returns
an AsyncTask

Example:

browseForFile("open", "choose file to open", "", "", function(task)
loadTextData(task.result, function(data)
print(data)
end)
end)
function loadTextData(path, callback)
load string from file.
Definition api.lua:225

◆ purge()

function purge ( target ,
callback  )

purge an/several element(s)/oscillator(s) from its/their content in order to release memory.

A purge command is sent and executed asynchronously to avoid blocking the script execution. One can specify either a single Element or an array of Elements to purge. Elements that contain other Elements are purged recursively. One can also specify an optional callback to be called upon completion of the asynchronous operation.

Parameters
targetit can be either a single oscillator, an Element or a Table of Elements
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

Examples: a) asynchronous callback

purge(Program.layers[1], function() print("layer is now purged") end)
function purge(target, callback)
purge an/several element(s)/oscillator(s) from its/their content in order to release memory.
Definition api.lua:440

b) polling (finished is also true once the task has been cancelled)

local task = purge(Program.layers[1])
while not task.finished do
wait(1000)
end
print("layer is now purged")

◆ saveData()

function saveData ( data ,
path ,
callback  )

save data to file.

the data is encoded using JSON, supported types are boolean, numbers, strings, arrays and dicts. A lua table that mixes array entries and string keys is saved as a dict, and its integer keys come back as strings when loaded: {1, 2, name = "x"} is restored with data["1"], while data[1] is nil. Keep arrays and dicts in separate tables. Nested tables are supported but circular references are not. Any other lua datatype that cannot be mapped to JSON will be ignored:

  • coroutines
  • lightuserdata
  • userdata
Parameters
datadata to save: a table, string, number or boolean
pathpath to file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask, or nil when data is of another type (nil, function, userdata...): nothing is written, no error is raised and the callback is never called

◆ saveMidi()

function saveMidi ( midifile ,
path ,
callback  )

save a midi file asynchronously

The file is written from the sequence itself, not from a copy: do not insert events into it until the task has finished, or the file may hold a partly edited sequence. The sequence stays alive until then, even if the script drops its last reference to it.

Parameters
midifilemidi sequence object
pathpath where the midi file should be saved
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

◆ saveState()

function saveState ( path ,
callback  )

save state to file.

Parameters
pathpath to file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

◆ saveTextData()

function saveTextData ( data ,
path ,
callback  )

save string to file.

Parameters
datastring to save, any other type raises an error
pathpath to file
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

◆ setPlaybackOptions()

function setPlaybackOptions ( oscillator ,
start ,
end_ ,
loopType ,
loopStart ,
loopEnd ,
playForward ,
callback  )

set playback options inside the oscillator

Parameters
oscillatorthe oscillator element to modify
startsample start position in samples
end_sample end position in samples
loopTypeloop mode: 0 = None, 1 = Forward, 2 = Alternate, 3 = OneShot
loopStartloop start position in samples
loopEndloop end position in samples
playForwardtrue to play forward, false to play in reverse
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

Example:

setPlaybackOptions(Program.layers[1].keygroups[1].oscillators[1], 0, 100, 0, 0, 0, true, function(task) print("done") print(task.success) end)
function setPlaybackOptions(oscillator, start, end_, loopType, loopStart, loopEnd, playForward, callback)
set playback options inside the oscillator
Definition api.lua:104

◆ unpurge()

function unpurge ( target ,
callback  )

unpurge an/several element(s)/oscillator(s) content in order to load their memory.

An unpurge command is sent and executed asynchronously to avoid blocking the script execution. One can specify either a single Element or an array of Elements to load. Elements that contain other Elements are unpurged recursively. One can also specify an optional callback to be called upon completion of the asynchronous operation.

Parameters
targetit can be either a single oscillator, an Element or a Table of Elements
callback(optional) callback function that will be called upon completion of the asynchronous task
Returns
an AsyncTask

Examples: a) asynchronous callback

unpurge(Program.layers[1], function() print("layer is now loaded") end)
function unpurge(target, callback)
unpurge an/several element(s)/oscillator(s) content in order to load their memory.
Definition api.lua:474

b) polling (finished is also true once the task has been cancelled)

local task = unpurge(Program.layers[1])
while not task.finished do
wait(1000)
end
print("layer is now loaded")