EN
Official Website Forum Donate Github

Scripting Reference

Here you can find an almost exhaustive reference on Chataigne specific functions.

Scripts in Chataigne are based on a simplified version of Javascript. Most functions are available, but some might be missing. If you're missing some functions, please contact me and consider donating so I can spend more time improving Chataigne !

This documentation only shows functions that I have added on top of JUCE's Javascript Engine. To know all the base functions that are available, you can take a look at the JavascriptEngine's source code

Common Functions

There are few common functions that you can use, no matter the type of script.

None of the functions below are needed when making a script, they are just helper functions. If you don't need them, don't add them in your script as Chataigne will optimize your script depending on the available functions in it.

MethodDescriptionExample

init()

If present, this function will be called right after the script is loaded.

function init() {

//init your values, log things and assign variables

}

update(deltaTime)

If present, this function will be called regularly at rate specified by the "Update rate" script parameter. This parameter is only visible when the function is present in the script. You can also change the rate from the script by calling script.setUpdateRate(rate). see below for more informations. deltaTime is in seconds, and the rate parameter is in Hz.

function update(deltaTime)

{

script.log("Delta time : " + deltaTime);

}

messageBoxCallback(id, result)

This function is called when a user has made a choice in a message box launched by this script.

function messageBoxCallback(id, result) {script.log("Message box callback : "+id+" > "+result); }

Parameters and triggers

All parameters and triggers have common methods and specific methods

Common methods and properties

MethodDescriptionExample

getParent()

Returns the value of this parameter

myParam.getParent();

setName(name)

Sets the parameters name

myParam.setName("new name");

setAttribute(attribute, value)

Sets a parameter's attribute.

All parameters get : readonly : sets the parameter as not editable

description : change the tooltip description

enabled : enable or disable this parameter

alwaysNotify : set the alwaysNotify flag (if true, this will trigger updates even if setting the same value than before). More information for specific parameters in each parameter's section.

myParam.setAttribute("readonly",true);

myParam.setAttribute("description"," new description");

myParam.setAttribute("enabled",false);

myParam.setAttribute("alwaysNotify", true);

isParameter()

returns whether the target is a parameter or a trigger

var isParam = myTarget.isParameter();

name

This is the name identifier of the object, as you would target it in a script.

script.log(myParam.name);

niceName

This is the "nice name" of the object, as you see it in the Inspector.

script.log(myParam.niceName);

getControlAddress ([reference])

Returns the OSC-style control address of this element. Optional reference parameter allows you to specify a root container to generate the address from.

script.log( myParam.getControlAddress());

getScriptControlAddress()

Returns the script control address of this element.

script.log( myParam.getScriptControlAddress());

resetValue()

Resets the value to its default

myParam.resetValue();

Trigger

MethodDescriptionExample

trigger()

Returns the value of this parameter

myTrigger.trigger();

Float Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myFloatParam.get();

set(value)

Sets the value of this parameter

myFloatParam.set(.5);

setAttribute(attribute, value)

Specific attributes :

ui : The UI to use to show this parameter. Accepted values are : time, slider, stepper, label

myStringParam.setAttribute ("ui", "time");

Integer Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myIntParam.get();

set(value)

Sets the value of this parameter

myIntParam.set(2);

setAttribute(attribute, value)

Specific attributes :

hexMode : Whether to show the value as decimal or hexadecimal.

myStringParam.setAttribute ("hexMode", true);

Boolean Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myBoolParam.get();

set(value)

Sets the value of this parameter

myBoolParam.set(true);

String Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myStringParam.get();

set(value)

Sets the value of this parameter

myStringParam.set("super");

setAttribute(attribute, value)

Specific attributes :

multiline: whether the parameter can be multiline

prefix: add a prefix before the value

suffix: add a suffix after the value

myStringParam.setAttribute ("multiline", true);

Color Parameter

MethodDescriptionExample

get()

Returns the value of this parameter. The result is an array containing [r,g,b,a], values are between 0 and 1

var value = myColorParam.get();

script.log("green : "+value[1]);

set(value)

Sets the value of this parameter. You can either set the value with ARGB hex value, [r,g,b,a] float array, or r,g,b,a separate values. r, g and b values are always between 0 and 1 and alpha is optional (you can specify r,g,b only);

//this is all set to cyan alpha 100%

myColorParam.set(0xff00ffff);

myColorParam.set([0,1,1,1]);

myColorParam.set(0,1,1,1);

Target Parameter

MethodDescriptionExample

get()

Returns the string value of the target address

var address = myTargetParam.get();

getTarget()

Returns the actual selected target

var target = myTargetParam.getTarget();

set(value)

Sets the string value of the target's address.

myTargetParam.set ("/root/modules/osc");

setAttribute(attribute, value)

Specific attributes :

targetType : the type of target to search. This can either be "container" or "controllable"

root : the root container from which to search

searchLevel : specify the max level to search from the root

showParameters : if target is controllable, hide or show parameters

showTriggers : if target is controllable, hide or show triggers

labelLevel : the level of parents to show in the UI.

allowedTypes : specify which types of targets are allowed

excludedTypes : specify which types of targets are not allowed

myTargetParam.setAttribute ("searchLevel",2);

myTargetParam.setAttribute ("root", root.sequences);

myTargetParam.setAttribute( "allowedTypes", "Mapping");

Enum Parameter

MethodDescriptionExample

addOption(label, value)

Add an option to the list

myEnumParam.addOption("new option",3);

get()

1.6.x : Return the selected key

1.7.x : Return the selected data

var label = myEnumParam.get(); //1.6.x

var value= myEnumParam.get(); //1.7.x

getData()

Get the selected data (1.6.x only)

var data = myEnumParam.getData(); //1.6

getKey()

Get the selected key (1.7.x only)

var key = myEnumParam.getKey(); //1.7

removeOptions()

Removes all options.

myEnumParam.removeOptions();

set(key)

This sets the parameter to the corresponding key.

myEnumParam.set("Option 1");

setData(data)

This sets the parameter to the corresponding data

myEnumParam.setData("data1");

setNext([loop])

Sets the value to the next element in list. Loop (optional) : loops throught the list

myEnumParam.setNext(true);

setPrevious([loop])

Sets the value to the previous element in list. Loop (optional) : loops throught the list

myEnumParam.setPrevious(true);

getAllOptions()

Returns an array with all available option.

Each element of the array is an object containing a "key" and a "value" property.

var options = myEnumParam.getAllOptions(); script.log(options[0].key);

getOptionAt(index)

Return an option at the defined index . This object contains a "key" and a "value" property.

var options = myEnumParam.getAllOptions(); script.log(options[0].key);

getIndex()

Returns the index of the selected option.

var index = myEnumParam.getIndex();

File Parameter

MethodDescriptionExample

setAttribute(attribute, value)

Specific attributes :

directoryMode: specify if this parameter should be looking for a file or a folder

myFileParam.setAttribute ("directoryMode",true);

readFile([asJSON])

Get the content of the file. If asJSON is true, then the content will be parsed and returned as an Object.

var myTextContent = myFileParam.readFile ();

var myJSONContent = myFileParam.readFile (true);

writeFile(data, overwriteIfExists)

Write the content or a string of an Object to the selected file. If the file exists, overwriteIfExists will let you decide whether to overwrite it or not (false by default).

var data = "super";

myFileParam.writeFile (data, true);

getAbsolutePath()

Returns the absolute path for this file.

var path = myFileParam.getAbsolutePath();

launchFile(arguments**)**

This will launch the selected file with the _arguments _ provided

myFileParam.launchFile ("--verbose")

Point2D Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myP2DParam.get();

set(x, y)

Sets the value of this parameter

myP2DParam.set(.5, 2);

Point3D Parameter

MethodDescriptionExample

get()

Returns the value of this parameter

var value = myP3DParam.get();

set(x, y, z)

Sets the value of this parameter

myP3DParam.set(.5, 2, -1);

Container

Containers are any object that contains parameters or other containers. If you're targetting something from the hierarchy (root.* **** or local.*), this will be either a container of a parameter, so if it's not a parameter, then it's a container.

MethodDescriptionExample

getChild(childName)

Returns the parameter or container with the provided name.

var child = myContainer.getChild("activity");

getParent()

Returns the parent container

var parent = myContainer.getParent();

setName(name, [shortName])

Changes the name of the container.

If shortName is specified, it will set a custom short name that you can access easily from the script.

myContainer.setName("new name");

setCollapsed(value)

Change the collapsed state of the container, if it can be collapsed.

myContainer.setCollapsed(false);

name

This is the name identifier of the object, as you would target it in a script.

script.log(myContainer.name);

niceName

This is the "nice name" of the object, as you see it in the Inspector.

script.log(myContainer.niceName);

addTrigger(name, description)

This will add a trigger (button).

var myTrigger = myContainer.addTrigger("My Trigger", "Trigger description");

addFloatParameter(name, description, default, min max)

This will add a float number parameter (slider).

var myFloatParam = myContainer.addFloatParameter("My Float Param","Description of my float param",.1,0,1);

addIntParameter(name, description, default, min max)

add an integer number parameter (stepper), default value of 2, with a range between 0 and 10

var myIntParam = myContainer.addIntParameter("My Int Param","Description of my int param",2,0,10);

addBoolParameter(name, description, default)

add a boolean parameter (toggle)

var myBoolParam = myContainer.addBoolParameter("My Bool Param","Description of my bool param",false);

addStringParameter(name, description, default)

add a string parameter (text field)

var myStringParam = myContainer.addStringParameter("My String Param","Description of my string param", "cool");

addColorParameter(name, description, default)

add a color parameter (color picker).

You can either set the default color with ARGB hex value, [r,g,b,a] float array, or r,g,b,a separate values. r, g and b values are always between 0 and 1 and alpha is optional (you can specify r,g,b only);

var myColorParam = script.addColorParameter("My Color Param","Description of my color param",0xff0000ff); //default blue alpha 100%

var myColorParam2 = script.addColorParameter("My Color Param 2 ","Description of my color param",[1,0,1]); //default purple

addPoint2DParameter(name, description)

add a point 2d parameter

var myP2DParam = myContainer.addPoint2DParameter("My P2D Param","Description of my p2d param");

addPoint3DParameter(name, description)

add a point 3d parameter

var myP3DParam = myContainer.addPoint3DParameter("My P3D Param","Description of my p3d param");

addTargetParameter(name, description)

add a target parameter (to reference another parameter)

var myTargetParam = myContainer.addTargetParameter("My Target Param","Description of my target param");

addFileParameter(name, description, [directoryMode])

Add a file parameter (to reference file or folder on the disk).

If directoryMode is set to true a folder instead of a file can be selected.

var myFileParam = myContainer.addFileParameter("My File Param","Description of my file param");

addEnumParameter(name, description, label1, value1, label2, value2, ...)

Add a enum parameter (dropdown with options)

Each pair of values after the first 2 arguments define an option and its linked data

var myEnumParam = myContainer.addEnumParameter("My Enum Param","Description of my enum param", "Option 1", 1,"Option 2", 5, "Option 3", "banana");

addContainer(name)

Add a container inside of the container.

var childContainer = myContainer.addContainer("My Child Container");

addAutomation(name)

Adds a curve container

var automation = myContainer.addAutomation("Curve");

removeContainer(name)

Remove a child container from the container.

myContainer.removeContainer ("myChildContainer")

removeParameter(name)

Remove a parameter from the container.

myContainer.removeParameter ("myChildParameter");

getControlAddress ([reference])

Returns the OSC-style control address of this element. Optional reference parameter allows you to specify a root container to generate the address from.

script.log( myContainer.getControlAddress());

getScriptControlAddress()

Returns the script control address of this element.

script.log( myContainer.getScriptControlAddress());

Manager

Managers are special types of container. In the software, you can see that a container is a manager when there is a "+" icon on the right of its block. Well, almost all the times, some of them are just enhanced containers. Most of the times, the managers you will be interested in are the Module manager, the Sequence manager, Layer managers and Automation keys managers.

When a manipulating a manager, you have access to specific functions and properties like adding items, removing items or getting an array of it's items.

MethodDescriptionExample

addItem([type])

Adds an item to the manager and returns it.

Some managers like the Module manager or the layer manager can create multiple types of items. Thus they need a type of item to create, which you must set in the type argument.

Other managers like the Sequence manager don't need this argument because there is only one type of sequence. In these cases you don't need to provide an argument when calling the function.

var newOSCModule = root.modules.addItem("OSC");

var newSequence = root.sequences.addItem();

removeItem(item)

Removes an item. item must be a item managed by this manager.

root.modules.removeItem (myModule);

getItems()

Returns an array containing all the items of this manager.

var items = root.sequences.getItems();

script.log("Num sequences : "+items.length);

getItemWithName(name)

Returns the first item found with name. This will search for exact match of niceName, shortName, and lowercase version.

var introSeq = root.sequences.getItemWithName ("Intro");

getItemAt(index)

Returns the item at the index.

var curSequence = root.sequences.getItemAt(1); //0 is first, so this will get the second sequence in the list.

getItemIndex(item)

Returns the index of the specified item.

var index= root.sequences.getItemIndex (curSequence);

getItemBefore(item)

Returns the item before the specified item.

var prevSequence = root.sequences.getItemBefore (curSequence);

getItemAfter(item)

Returns the item after the specified item.

var nextSequence = root.sequences.getItemAfter (curSequence);

reorderItems()

Reorders all items in this manager.

var mappingLayer = root.sequences.sequence.layers.mapping;

mappingLayer.automation.reorderItems();

States

States have dedicated methods to ease the creations of certain items like transitions.

MethodDescriptionExample

addTransition(source, dest)

Adds a transition between two states. source and dest are the two names of the States to transition from/to

var transition = root.states.addTransition("State A", "State B");

Automation

Automations are special managers that handle curves. You can find them in Mapping Layers, or Curve Map filters for instance. They have special methods that you can use to get more specialized info about the curve data.

MethodDescriptionExample

addKey(position, value)

Adds a key at the given position and value

var key = automation.addKey(.5,1);

setLength(length, stretch, stickToEnd)

Set a new length for this automation. Stretch allows to stretch all keys to keep relative positioning across the whole automation, stickToEnd forces them to repositioning relative to then end

automation.setLength(12.1, false, false);

getValueAtPosition(position)

Returns the value of the curve at the given position

var val = automation.getValueAtPosition(2.5);

getKeyAtPosition(position)

Returns the closest key at the given position

var key = automation.getKeyAtPosition(2.5);

getKeysBetween(start, end)

Returns an array of all the keys contained between start and end

var keys = automation.getKeysBetween(2.5, 4.7);

Script object

The script object refers to the script container. You can add your own custom parameters here, as well as logging informations, warnings and errors.

MethodDescriptionExample

addTrigger(name, description)

This will add a trigger (button)

var myTrigger = script.addTrigger("My Trigger", "Trigger description");

addFloatParameter(name, description, default, min max)

This will add a float number parameter (slider).

var myFloatParam = script.addFloatParameter("My Float Param","Description of my float param",.1,0,1);

addIntParameter(name, description, default, min max)

add an integer number parameter (stepper), default value of 2, with a range between 0 and 10

var myIntParam = script.addIntParameter("My Int Param","Description of my int param",2,0,10);

addBoolParameter(name, description, default)

add a boolean parameter (toggle)

var myBoolParam = script.addBoolParameter("My Bool Param","Description of my bool param",false);

addStringParameter(name, description, default)

add a string parameter (text field)

var myStringParam = script.addStringParameter("My String Param","Description of my string param", "cool");

addColorParameter(name, description, default)

add a color parameter (color picker).

You can either set the default color with ARGB hex value, [r,g,b,a] float array, or r,g,b,a separate values. r, g and b values are always between 0 and 1 and alpha is optional (you can specify r,g,b only);

var myColorParam = script.addColorParameter("My Color Param","Description of my color param",0xff0000ff); //default blue alpha 100%

var myColorParam2 = script.addColorParameter("My Color Param 2 ","Description of my color param",[1,0,1]); //default purple

addPoint2DParameter(name, description)

add a point 2d parameter

var myP2DParam = script.addPoint2DParameter("My P2D Param","Description of my p2d param");

addPoint3DParameter(name, description)

add a point 3d parameter

var myP3DParam = script.addPoint3DParameter("My P3D Param","Description of my p3d param");

addTargetParameter(name, description)

add a target parameter (to reference another parameter)

var myTargetParam = script.addTargetParameter("My Target Param","Description of my target param");

addFileParameter(name, description, [directoryMode])

Add a file parameter (to reference file or folder on the disk).

If directoryMode is set to true a folder instead of a file can be selected.

var myFileParam = script.addFileParameter("My File Param","Description of my file param");

addEnumParameter(name, description, label1, value1, label2, value2, ...)

add a enum parameter (dropdown with options)

Each pair of values after the first 2 arguments define an option and its linked data

var myEnumParam = script.addEnumParameter("My Enum Param","Description of my enum param", "Option 1", 1,"Option 2", 5, "Option 3", "banana");

log(message)

Logs a message (must activate "Log" in the script parameters)

script.log("This is a message");

logWarning(message)

Logs a message as a warning

script.logWarning("This is a warning");

logError(message)

Logs a message as an error

script.logError("This is an error");

setUpdateRate(rate)

Sets the rate at which the update() function is called

script.setUpdateRate(50);

setExecutionTimeout( timeInSeconds)

Sets the maximum time that a call in the script can take in seconds.

script.setExecutionTimeout(10);

function scriptParameterChanged (param)

This function will be called each time a parameter of this script has changed.

function scriptParameterChanged(param){ script.log("Param changed : "+param.name); }

Root object

The root object refers to Chataigne's engine, which is the root object of all parent. It allows you to access any object in Chataigne's hierarchy. The best way to access them is to right click on a parameter's UI and select "Copy Script control address". Then you can past the address in your script and you will be able to control this parameter.

Local object

The local object depends on where the scripts is running.

  • If the script is running inside a module, the local variable will referring to the module. You can find all the module functions in the Module Scripts section.

  • If the script is running inside a condition, the local variable will be referring to the condition. You can find all the condition functions in the Condition Scripts section.

  • If the script is running inside a filter, the local variable will be referring to the filter. You can find all the filter functions in the Filter Scripts section.

Util object

The util object provides helpers and utility functions like time or conversion.

MethodDescriptionExample

getAppVersion()

Retourne la version actuelle de l'application

var version = util.getAppVersion();

getOSInfos()

Returns informations about the OS. The returned object contains the following properties :

"name" : name of the OS

"type": OS type "computerName": name of the computer

language": OS language

"username" : name of the logged on user

var infos = util.getOSInfos(); script.log("Hello "+infos.username);

getEnvironmentVariable(key)

Returns the value of an environment variable from the OS.

var pathEnv = util.getEnvironmentVariable("PATH");

getTime()

Returns the time since system start in seconds

var time = util.getTime();

getTimestamp()

Returns the time since January 1st 1970 in seconds

var timestamp = util.getTimestamp();

delayThreadMS(milliseconds)

delays the scripts execution the amount of milliseconds provided.

util.delayThreadMS(200);

getFloatFromBytes(byte1, byte2, byte3, byte4)

Returns a float from 4 bytes (big endian, byte1 is most significant)

var value = util.getFloatFromBytes(0, 0, 2, 10);

floatToHexSeq( float, true )

Returns a Sequence of HEX values from float (4 bytes) (big endian or little endian)

var strValue = util.floatToHexSeq(15.1225,true);

getInt32FromBytes(byte1, byte2, byte3, byte4)

Returns a 32-bit integer from 4 bytes (big endian, byte1 is most significant)

var value = util.getInt32FromBytes(0, 0, 2, 10);

getInt64FromBytes(byte1, byte2, byte3, byte4, byte5, byte6, byte7, byte8)

Returns a 64-bit integer from 8 bytes (big endian, byte1 is most significant)

var value = util.getInt64FromBytes(0, 5, 7, 22, 0, 0, 2, 10);

doubleToHexSeq( double, true )

Returns a Sequence of HEX values from double (8 bytes) (big endian or little endian)

var strValue = util.doubleToHexSeq(15.1225,true);

getIPs()

Returns an array of all IP addresses found

var ips = util.getIPs();

for(var i=0; i<ips.length; i++) { script.log(ips[i]); }

hexStringToInt( String )

Returns Int value from HEX 'string' (from "00" to "FF")

var intValue = util.hexStringToInt("1D");

encodeHMAC_SHA1(text, key)

Returns a HMAC-SHA1 encoded string

var encoded = util.encodeHMAC_SHA1("my text", "my key");

toBase64(value);

Returns a converted base-64 string from an utf8 string.

var str64 = util.toBase64("cool");

fromBase64(value);

Returns a converted data block from a base-64 encoded string

var str_decoded = util.toBase64("sGVsbG8gd29ybGQh");

fileExists(path)

Returns true if a file exists at the path provided, otherwise returns false

script.log(fileExists("myfile.txt"));

directoryExists(path)

Returns true if a directory exists at the path provided, otherwise returns false

script.log(directoryExists("myFolder"));

readFile(path, **** [asJSON])

Get the content of the file at path. If asJSON is true, then the content will be parsed and returned as an Object.

var myTextContent = util.readFile("myfile.txt");

writeFile(path, data, overwriteIfExists)

Write the content of a string or an Object to the file at path . If the file exists, overwriteIfExists will let you decide whether to overwrite it or not (false by default).

var data = "super";

util.writeFile("myfile.txt", data, true);

createDirectory(folderPath)

Creates a directory at the path specified.

util.createDirectory("path/to/dir");

getObjectProperties(object, includeParameters, includeObjects)

Returns an array of all the properties names of this object. You can specify if you want to include parameters and/or objects (like containers) Default is include all.

var propNames = util.getObjectProperties(myObject, true, false); //only get parameters

getObjectMethods(object)

Returns an array of all the method names of this object.

var methods= util.getObjectMethods();

copyToClipboard(data, data2...)

Copies all data joined into string to the clipboard

util.copyToClipboard("super",5, myData);

getFromClipboard()

Returns the content of the clipboard

var data = util.getFromClipboard();

showMessageBox(title, message, [icon, buttonText])

Shows a popup message box with only one button. Additionally to title and message, you can provide an icon (accepted values are "info", "warning", "question" ) and the text of the button.

util.showMessageBox("Super info !", "This is a message for you", "info", "Got it");

showOkCancelBox(id, title, message, [icon, button1Text, button2Text])

Shows a popup message box with only one button.

id is the id that will be provided when the messageBoxCallback is called (see Common functions). Additionally to title and message, you can provide an icon (accepted values are "info", "warning", "question" ) and the text of the button.

This method will return true if the first button has been clicked, false otherwise

util.showOkCancelBox("myWarningBoxId", "Super warning!", "This is a warningfor you", "warning", "Got it","Naaah");

showYesNoCancelBox(

id, title, message, [icon, button1Text, button2Text, button3Text] ),

Shows a popup message box with only one button.

id is the id that will be provided when the messageBoxCallback is called (see Common functions).

Additionally to title and message, you can provide an icon (accepted values are "info", "warning", "question" ) and the text of the button.

This method will return either 0,1 or 2 depending on the button that has been clicked.

util.showYesNoCancelBox("myConfirmBoxId", "Confirm ?", "Do you really want to do that ?", "question", "Yeah", "Never", "Don't care...");

PreviousIntroduction to ScriptsNextModule Scripts

Last updated