Scripts

Note: Scripting is a very powerful program feature and abusing it might have undesired results. Please become familiar with all Turbo Play aspects before trying to write a script.

Introduction
Using the Script Editor
Using JavaScript, VBScript or another Scripting Language (PHP/Perl/LUA/etc)
Using TP Language

Actions found in keyboard/joystick/controller/sensor/3D mappings. <-- Options appearing in Controller Map / Keyboard Map / Joystick Map dialog boxes.

Function List

Introduction

A script is a collection of code to perform things. It is very useful to automate things to happen at specific events, for example, when a certain time limit is reached, or when a midi event is received (for more, see Markers) .

You can write/load/save/run scripts through the Script Explorer (Alt+S). This window also has a script debugger that will notify you of errors/warnings when something occurs. Turbo Play runs all scripts in a separated thread, so it can't block due to a blocking script.

As of now, Turbo Play supports simple commands in scripts, each command takes one line. Currently functions are in the form function("param1","param2") etc.

Using the Script Editor

Show the script editor with ALT+S. From there you can:

Using TP Language

TP language is simple, at the moment you just call functions. For example: 

// Sample of a TP Script
Goto("1|1");

Using Javascript,VBScript or another Scripting language (PHP,Perl,LUA,...)

TP allows you to use the scripting language you prefer. Windows has preinstalled Javascript and VBScript and you can install any other language.
To specify a language, use the #language directive, and then you can use the name "TP" to call TP commands. For example:

// Sample of a JScript
#language JScript
  
var gp = TP.Goto("1|1");
alert(gp);

You can check the menu "Script" in the Script Explorer to see which scripting languages are available. Windows includes by default VBScript and JavaScript. Using the ActiveScripting capabilities you can also install other languages like PHP, Perl, LUA etc.

 

Actions

This section describes all possible actions that appear on "quick text" and also in keyboard/joystick/midi map dialogs.

For items that include axes (joystick axes or 3D mouse axes) or sliders (midi controllers or midi right/left controllers) or automated parameters (VSTs):

 

For button items (joystick buttons, midi buttons, keyboard,3D Mouse Keyboards):

 

Script Parameters

You can use $1 , $2 ... $9 inside a script to replace command line parameters. Some script callers (Like the Sensor Map) pass parameters to the script.

Functions

 

PRESET Functions
These functions load presets. Using these functions allows you to change the configuration of many TP features at runtime.

LoadLinkPreset
Loads a linker preset.

Syntax
int LoadLinkPreset(string name)
  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new linker configuration persists until another LinkPreset command is executed or you change it manually.
Examples
LoadLinkPreset("Preset 1") : Loads "Preset 1".

Return Value
0 - Preset not found
1 - Preset found and loaded
LoadControllerMapPreset
Loads a controller map preset.

Syntax
int LoadControllerMapPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new controller map configuration persists until another ControllerMapPreset command is executed or you change it manually through the Controller Map dialog.

Examples
LoadControllerMapPreset("Map 1") : Loads "Map 1".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadMarkerPreset
Loads a marker preset.

Syntax
int LoadMarkerPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded.

Examples
LoadMarkerPreset("Marker Set 3 ") : Loads "Marker Set 3 ".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadRegionPreset
Loads a region preset.

Syntax
int LoadRegionPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded.

Examples
LoadRegionPreset("Region Set 4") : Loads "Region Set 4".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadTempoPreset
Loads a tempo preset.

Syntax
int LoadTempoPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded.

Examples
LoadTempoPreset("Tempo Map 12") : Loads "Tempo Map 12".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadKeyboardMapPreset
Loads a keyboard map preset.

Syntax
int LoadKeyboardMapPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new keyboard map configuration persists until another KeyboardMapPreset command is executed or you change it manually through the Keyboard Map dialog.

Examples
LoadKeyboardMapPreset("Map 1") : Loads "Map 1".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadJoystickMapPreset
Loads a Joystick map preset.

Syntax
int LoadJoystickMapPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new Joystick map configuration persists until another JoystickMapPreset command is executed or you change it manually through the Joystick Map dialog.

Examples
LoadJoystickMapPreset("Map 1") : Loads "Map 1".

Return Value
0 - Preset not found
1 - Preset found and loaded

LoadSensorMapPreset
Loads a sensor map preset.

Syntax
int LoadSensorMapPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new sensor map configuration persists until another SensorMapPreset command is executed or you change it manually through the Sensor Map dialog.

Examples
LoadSensorMapPreset("Map 1") : Loads "Map 1".

Return Value
0 - Preset not found
1 - Preset found and loaded

Load3CDXMapPreset
Loads a 3CDX map preset.

Syntax
int Load3CDXMapPreset(string name)

  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. The new 3CDX map configuration persists until another 3CDXMapPreset command is executed or you change it manually through the 3CDX Map dialog.

Examples
Load3CDXMapPreset("Map 1") : Loads "Map 1".

Return Value
0 - Preset not found
1 - Preset found and loaded

 

Mixer and State Functions
These functions handle the state (mute,solo,volume,record,write,effects etc) of the requested object.

SetState
Sets the state of an object

GetState
Gets the state of an object

Syntax
int SetState(string object,string value,float param1)
float GetState(string object,string value)

  • object = The object to set the state. This can be an object by name:
    • One of the 7 predefined live mixers
      • "Midi In"
      • "Audio In"
      • "Master In"
      • "Midi Out"
      • "Audio Out"
      • "Master Out"
      • "Tempo"
    • One of the links (You can see the full link name in the Live Mixer
    • One of the tracks

    It can be also an object by index:
    • M#1,M#2... M#7 for the 7 predefined live mixers
    • L#1,L#2 ... for the links
    • T#1, T#2 ... for the tracks.
    Searching an object by index might be necessary in case that objects share their names (for example, if you have a track with a name "Midi In".
  • value = the value to set or query. This can be one of the following
    • volume : The volume of the object. Param1 is the volume value in percentage (say, 100 for 100%).
    • tempo : The tempo of the object. Param1 is the tempo value in percentage (say, 100 for 100%).
    • mute : The mute state of the object. Param1 is 0 when the property is not set, or any other value if it is set.
    • solo : The solo state of the object. Param1 is 0 when the property is not set, or any other value if it is set.
    • record : The record state of the object. Param1 is 0 when the property is not set, or any other value if it is set.
    • write : The write state of the object. Param1 is 0 when the property is not set, or any other value if it is set.
    • pause : The pause state of the object. Param1 is 0 when the property is not set, or any other value if it is set.
      Note: this property is not relevant with the Transporter Pause.
    Note that some properties have no meaning for all objects, for example the "tempo" property has only meaning for the "Tempo" object, and the "record" and "pause" properties have only meaning for the tracks.

 

 

 

Examples
SetState("T#1","mute",1) : Sets first track's mute.
var vg = TP.GetState("L#1","volume") : Gets the volume of the first link (Javascript)

Return Value
SetState
0 - Property not found
1 - Property found and set
GetState
The requested value

 

Miscellaneous Functions
Script
Loads another script and executes it in the background, that is, it does not wait for that script to finish before resuming. See also RUN.
Syntax
int Script(string name)
name = The preset name (case insensitive) of the script.

Examples
SCRIPT("Test 2") : Executes "Test 2" script.

Return Value
0 - Script not found
1 - Script found and executed
Run
Loads another script and executes it in the foreground, that is, it waits for that script to finish before resuming. See also SCRIPT.

Syntax
int Run(string name)

  • name = The preset name (case insensitive) of the script.

Examples
Run("Test 2") : Executes "Test 2" script.

Return Value
0 - Script not found
1 - Script found and executed

Command
Executes a TP Command from the menu.

Syntax
void Command(int cmd)

  • cmd = The number of the command. To learn the numbers of the commands, see Keyboard Map.

Examples
Command(11) : Executes command 16, "Play".

Return Value
0 - Script not found
1 - Script found and executed

 

Transporter Functions
These functions control the transporter, for example you can move to a position, start/stop/record etc.
Goto
Goes to the specified position.

Syntax
string Goto(string position)

  • position = The position to go, either a marker or region name, or an absolute time (hh:mm:ss.mmm), or a measure|beat (m|b). If a valid time cannot be deduced by the argument, Goto goes to 0.

Examples:
Goto("00:00:00.123") : Goes to absolute time position
Goto("5|1)" : Goes to measure 5 beat 1.
Goto("j65)" : Goes to marker or region named "j65"

Return Value
A string specifying the new position

GetSeek
SetSeek
Sets/Gets the seek position.

Syntax
float GetSeek(string Track)
void SetSeek(string Track,float Value)

  • Value = The new seek position (for SetSeek)
  • Track (optional) = The track name to set an individual seek. If this is not specified, the functions manipulate the global seek position (transporter).

Examples:
SetSeek("00:00:00.123") : Goes to absolute time position. Same as Goto().

Return Value
The seek position (GetSeek)

 


Plugin Functions
These functions allow you to query/set values and properties of your plugins (VST,DirectX etc) at runtime.
PluginSetParameter
Sets a VST parameter to a specific value.

 

Syntax
int PluginSetParameter(string PluginName,string ParamName,float Value)

  • PluginName = The unique name of the plugin. TP assigns unique names to VSTs even if you load a VST twice. The Device List has the unique names for each plugin.
  • ParamName = The parameter name of the plugin. For a VST, you can see all parameters in the VST Editor.
  • Value = The value to set.

Examples
PluginSetParameter("foo VST","Amplification",0.95)

Return Value
0 - Parameter not set, either because the plugin was not found or because the parameter name is invalid.
1 - Success.
PluginGetParameter
Queries a VST parameter for its value.

Syntax
float PluginGetParameter(string PluginName,string ParamName)

  • PluginName = The unique name of the plugin. TP assigns unique names to VSTs even if you load a VST twice. The Device List has the unique names for each plugin.
  • ParamName = The parameter name of the plugin. For a VST, you can see all parameters in the VST Editor.

Examples
$v = PluginGetParameter("foo VST","Amplification Left ")
PluginSetParameter("foo VST","Amplification Right ",$v)

Return Value
The value of the parameter. If the parameter is not found, it returns 0.

PluginSetProgram
Selects a VST program

 

Syntax
int PluginSetProgram(string PluginName,int Program)

  • PluginName = The unique name of the plugin. TP assigns unique names to VSTs even if you load a VST twice. The Device List has the unique names for each plugin.
  • Program = 1-based index of the program to select.

Examples
PluginSetParameter("foo VST",2) // Selects the 2nd program

Return Value
The currently selected program (1-index) or 0 if error
PluginGetProgram
Returns the currently selected program.

Syntax
int PluginGetProgram(string PluginName)

  • PluginName = The unique name of the plugin. TP assigns unique names to VSTs even if you load a VST twice. The Device List has the unique names for each plugin.

Examples
$v = PluginGetProgram("foo VST")

Return Value
The value of the currently selected program (1-index).

 

Take Functions
These functions manipulate track takes.
SelectTake
Selects a take for a specific track

 

Syntax
int SelectTake(string TrackName,string TakeName,int index)

  • TrackName = The unique name of the track. It can be either a full track name or a T#1 , T#2 index-based value.
  • TakeName = The name of the take group. It can be also a valid time specifier, for example "00:00:01.000" (See Marker Dialog for possible time formats).
  • Index = The 0-based index of the take. Use -1 to select the main region.

Examples
SelectTake("T#2","TakeGroup1",1)

Return Value
0 - Take not selected, either because the track or the take group was not found.
1 - Success.
AddTake
Adds a take for a specific track. The specified take group must have been created manually already.

 

Syntax
int AddTake(string TrackName,string TakeName)

  • TrackName = The unique name of the track. It can be either a full track name or a T#1 , T#2 index-based value.
  • TakeName = The name of the take group. It can be also a valid time specifier, for example "00:00:01.000" (See Marker Dialog for possible time formats). If this take group doesn't already exist, the function fails.

Examples
AddTake("T#2","TakeGroup1")

Return Value
0 - Take not selected, because either the track or the take group was not found.
1 or higher - Index + 1 of the take track created.

 

Loop Functions
These functions manipulate loops
SetLoop
Selects and loads a particular loop or loop part.

 

Syntax
int SetLoop()


Examples
SetLoop()

Return Value
0 - Loop not loaded , because either the loop or the section was not found.
1 - Success.

MIDI Message Functions
These functions send short or long MIDI messages to MIDI out devices.
SendShortMIDIMessage
Sends a short (DWORD) message to the destination midi out device.

 

Syntax
void SendShortMIDIMessage(int midiout,int value)

  • midiout = 0-based midi out index device.
  • value = The message to send.

Examples
SendShortMIDIMessage(0,18880); // 0x49C0 Send Program for Channel 0 to 0x49.

Return Value