Vst Lua Api

The VstLua GUI is simple enough. The top window shows output messages from the lua script; the bottom shows error messages.

For scripting, the API is simple. There are two important categories of interface: the callbacks and the built in functions. Functions here are either C functions, or Lua functions defined in the scripts in lua/.

NB: If a function is documented, it's relatively stable, and it should be safe to use it in future scripts (changes will be backwards compatible). If you use an undocumented function, it may well change in the next release!



Lua Extensions

Basic Utilities

vprint(str)
verror(str)
escape(str)
unescape(str)

Callbacks

To (re-)define a callback, just define a function with the right name. For example, to add a frame callback, add the following to your script:
function onFrameCb()
... do something ...
end
Note: callbacks are actually wrapped in the file lua/callback_wrappers.lua which does various bits of magic to simplify things.

onFrameCb()
midiEventCb(midiEvent)
sysexCb(sysex)
resetCb()
networkReceiveCb()
messageCb(name, msg)
saveProgramCb()
loadProgramCb()
initCb()
openCb()
closeCb()
keyCb(key)
dragCb(drag)
helpCb()
setParameterCb(par, value)
valueChangedCb(control, value, str)

Host Access

getHostTime()
setHostTime()
getCycle()
getTimeUs()
getBarStart()
getVSTParameter(par)
setVSTParameter(par, value)
sendMidi(event)
sendSysex(sysex)

Network and OSC

networkReceiveLoop(udp)
getInstances()
sendToInstance(name, msg)
toOSC(table)
fromOSC(string, fulltypes=false)

GUI

guiAddControl(control)
guiGetSize()
guiSetSize(size)
guiSetValue(control, value)
guiGetValue(control)
guiSetLabel(control, string, highlighted)
openFileSelector(pattern="*.*", func=nil)

Internals

reset(scriptName)
getVSTPath()

Global variables

VSTFrameLength
VSTSampleRate
ScriptName
VSTFrameStartUs
VSTProgramName
GUISizes

Customizing VstLua's GUI

If you don't like the default controls for VstLua, you can replace them with your own. Create bitmaps in a subdirectory called gui/ under the location of the dll, and the images will be loaded in place of the original control images. The following filenames are used:

Lua Modules

The various scripts in lua/ add a bunch of functions which simplify things greatly. These are all loaded automatically at startup; they work just like the C functions.

midi.lua

utils.lua

print()
print_table(table, [printer])
t = reverseMapping(q)
str = serializeTable(t, name)

callback_wrappers.lua

This function defines the wrappers around the basic callbacks. You probably shouldn't change this file, but if you want to hook the callbacks, this is place to do it. It defines the following global variables:
help

timing.lua

length,beatIndex,timeToBeat = computeBeatTime(samplePos, tempo, sampleRate, beatFraction)

adsr.lua

class ADSR

keys.lua

key_name(key)
virtualkeys

persistence.lua

programData
savePersistentProgramData
loadPersistentProgramData
globalPersistence
loadGlobalPersistence
saveGlobalPersistence

sysex.lua

sysexToTable(dump)
hexToSysex(specifier)
sysexToHex(dump)

shared.lua

Shared memory functions.
setSharedMemAlias(name)
sharedMemAliases
sharedMemReverseAliases
sendMidiToInstance(name)

executeTrap.lua

Deals with setting the execution limits, that specify how long the lua interpreter will run before aborting. This is useful to catch infinite loops.
executeTrap.limit
executeTrap.frameLimit

partial.lua

Defines some useful functions for partially executing code. This is useful if you want to split a calculation among several onFrameCb() calls, for example, without having to add explicit yielding.
createPartialCoroutine(func, instructions)
createTimedPartialCoroutine(func, ms, resolution = 500)