Vst Lua Api

• "load" allows you to load a new script.
• "reset" reinitialises the script (useful if the script halts with an error or somesuch). The "reset" button will light up if the script is currently halted.
• The "halt" button stops all callbacks to the script until "reset" is pressed.
• The "console" button brings up the console, so you can enter commands directly to the interpreter.
• The "help" button brings up the any help for the script.
• The "GUI" button at the top right switches between this default view and the custom GUI the script may have defined. See scripts/guitest.lua for an example.

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

• There are some Lua extensions built in to this compile. These are:
  
  
  • Bitwise operators. You can used & (and) | (or), ^^ (xor), << (left shift), >> (right shift), \ (integer divide) and != (inequality, same as ~=)
    
    
  • Argument unpacking from a table. So you can do:

           ...
           local a, b, c in mytable
           ...
        

    which reads the fields "a", "b" and "c" from "mytable" and makes them local variables.
  
  
  
• Better random number generation with the Mersenne Twister.
  • r=random.new() -- generate a new random number generator object
  • r:seed(x) -- seed the generator object
  • r:value() -- get a new float, 0--1
  • r:valuei(a,b) -- return a new integer, from a to b
  • r2 =r:clone() -- get a new random generator with matching state
  
  
  
• Binary structure handling (pack/unpack). See http://www.inf.puc-rio.br/~roberto/struct/
  
  
• Value hashing. hash(val) returns the hash of value, which can be of any type. The hash is based on the _value_ of the argument, not the address, so you can safely compare hashes between instances (hash("hello")==hash("hello"), even if this is a different session). Only strings, booleans, numbers and tables have values to hash. Other types (userdata etc.) get fixed hashes. Note that functions get a hash based on their name and the sourcefile they were defined in.

Basic Utilities

vprint(str)

• prints out the given string to the window. NOTE: you can just use normal print() statements, which are wrappers for calls to vprint()

verror(str)

• prints out to the error window, and halts all callbacks until the reset button is used

escape(str)

• Returns a string which has all zeros replaced with \0, and all \ replaced with \\.

unescape(str)

• Undoes escape()

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

• This is called each VST processing frame. Timing sensitive functions should be done in here.

midiEventCb(midiEvent)

• Called every time the plugin receives a MIDI event. The midi event is a table with the following fields:
• delta: time offset in frames
• channel: MIDI channel 0--15
• type: midi event type (note on, cc etc.). The table "midi" loaded in init.lua defines names for these, so
• you can test the type with things like "if midievent.type==midi.noteOn then"
• byte2: first part of midi data. For notes, this is the note number. For cc's, this is the controller number.
• byte3: second part of midi data. For notes, this is velocity. For cc's this the value of the cc.
• byte4: third part of midi data. Rarely used.
• The following fields are present but are rarely useful:
• noteOffVelocity: velocity of the noteoff event
• detune: note detune
• noteLength: note length (if available)

sysexCb(sysex)

• Called when a sysex is received. The sysex is passed in as a string.

resetCb()

• Called before the script is reset or the plugin is shutdown. Useful to close files/network connections.

networkReceiveCb()

• If a non-blocking network receive loop is created with networkReceiveLoop, this callback will be called everytime a new UDP packet arrives. If this returns 1, packets will continue to be read. If it returns 0, the network loop thread will end.

messageCb(name, msg)

• Called if a remote instance sends a message to this instance. The calling instances name is the first parameter, the message is the second.

saveProgramCb()

• Called just before a new program is loaded by the host.

loadProgramCb()

• Called just after a new program is loaded by the host.

initCb()

• Called when the VST is loaded or reinitialised (with the reset button)

openCb()

• Called when the VST window is recreated (or reinitialised). All GUI creation must go in here.

closeCb()

• Called just before the VST window is closed (or reinitialised).

keyCb(key)

• Called when the user presses or releases a key. The parameter is a table with the following format:
  • character: character
  • virtual: virtual keycode. See lua/keys.lua for a complete table
  • modifier: shift, alt, ctrl, etc. See lua/keys.lua for a complete table
  • down: 1 if the key went down, 0 if it went up.
  The utility function keyName in lua/keys.lua converts a key table to a readable string if you want to test it. NB: Shift-Escape resets the plugin, so you cannot handle this event (it will never be passed to keyCb).

dragCb(drag)

• Called when the user drags something into the plugin window. The parameter is a table, with each of the elements dragged. Each element of this table is a subtable with two entries:
  • type: dragType.file(=0) if it's a filename, dragType.text(=1) if it's plain text
  • value: the value, as a string
  If, for example, you drag one file into the window, you'll receive a table which looks like: {{type=0, value="c:\files\myfile.txt"}}

helpCb()

• Called if the user presses the help button. Should return a string describing the plugin, which will be shown in the help window.

setParameterCb(par, value)

• Called when a VST parameter changes. Par has the number of the parameter, and value its new value (0.0--1.0).

valueChangedCb(control, value, str)

• Called when one of the scripts GUI controls is changed. Control is the tag id of the control (returned
from guiAddControl), and value is the new value (0.0--1.0). If the item is a menu, str is the string of the last selected element (this is necessary so you can tell sub-menus apart). If it's a text box, the new string is returned. If it's an xy pad, the co-ordinates are returned as a string in the form "{x,y}".

Host Access

getHostTime()

• returns the host time information. This is a table with the following fields:
• ppqPos: playback position in ppq's (0 if stopped, or not supported). 1.0 ppq = 1 beat.
• samplePos: playback position in samples
• timeSigNumerator: top bit of the time signature...
• timeSigDenominator: ... and the bottom bit
• tempo: host tempo in bpm
• sampleRate: current sample rate
• nanoSeconds: system time in nanoseconds
• playing: 1 if playing, 0 if stopped
• recording: 1 if recording, 0 if stopped

setHostTime()

• NOTE: most hosts don't support this (in fact, I think only Bidule supports it). Sets the host time, in the same format as getHostTime(). Returns 1 if it succeeds.
• ppqPos: playback position in ppq's (0 if stopped, or not supported). 1.0 ppq = 1 beat.
• timeSigNumerator: top bit of the time signature...
• timeSigDenominator: ... and the bottom bit
• tempo: host tempo in bpm

getCycle()

• returns the cycle data from the host (if it supports it). The result is a table with entries start and end,
  representing the start and end of the currently looped portion, both of which are in ppq units.

getTimeUs()

• Returns the time in microseconds. NB underlying accuracy is likely to be 1ms!

getBarStart()

• returns the start of the current bar in ppq units, if the host supports it.

getVSTParameter(par)

• returns the value of the given VST parameter. VstLua has 128 parameters that can be used, so
par should be from 0--127. Values are 0.0--1.0

setVSTParameter(par, value)

• sets the value of the given VST parameter. par should be from 0--127. Values are 0.0--1.0

sendMidi(event)

• Send a MIDI event to the host. The format of event is the same as for midiEventCb(). This means a simple
pass through is just:

function midiEventCb(event)
   sendMidi(event)
end  

sendSysex(sysex)

• Sends a sysex message. The message should be a string. lua/sysex.lua defines a number of utilities for manipulating sysex strings.

Network and OSC

networkReceiveLoop(udp)

• Pass this function an open UDP object, and it will start a thread which will monitor the socket, and call networkReceiveCb() as soon as new packets arrive. This thread will stop if networkReceiveCb() returns 0, or if the socket is closed.

getInstances()

• Returns a list of all the currently running instances of VstLua. Each instance has a name like "VSTLUAx", where x is the number of the instance. The table which this function returns has a field called "this" which is the name of the current (i.e. the calling) instance.

sendToInstance(name, msg)

• Sends a message to the instance with the given name (which should be one of the names returned by getInstances()). The remote instance will get a messageCb callback with the message.

toOSC(table)

• Converts a table into an OSC message. The table should be formatted as follows:

      {oscaddress, {value1, value2, value3...}}
      

  toOSC("/test/message", {1, "hello", true}) is valid, for example.
  If you want to use OSC bundles, just put each message inside a subtable and call toOSC (it will convert it to a bundle automatically). Make the first element the timetag:

      {timetag, {oscaddr1, {val1, val2, val3...}}, {oscaddr2, {val1, val2, val3...}},...}
      

  You can nest bundles if you wish. If you want to specify types other than float, integer, string and bool you can explicitly set the type. To do this, instead of passing a bare value, pass a table, where the first element is the type name, and the second is the value. For example:

   toOSC("/test/message", {{"float", 1.0}, {"rgbacolor", 2113140}, {"blob", "someblobtext"}} 

  Valid values for the type are:
  • float
  • double
  • boolean
  • int32
  • int64
  • timetag (the value should be a number)
  • char (the value can either be a number or a single-character string)
  • blob (use a string as the value)
  • symbol (string as value)
  • midi (number as value, which should specify the 4 bytes of a midi message)
  • rgbacolor (32 bit int as value)
  • infinite (does not take a value)
  • nil (does not take a value)

fromOSC(string, fulltypes=false)

• Converts a binary OSC message to a table, in the same format as toOSC. If it's a bundle the first element will be the timetag, otherwise it's the address of a plain message. NB: it's up to you to deal with the timetag if you want to! By default, all values will be converted to basic Lua types (number, string, boolean). If you set fulltypes, a table with all the types explicitly given will be returned (same format as toOSC uses, each entry is a table with type name and value).

GUI

guiAddControl(control)

• NB: call this in the handler for openCb. calling it at other times will
• cause unpredictable results (since the controls won't be recreated when the VST window reopens)
• adds a GUI control. "control" should be a table with the following fields:
• x: position
• y: position
• type: type of control. Use one of the fields of GUITypes (defined in init.lua).
• these are:
• GUITypes.onOffButton
• GUITypes.kickButton
• GUITypes.transientLed (flashes when set)
• GUITypes.stickLed (stays in set position)
• GUITypes.knob (rotary knob)
• GUITypes.hslider (horizontal slider)
• GUITypes.vslider (vertical slider)
• GUITypes.label (no control, just a label)
• GUITypes.menu (a popup menu)
• GUITypes.text (a text box)
• GUITypes.xypad
• GUITypes.vuMeter (display only vu meter)
• label: label string for the control
• menu_items: only used if the type is a menu. Should be a array containing a number of strings. Entries can also define submenus, by having a table giving the name then the sub-elements. Example :

          menu_items = {'One', {'Two', {'Two.sub1', 'Two.sub2, {'Two.sub3', {'Two.sub3.sub1','Two.sub3.sub2'}}}}, 'Three'}
      

  defines a menu like:
  • One
  • Two
    • Two.sub1
    • Two.sub2
    • Two.sub3
      • Two.sub3.sub1
      • Two.sub3.sub2
  • Three


• this function returns the tag id for this control (as an integer). This will be used for all
access of this control (e.g. in the valueChangedCb() callback), so make sure you store it!

guiGetSize()

• Returns the size of the GUI window as a table with "width" and "height" entries.

guiSetSize(size)

• Sets the size of the GUI window. Pass a table with "width" and "height" entries, which are the new window size in pixels. Example: guiSetSize({width=800, height=200}) . If you specify (0,0) for the size, the default window size will be used.

guiSetValue(control, value)

• set the current value of the given control. control is the id returned from guiAddControl. value is from
0.0--1.0

guiGetValue(control)

• returns the value of the given control. control is the id returned from guiAddControl. value is from
0.0--1.0

guiSetLabel(control, string, highlighted)

• changes the label of a control to the given string. If highlighted is 0, draws normally, else draws with a highlighted background.

openFileSelector(pattern="*.*", func=nil)

• Opens a file selector, and returns the file selected. First argument specifies the file mask. If you pass a function as the second argument, the selector will not block the thread, and will call the given function on return.

Internals

reset(scriptName)

• Resets the interpreter. If scriptName is given, the script is loaded and restarted.

getVSTPath()

• Returns the directory which this plugin was loaded from.

Global variables

VSTFrameLength

• this holds the length of the current frame in samples. It is updated immediately before onFrameCb() is called. NB: this will be nil until the first onFrame is called.

VSTSampleRate

• Current sample rate. Again, nil until first call of onFrame.

ScriptName

• Full path of the current script.

VSTFrameStartUs

• Start time of the frame in us. Again, nil until first call of onFrame.

VSTProgramName

• Current program name.

GUISizes

• holds the sizes of each gui component (as in GUITypes, defined in init.lua). Each value is an table with a "width" and "height" field. Example:

   GUISizes[GUITypes.knob] 

  returns the size of the knob component.

Customizing VstLua's GUI

• button.bmp -> on/off button, should be twice the height of a single button, top half on, bottom off
  
  
• gui.bmp -> background image
  
  
• hslider.bmp -> background of horizontal slider
  
  
• hslider_handle.bmp -> handle for horizontal slider
  
  
• vslider.bmp -> background of vertical slider
  
  
• vslider_handle.bmp -> handle for vertical slider
  
  
• textbox.bmp -> textbox
  
  
• vu_on.bmp -> vu meter on bitmap
  
  
• vu_off.bmp -> vu meter off bitmap
  
  
• xypad.bmp -> XY pad bitmap
  
  
• led.bmp -> led bitmap (same format as for button)
  
  
• menu_1.bmp -> menu background
  
  
• menu_2.bmp -> menu background, when selected
  
  
• knob.bmp -> knob image, must be 31 frames stacked vertically (e.g. as created by KnobMan)
  
  

Lua Modules

midi.lua

• General features

  Additional table entries in midi events.

  • Midi events have aliased fields for easier access. Rather than using event.byte2, you can just use event.note. This works for both reading and writing. The defined aliases are:
    • event.note -> event.byte2
    • event.velocity -> event.byte3
    • event.controller -> event.byte2
    • event.value -> event.byte3
    • event.bend -> event.byte2 + event.byte3 (deals with splitting into MSB and LSB automatically)
    • event.program -> event.byte2
    • event.aftertouch -> event.byte2

• Functions

  noteToNumber(noteSpec)

  • Convert a notespec of the form "C-4" to a midi note number. The last digit is the octave. Naturals are of the form C-4, sharps C#4, flats Cb4. Octave can be 0--9.

  numberToNote(number)

  • Does the opposite of noteToNumber. Only ever returns sharps or naturals, not flats (e.g. "C#4", but never "Db4").

  copyMidiEvent(event)

  • Returns a copy of a midi event.

  completeMidiFields(event)

  • Fill in all missing fields of an event with default values. (for example, you could create a table, fill out the type, channel and byte2 fields, and then call completeMidiFields() to transform it into a fully-specified midi event table).
  
  
  • Event Creation

    sysexMsg(sysex)

    • Returns a midi event which sends the given sysex string.

    noteOn(note,vel,channel, delta=0)

    • Returns a note on midi event with the given arguments.

    noteOff(note,channel, delta=0)

    • Returns a note off midi event with the given arguments.

    setCC(controller,value,channel, delta=0)

    • Returns a CC change event.

    programChange(program,channel, delta=0)

    • Returns a program change event.

    pitchBend(bend, channel, delta=0)

    • Returns a pitch bend event. Deals with splitting to MSB and LSB automatically.

    channelAftertouch(aftertouch, channel, delta=0)

    • Returns a channel aftertouch event.

    polyAftertouch(note, aftertouch, channel, delta=0)

    • Returns a polyphonic aftertouch event.

  midiEventToString(event)

  • Returns a printable string from a midi event. Example: "Ch:0 Type:noteOn C-4 57"

  panic()

  • Sends all notes off and all sound off immediately, and clears outputNotesDown and outputCC.

  stopAllPlaying()

  • Sends a noteOff for each note currently marked as down in outputNotesDown. Useful to call in the resetCb() callback to avoid stuck notes.

  addMidiFilter(filter)

  • Allows simple manipulation of midi events by registering a filter which responds to specific events. The filter table can have any of the fields that a midi event has (type, byte2, channel, etc.). The value of the field can either be an integer (match that number), a range given as a string with a dash (e.g. "5-17"), or a list of numbers or ranges (match any of those numbers).
    
    Filter must also have a field "callback" which will be called when an event matching the given description is detected.
    
    Examples:

            --convert cc1 to pitchbend
    addMidiFilter{type=midi.cc, controller=1, callback = function(event)
    event.type = midi.pb
    event.bend = event.velocity * 127
    sendMidi(event)
    end}
        

            --transpose notes from 40--60 down by a fifth
           addMidiFilter{type={midi.noteOn,midi.noteOff}, byte2="40-60", callback = function(event) 
    event.byte2= event.byte2-7
    sendMidi(event) 
    end}
        

• Global Variables

  inputNotesDown

  • Stores all notes currently held down on the input to the plugin (i.e. all notes for which a note on but no matching note off has been received). This is automatically updated as events arrive.

  outputNotesDown

  • Stores all notes currently held down on the output of the plugin. This monitors all events send via sendMidi()

  inputCC

  • as inputNotesDown(), but for continuous controllers. Remember, this only tracks the state of events that have happened while this script has been running (since the last reset)!

  outputCC

  • as inputCC(), but for controller commands sent from the script via sendMidi.

  noteNames

  • maps note strings (of the form "C-" or "C#" or "Cb") to numbers in the octave.

  plainNoteNames

  • as noteNames, but in the format either "C" (for naturals) or "#" for sharps (no flats).

  plainNoteNumbers

  • reverse mapping of plainNoteNames, maps numbers from 0-11 to names.

  noteNumbers

  • reverse mapping of noteNames, maps numbers from 0-11 to names. Only ever returns strings with sharps, never flats.

  midi

  • Defines midi event types (for comparison with event.type). The values are:
    • noteOn=9
    • noteOff=8
    • polyAT=10
    • cc=11
    • pc=12
    • channelAT=13
    • pb=14
    • sysex=15

  midiTypeNames

  • Reverse mapping of midi (maps numbers to names)

  midicc

  • Defines names for all midi continuous controllers according to the GM standard. The entries are:
    bankSelect=0
    • modulation=1
    • breath=2
    • foot=4
    • portaTime=5
    • dataMSB=6
    • volume=7
    • balance=8
    • pan=10
    • expression=11
    • effect1=12
    • effect2=13
    • gp1=16
    • gp2=16
    • gp3=16
    • gp4=16
    • sustain=64
    • portamento=65
    • sustenuto=66
    • softPedal=67
    • legato=68
    • hold2=69
    • soundController1=70
    • soundController2=71
    • soundController3=72
    • soundController4=73
    • soundController5=74
    • soundController6=75
    • soundController7=76
    • soundController8=77
    • soundController9=78
    • soundController10=79
    • gp5=80
    • gp6=81
    • gp7=82
    • gp8=83
    • portaControl=84
    • effect1Depth=91
    • effect2Depth=92
    • effect3Depth=93
    • effect4depth= 94
    • effect5Depth=95
    • dataIncrement=96
    • dataDecrement=97
    • NRPNLSB=98
    • NRPNMSB=99
    • RPNLSB=100
    • RPNMSB=101
    • allSoundOff=120
    • resetAllControllers=121
    • localOnOff=122
    • allNotesOff=123
    • omniOff=124
    • omniOn=125
    • monoOn=126
    • polyOn=127

  scheduler.lua

  scheduleEvent(event)

  • Schedules an event to be sent in the future. This uses the delta field of a midi event to determine timing. You can safely call scheduleEvent() with any value for delta, and the event will be played at the right time (e.g. to play in 1 second at 44100Hz, just add 44100 to event.delta and call scheduleEvent(event)). Can generally be used as a replacement for sendMidi().

  gui.lua

  addControl(constructor)

  • Simplifies management of GUI controls. It wraps up the guiAddControl functionality. It automatically scales values to the given range, allows a simple callback to be used for responding to control changes, and allows automatic linkage to VST parameters.
    
    addControl() can be called at any time, not just within openCb(); the creation of controls as the window is opened and closed is managed behind the scenes.
    
    Call this with a constructor with the following fields:
    • x: position
    • y:
    • type: (a value from GUITypes, e.g. GUITypes.onOffButton)
    • label: label
    • value (optional): initial value.
    • max: (optional): maximum value for the control. Values will be scaled from min..max
    • min: (optional): minimum value for the control. Values will be scaled from min..max
    • callback: callback that will be called when a value changed occurs.
    • vstparameter (optional): if specified, the value of the control will be linked to the given VST parameter number.
    
    
    The value returned is a table, in which setting the "value" field sets the value of the control, and reading it likewise reads its current value. (e.g. time=mycontrol.value).

  intervals.lua

  Defines a number of musical intervals in the following tables:

  interval

  • Normal intervals
    • unison =0
    • minor_second=1
    • major_second=2
    • minor_third=3
    • major_third=4
    • fourth=5
    • tritone=6
    • fifth=7
    • minor_sixth=8
    • major_sixth=9
    • minor_seventh=10
    • major_seventh=11
    • octave=12

  dimIntervals

  • Diminished intervals. As normal intervals, but all -1.

  augIntervals

  • Augmented intervals. As normal intervals, but all +1.

  chords.lua

  Defines a number of chords, in the tables chords and common_chords (which is a subset of chords).

  chords

  • Full chord list. Entries:
    • +2
    • +3
    • +4
    • +b3
    • 5
    • b5
    • 6sus4(-5)
    • aug
    • dim
    • dim5
    • maj
    • min
    • sus2
    • sus2sus4(-5)
    • sus4
    • 6
    • 6sus2
    • 6sus4
    • 7
    • 7#5
    • 7b5
    • 7sus2
    • 7sus4
    • add2
    • add4
    • add9
    • dim7
    • dim7susb13
    • madd2
    • madd4
    • madd9
    • mmaj7
    • m6
    • m7
    • m7#5
    • m7b5
    • maj7
    • maj7#5
    • maj7b5
    • maj7sus2
    • maj7sus4
    • sus2sus4
    • 6/7
    • 6add9
    • 7#5b9
    • 7#9
    • 7#9b5
    • 7/11
    • 7/13
    • 7add4
    • 7b9
    • 7b9b5
    • 7sus4/13
    • 9
    • 9#5
    • 9b5
    • 9sus4
    • m maj9
    • m6/7
    • m6/9
    • m7/11
    • m7add4
    • m9
    • m9/11
    • m9b5
    • maj6/7
    • maj7/11
    • maj7/13
    • maj9
    • maj9#5

  scales.lua

  Defines a number of scales and modes.

  modes

  • Defines the following modes:
    • ionian
    • dorian
    • phyrgian
    • lydian
    • mixolydian
    • aeolian
    • locrian

  scales

  Defines a number of scales. See the source file for details.

utils.lua

print()

Simple wrapper for vprint. Can print all types (including tables).

print_table(table, [printer])

Prints the given table. You can optionally specify the print function; this will be called with a single string argument each time printing is required. By default, this is vprint().

t = reverseMapping(q)

Returns a reverse mapping a table, so that the key->value mappings in the original table become value->key mappings in the returned table.

str = serializeTable(t, name)

Returns a string, which if loaded with loadstring() and executed, will restore the given table, and store it in the global variable given by name. Example:

        t = {1, 2, "hello", {4, 5, 6}}
        str = serializeTable(t, "newTable")
        (loadstring(str))() --restore the table
        print_table(newTable) --prints the restored table    
    

callback_wrappers.lua

help

• Set the help table to make the "Help" button give instructions when pressed. The table should have three fields: name, description and author. Set this in initCb(), or at the toplevel, so that it is present when the script loads. Example:

          help.name="Transpose"
          help.description="Simple MIDI transpose. Transposes everything up by 1 semitone"
          help.author="tzec"
      

timing.lua

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

Computes the length of a beat (in samples), the index of the beat (i.e. the number of complete beats since the start of the sequence) and the time in samples until the next beat. The parameters are all values returned from getHostTime(). beatFraction can be used to get fractions or multiples of a beat; at 1.0 it's a whole beat, at 0.25 it's a quarter beat, at 4 it's a bar, etc.

adsr.lua

class ADSR

Simple ADSR envelope class. Has the following methods:
• new(a,d,s,r) a,d,r are in samples. s is a level.
• trigger(level) Start the envelope.
• release() Enter the release portion.
• v = update(time) Should be called in each onFrameCb(), with the VSTFrameTime as the parameter. Updates the envelope, and returns its current value.

keys.lua

key_name(key)

Translates a key table returned by keyCb() callback to a readable string.

virtualkeys

Defines virtual keycodes. The following keys are defined:
• back
• tab
• clear
• kreturn
• pause
• escape
• space
• knext
• kend
• home
• left
• up
• right
• down
• pageup
• pagedown
• select
• kprint
• enter
• snapshot
• insert
• delete
• help
• num0
• num1
• num2
• num3
• num4
• num5
• num6
• num7
• num8
• num9
• asterisk
• plus
• separator
• minus
• decimal
• divide
• f1
• f2
• f3
• f4
• f5
• f6
• f7
• f8
• f9
• f10
• f11
• f12
• numlock
• scroll
• shift
• control
• alt
• equals

persistence.lua

programData

Anything stored in this table will be stored alongside the program (preset) in the host. It will persist between sessions if the preset is stored to disk (e.g. by saving as .fxp or .fxb). You can use any primitive type in this table: strings, numbers, booleans or other tables. The table updates as programs change (it updates just before calls to saveProgramCb() and loadProgramCb(), if you want to catch the changes).

savePersistentProgramData

Forces the program data string to be updated with the current value of programData.

loadPersistentProgramData

Updates programData with the value of the program data string.

globalPersistence

Peristent table, which is unaffected by programs or resets. It is reread on init, and flushed back to disk when the script ends. The table is stored in a file called "persistent_store.lua", in the same directory as the VstLua DLL.

loadGlobalPersistence

Updates globalPersistence. Called on script initialisation.

saveGlobalPersistence

Updates the persistence file with globalPersistence. Called on script termination.

sysex.lua

sysexToTable(dump)

• Converts a sysex string to a list of integers.

hexToSysex(specifier)

• Slightly misleadingly named. Converts either: a number, a hex string, or a table containing these into a sysex string. Valid examples:

          hexToSysex(0xf0, 0x41, 0xf7)
          hexToSysex("F041F7")
          hexToSysex("F041", 31, 32, "F7")
          hexToSysex("F041", {31, 32} "F7")
          hexToSysex("F041", {31, "BD091A", 32} "F7")
      

sysexToHex(dump)

• Converts a sysex string to a hex string (like "F00441F7").

shared.lua

setSharedMemAlias(name)

• Sets the alias for this instance to be name, and updates all active instances.

sharedMemAliases

• Table which maps raw names ("VSTLUA1" etc.) to aliased names. This will be kept up to date as instances start and exit.

sharedMemReverseAliases

• Maps the reverse of sharedMemAliases -- aliases to raw names.

sendMidiToInstance(name)

• Sends a midi message to the instance given by name. This can either be the raw name (as returned by getInstances, like "VSTLUA1", or an aliased name). The message will automatically be intercepted by the callback wrapper in the receiving instance, and sent on to that host.

executeTrap.lua

executeTrap.limit

• Number of instructions that will be executed before aborting. Default is 10 million

executeTrap.frameLimit

• Number of instructions that will be executed before aborting while in onFrameCb(). Default is 1 million.

partial.lua

createPartialCoroutine(func, instructions)

• Returns a function that, when called, will execute at most "instructions" instructions of "func", then yield. Subsequent calls to the function will resume from where it left off. Example:

      function do_something()
          for i=1,1000000 do
              vprint(i.."\n")
          end
      end
      
      z = createPartialCoroutine(do_something, 1000)
      
      z() --executes 1000 instructions worth of func
      z() --executes another 1000 instructions worth of func    
  

createTimedPartialCoroutine(func, ms, resolution = 500)

• Returns a function that, when called, will execute "func" for at most "ms" milliseconds, then yield. Subsequent calls to the function will resume from where it left off. Note that timing is not guaranteed to be accurate; resolution determines how many instructions will be called before testing the time again (smaller numbers mean more frequent tests).