LoopToGo scripting language

Introduction

LooToGo boasts a straightforward yet robust scripting language, employing text files containing command lists associated with Script Markers, keyboard shortcuts, MIDI events, or buttons. These scripts serve to expand the software’s functionality beyond its native design, enabling users to combine shortcuts, create dynamic song templates, and customize the looper’s behavior. Script files are identified by the .ltgs or .txt extension, empowering users to tailor LooToGo to their specific needs and preferences.

Warning: Scripts are to be used by LoopToGo advances users. We suggest that you get familiar with LoopToGo standard functionalities before using scripts. Also, scripts can be very demanding in CPU and or memory when not used properly. It is even possible to make LoopToGo crash with a script (Example: a never ending for-loop or while-loop without and « wait » command). Never use a script in a live performance if the script has not been thoroughly tested before. Don’t hesitate to contact us if you need help to write specific scripts.

Different ways to execute a script

Button

You can create a Script Button that will execute a script when pressed. The button will be added to the Script Button Panel (located at the left of the Looper View) and to the Script Buttons Window. You can select to individually show or hide the Script Button Panel and the Script Button Window in the View Menu. Contrary to the other way to execute a script (Marker and Event), a script associated with a button will be loaded each time the button is pressed.

To change the color of a script button, in the Button Script Dialog, press the Example button located top right. A Choose color dialog will be shown, simply click on a color.

Script Marker

The commands are executed when the song tick reach a Script Marker while the song is playing or recording. To create a Script Markers, create a Marker (see the help page) and check Script Marker then choose a script file and, optionally, add arguments that will be passed to the script. Alternatively, you can use the Manage Scripts Dialog Window to create a Script Marker. Note that for Script Markers, the list of commands is loaded in memory when the script is associated to the marker. If you edit the script file, you have to reload the script in memory (Scripts/Reload all scripts or edit the marker). For this reason, it could be more efficient to use the Manage Scripts Dialog Window to develop and test the script before associate it to a Script Marker. If the script is already running, it won’t start again.

Keyboard shortcut or midi event

The commands are executed when the event occurs. To associate a script with an event, use the « Scripts/Link Script to midi or keyboard event » menu. Alternatively, you can use the Manage Scripts Dialog Window. Note that for Keyboard shortcuts or midi events, the list of commands is loaded in memory when the script is associated to an event. If you edit the script file, you have to reload the script in memory (Scripts/Reload all scripts or edit the event with Scripts/Manage scripts). For this reason, it could be more efficient to use the Manage Scripts Dialog Window to develop and test the script before associate it to a shortcut or midi event. If the script is already running, it won’t start again.

Note: It is suggested to use the ALT modifier to assign script to keyboard shortcut (Example ALT-L). As a matter of fact, LoopToGo default shortcut are assigned to CTRL and SHIFT modifiers and not ALT modifier. The only exception are ALT-1, ALT-2, etc. which are used for muting and unmuting tracks and ALT-Right and ALT-Left. If you still prefer to use a CTRL or SHIFT modifier, make sure to unassigned the default shortcut.

Auto start

It is possible to automatically starts a script when LoopToGo starts or when a song is loaded. To do so, create a file named autoStart.ltgs in {user}/Documents/Scripts or in {user}/Documents/Songs/{Song folder} respectively. It is recommended to use the loadScript or loadScriptDynamic commands inside autoStart.ltgs instead of putting the actual script commands for more reusable scripts. Note that the script launched when a song is loaded will stop when a new song is created or loaded.

Auto exit

It is possible to automatically starts a script when LoopToGo exits or when a song is closed. To do so, create a file named autoExit.ltgs in {user}/Documents/Scripts or in {user}/Documents/Songs/{Song folder} respectively. It is recommended to use the loadScript or loadScriptDynamic commands inside autoExit.ltgs instead of putting the actual script commands for more reusable scripts. Note that it is recommended to keep these scripts short as LoopToGo might kill them if they are too long.

Loop Scripts

Scripts can be executed when entering or leaving a loop. To set this up, follow these steps:

• Open the loop’s Properties dialog window.
• Choose a script for either « Entering a loop » or « Leaving a loop ».

For a record loop, you also have the option to call the corresponding scripts for the linked play loops. If you select a script for a play loop and the associated record loop has this option enabled, both scripts will be called.

When a script is called the following System Variables are set:

• $loopEvent: « Enter » or « Leave »
• $eventLoopID: ID of the loop that triggered the event
• $scriptLoopID: IF of the loop where the script is defined. Will be different from $eventLoopID if the is triggered from a play loop but the script was provided from its linked record loop (where the « Also apply to linked loops » option is checked).

DEPRECATED but still valid when the argument field is empty: A script called when entering or leaving a loop will receive the following arguments:

• Argument 1: « Enter » or « Leave »
• Argument 2: Loop ID (loop for which an event is triggered)
• Argument 3: Calling Loop ID (if different from « Loop ID », it means, this is the ID of the record loop from which the script is called)
• Argument 4: Loop start bar value
• Argument 5: Loop end bar value

Note that these events can occur even when the playhead is not at the beginning or the end of the loop. For example, this can happen when the user clicks inside or outside the loop or when the playhead enters or exits the loop due to a jump. It is the responsibility of the script to check the song’s state (playing, recording, paused, or stopped) and the position of the playhead within the loop to determine the appropriate action.

Additionally, note that a script may be called up to 5 milliseconds (or more, depending on computer specifications) after the events. Therefore, it is not suitable for actions that need to be executed immediately at the beginning or end of the loop.

The script manager

The Script Manager is a powerful tool designed to help create, edit and debug a script. Furthermore, it is very easy to setup the way a script will be used from the « Script Manager.Select Scripts/Manage scripts… ». To launch the Script Manager.

Getting Started – running your first script

To create a script, select « Scripts/Manage scripts… ». Then click on « New script… ». Windows will prompt you to select an application to edit your script file. Choose any text file editor. Notepad can be used at first but you might want to use a more advanced editor as you create bigger scripts.

Note: we suggest that you use Notepad++ for editing LoopToGo’s scripts. An auto-format file as well as an auto-completion file are provided to ease the writing of scripts. See Editing Scripts Appendix for more details.

In the text editor, type the following line:

printInMessageBox "Hello world!"

Hello world

Then save the file. You should see the file listed in the Script Browser section. Select the file and hit « Run selected script ». A Message Box should appear showing « Hello word! ». You are now ready to create more interesting scripts.

Syntax

The script syntax is very simple. Each line is either empty, staring with a command or starting with the comment symbol (//). Empty and commented lines are ignored. Commands may be followed by arguments. Arguments might be mandatory or optional. You will find the list of commands in Appendix A but you have to know some basics commands before starting to write your own script. We suggest that you read the sections below and try the example to get use to the script syntax.

Unknown commands will make the Error/Log console popup and show an error message when loading a script.

Note: commands are case sensitive.

Note: it is suggested to use the « Manage Scripts » window to test the examples below.

File extensions

File extension for script could be .ltgs or .txt. You can use either extension but the .ltgs is recommended since some text editor can be configured for syntax highlighting. Also, file with the .txt exetsnion wont be shown in the script browser. This can be useful to use the .txt extension for utility scripts that are not standalone (must be called by other script such as aliases.txt, see below).

Comments

The double backslash (//) is used to comment a line or a part of a line.

Example:

// This line is commented

print "Hello world!" // A comment

Hello world!

The « alias » command

Similar to the variable command (but still different), the alias command is used to make the code clearer by replacing any text by other text. Unlike the variable command, the alias command is used without the symbol $.

Important note: the alias command (unlike the variable command) is interpreted when the script is loaded, not at runtime.

For example, say that you want to write a script that will start recording, wait 2 bars, then stop. The script could be:

shortcut "Ctrl+Space"
waitDelta 2
shortcut Q

However, the first and third lines are not really meaningful and you could forget what they do when you edit this script later on. Here is an alternative using the alias command:

alias record 		shortcut "Ctrl+Space"
alias stop 		shortcut Q

record
waitDelta 2
stop

As you can see, the script is now easier to understand. Furthermore, you can write all your aliases in a file and use the loadScript command to use them in all your scripts. Here is an example of what a aliases.txt file could be:

// Aliases from shortcuts
alias play 		shortcut "Ctrl+P"
alias stop 		shortcut Q
alias record 		shortcut "Ctrl+Space"
alias setTickHere 	shortcut V
alias toggleGoTo	shortcut G
alias newSong		shortcut "Ctrl+N"
alias jamMode		shortcut J
alias erase		shortcut E
alias outOfJamMode	shortcut O
alias selectChain1	shortcut "Ctrl+1"
alias selectChain2	shortcut "Ctrl+2"
alias selectChain3	shortcut "Ctrl+3"
alias selectChain4	shortcut "Ctrl+4"
alias jumpSection1	shortcutByID 23528
alias jumpSection2	shortcutByID 23529
alias jumpSection3	shortcutByID 23530
alias jumpSection4	shortcutByID 23531

And the previous example will be:

loadScript aliases.txt

record
waitDelta 2
stop

Note that loadScript will insert the script file inside the current script at load time. It is equivalent to copy the content of the loaded file into the current script.

The « print », « printInMessageBox » and « printInBlockingMessageBox » command

The print and printInMessageBox commands are used to output information to the user. These commands can take up to 15 arguments (15 is the maximum for all commands).

The print command will write the arguments to the Error/Log console if visible and to the Manage Scripts/Error/Log Console if visible. All arguments will be separated by one space. If both windows are not visible, the message will be lost. This behavior is to avoid using too much memory. If one of the arguments contains ERROR, the Error/Log console will pop up and show the message in bold red.

The print command is mainly used for debugging purpose and error messages.

The printInMessageBox is used to display informations to the user by showing a window

The printInBlockingMessageBox has the same syntax of print but will display the message in a dialog and wait for the user to press ok. It is used to give informations to the user and to pause the script until the user press OK.

print "Hello World!"
print How yo you do?

Hello World! 
How yo you do? 

The « variable », « globalVariable » and « parentVariable » commands

The variable, globalVariable and parentVariable commands are used to create dynamic values (values that can be changed) in a script. Here are the difference between these commands:

A variable command creates or modifies a variable that « exists » only in the context of a script and all its children if any. It is referred to as standard variable in this document.

A globalVariable command creates or modifies a variable that « exists » only in the context of the application (will exists in all script context after its creation). It will still exist after a script ends and until LoopToGo close. A global variable can be used to keep a state. For example, a script could have different behavior upon it is run for the firs time, the second time, etc. A global variable can also be used to exchange information between scripts. For example, a script that starts a repetitive action in a while loop and another script that stops the action by changing the condition of the while loop. Warning: one of the « wait » commands must be used inside the while loop otherwise, the other script might not be called (see the while section for more details).

A parentVariable command creates or modifies a variable that « exists » in the context of the parent script and all its children if any. It is useful for returning values to its parent. A child script is created either by using the loadScriptDynamic command or the callFunction command. See more details in the function section.

Note that many other commands will also create variables as a way of getting information. These will be equivalent to standard variables.

Contrary to the alias command, the evaluation of a variables is done at runtime. It is « technically » slower that an alias for scripts that are loaded in memory. The variable is preceded by the dollar sign ($) when used but not when created. The variable and globalVariable commands take 1 mandatory argument (the value) and 1 optional argument (quantization). You have to use the quote marks if the value argument contains spaces. Example:

variable var1 Hi
variable var2 "Hello word!"

print $var1
print $var2
print $var1 "my friend!" $var2

Hi
Hello word!
Hi my friend! Hello word!

A variable can be reinitialized many times using the variable command. A variable that has not been initialized will be replaced by 0:

variable var1 1
variable var1 "A sentence"
variable var1 "Another sentence"

print $var1
print $var2

Another sentence
0

The dollar symbol can be used many times to solve variables. Example:

variable myVariable "My first variable"

variable v1 myVariable

print $v1
print $$v1

myVariable
My first variable

Here are some examples with quantization:

variable v1 2.76 1
variable v2 2.76 .5
variable v3 2.76 .25

print $v1
print $v2
print $v3

2.000000 
2.500000 
2.750000 

Here is an example showing the difference between the variable command and the globalVariable command. The following script is run three times to show that the global variable is persistent.

if $var
	variable var $var + 1
else
	variable var 1
endIf

if $gVar
	globalVariable gVar $gVar + 1		
else
	globalVariable gVar 1
endIf

print var : $var
print gVar : $gVar

// First run
var : 1 
gVar : 1 

// Second run
var : 1 
gVar : 2 

// Third run
var : 1 
gVar : 3 

System variables

System variables are internal variables that are defined at runtime when a command is executed. Examples of these variables are script arguments and looper states such as the Song bar value. Appendix B lists all system variables. Don’t hesitate to contact us to suggest new system variables to add to the list if needed.

Note that system variables are read only variables. Setting it to a new value will have no effect!

Example:

print Song tempo is $tempo BPM

variable tempo 100 // This has no effect!

print Song tempo is $tempo BPM

Song tempo is 120.000000 BPM 
Song tempo is 120.000000 BPM 

Algebraic operations

The four main algebraic operation are supported in LoopToGo scripting language : multiplication (*), division (/), addition (+) and subtraction(-). Multiplication and division have greater priority than addition and subtraction. See all the priority order in the section « Order of execution » below.

It is important to note that text, text variables and undefined variables are interpreted as 0 (zero) in algebraic operations.

Also, a division by 0 will be replaced by the text #DIV/0 which could be interpreted as 0 in the remaining operations.

Examples:

print 1 + 2

print 1 + 2*3

print 12/3 - 6/2 

3
7
1

variable var1 3.5
variable var2 "Hello"

print 1 + $var1
print 1 + var1
print 2*$var1

print 1 + $var2
print 1 + var2
print 2*$var2

4.5
1
7
1
1
0

print 2.5/0

variable var1 3/0

print $var1

print $var1 + 2

#DIV/0
#DIV/0
2

Note: As for release 2.3.0 negative numbers can only be created as a result of an operation. Otherwise, the results are inconsistent. We suggest using 0-x to create negative number -x. This issue might be fixed in future releases but using 0-x to create -x will still be valid.

variable neg2 0-2

print 1.5*$neg2

print 3 + $neg2

print $neg2 + $neg2
print $neg2*$neg2

-3
1
-4
4

Concatenation operator

The ampersand symbol (&) is used for concatenation. The result will be a text that could still be interpreted as a number if possible. Examples

print Hello World
print Hello & World

variable v1 Live
variable v2 Looping

print $v1 $v2
print $v1 & $v2

print 3 & 0
print 2 * 3&0

Hello World 
HelloWorld 
Live Looping 
LiveLooping 
30 
60 

The « namespace » and « namespaceEnd » commands

The LoopToGo scripting language incorporates the namespace concept commonly found in most programming languages. This represents an advanced concept, and we recommend skipping this section if you are just beginning to use LoopToGo’s scripting language. The primary purpose of employing this concept is to resolve naming conflicts when utilizing script libraries. Please note that employing the namespace concept may lead to a slight performance loss for your script.

The namespace concept allows users to organize and encapsulate variables, aliases, and functions within distinct containers. To create a namespace, the « namespace » command is employed, specifying the desired namespace name, and it concludes with the « endNamespace » command. This organizational structure helps avoid naming conflicts and enhances code modularity. Accessing elements within the same namespace requires no special syntax. However, when accessing variables, aliases, or functions from the global namespace, users can use the format $NamespaceName::ElementName, simplifying cross-namespace interactions. For instance, if the namespace is « MyNamespace » and the variable is « loopLength, » accessing it globally would involve using $MyNamespace::loopLength.

variable myVar 1.5

namespace MySpace
    variable myVar 2.2
    print "1 myVar :" $myVar
endNamespace

print "2 myVar :" $myVar
print "3 MySpace::myVar :" $MySpace::myVar

1 myVar : 2.2 
2 myVar : 1.5 
3 MySpace::myVar : 2.2

Different namespaces can be nested within each other if wanted.

variable myVar 1.5

namespace Sp1
    variable myVar 2.2
    print "1 myVar :" $myVar
	
    namespace Sp2
        variable myVar 3.7
        print "2 myVar :" $myVar
    endNamespace
	
endNamespace

print "3 myVar :" $myVar
print "4 Sp1::myVar :" $Sp1::myVar
print "5 Sp1::Sp2::myVar :" $Sp1::Sp2::myVar

1 myVar : 2.2 
2 myVar : 3.7 
3 myVar : 1.5 
4 Sp1::myVar : 2.2 
5 Sp1::Sp2::myVar : 3.7 

To access an element (alias, variable, or function) defined in the global namespace from within a namespace, precede the element by two colons (::).

variable myVar 1.5

namespace Sp1
  variable myVar 2.2
  print "1 myVar :" $myVar
  print "2 ::myVar :" $::myVar
	
  namespace Sp2
    variable myVar 3.7
    print "3 myVar :" $myVar
    print "4 ::Sp1::myVar :" $::Sp1::myVar
    print "5 ::myVar :" $::myVar
  endNamespace	
endNamespace

1 myVar : 2.2 
2 ::myVar : 1.5 
3 myVar : 3.7 
4 ::Sp1::myVar : 2.2 
5 ::myVar : 1.5 

Now, imagine you have two libraries implementing the same functionalities. For instance, you might have a library named providerAUtilities.ltgs and another named providerBUtilities.ltgs, both featuring a function called setPadColor. When using both libraries in the same script, the namespace concept becomes essential to resolve the conflict. Here are some examples (Note that it could also have been possible to create only 1 namespace. The other library would be in the global namespace):

namespace ProviderA
	loadScript providerAUtilities.ltgs
endNamespace

namespace ProviderB
	loadScript providerBUtilities.ltgs
endNamespace

// Here are different ways to call the functions from the libraries above

callFunction ProviderA::setPadColor MidiDeviceFromProviderA 5 15
callFunction ProviderB::setPadColor MidiDeviceFromProviderB 3 32

namespace ProviderA
	callFunction setPadColor MidiDeviceFromProviderA 5 15
	
	callFunction ::ProviderB::setPadColor MidiDeviceFromProviderB 3 32
endNamespace

namespace ProviderB
	callFunction setPadColor MidiDeviceFromProviderB 3 32
	
	callFunction ::ProviderA::setPadColor MidiDeviceFromProviderA 5 15
endNamespace

Scripting concepts

Arguments

Passing arguments to a script is the way to add flexibility to the script and make it more reusable. There are 2 types of arguments that can be passed to a script: Standard arguments and User arguments. In both cases, the arguments, if any, are created as variables.

Standard arguments

Standard arguments are the arguments that are written in a dedicated field in the window used for creating or launching the script. The argument field can be found in the Manage Script window, in the Marker window (in the script section), in the Add Script Button window and in the Link Script to Midi or Keyboard Event window.

Standard argument can also be passed to another script using the loadScriptDynamic command or the callFunction command.

Note: Standard arguments can be numbers or text strings

When the script is run, the following variables are created:

The following script can be used to display the standard arguments passed to a script. In this example, the argument field was: 5 men are « drinking soda ».

Note the use of 2 dollars symbol in this example to solve a « composed » (arg & $i) variable.

print nbArgs : $nbArgs

for i 1 $nbArgs
  variable arg arg & $i
  print Argument $i is equal to: $$arg
endFor

nbArgs : 4 
Argument 1 is equal to: 5 
Argument 2 is equal to: men 
Argument 3 is equal to: are 
Argument 4 is equal to: drinking soda

User arguments

User arguments are numbers typed by the user just before launching a script. The user must type a semi-colon between each arguments. When typing these arguments, they will appear at the bottom right corner of the main window.

User arguments can also be passed to another script using the setUserArgs command before calling the loadScriptDynamic or callFunction command if needed.

Important note: the script as the responsibility to reset the arguments with the command setUserArgs when done with them. Otherwise, the new numbers (or semi-colon) typed by the user will be added to what was typed before (this is generally not what you want).

Important note: User arguments can only be numbers.

Important note: the command setUserArgs must be used once the user arguments are used to clear the users args buffer.

When the script is run, the following system variables are created:

The following script can be used to display the user arguments passed to a script. In this example, the user type 2;3.5;4 just before calling the script.

print nbUserArgs : $nbUserArgs

for i 1 $nbArgs
  variable arg userArg & $i
  print User arg $i is equal to: $$arg
endFor

// We must reset the args for next use!
setUserArgs

nbUserArgs : 3 
User arg 1 is equal to: 2 
User arg 2 is equal to: 3.5 
User arg 3 is equal to: 4 

Comparison operators

The scripting langage supports 3 Comparison operator: lower than (<), greater than (>) and equal (=).

It is important to note that text strings, text variables and undefined variables are interpreted as 0 (zero) in lower and greater comparisons.

It is important to note that undefined variables are interpreted as 0 (zero) in lower and greater comparisons. However, text and text variables are kept as text in equality comparisons (text = 0 will be false).

Examples:

print 1 < 2
print 2 < 1
print 1 < 1

print 1 > 2
print 2 > 1
print 1 > 1

1
0
0
0
1
0

print 1 + 1 < 2 + 1
print 2 + 1 < 1 +1
print 2*1 < 2*2

1
0
1

print text < 1
print $undefinedVariable < 1
print 1/0 < 1  // Note 1

1
1
1

Note 1: This is not as expected because 1/0 is converted to text (#DIV/0) and text is converted to 0 in comparisons other than equal.

print 1 = 1
print 1 = 2
print 1 = text
print text = 0		// Note 2
print $undefined = 0 	// Note 3
print Hello! = Hello!
print Hello! = Bye!

variable v1 5
print $v1 = 5

variable v2 "Hello"

print $v2 = 0		// Note 2

1 
0 
0 
0 
1 
1 
0 
1 
0 

Note 2: Text is not converted to 0 in equality tests.

Note 3: Undefined variable are converted to 0 in equality tests

« if », « ifNot » « else » and « endIf » commands

The « if » and « endIf » commands are used to execute a list of commands given a that a condition is true (or false if ifNot is used). The « else » command can be used to execute another list of commands if the condition is false.

Note that 0, text and unset variables are interpreted false. Numbers (and variables) different than 0 are interpreted as true.

Note: Algebric operation or comparator can be used in the condition

Examples:

if 1
	print True
else
	print False
endIf

True

if 0
	print True
else
	print False
endIf

ifNot 0
	print True
else
	print False
endIf

False
True

variable value1 3
variable value2 5

if $value1 < $value2
	print Value1 is lower than Value2
else
	print Value1 is greater than Value2 or equal
endIf

Value1 is lower than Value2

« for » and « endFor » commands

The « for » and « endFor » commands are used to execute the same list of commands n time. The « for » command takes a minimum of 3 arguments an an optional 4th.

Important: if a for loop is too long, it can use too much CPU and cause glitches in the audio engine or make the user interface freeze. See the « while » section below to learn how to avoid this problem.

Examples:

for iterator 2 5
  print $iterator
endFor

2
3
4
5

for v 1 2 .2
  print $v
endFor

1
1.2
1.4
1.6
1.8
2

for v 3 3
  print $v
endFor

3

Note: negative steps are supported but due to the algorithm syntax priority (see above), a negative step must be preceded by 0:

for v 3 1 0-1
  print $v
endFor

3
2
1

The « while » and « endWhile » commands

The « while » and « endWhile » commands are used for executing a list of commands until a condition becomes false.

Important: A while loop that never ends might result in LoopToGo freezing or crashing. You have to be careful when using it. Read all this section to learn how to avoid this problem.

Example:

variable iterator 4

while $iterator
    print $iterator
    variable iterator $iterator - 1
endWhile

4 
3 
2 
1 

It is crucial to make sure that the condition will eventually become false. Otherwise, the script will never end and use all the CPU making LoopToGo to freeze. Even if a while loop would eventually end, if it’s too long, it can causes glitches to the audio engine or impact the user interface. Finally, one could want to write a script that never ends or stops when the user do a particular action (stops the song for example). The way to make sure that a while loop (also a for loop) does not take all the CPU is to use one of the wait commands in the loop section: waitDelta, waitTilSongBar, waitForSongStop, etc.

Example:

variable iterator 4

// The following loop never ends
// Press the Stop Script button
// in the Transport panel to stop it
while $iterator
	print $iterator
	// wait for 1/10th of a bar
	waitDelta .1 
endWhile

4 
4 
4 
4 
4 
4 
4 
4 
4 
Scripts stopped!

The « loadScript » and « loadScriptDynamic »

It is a good practice in programming language to reuse code as much as possible. The way to do it in LoopToGo scripting language is to use the loadScript and loadScriptDynamic. The two commands are very similar and can lead to very similar results but it is important to understand the difference and the context in which one or the other must be used.

Important note: Since Release 2.3.0, the function concept was added to the scripting language. Most of the time, it is a better idea to use the callFunction command instead of loadScriptDynamic. See the « Functions » section for more details.

Similarity: both commands will allow the users to execute commands from another script file.

Differences:

Order of execution

Here is a table showing the order of execution for a script at load time:

Here is a table showing the order of execution for a script at runtime:

Functions (function, endFunction and callFunction commands)

Using the function concept in a script can be very helpful in many ways. First, functions let programmers reuse certain tasks, so they don’t have to rewrite the same code again and again. Second, functions make the code easier to understand by breaking it into smaller, named sections. Lastly, functions make it easier to find and fix errors, making the program more reliable overall.

Note calling a function is like calling another script as one would do with loadScriptDynamic but it’s more efficient because the script commands are already in memory (no need to access the disk). The calling scroipt is consider to be the parent script while the function is considered to be the child script.

To create a function, you simply put some code between the « function » command and « endFunction » command. This is the « function definition ». Here is a first example:

function printHelloWorld
	
	print "Hello World!"
endFunction

To call the function, use the « callFunction command »:

callFunction printHelloWorld

Note that the « function definition » can be anywhere in the script. It does not have to be before the callFunction command. In this example file, most of the time, we define the function first for ease of comprehension but putting all the functions at the end is as good. Also, we suggest that you put frequently used functions in different files and use them with loadScript. This will work as well:

callFunction mySecondFunction

function mySecondFunction
	print "Printed by a function defined after callFunction!"
endFunction

You can pass arguments to a function. Inside the function, you process the arguments the same way you would do it for a script. As a matter of fact, internally, a function is a child script.

function addNumbersAndPrintResult // number1 number2

	if $nbArgs = 2
		print $arg1 "+" $arg2 "=" $arg1 + $arg2 
	else
		print "This function takes 2 arguments"
	endIf

endFunction

callFunction addNumbersAndPrintResult 3.4 2.5

The result will be:

3.4 + 2.5 = 5.9

It could be useful for a function to return one or many values. This is done by passing variables names to the function. We suggest that you identify in a comment which arguments are inputs and which are outputs. Note that an argument can be both input and output. There is an example below (see incrementCounter).

function addNumbers // number1[In] number2[In] result[Out]

	if $nbArgs = 3
		parentVariable $arg3 $arg1 + $arg2
	else
		print "This function takes 3 arguments"
	endIf

endFunction

callFunction addNumbers 3.4 2.5 answer
print "3.4 + 2.5 =" $answer

Note that we use parentVariable to create the $answer variable. This variable will be accessible by the parent script (the calling script). If we would have used the standard variable command, the variable would have only exist in the function context.

The order of the in and out arguments are not important and can be set to suite the function. For example, here is a function that does not always take the same number of arguments

function quantizeNumbers // quantValue[In] value1[In] result1[out] value2[In] result2[out] ...

	variable nbValues $nbArgs - 1
	variable nbValues $nbValues/2
	variable nbValuesInt $nbValues 1 // Quantized
	
	if $nbValues = $nbValuesInt	// Make sure we have as many outputs as inputs
		for i 1 $nbValues
			variable indexInput $i*2 		// input starts at $arg2
			variable indexOutput $i*2 + 1	// output starts at $arg3
			variable input arg & $indexInput
			variable output arg & $indexOutput	
						
			parentVariable $$output $$input $arg1  // $arg1 is the quantization numer
			
		endFor
	else
		print "Numbers of input and output differ!"
	endIf
endFunction

callFunction quantizeNumbers .5 3.2 q1 4.6 q2
print 3.2 quantized to .5 "=" $q1
print 4.6 quantized to .5 "=" $q2

variable quant 1
callFunction quantizeNumbers $quant 3.2 q1 4.6 q2 100.9 q3 100.9 + $quant/2 q4
print 3.2 quantized to $quant "=" $q1
print 4.6 quantized to $quant "=" $q2
print 100.9 quantized to $quant "=" $q3
print "100.9 +" $quant/2 quantized to $quant "=" $q4

The output will be :

3.2 quantized to .5 = 3 
4.6 quantized to .5 = 4.5 
3.2 quantized to 1 = 3 
4.6 quantized to 1 = 4 
100.9 quantized to 1 = 100 
100.9 + 0.5 quantized to 1 = 101 

A function can be called inside a function but you can not define a function inside another function. When calling a function, LoopToGo will search in the current context and if no function is found, it will search in the parent script and its ancestors until a function is found. This means that loadScriptDynamic must not be used to load a « library of functions ». The way to do this is to use loadScript. Note that the script loaded by loadScriptDynamic and its children will have acess to all the parent functions. In the following example, you will see that a function as access to its parentvariables (same as for loadScriptDynamic).

function incrementCounter // cnt [In and Out] increment [In]
	if $nbArgs = 2
		parentVariable $arg1 $$arg1 + $arg2		
	else
		print "This function needs 2 arguments
	endIf
endFunction	

variable cnt 5
callFunction incrementCounter cnt 2
print cnt "=" $cnt

The output will be :

cnt = 7 

Let’s create a function that will call incrementCounter.

function moduloFunction // number [In] modulo [In] result [Out] 
	// Warning: very bad implementation of modulo!!! This is just an example
	
	if $nbArgs = 3
	
		variable number $arg1
		variable cnt 0
		variable modulo $arg2
		
		while $cnt + $modulo < $number
			callFunction incrementCounter cnt $modulo
		endWhile
	
		parentVariable $arg3 $number - $cnt 1 // Quantized to 1
	
	else
		print "This function needs 3 arguments"
	endIf
endFunction

callFunction moduloFunction 28 8 answer
print 28 modulo 8 "=" $answer
callFunction moduloFunction 107 19 answer
print 107 modulo 19 "=" $answer

The output will be:

28 modulo 8 = 4 
107 modulo 19 = 12

When to use loadScript, loadScriptDymanic or callFunction

It is important to understand the difference between loadScript, loadScriptDymanic and callFunction, and when to use them.

loadScript fileName: it is the equivalent of copying the content of file name in the calling script. This is done at loading time and filename can not be a variable. It does not take arguments. Though it would be possible to create variables to emulate arguments passing before the loadScript command, it is reccomanded to use callFunction when arguments are needed. loadScript is ideal for loading a list reusable aliases and function definition.

loadScriptDymanic filename: loadScriptDynamic was implemented before the concept of functions and most of the time, callFunction is a better solution than loadScriptDymanic because callFunction is more efficient (no hard disk access at execution time). But still, there a a few reasons why one would want to use loadScriptDymanic. Because loadScriptDymanic read its file at execution time and accepts a variable as filename, it can be used to load files with different names and/or files with content that can be changed by another application.

callFunction functionName: should be used to reuse code in an efficient way. If the functions are to be used in many scripts, it is suggested to put the function definitions in a separate file and to load it using loadScript

Script timing accuracy

All script are run by an internal timer with a period of 5ms. The first command will be executed between 0 to 5ms. The other commands will be executed right after the first command unless there is a « wait » command with a non reached condition. Then, every 5ms, the script engine will check if the wait has reached it’s resume condition. If so, the other commands will be executed without delay until another wait command is encounter.

Because of this granularity, some scripts might not behave as expected. For example, the following script will not make the audio engine stops at exactly 2.0 and will not always stop exactly at the same bar.

loadScript aliases.txt

setBar 1.0

play

waitTilSongBar 2.0
stop

print $songBar

// First run
2.010160 

// Second run
2.015965

If accuracy is needed and when possible, it is suggested to use temporary marker because their action are done by the audio engine at a higher accuracy. As of release 2.0.0, there are temporary markers for the following actions: Stop, Pause, GoTo. It is also possible to create a temporary Section Marker and use it to jump from or jump to other temporary or normal Section Marker. The previous code can be written to achieve more accuracy. Temporary markers will be shown in green and will be deleted when the song stops.

loadScript aliases.txt 

setBar 1.0

addTemporaryStopMarker	2

play

waitForSongStop

print $songBar

// First run
2.000000 

// Second run
2.000000 

Appendix A – List of commands

Appendix B – List of System variables

Appendix C – Script Examples

Installation instruction : download the zip file above and extract it in {user}/Documents/LoopToGo/Scripts

Appendix D – Editing Scripts

We suggest that you use Notepad++ for editing LoopToGo’s scripts. An auto-format file as well as an auto-completion file are provided to ease the writing of scripts. These files may be updated with every new LoopToGo releases so make sure to re-install them from time to time.

When the auto-format file is properly imported in Notepad++, the LoopToGo script code should look like this in Notepad++:

Furthermore, the auto-completion file will give a list of key words from the scripting language to choose from when you start typing.

Installing the auto-format file (UDL)

Download the AllLoopToGoScripts.zip file from the Appendix C and unzip it in the {User}/Documents/Scripts folder. Then, in Notepad++, select Language/User Defined Language/Define your language… Then, click on the Import… button and select the auto-format file: {User}/Documents/LoopToGo/Scripts/LoopToGo/LTGSFormatForNotepad+.xml

The next time you will load a file with the .ltgs extension, it will use this file format. if a file is already loaded in Notepad++ or if you want to use the same formatting for a file with another extension (.txt for example), simply click on Language and select LoopToGoScript.

For the auto-formatting to work, the file your editing must use the LoopToGoScript language. The language used is shown at the left bottom corner of Notepad++.

Installing the auto-completion file

Copy {User}/Documents/LoopToGo/Scripts/LoopToGo/LoopToGoScript.xml into c:/program Files/Notepad++/autoCompletion/ folder. The name of the file must not be changed as it is the language name. Restart Notepad++.

For the auto-Completion to work, the file your editing must use the LoopToGoScript language. The language used is shown at the left bottom corner of Notepad++.