Templates Engine

Note: This chapter is only for advanced users, and only if you want to Note: create/modify patches dynamically. Note: Note: You can create and add personal templates in the /Config/Templates/ folder.

Note: Before creating any template you have to activate the god mode the setup-panel-tab-expert.

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

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 :

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

[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

• in: the template concerns inlets of a module.
• out: the template concerns outlets of a module.
• * **: the template concerns as well as inlets or outlets of a module.

FLOWTYPE

Type of flow concerned by the template.

• NONE: not used.
• ALL_DATA: DATA_FLOAT or GAIN or MIDINOTE or INTEGER or Timecode
• ALL_DATA_DISCRETE: SWITCH or TRIGGER
• DATA_FLOAT: float data flow
• AUDIO: audio flow
• GAIN: gain flow
• SWITCH: switch flow
• TRIGGER: trigger flow
• MIDINOTE: MIDI note fader
• TIMECODE: timecode flow
• INTEGER: integer flow
• LISTBOX: listbox flow
• ALL_TEXT: TEXT or FILENAME or DIR or PASSWORD
• TEXT: general text flow
• FILENAME: text filename flow
• DIRECTORY: directory name flow
• PASSWORD: password flow
• ALL_CARDINAL: HEXA or BITWISE or COLOR or IPADDR
• HEXA: hexadecimal flow
• BITWISE: bitwise flow
• COLOR: color flow
• IPADDR: IP address
• MIDI: MIDI flow
• POINTER: pointer flow
• BITMAP: bitmap or video flow
• ARRAY: array flow
• SYSEX: MIDI sysex flow
• MIDI2: MIDI 2.0 flow
• GENERIC: general purpose flow
• ALL_NUMBER: any flow containing numbers
• ALL: any flow

ON-WIRE

• true
• false

Determines if the template concerns a [Right-Click] on a wire.

[TEMPLATE]
VERSION=1
NAME=Pass if Changed
FLOWTYPE=ALL_DATA ALL_DATA_DISCRETE 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

• true
  • false

Determines if the template concerns a [Right-Click] on an empty zone of the patch.

[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.

FILENAME-EXTENSION

Extension of the dropped file, ie. PAT, WAV, AIF, MOV, etc

[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

TARGET_PATCH

Contains the patch designed as the target patch, in other word it's the patch that executes the commands.

SENDER_PATCH

Contains the patch which actually sending the messages. This variable is automatically set by Usine.

MOUSE_X

Contains the current X coordinate of the mouse. This variable is automatically set by Usine.

MOUSE_Y

Contains the current Y coordinate of the mouse. This variable is automatically set by Usine.

SHIFT_PRESSED

Its value is 1 if the user is pressing the [shift] key, 0 otherwise.

CONTROL_PRESSED

Its value is 1 if the user is pressing the [control] key, 0 otherwise.

ALT_PRESSED

Its value is 1 if the user is pressing the [Alt] key, 0 otherwise.

lAST_CREATED_MODULE_NAME

Contains the name of the last created module by the command CREATE_MODULE. This variable is automatically set by Usine.

ON_WIRE

Its value is 1 if the user has dropped a file on a wire.

BUSES_LIST_DATA

Contains the list of all available DATA buses for the current patch.

BUSES_LIST_AUDIO

Contains the list of all available AUDIO buses for the current patch.

BUSES_LIST_MIDI

Contains the list of all available MIDI buses for the current patch.

templates variables

The following variables are automatically set by Usine when the user try to create a new wire in a patch. They are used in the Templates Engine.

SRC_TERM_IN_OUT

TARG_TERM_IN_OUT

• none=0,
• in=1,
• out=2

SRC_TERM_FLOW_TYPE

TARG_TERM_FLOW_TYPE

SRC_SCALE

• Linear=0,
• Log=1,
• Exp=2,
• Other=maxint

SRC_MIN

min value of the selected terminal

SRC_MAX

max value of the selected terminal

TARG_MIN

min value of the target terminal

TARG_MAX

max value of the target terminal

SRC_TERM_NAME

name of the selected terminal

SRC_TERM_NUM

num (order) of the selected terminal

TARG_TERM_NUM

num (order) of the target terminal

SRC_SYMBOL

symbol string of the selected terminal

SRC_FORMAT

format string of the selected terminal

SRC_MODULE

selected module

SRC_MODULE_ID

selected module ID

DROP_FILENAME

full name of the dropped file

DROP_SHORT_FILENAME

short name of the dropped file

DROP_FILEEXT

extension of the dropped file

SRC_COMMATEXT

string which contains all the items of the list box separated by commas

SRC_NB_COMMATEXT_ITEMS

number of items in the list box

SRC_VALUE

value of the terminal

SRC_DEFAULT_VALUE

default value of the terminal

SRC_PRECISION_INDEX

number of digits displayed of the terminal

SRC_VALUE_STRING

value as a string format (for text terminals)

TARG_QUERY_INDEX

query index of the target. Determines for example, if a module is mono, stereo, etc.

Procedures

Names between brackets [] are optional

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

SET_VAR name value [value2]

Sets a variable value

SET_VAR pi 3.14
SET_VAR HelloString 'Hello guys'

for strings optional value2 is concatenated

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

CREATE_MODULE modulename id x y [filename] [queryindex]

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

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

For sub-patch (modules id=6) you must specify the filename of the sub-patch.

For user modules (id=95) you must specify the user module filename.

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

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

CREATE_PLUGIN modulename x y 'plugfilename'

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

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

Note: 'plugfilename' must be a valid file name, located in the /Config/Plug-ins/ folder inside Note: the Usine's package.

RENAME_MODULE oldmodulename [newmodulename]

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

RECREATE_MODULE modulename

Recreates the modulename module.

SELETE_MODULE modulename

Deletes the modulename module.

SET_TARGET_PATCH patch

Defines the target patch which will receive Internal Messages

SET_TARGET_PATCH SENDER_PATCH  the active patch is the current patch

SET_TARGET_PATCH sub-patch-name

Defines the target sub-patch that will receive Internal Messages.

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

SET_TARGET_PATCH racknum patchnum

Set a patch with patchnum index in the racknum rack as the target

SET_TARGET_PATCH 2 1  

SET_VALUE modulename terminalname value

Sets the terminalname value of the modulename module

CREATE_MODULE MyMIDICreate 78 100 100  //create a Create MIDI note module
SET_VALUE MyMIDICreate create 1  //set the ‘create' inlet of the ‘MyMIDICreate' module value to 1
...
CREATE_MODULE MyDelay 54 100 100  //create a Delay module
SET_VALUE MyDelay delay 100  //set the delay inlet of the ‘MyDelay' module value to 100ms

SET_STRING_VALUE modulename terminalname stringvalue

Same as the SET_VALUE above but for strings values. SET_STRING_VALUE fader1 Caption “I love you"

SET_STRING_VALUE modulename terminalname stringvalue

SET_COMMATEXT modulename terminalname commatext

Sets the values of a listbox items. The comma-text is a list of possible values separated by commas.

SET_COMMATEXT Listbox1 list “delay, flanger, filter"

GET_COMMATEXT modulename terminalname destvariable

Gets the values of a listbox items and store it in destvariable. A comma-text is a list of possible values separated by commas.

GET_COMMATEXT Listbox1 list value

GET_VALUE modulename terminalname destvariable

Retrieves the value of a terminal and store it in a destvariable variable.

GET_INDEX modulename terminalname destvariable

Retrieves the index of a terminal and store it in a destvariable variable.

GET_CAPTION modulename terminalnum destvariable

Retrieves the caption of a terminal and store it in a destvariable variable.

GET_STRING_VALUE modulename terminalname destvariable

Retrieves the value of a string terminal and store it in a destvariable variable.

cREATE_LINK moduleSrcOut terminalSrcOut moduleDestIn terminalDestIn

CREATE_LINK moduleSrcOut termSrcOutNum moduleDestIn termDestOuNum

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

CREATE_LINK Step1 out Delay1 delay

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

CREATE_LINK in1 in SRC_MODULE SRC_TERM_NUM

DELETE_LINK moduleSrcOut terminalSrcOut moduleDestIn terminalDestIn

Deletes a link (wire)

DELETE_LINK Step1 out Delay1 delay

Az above the DELETE_LINK command can also be used with Terminal order number instead of terminal names.

CLEAR_PATCH

Clears the target patch. No prompt is made.

STORE_FOR_UNDO

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

For example, if you send the single command

CLEAR_PATCH

Then undo is impossible...

Now, if you send

STORE_FOR_UNDO
CLEAR_PATCH

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

LOAD_PATCH filename

Loads a new patch in the target patch. Be careful, no prompt for save is done…

SAVE_PATCH filename

Saves the target patch as a new name

RELOAD_PATCH

Reloads the current Target patch.

RENAME_PATCH newfilename

Renames the target patch without saving it.

LOAD_RACK filename

Loads a new rack in the current workspace. Be careful, no prompt for save is done…

ADD_GROUP filename X Y

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

INPUT_QUERY_VALUE textToDisplay VarName DefaultValue

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

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

INPUT_QUERY_STRING textToDisplay VarName DefaultValue

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

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 WindowTitle Question List ResultStringVariableName ResultIndexVariableName(optional)

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

Note: The last parameter is optional.

Generally used with the following variables:

• BUSES_LIST_DATA
• BUSES_LIST_AUDIO
• BUSES_LIST_MIDI

For 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.

PROMPT_FOR_SAVE
CLEAR_PATCH

LOAD_WORKSPACE filename

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

SAVE_WORKSPACE filename

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

CREATE_UID variable

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

PAUSE

Pauses and process queued Usine messages.

SELECT_MODULE modulename

Selects the modulename module.

END_TEMPLATE

Optional template finalization.

Note: Must be used if you IML commands in scripts with a sub-patch as target

SET_SETTING modulename settingname value

SET_SETTING myOscilloscope "border width" 3

Modules ID's

Here is the list of modules ID's used in the CREATE_MODULE message.

See also

• Templates Panel
• Templates Engine