Async

Classes
class	AsyncTask
	An Asyncronous task. More...
class	AsyncBrowseForFileTask
	An Asyncronous task that browses for a file on disk. More...
class	AsyncMidiFileLoadTask
	An Asyncronous task that load a MIDI file. 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 to file.
function	saveState (path, callback)
	save state from 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	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 and 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:

• browseForFile() - File open/save dialogs
• loadMidi() - Load MIDI files
• purge() - Unload samples from memory
• Sample loading operations

Task Management:

• AsyncTask - Base task class with status tracking
• AsyncBrowseForFileTask - File dialog results
• AsyncMidiFileLoadTask - MIDI file loading results

Usage Patterns:

• Callback pattern: Pass a function to be called on completion
• Polling pattern: Check task.finished in a loop with wait()

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

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

createMidiFile()

function createMidiFile	(	maxNumTracks	,
		maxNumEvents	,
		callback	)

create a midi file asynchronously

Parameters

maxNumTracks
maxNumEvents
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncMidiFileLoadTask

loadData()

function loadData	(	path	,
		callback	)

load data from file.

Parameters

path	path to file
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncTask

Example:

browseForFile("open", "choose file to open", "", "", function(task)  
    loadData(task.result, function(data)
        print(data)
    end)
end)

loadImpulse()

function loadImpulse	(	reverb	,
		path	,
		callback	)

load and impulse response inside the reverb.

Parameters

reverb
path	path to impulse response file
callback	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)

loadMidi()

function loadMidi	(	path	,
		callback	)

load a midi file asynchronously

Parameters

path	path to midi file
callback	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

Parameters

oscillator
path	path to sample file
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncTask

Example:

loadSample(Program.layers[1].keygroups[1].oscillators[1],  "samples/sample.wav", function(task)  print("done") print(task.success) end)

loadState()

function loadState	(	path	,
		callback	)

load state to file.

Parameters

path	path to file
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncTask

loadTextData()

function loadTextData	(	path	,
		callback	)

load string from file.

Parameters

path	path to file
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncTask

Example:

browseForFile("open", "choose file to open", "", "", function(task)  
    loadTextData(task.result, function(data)
        print(data)
    end)
end)

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 and optional callback to be called upon completion of the asynchronous operation.

Parameters

target	it can be either a single oscillator, and Element or a Table of Elements
callback	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)

b) polling

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, arrays and dicts lua tables can be both arrays and dicts at the same time, this case cannot be converted and is thus unsupported, the result is undefined is undefined. Lua tables that are saved should be either arrays or dicts. 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

data	data to save
path	path to file
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncTask

saveMidi()

function saveMidi	(	midifile	,
		path	,
		callback	)

save a midi file asynchronously

Parameters

midifile	midi sequence object
path	path where the midi file should be saved
callback	callback function that will be called upon completion of the asynchronous task

Returns

an AsyncMidiFileLoadTask

saveState()

function saveState	(	path	,
		callback	)

save state from file.

Parameters

path	path to file
callback	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

data	string to save
path	path to file
callback	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

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	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, function(task)  print("done") print(task.success) end)

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 and optional callback to be called upon completion of the asynchronous operation.

Parameters

target	it can be either a single oscillator, and Element or a Table of Elements
callback	callback function that will be called upon completion of the asynchronous task

Returns

a handle

Examples: a) asynchronous callback

unpurge(Program.layer[1], function() print("layer is now loaded") end)

b) polling

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