Templates Engine (IML)

examples

In the Resources/Templates folder, you will find default patch files used in Usine. You can modify, adapt those files to your needs.

Create Templates

Usine includes a powerful Templates Engine. To manipulate and create your own templates you have to understand how work's the internal messages describes below.

To have an idea of how it works, start to open the Usine inspector-console.

Then open a patch and drag&drop a file.

You will see several lines added in the console, something like

Example:

    SET_VAR patch SENDER_PATCH = noname
    SET_VAR integer MOUSE_X = 150
    SET_VAR integer MOUSE_Y = 189
    SET_VAR integer CONTROL_PRESSED = 0
    SET_VAR integer SHIFT_PRESSED = 0
    SET_VAR integer ALT_PRESSED = 0
    SET_VAR integer ON_WIRE = 0
    SET_VAR integer SRC_TERM_IN_OUT = 0
    SET_VAR String DROP_FILENAME = /Applications/Usine.app/Usine Library/Audio FX/Delays/Delay.pat
    SET_VAR String DROP_FILEEXT = pat
    SET_VAR integer SRC_MODULE_ID = 1
    SET_VAR String DROP_SHORT_FILENAME = Delay

If you now try to create a wire on the patch, you will see in the console :

Example:

    SET_VAR integer CONTROL_PRESSED = 0
    SET_VAR integer SHIFT_PRESSED = 0
    SET_VAR integer ALT_PRESSED = 0
    SET_VAR integer MOUSE_X = 233
    SET_VAR integer MOUSE_Y = 432
    SET_VAR patch SENDER_PATCH = /Applications/Usine/Usine Library/Audio FX/Delays/Delay.pat
    SET_VAR integer SRC_TERM_NUM = 1
    SET_VAR integer SRC_MODULE_ID = 9
    SET_VAR integer SRC_TERM_IN_OUT = 2
    SET_VAR module SRC_MODULE =  
    SET_VAR integer ON_WIRE = 0

Those values are interpreted by the template engine to offer several choices to user after a wire creation or what to do with a dropped file.

In the folder Templates you will find lots of examples (files *.txt) that you can easily adapt to you own purpose like

Example:

    [TEMPLATE]
    VERSION=1
    NAME=Horizontal Fader
    IO=in
    FLOWTYPE=ALL_DATA ALL_NUMBER

    [COMMANDS]
    SET_TARGET_PATCH SENDER_PATCH
    CREATE_MODULE fader1 3 MOUSE_X MOUSE_Y 
    CREATE_LINK fader1 1 SRC_MODULE SRC_TERM_NUM
    SET_VALUE fader1 min SRC_MIN
    SET_VALUE fader1 max SRC_MAX
    SET_VALUE fader1 1 SRC_VALUE 
    SET_STRING_VALUE fader1 symbol SRC_SYMBOL
    SET_STRING_VALUE fader1 caption SRC_TERM_NAME
    SET_VALUE fader1 precision  SRC_PRECISION_INDEX
    SET_VALUE fader1 scale SRC_SCALE
    SET_VALUE fader1 'default val' SRC_DEFAULT_VALUE
    RENAME_MODULE fader1

VERSION

Current Template Engine version, should be 1.

NAME

Name of the template which appears in the templates list.

IO

FLOWTYPE

ON_WIRE

Example:

    [TEMPLATE]
    VERSION=1
    NAME=Pass if Changed
    FLOWTYPE=ALL_DATA DATA_SWITCH DATA_TRIGGER ARRAY MIDI ALL_TEXT ALL_CARDINAL ALL_NUMBER GENERIC
    ON-WIRE=true

    [COMMANDS]
    SET_TARGET_PATCH SENDER_PATCH
    CREATE_MODULE m1 156 MOUSE_X MOUSE_Y
    RENAME_MODULE m1

EMPTY_ZONE

Example:

    [TEMPLATE]
    VERSION=1
    NAME=Horizontal Fader
    FLOWTYPE=NONE 
    EMPTY-ZONE=true

    [COMMANDS]
    SET_TARGET_PATCH SENDER_PATCH
    CREATE_MODULE mod123 3 MOUSE_X MOUSE_Y 
    RENAME_MODULE mod123

SOURCE-MODULE-ID

Num ID of the source module when a wire is created.

Example:

    [TEMPLATE]
    VERSION=1
    NAME=Open Patch
    FILENAME-EXTENSION=PAT

    [COMMANDS]
    SET_TARGET_PATCH SENDER_PATCH
    PROMPT_FOR_SAVE
    CLEAR_PATCH
    LOAD_PATCH DROP_FILENAME

Internal Messages Language (IML)

Since the v4.1 Usine provides a powerful internal language to create patch dynamically.

The background idea is very simple: you send messages to the internal messages manager by several ways:

• use the patch-send-internal-message module
• use the SendInternalMsg in scripts
• use the SDK.

Of course, commands can be sent over the network with OSC modules.

global variables

Commands

Names between brackets [] are optional

The name of a module can be changed with [Alt+Click].

SET_VAR variable_name value [value2]

Sets a variable value

Example:

    SET_VAR pi 3.14
    SET_VAR HelloString 'Hello guys'

for strings optional value2 is concatenated

Example:

    SET_VAR newName 'hello' DROP_FILENAME 
    // new name will be the concatenation of 'hello' and the DROPFILENAME variable

CREATE_PATCH rack_index patch_name

Creates a new patch in the rack rack_index and renames it to patch_name.

Example:

    CREATE_PATCH 0 "example"  

CREATE_RACK rack_index [rack_name]

Creates a new rack rack_index and renames it to patch_name.

Example:

    CREATE_PATCH 0 "example"  

CREATE_MODULE user_name calss_id x y [file_name] [query_value_1] [query_value_2]

Creates a new module at the position x y in the patch.

The module type is set by the parameter class_id (see the list of id's bellow). Then the module is renamed with the **user_name.

For sub-patch (class_id=6) you must specify the file-name of the sub-patch.

For user modules (class_id=95) you must specify the user module file_name.

You can also set the query_value_1 and query_value_1, which is the value of the choice order in the query creation box. ie:for audio modules 0=mono, 1=stereo, 2=4 channels, etc.

Example:

    CREATE_MODULE vol 4 100 100  //creates an audio volume stereo module
    CREATE_MODULE vol 261 100 100 24 //creates an audio volume 4 channels module (queryindex=4) 
    CREATE_MODULE gate 6 100 100 'c:UsineGate.pat'  //adds the Gate.pat [sub-patch](/learn-usine/patching/sub-patch)
    CREATE_MODULE matrix 95 100 100 'Matrix.usr'  //creates the Matrix.usr User module 
    CREATE_MODULE reverb 95 100 100 'Reverb.usr' 0  //creates the Reverb.usr User module in Mono version (queryindex = 0) 

CREATE_PLUGIN user_name x y file_name'

Creates a new plugin module (for example VST) at the position x y in the patch.

Example:

    CREATE_PLUGIN myplug 100 100 'ACE(x64).plugin'

RENAME_MODULE old_user_name [new_user_name]

Changes the name of the module. If the new_user_name parameter is omitted, the name is set to nothing (blank).

RECREATE_MODULE user_name

Recreates the user_name module.

DELETE_MODULE user_name

Deletes the user_name module.

SET_TARGET_PATCH [rack_indexber] [patch_number] [predefined] [patch_name]

Defines the target patch which will receive Internal Messages. This message can have different and optional parameters or predefined strings SENDER_PATCH or PARENT_PATCH. The rack_indexber and patch_number start by the index 0 (rack_indexber 0 is the rack 1) Example:

    SET_TARGET_PATCH SENDER_PATCH // the active patch is the current patch
    SET_TARGET_PATCH PARENT_PATCH // the active patch is the parent patch of the current patch
    SET_TARGET_PATCH 0 2 // the 3th patch of the rack 1
    SET_TARGET_PATCH mypatch  // the patch named `mypatch`

Example for a sub-patch:

    SET_TARGET_PATCH 'MY DELAY'  
    CREATE_MODULE wd1 6 MOUSEX MOUSEY 
    SET_TARGET_PATCH wd1

Example:

    SET_TARGET_PATCH 2 1  

SET_VALUE user_name parameter_name value

Sets the parameter_name value of the user_name module

Example:

    CREATE_MODULE MyMIDICreate 78 100 100  // creates a Create MIDI note module
    SET_VALUE MyMIDICreate create 1  // sets the 'create' inlet of the 'MyMIDICreate' module value to 1
    ...
    CREATE_MODULE MyDelay 54 100 100  // creates a Delay module
    SET_VALUE MyDelay delay 100  // sets the delay inlet of the 'MyDelay' module value to 100ms
    SET_VALUE MyFader caption 'hello boys' // sets the caption of a fader  
    SET_VALUR MyFader color $FF123456 // sets the color of a fader     

GET_VALUE user_name parameter_name dest_variable

Retrieves the value of a parameter and store it in a dest_variable variable.

GET_TERMINAL_INDEX user_name parameter_name dest_variable

Retrieves the index of a parameter and store it in a dest_variable variable.

GET_CAPTION user_name parameter_num dest_variable

Retrieves the caption of a parameter and store it in a dest_variable variable.

CREATE_LINK user_name_src_out parameter_name_src_out user_name_dest_in parameter_name_dest_in

CREATE_LINK user_name_src_out parameter_num_src_out user_name_dest_in parameter_num_dest_in

Adds a new link (wire) between two modules. Always from out to in.

Example:

    CREATE_LINK Step1 out Delay1 delay

The CREATE_LINK command can also be used with Terminal order number instead of parameter names. Typically, the SRCTERMNUM gives the order of the target inlet. The following example comes from a template.

Example:

    CREATE_LINK in1 in SRC_MODULE SRC_TERM_NUM

DELETE_LINK user_name_src_out parameter_name_src_out user_name_dest_in parameter_name_dest_in

DELETE_LINK user_name_src_out parameter_num_src_out user_name_dest_in parameter_num_dest_in

Deletes a link (wire)

Example:

    DELETE_LINK Step1 out Delay1 delay

As above the DELETE_LINK command can also be used with Terminal_order_number instead of parameter_names.

CLEAR_PATCH

Clears the target patch. No prompt is made.

CLEAR_WORKSPACE

Clears the workspace patch. No prompt is made.

CLEAR_RACK rack_index

Clears the rack number rack_index. No prompt is made.

STORE_FOR_UNDO

Stores Undo information. So the user will be able to cancel the last operation.

For example, if you send the single command

Example:

    CLEAR_PATCH //Then undo is impossible...

Example:

    STORE_FOR_UNDO
    CLEAR_PATCH  // Then undo is possible...

The user will be able to undo the Clear patch operation.

UNDO_PATCH

Executes an undo on the target patch.

REDO_PATCH

Executes a redo on the target patch.

DELETE_PATCH patch_name

Deletes the the patch named patch_name or the current target patch if patch_name is not specified.

LOAD_PATCH file_name

Loads a new patch in the target patch.

SAVE_PATCH file_name

Saves the target patch as a new name.

RELOAD_PATCH

Reloads the current Target patch.

RENAME_PATCH new_name

Renames the target patch without saving it.

LOAD_RACK file_name

Loads a new rack in the current workspace.

ADD_GROUP file_name X Y

Opens a patch and add new modules to the actual patch (without clear it before).

INPUT_QUERY_VALUE text_to_display dest_var default_value

Ask the user to enter a numerical value and stores the result in dest_var.

Example:

    SET_TARGET_PATCH SENDER_PATCH
    INPUT_QUERY_VALUE 'Enter the fader value' FADERVALUE 50
    SET_VALUE FA1 fader FADERVALUE

INPUT_QUERY_STRING text_to_display dest_var default_value

Ask the user to enter a string and stores the result in VarName.

Example:

    SET_TARGET_PATCH SENDER_PATCH
    INPUT_QUERY_STRING 'Input items, separated by commas' COMMATEXT 'a,b,c,d'
    SET_COMMATEXT LB1 list COMMATEXT

INPUT_QUERY_LIST window_title question list dest_var_string [dest_var_index]

Ask the user to select an item in a List. Stores the selected string result in ResultStringVariableName and the selected item index in ResultIndexVariableName.

Generally used with the following variables:

• BUSES_LIST_DATA
• BUSES_LIST_AUDIO
• BUSES_LIST_MIDI
• BUSES_LIST_TEXT
• BUSES_LIST_VIDEO
• BUSES_LIST_COLOR
• BUSES_LIST_DMX
• QUICKLINKS_LIST

Example:

    SET_TARGET_PATCH SENDER_PATCH
    INPUT_QUERY_LIST 'Get from Audio Bus' 'Select Bus' BUSES_LIST_AUDIO BUSNAME
    CREATE_MODULE data1 284 MOUSE_X MOUSE_Y
    CREATE_LINK data1 'get bus' SRC_MODULE SRC_TERMNUM
    SET_STRING_VALUE data1 name BUSNAME

PROMPT_FOR_SAVE

Ask the user to save the target patch if it has been modified.

Can be used before a CLEAR_PATCH or a LOADPATCH operation.

Example:

    PROMPT_FOR_SAVE
    CLEAR_PATCH

LOAD_WORKSPACE file_name

Loads a new workspace. Be careful, no prompt is done...

SAVE_WORKSPACE file_name

Saves the current workspace as a new name. If no file-name is specified it saves the workspace with its current file name.

SHOW_PANEL panel_name

Shows a specific UI panel in Usine

Example:

    SHOW_PANEL mixer

CREATE_UID variable

Creates an Unique Identifier (UID) and store it in variable

PAUSE

Pauses and process queued Usine messages.

SELECT_MODULE user_name

Selects the user_name module.

END_TEMPLATE

Optional template finalization.

LIST_ALL_VARIABLES

Lists all the internal variables in the console.

Modules ID's

Here is the list of modules ID's used in the CREATE_MODULE IML message and in script CreateModule().

See also

• Templates Panel
• Templates Engine (IML)
• Modules ID