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. This manual assumes you are familiar with programming.


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

Using the Script Editor

Show the script editor with F7. From there you can:

Creating a new Script in Javascript or another Scripting language (VBScript, PHP, Perl, LUA, ...)

Turbo Play allows you to select the scripting language you will use. Windows has preinstalled Javascript and VBScript and you can install any other language. The #language directive selects the language that should be used in the script. By default, TP uses Javascript. You can use the namespace "TP" to call TP commands. For example:

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

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

 

Script Actions

This section describes all possible actions that appear on "quick text" and also in keyboard/joystick/midi map/remote 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

The list below contains all currently defined functions.

Generic Functions
These functions are called from the namespace "TP", for example TP.Run();
Run
Starts execution of another script
Syntax
void Run(string name,string p1,...)
Name = name of the script. If the script is not defined, this function does nothing. You can also pass optional parameters.

Examples
Run("script1") : Starts "script1".

Return Value
Command
Executes a TP menu command.
Syntax
void Command(int ID)
ID = The ID of the command. The script editor can show all the available commands via the menus.

Examples
Command(101) : Executes menu command 101.

Return Value
Shell
Executes an application or file
Syntax
void Shell(string f)
f = The file to run, either an executable or a document. Depending on the language, the path might need escape commands such as \\.

Examples
Shell("c:\\file.txt") : Executes c:\file.txt (use \\ in Javascript).

Return Value
SetGlobal / GetGlobal
Sets/Gets value of a global variable
Syntax
void SetGlobal(string param,string value)
string GetGlobal(string param)
param = The global variable. If it does not exist, it is created. Global variables are reset when playing finishes.
value = the new value of the parameter.

Examples (Javascript)
TP.SetGlobal("foo","hi"); // Now "foo" is equal to "hi"
$j = TP.GetGlobal("foo"); // Now $j contains "hi"

Return Value
The value of the parameter (for GetGlobal()).

 

 

Track Functions
SetSelection
Sets current Track Manager selection.
Syntax
int SetSelection(float from,float to)
from,to = The range to set in ms.

Examples
SetSelection(0,1000) : Sets the selection from 0 to 1000 ms.

Return Value
SetView
Sets current Track Manager view.
Syntax
int SetView(float from,float to)
from,to = The range to set in ms.

Examples
SetView(0,1000) : Sets the view from 0 to 1000 ms.

Return Value
SetDMXValue
Sets a DMX value for a DMX channel in a track.

 

Syntax
int SetDMXValue(string TrackName,string ChName,int Type,intvalue)

  • TrackName = The unique name of the track. It can be either a full track name or a T#1 , T#2 index-based value.
  • ChName = The name of the DMX channel, or a 0-based index.
  • Type = 0 normal 1 from midi.
  • value = The 0-255 value (or if type == 1, 0-127) to set.

Examples
SetDMXValue("T#2","Ch1",0,250)

Return Value
0 - Value not set, either because the track or the DMX channel was not found.
1 - Success.

SetAutomation
Sets an automation string

 

Syntax
int SetAutomation(string Track,string Automation,int Type)

  • Track = The Track name or T#1 T#2 etc.
  • Automation = A string which contains script-style associations, separated with ,,,. For example: "TRACK|0|Test,,,TRACK|1|Loop"
  • Type = 0 for a volume automation, 1 for an automation track playing and 2 for an automation track recording. Most common will be the type == 1.

Examples
SetAutomation("T#3","TRACK|4|Audio,,,TRACK|5|Audio 2",1)

Return Value
0 - Parameter not set, either because the plugin was not found or because the parameter name is invalid.
1 - Success.

   

PRESET Functions
These functions load presets. Using these functions allows you to change the configuration of many TP features at runtime. They are available through the "TP.Preset" namespace, for example TP.Preset.LoadLinkPreset("linkpreset1");

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

LoadRemoteMapPreset
Loads a remote map preset.

Syntax
int LoadRemoteMapPreset(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 RemoteMapPreset command is executed or you change it manually through the Remote Map dialog.

Examples
LoadRemoteMapPreset("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 joystick,string name)

  • joystick = The Loaded joystick name or J#0, J#1 etc.
  • 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

LoadVSTPreset
Loads a VST preset.

Syntax
int LoadVSTPreset(string VST ,string name)

  • VST = The VST name or V#1, V#2 etc.
  • name = The preset name (case insensitive). If more than one presets have the same name, the first preset found is loaded. If a state preset has the same name with a global preset, the state preset is loaded.

Examples
LoadVSTPreset("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.
    • human_active,human_pitch,human_velocity,human_time : These properties set humanization options for midi track.
      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 are called from the namespace "TP.Transporter", for example TP.Transporter.Goto(). 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

 


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.

PluginSetFreeze
Sets a VST freeze to a specific freeze value.

 

Syntax
int PluginSetFreeze(string PluginName,int FreezeIndex)

  • 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.
  • FreezeIndex = The index of the freeze to select, or 0 if the plugin is to be used without freezing.

Examples
PluginSetParameter("foo VST",0)

Return Value
0 - Parameter not set, either because the plugin was not found or because the freeze index is invalid.
1 - Success.

PluginGetFreeze
Queries a VST parameter for its freeze value.

Syntax
int PluginGetFreeze(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 = PluginGetParameter("foo VST")


Return Value
The value of the freeze index, or 0 if the plugin is not frozen.

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

PluginSetBypass / PluginSetSilence
Sets a VST's Bypass or Silence flag

 

Syntax
int PluginSetBypass(string PluginName,int Set) ;
int PluginSetSilence(string PluginName,int Set) ;

  • PluginName = V#1,V#2 etc or 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.
  • Set = 1 to set, 0 to disable.

Examples
PluginSetSilence("V#1",1); // Sets silence to plugin #1

Return Value
None

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.

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