![]() |
uvi-script
Musical event scripting with Lua
|
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. | |
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:
| function browseForFile | ( | mode | , |
| title | , | ||
| initialFileOrDirectory | , | ||
| filePatterns | , | ||
| callback | ) |
launch a file chooser to select a file to open or save
| mode | file browsing mode ("open" or "save") |
| title | a text string to display in the dialog box to tell the user what's going on |
| initialFileOrDirectory | the 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 |
| filePatterns | a 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 |
Example:
| function createMidiFile | ( | maxNumTracks | , |
| maxNumEvents | , | ||
| callback | ) |
create a midi file asynchronously
| maxNumTracks | maximum number of tracks, must be greater than 0 |
| maxNumEvents | maximum number of events, must be greater than 0 |
| callback | callback function that will be called upon completion of the asynchronous task. Unlike the other asynchronous functions it is required: omitting it raises an error |
| 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.task.result is an empty table, task.success is false and task.error tells why; task.error is nil otherwise.| path | folder 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 |
Example:
| 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.
| path | path to file |
| callback | (optional) function called with the decoded data once the file has been read |
Example:
| function loadImpulse | ( | reverb | , |
| path | , | ||
| callback | ) |
load an impulse response inside the reverb.
| reverb | the sampled reverb or convolver element to load into |
| path | path to impulse response file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
Example:
| function loadMidi | ( | path | , |
| callback | ) |
load a midi file asynchronously
| path | path to midi file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
| 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).
| oscillator | the sample-based or wavetable oscillator to load into |
| path | path to sample file |
| callback | (optional) callback function called upon completion of the asynchronous task |
Examples: a) with completion callback
b) fire-and-forget (no callback, returns nil)
c) polling (a callback is required to get a task back)
| function loadState | ( | path | , |
| callback | ) |
load state from file.
| path | path to file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
| 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.
| path | path to file |
| callback | (optional) function called with the file content once the file has been read |
Example:
| 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.
| target | it 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 |
Examples: a) asynchronous callback
b) polling (finished is also true once the task has been cancelled)
| 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:
| data | data to save: a table, string, number or boolean |
| path | path to file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
data is of another type (nil, function, userdata...): nothing is written, no error is raised and the callback is never called | 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.
| midifile | midi sequence object |
| path | path where the midi file should be saved |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
| function saveState | ( | path | , |
| callback | ) |
save state to file.
| path | path to file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
| function saveTextData | ( | data | , |
| path | , | ||
| callback | ) |
save string to file.
| data | string to save, any other type raises an error |
| path | path to file |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
| function setPlaybackOptions | ( | oscillator | , |
| start | , | ||
| end_ | , | ||
| loopType | , | ||
| loopStart | , | ||
| loopEnd | , | ||
| playForward | , | ||
| callback | ) |
set playback options inside the oscillator
| oscillator | the oscillator element to modify |
| start | sample start position in samples |
| end_ | sample end position in samples |
| loopType | loop mode: 0 = None, 1 = Forward, 2 = Alternate, 3 = OneShot |
| loopStart | loop start position in samples |
| loopEnd | loop end position in samples |
| playForward | true to play forward, false to play in reverse |
| callback | (optional) callback function that will be called upon completion of the asynchronous task |
Example:
| 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.
| target | it 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 |
Examples: a) asynchronous callback
b) polling (finished is also true once the task has been cancelled)