Usine Objects

The scripting engine V2 gives the possibility to get or set any Usine Object values of the workspace or the current patch. The idea is to be able to replace wires inside patches.

To use Usine-Object it is recommended to activate the god mode in the setup-panel-tab-expert.


Get object values

function GetObject ( name:string ):variant;                             // for float, integer, string (slower)
function GetObjectFloat ( name:string ):float;                          // for float (faster)
function GetObjectInteger ( name:string ):integer;                      // for integer (faster)
function GetObjectArray ( name:string; index:integer ):float;           // for arrays
function GetObjectMIDI ( name:string; index:integer ):TMIDI;            // for MIDI
function GetObjectColor ( name:string ):TAlphaColor;                    // for one color value
function GetObjectArrayColor ( name:string; index:integer ):TAlphaColor // for array of colors

Set object values

procedure SetObject ( name:string; v:variant );                              // for float, integer, string (slower)
procedure SetObjectFloat ( name:string; v:float ) ;                          // for float (faster)
procedure SetObjectInteger ( name:string; v:integer ) ;                      // for integer (faster)
procedure SetObjectArray ( name:string; index:integer; v:float );            // for arrays
procedure SetObjectMIDI ( name:string; index:integer; midi:TMIDI );          // for MIDI
procedure SetObjectColor ( name:string; c:TAlphaColor );                     // for one color value
procedure SetObjectArrayColor ( name:string; index:integer; c:TAlphaColor ); // for array of colors

Object Flow Length

function GetObjectLength ( name:string ):integer;                       // get the length of the object for array, MIDI
procedure SetObjectLength ( name:string; length:integer );              // set the length of the object for array, MIDI 

Object various

function ObjectExists ( name:string ):boolean;        // returns TRUE if an object exists in the current workspace
function FindObject ( name:string ):string;           // returns a commaText containing all the objects names that match with the name
function GetObjectListHash :string;                   // returns a hash string of the usine objects, see bellow

findObject('x-1') returns the list (as a commaText) of all object containing the string x-1 inside the current workspace.

FindObject procedure can be very slow to process, see bellow for a solution.

Buses values

Set or get values for data or array buses.

function GetBusFloat ( busname:string ):float;                    // gets the bus float value
function GetBusArray ( busname:string; index:integer ):float;     // gets the bus array value at the index

procedure SetBusFloat ( busname:string; v:float );                // sets the bus float value
procedure SetBusArray ( busname:string; index:integer; v:float ); // sets the bus array value at the index


Each object in Usine has an internal script name, generally made of the concatenation of its captions. For example the master-synchro tempo is identified by the internal name usine.master-synchro.tempo.

Then inside the script you can use the SetObject of GetObject functions to respectively set or get the value of the object.

Example : Random Tempo

// Random Tempo 
procedure Process;
var tempo : float;
  tempo := 30+100*random;  

Example : Trace the Tempo

// trace the tempo
procedure Process;

The list of all available global Usine-Objects is available in the third tab of the script-editor.

Accessing to controls inside a patch

We can access to controls (faders, switches, buttons, listboxes) inside a patch very simply. For example, in the following patch:

You can take a look on the second Tab of the script-editor to retrieve the names of available objects:

In our case the names are patch.fader-1 and patch.fader-2. The prefix is patch. followed by the caption of the control.

If two objects have the same name (or caption), the second object is ignored and can't be accessible.

Example : link 2 faders

// Link 2 controls
var v : float;
    v := getObject('patch.fader-1');

Accessing to any modules inside a patch

Let's take an example with a LFO module in a patch.

To have a direct access to modules settings inside a script, the first thing is to set a user-name for the module by [Alt+Click]. In this example we choose MYLFO.

give a name to the module

Now, inside the script-editor you can get the list of available objects in the script. As you can see the script engine can access to almost all parameters of the module without any wire.

Example : get the value of the LFO

//Link a LFO out to a Fader
var v : float;
    v := getObject('patch.mylfo.out');

Accessing to objects inside a sub-patch

Controls inside sub-patches are accessible with the name of the sub-patch followed by the voice number. control

For example in the following patch:

You can check the list of available controls:

You can see that the name of the knob-1 is patch.mysubpatch.1.knob-1

//Link a fader to a sub-patch knob
var v : float;
    v := getObject('patch.fader-1');

Array objects

You can manipulate Array objects with the functions:

  • GetObjectArray
  • SetObjectArray
  • GetObjectLength
  • SetObjectLength

Example : copy an array to another array

In the simple following patch we want to copy the output of ARRAY1 to the input of ARRAY2.

var v : float; 
var size,i : integer; 
    size := getObjectLength('patch.array1.output');
    for i := 0 to size-1
    do begin    
       v := getObjectArray('patch.array1.output',i);

MIDI objects

You can manipulate MIDI objects with the functions:

  • GetObjectMIDI
  • SetObjectMIDI
  • GetObjectLength
  • SetObjectLength

Example : copy an array to another array

In the simple following patch we want to copy the output of RANDOMMIDI to the input of SAMPLER.

var M : TMIDI;            
var size,i : integer; 
    size := getObjectLength('patch.randommidi.midi-out');     
    for i := 0 to size-1
    do begin    
       M := getObjectMIDI('patch.randommidi.midi-out',i);

Color objects

In the simple following patch we want to copy the output color array of RANDOMCOLOR to the input colors of XYDRAW.

var i : integer;
var col : TalphaColor;      
  for i := 0 to  31 
  do begin
    col :=  GetObjectArrayColor('patch.randomcolor.color-array',i);  

Access to everything

Inside a script you can access to any object anywhere in the workspace not only in the current patch. You have to remember that objects are identified by their captions. So if we have the rack 'myrack' which contains the patch 'mypatch' which contains 'fader 1' and 'fader 2'.

The global objects gives you the names of the Usine Objects to access to 'fader-1' or 'fader 2' anywhere in Usine.

The global names are:

  • usine.workspace.myrack.mypatch.fader-1
  • usine.workspace.myrack.mypatch.fader-2

If two objects (rack, patch, control, module) have the same name, the second object is ignored and can't be accessible.

FindObject is slow

The FindObject procedure is very slow and it's not necessary to execute it all the time, but only when something has changed in the workspace. For that you can use GetObjectsListHash which returns the hash string of the UsineObjects list. If the something has changed in Usine (rack,patch,modules,etc..) the hash string will be different.

In other words, you can execute a part of a script only if the workspace has changed.

var FLastHash : string;
if GetObjectsListHash<> FLastHash
then begin     
      FLastHash := GetObjectsListHash;
      s := findObject('myobjectname.out');

See also

version 5.2.221206

Edit All Pages