Subscribe in a reader

Example Script

class Plugin

since 1.0.5

Description

Setting up a Plugin1

A Lua Plugin is a Lua script file which (if is valid) is treated as any other plugin by VSTForx. That means it will be recognized by the plugin scanner. So the first step to create a Lua plugin sould be to create a *.lua textfile in your VST plugin folder. Furthermore your script needs some initial informations:
Setup Table: "gpConfig"
Here you can config your plugin.
  --setup table example 
gpConfig = {
type="frx_lua_plugin", -- this field is required
name="Simple Delay" -- the plugin name,
author="Samba Godschynski", -- optional information
numInChannels=2 -- the number of input channels (two channels are applied to one node in vstforx),
numOutChannels=2, -- the number of output channels
info="A simple example script." -- optional
}
Note: Since VSTForx couldn't handle changing the I/O configuration at runtime you have to re-add your plugin after changing numInChannels or numOutChannels.
Parameter Setup: "gpParameterSetup"
The parameter setup table has two functions:
  • configure the plugin parameter setup by using its (name, value) pairs
  • update its values after a parameter changed
Note that the parameter value access is read only, for changing a parameter value use setParameterValue().
  --parameter setup example  gpParameterSetup = { 
parameter1 = 0.1,
parameter2 = 0.2,
parameter3 = 0.3
}
Now your plugin is ready to go.

Messages

Script -> VSTForx
Requests to VSTForx are handled by an object of this Plugin class which can be found in the global Frx table:
  -- accessing the plugin object example 
frx.plug:log("Hello")
VSTForx -> Script
Information between VSTForx and your script are exchanged by so called callback functions. To distinguish them from regular lua functions, all callback functions have a "lc" (lua callback) prefix.
Callback Functions
lcInit()
called when loading the plugin
lcOnSave()
called when VSTForx is about to save the plugin state. Now it's a good time to call setPersistUserData()
lcOnLoad()
called when VSTForx is about to load the plugin state. You can restore your previous saved data using getPersistUserData()
lcProcess(numSamples)
This is the heart of the plugin. All input and output processing happens here. getChannel() and setChannel()
lcProcessMidi(messages)
Will be called when a midi message receives. The messages have following format:
        { {deltaFrames=0, data={dataByte1, ...}}, ... }      
lcSetAudioConfig(blockSize, sampleRate)
Whenever your DAW changes its configuration this function will be called. Use this to configure buffers etc.

Functions

void log ( mixed_values ... )
void logWarn ( mixed_values ... )
void logErr ( mixed_values ... )
void logTrace ( mixed_values ... )
void sendMidi ( sequence msg )
sequence getChannel ( int nb )
sequence fft ( sequence r , sequence i )
void setChannel ( int nb , sequence data )
double getSamplePos ( )
double getBarStartPos ( )
double getPpqPos ( )
double getTempo ( )
void setParameterValue ( string id , float value )
void setParameterDisplay ( string id , string txt )
float getParameterValue ( string id )
string getParameterDisplay ( string id )
void addParameterListener ( string id , string function )
void removeParameterListener ( string id , string function )
sequence getPersistUserData ( string key )
void setPersistUserData ( string key , sequence data )

Fields

no fields

Detailed Description

Functions

void log ( mixed_values ... )
since 1.0.5
Description
Sends a log message to the plugin editor console.
Parameters
... -
void logWarn ( mixed_values ... )
since 1.0.5
Description
Sends a log warning message to the plugin editor console.
Parameters
... -
void logErr ( mixed_values ... )
since 1.0.5
Description
Sends a log error message to the plugin editor console.
Parameters
... -
void logTrace ( mixed_values ... )
since 1.0.5
Description
Sends a log trace message to the plugin editor console.
Parameters
... -
void sendMidi ( sequence msg )
since 1.0.5
Description
Sends a midi message to VSTForx.
Parameters
msg - the midi byte message
sequence getChannel ( int nb )
since 1.0.5
Description
this function can only be called during the lcProcess callback
Parameters
nb - the channel number
Return
The input data of the given channel.
sequence fft ( sequence r , sequence i )
since 1.0.5
Description
Calculates fft data according to this algorithm: fftguru.com
Parameters
r - the r input sequence
i - the i input sequence
Return
the fft data output sequence
void setChannel ( int nb , sequence data )
since 1.0.5
Description
Set the channel output data.
this function can only be called during the lcProcess callback
Parameters
nb - the channel number
data - the channel data sequence
double getSamplePos ( )
since 1.0.5
Description
Return
the current position in audio samples
double getBarStartPos ( )
since 1.0.5
Description
Return
the last bar start position, in quarter note
double getPpqPos ( )
since 1.0.5
Description
Return
musical position, in quarter note (1.0 equals 1 quarter note).
int getTimeSigNumerator ( )
since 1.0.5
Description
Return
time signature numerator (e.g. 3 for 3/4).
int getTimeSigDenominator ( )
since 1.0.5
Description
Return
time signature denominator (e.g. 4 for 3/4).
double getTempo ( )
since 1.0.5
Description
Return
the current tempo in BPM
bool transportIsPlaying ( )
since 1.0.51
Description
Return
true if the transport of the main DAW is playing
void setParameterValue ( string id , float value )
since 1.0.5
Description
Set the parameter value
Parameters
id - the parameter id
value - the parameter value (0..1)
void setParameterDisplay ( string id , string txt )
since 1.0.5
Description
Set the parameter display text.
Parameters
id - the parameter id
txt - the text
float getParameterValue ( string id )
since 1.0.5
Description
Parameters
id - the parameter id
Return
the parameter value
string getParameterDisplay ( string id )
since 1.0.5
Description
Parameters
id - the parameter id
Return
the parameter display text.
void addParameterListener ( string id , string function )
since
Description
Adds a listener to a parameter.
Parameters
id - the parameter id
function - a callback function which accepts a string (the id) and a float (the value) argument
  function onParameterChanged(id, value) 
frx.plug:log(id, value)
end
frx.plug:addParameterListener("param1", "onParameterChanged")
void removeParameterListener ( string id , string function )
since
Description
Removes a parameter listener. (addParameterListener())
Parameters
id - the parameter id
function - the registered callback function
sequence getPersistUserData ( string key )
since 1.0.5
Description
there is currently an issue here: it's not guaranteed that the data table entries are in the same order as saved. (see #488)
Parameters
key - the key
Return
the persist user data for a key.
void setPersistUserData ( string key , sequence data )
since 1.0.5
Description
Set persist user data for a given key.
Parameters
key - the key
data - the data value sequence e.g {"first value","second value", 100}

Fields

no fields

Example

 
--file: SimpleDelay.lua
--setup table, will be loaded when initalizing plugin
gpConfig = {
   type="frx_lua_plugin", 
   name="Simple Gain", 
   author="Samba Godschynski",
   numInChannels=2, 
   numOutChannels=2,
   info="A simple gain to demonstrate how a VSTForx.lua plugin works."
}
--Parameter setup table, will be loaded when initalizing plugin.
--When a parameter is changed this map will be updated, so you can
--use 'gpParameterSetup[name]' for reading a parameter value.
--This map is READ only, writing values will have no affect.
--Use frx.plug:setParameterValue(name, value) instead.
gpParameterSetup = { 
   gain = 0.5
}
--a handy abbreviation for gpParameterSetup
p=gpParameterSetup
 
maxRange=5
gain=0
 
--add a parameter listener for gain
frx.plug:addParameterListener("gain", "onGainChanged")
function onGainChanged(name, value)
   --we want a value range between 0..maxRange
   gain=value*maxRange
   --parameters can only handle values between 0..1
   --but we can set the parameter display
   str=string.format("x%0.2f", gain) --we want only 2 digits of precision
   frx.plug:setParameterDisplay("gain", str)
end
 
 
--this is the process callback
function lcProcess(numSamples)
   --get the input data
   l = frx.plug:getChannel(1) --left channel
   r = frx.plug:getChannel(2) --right channel
   --apply gain
   for i=1, numSamples, 1 do
      l[i] = math.min(1, l[i] * gain) 
      r[i] = math.min(1, l[i] * gain)
   end
   --set the resulting data
   frx.plug:setChannel(1, l)
   frx.plug:setChannel(2, r)
end