|
|
Internal Messages Language (IML)
do not translate
This chapter is only for advanced users, and only if you want to create/modify patches dynamically.
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 Send Usine Internal Messages module
- use the SendInternalMsg(msg) in Scripting Language or in the sdk.
(Note that the SendInternalMsg script command should not be executed in the context of the audio thread. Use SetFastCallBack(MyIMLTriggeringInputParameter, false); to asynchronously execute the callback function that contains the SendInternalMsg calls in the Usine message processing thread instead of the audio thread. Otherwise IML calls might lead to undefined behaviour (function might or might not be executed, Usine crashes etc.))
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 : Contain 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.
LIST_CAPTIONS_OUT list of used Out captions.
LIST_CAPTIONS_IN list of used In captions.
LIST_CAPTIONS_ALL_OUT list of all Out captions.
LIST_CAPTIONS_ALL_IN list of all In captions.
LIST_CAPTIONS_ALL_AUX list of all aux captions.
LIST_CAPTIONS_MIDI_OUT list of all Midi Out captions.
LIST_CAPTIONS_TRACK list of all used Track caption.
LIST_CAPTIONS_ALL_TRACK list of all Track captions.
LIST_CAPTIONS_ALL_MASTER list of all Master track captions.
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 none=0,in=1,out=2
SRC_TERM_FLOW_TYPE None=0, Audio=1 InternText=2 Data=3 MIDI=4 Array=5 User=6 EvtText=7 Pointer=8 Intern=9 Other=maxInt
SRC_TERM_DISPLAY_FLOW_TYPE Text=0 gainFader=1 Directory=2 Switch=3 Button=4 IntegerFader=5 FloatFader=6 SelectColorFader=7 ListBox=8 Array=9 IPAddress=10 Smpte=11 FileName=12 MidiNote=13
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
SRC_TERM_NAME name of the selected terminal
SRC_TERM_NUM num (order) of the selected 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)
Procedures
Names between brackets [] are optional
SET_VAR name value
Set a variable value
SET_VAR pi 3.14 SET_VAR HelloString 'Hello guys'
CREATE_MODULE modulename id x y [filename]
Create 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-patches modules (id=6) you must specify the filename of the sub-patch.
CREATE_MODULE vol 4 100 100 // creates an audio volume module CREATE_MODULE gate 6 100 100 'c:UsineGate.pat' // add the Gate.pat sub-patch CREATE_MODULE matrix 95 100 100 'Matrix.usr' // create the Matrix.usr User module
CREATE_PLUGIN modulename x y [plug_filename] Usine V6 only Create a new plugin module (for example VST) at the position x y in the patch.
CREATE_PLUGIN myplug 100 100 'C:Program filesSteinbergVstpluginsReaktor.dll'
RENAME_MODULE oldmodulename [newmodulename]
Change the name of the module. If the newmodule name parameter is missing, the module name is set to nothing (blank).
DELETE_MODULE modulename
Deletes the modulename module.
SET_TARGET_PATCH patch
Define the target patch which will receive Internal Messages
SET_TARGET_PATCH SENDER_PATCH // the active patch is the current patch
SET_TARGET_PATCH track line Set the patch on track number and line of the grid as the target
SET_TARGET_PATCH 1 2 // activate the patch on track 1 and line 2
SET_TARGET_PATCH subpatchname
Defines the target subpatch that will receive Internal Messages.
SET_TARGET_PATCH SENDER_PATCH // the active patch is the current patch CREATE_MODULE wd1 6 MOUSE_X MOUSE_Y 'wave+pitch+gain.pat' SET_TARGET_PATCH wd1
SET_VALUE modulename terminalname value
Set 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_COMMATEXT modulename terminalname commatext
Set the values of a listbox items. A comma text is a list of possible values separated by commas.
SET_COMMATEXT Listbox1 list “delay, flanger, filter”
GET_COMMATEXT modulename terminalname destvariable
Get 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
Retrieve the value of a terminal and store it in a destvariable variable.
GET_INDEX modulename terminalname destvariable
Retrieve the index of a terminal and store it in a destvariable variable.
GET_CAPTION modulename terminalnum destvariable
Retrieve the caption of a terminal and store it in a destvariable variable.
GET_STRING_VALUE modulename terminalname destvariable
Retrieve 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
Add 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 SRC_TERM_NUM 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
Delete a link (wire)
DELETE_LINK Step1 out Delay1 delay
AS above the DELETE_LINK command can also be used with Terminal order number instead of terminal names.
CLEAR_PATCH
Clear the target patch. No prompt is made.
STORE_FOR_UNDO
Store 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 no undo is possible…
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
Load a new patch in the target patch. Be careful, no prompt for save is done…
SAVE_PATCH filename
Save the target patch as a new name
RELOAD_PATCH
Reload the current Target patch.
RENAME_PATCH newfilename
Rename the target patch without saving it.
ADD_GROUP filename X Y
Open 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' FADER_VALUE 50 SET_VALUE FA1 fader FADER_VALUE
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. The last parameter is optional.
Generally used with the following variables:
- BUSES_LIST_DATA
- BUSES_LIST_AUDIO
- BUSES_LIST_MIDI
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_TERM_NUM 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 LOAD_PATCH operation.
PROMPT_FOR_SAVE CLEAR_PATCH
LOAD_WORKSPACE filename
Load a new workspace. Be careful, no prompt is done…
EXECUTE_SCRIPT scriptfilename Compile and execute once a script
SET_TARGET_PATCH SENDER_PATCH EXECUTE_SCRIPT 'create-patch.script'
CREATE_USER_CURVE name Create a user curve module from SRC_MODULE and SRC_TERM_NUM in the TARGET_PATCH.
SET_CTRL_POS modulename left top autosize(optional) Set the position , in the control panel or IB, of the associated control of the module.
Provides an automatic control panel resizing by default. Set autosize to false to disable the control panel resizing.
SET_CTRL_POS BUTTON1 100 100 // the control panel is resized SET_CTRL_POS BUTTON1 100 100 false // the control panel is not resized
SET_CTRL_POS_PC modulename left(%) top(%) Set the position , in the control panel or IB, of the associated control of the module with left and top defined in percent ([0..1]) of the parent panel size.
No automatic control panel resizing is done. SET_CTRL_POS_PC BUTTON1 0.2 0.56
SET_CTRL_SIZE modulename width height autosize(optional) Set the size of the associated control of the module.
Provides an automatic control panel resizing by default. Set autosize to false to disable the control panel resizing.
SET_CTRL_SIZE BUTTON1 100 20 // the control panel is resized SET_CTRL_SIZE BUTTON1 100 20 false // the control panel is not resized
SET_CTRL_SIZE_PC modulename width(%) height(%) Set the size of the associated control of the module with values in percent ([0..1]) of the parent panel size.
No automatic control panel resizing is done.
SET_CTRL_SIZE BUTTON1 0.1 0.1
SET_LAYOUT modulename layoutFieldName value Set the LayoutFieldName value of the modulename
This function is CPU hungry if you use it in a script.
SET_LAYOUT TheFader "border width" 12
CREATE_UID variable Creates an Unique Identifier (UID) and store it in variable
PAUSE Pause and process queued Usine messages
SELECT_MODULE modulename Selects the modulename module.
Modules ID’s
Here is the list of modules ID’s used in the CREATE_MODULE message.
Fader = 3 AudioOut= 2 AudioIn = 1 Volume = 4 MidiIn = 5 subPatch= 6 Vst = 7 Button = 8 Switch = 9 Trace = 10 Sin = 11 Cos = 12 LN = 13 LOG = 14 EXP = 15 1 / X = 16 SQRT = 17 ABS = 18 -X = 19 DataIn = 20 DataOut = 21 MIDIOut = 22 Round = 23 Trunc = 24 Var = 25 ArcSin = 26 ArcCos = 27 Pi = 28 Const = 29 TimeMs = 30 TimeSec = 31 Random = 32 NumActiveTrack = 33 Keyboard = 34 A+B = 35 A-B = 36 A/B = 37 A*B = 38 A div B = 39 A mod B = 40 > = 41 < = 42 >= = 43 <= = 44 <> = 45 Min = 46 Max = 47 Power = 48 Equal = 49 And = 50 Or = 51 Xor = 52 Not = 53 DelayAudio = 54 EnvFollower = 55 Samplerx2 = 56 RandomDATA = 57 PeakFollower = 58 Presetx8 = 60 Step = 61 Separator = 62 Granular = 65 Delta = 66 Selector = 67 ComboBox = 68 Panner4 = 69 SmoothData = 70 Wait1 = 71 XY Pad = 72 A*X+B = 73 Mouse = 74 StopEvent = 75 FreezeEvent = 76 MidiFilter = 77 CreateMidi = 78 Text = 79 MidiTransformer = 80 VuMeter = 81 AdditionalIn = 82 RangeFader = 83 Lfo = 84 CrossFadeMono = 85 NoteToFreq = 86 FreqToNote = 87 CurrentTrackNum = 88 EmptyModule = 89 OnInitialization = 90 CookFilter = 91 ArrayDisplay= 92 FFT = 93 FFTInv = 94 User = 95 WaveDisplay = 96 CoeffTodb = 97 dbToCoeff = 98 SeqSwitch = 99 StepMidi = 100 RandomMidi = 101 SeqLines = 102 OnActivation = 103 CheckBoxLed = 104 HasChanged = 106 ZeroCrossing = 107 Oscilloscope = 108 IPLocalAddress = 109 MixerDown = 110 MixerUp = 111 SetGlobVar = 113 GetGlobVar = 114 AdditionalOut= 115 UserCurve = 116 MasterSection= 117 SetMidiBus = 118 GetMidiBus = 119 VolumeMono = 120 LoadWkp = 121 LoadPatch = 122 Script (old) = 123 // do not use, prefer Fast_Script SelectGrid = 124 SysExEditor = 125 Dispatch = 126 OSCReceive32 = 127 OSCSend1 = 128 OSCSend2 = 129 OSCSend8 = 130 OSCSend4 = 131 MaxArray = 132 MinArray = 133 GrainSampler = 134 OSCSend16 = 135 QueueData = 136 SortArray = 137 SwapArray = 138 ArrayElementValueGet= 139 ArrayElementValueSet= 140 SumArray = 141 MeanArray = 142 StdDevArray = 143 BlocSize = 144 SampleRate = 145 PowerScale = 146 ExpScale = 147 MultipleVar = 148 ArraySize = 149 MapperCurve = 150 MapperData = 151 ArrayEditor = 152 DashBoard = 153 PianoRoll = 154 ConcatArray = 155 OnlyIfHasChanged = 156 PassEventFlow = 157 OSCReceive1 = 158 OSCReceive2 = 159 OSCReceive4 = 160 OSCReceive8 = 161 OSCReceive16 = 162 OSCSend32 = 163 TextField = 164 ConcatStrings = 165 InArray = 166 OutArray = 167 OSCSendTxt = 168 PatchActiveOnOff = 169 OSCSendOnlyTxt = 170 VuMeterVert = 171 FaderVert = 172 Sequencer = 173 Image = 174 Knob = 175 PreciseTimeMs = 176 ListBox = 177 Conductor = 178 SynchroLite = 179 LocalSynchro = 180 GetSMPTEpos = 181 SoftClip = 182 Markers = 183 VstLite = 184 Sampler1 = 187 Sampler4 = 188 Sampler8 = 189 Sampler16 = 190 GrainSampler1 = 191 JoyStick = 193 Shell = 194 WavePlayer1 = 195 WavePlayer2 = 196 WavePlayer4 = 197 WavePlayer8 = 198 Ramp old version = 200 LP24db = 201 GrainSampler4 = 202 GrainSampler8 = 203 GrainSampler16 = 204 WavePlayer16 = 205 SeqMidiPlayer = 206 ShiftArray = 207 InterfaceBuilder = 208 WhatTimeIsIt = 209 MaxArrayPos = 210 VideoPlayer = 211 ListBoxBtn = 212 WaveShaper = 213 Crusher = 214 Phaser = 215 From0To1 = 219 From1To0 = 220 Toggle = 221 FaderMidiNote = 222 ColorSelector = 223 MinArrayPos = 224 PolarToCart = 225 CartToPolar = 226 ArrayMinMaxRange = 227 ArrayGate = 228 SetArraySize = 229 ExpandArray = 230 FillArray = 231 SetSMPTEpos = 232 CurPatchInfo = 233 IntToStr = 234 DataMixer = 235 AudioMixer = 236 Wiimote = 237 PointCurve = 238 DblClickPatch = 239 FillRampArray = 240 ADSR = 241 Preset16 = 242 Device = 243 DrawObject = 244 ConcatArray3 = 245 ExtractArray = 246 ConcatArray4 = 247 UsineMsg = 248 OSCReceiveBytes = 249 Current_Patch_Name = 250 Get_Buses_List = 251 output_Usine_MIDI = 252 Quadratic_Distance_2D = 253 Battery_Level = 254 Comment = 257 Sampler = 258 (Query) Grain_Sampler = 259 (Query) Array_display = 260 (Query) Volume_audio = 261 (Query) XY = 262 (Query) DrawPanel = 263 (Query) Popup = 264 Selector = 265 (Query) Dispatch = 266 (Query) Audio_Mixer = 267 (Query) Data_Mixer = 268 (Query) Step = 269 (Query) Lines = 270 (Query) Points_Curve = 271 (Query) Sequenced_Switch = 272 (Query) Fast_Script = 273 Step_Midi = 274 (Query) PianoRoll = 275 (Query) Preset = 276 (Query) OSC_Send = 277 (Query) OSCReceive = 278 (Query) Float_To_String = 279 Sequencer_Wave_Player = 280 Send_Mouse_Msg = 282 Video_Detect = 283 Get_From_Audio_bus = 284 Send_to_Audio_bus = 285 Video_Detect_DX = 286 Current_Line_Num = 287 Active_Line_Num = 288 FaderColor = 289 1-X = 290 X+1 = 291 OpenGLPanel = 292 Current_Voice_Num = 293 SubPatch_Polyphony = 294 Mapper_Data = 295 (Query) Midi_Voice_Dispatcher = 296 Draw Panel New = 297 X-1 = 298 Bloc_Duration = 299 DBAP_2D = 300 ArcTan = 301 Open Dialog = 302 Formant Filter = 303 Ramp = 304 Cross_Fade = 305 GetURLFile = 306 PutURLFile = 307 Setup = 308 WebBrowser = 309 Sign = 310 Always_Calculated = 311 Selector_string = 312 Additional_Audio_Input= 313 Thru = 314 Osc Lister = 315