OSC Table |
|
OSC Table |
|
OSC Table |
|
OSC Table |
|
Loading...
The OSC Table is a specialized Scripting object, that is to be used in combination with the OSC TCP or OSC UDP device. It facilitates receiving and sending messages as meaningful names can be assigned to OSC addresses, such as "volume_left" instead of "/3/fader2".
The table stores your OSC adresses and make them accessible by an alias name. Next to the OSC address (e.g. "/1/fader1") the number and type of associated arguments are saved (e.g. one string value). In other words, once the OSC addresses and value types are setup, one does not need to refer to the device manual ever after.
Optionally, you can add scripts that are triggered when a valid message is received. In contrast to the Event Listener, which would be triggered with any message, here you can setup various scripts for specific OSC addresses.
To add a OSC Table, open the Devices menu and select OSC > Table > Create Table. This will open the Configuration dialog. Alternatively, you can add a new table in the Configuration dialog with the "+" button when the dialog is already open.
On the right side, you see several options:
The Type informs you about the type of device or connection.
The Groups lists the groups to which this device belongs.
The Name is the unique identifier for this OSC Table object in WD. It is best practice to use a descriptive name such as "Audio desk" to group all related OSC messages within this table. The general rules for naming objects apply here as well: only letters, numbers and underscores are allowed; the first symbol must be a letter. It is possible to change the default name to a more descriptive one. When scripting, enter this Name to access available members or use the Project object and device Type instead; examples are shown further down.
The Id offers an alternative way to address the object when scripting.
The "Enable" check box is ticked per default. On the left side, you should see that the icon in front of your OSC Table is a filled blue circle, which means that the table is enabled. A filled gray circle indicates a disabled table.
You can close the dialog at any time. The newly created table will also be added to the Devices menu > OSC > Table and can be opened from here or with Devices menu > Configuration.
Click on the button "Add New Alias".
Choose how to name the Alias; it needs to be unique within this OSC Table. The name will be used in scripts or nodes.
The X button can be clicked to remove the Alias from the table again.
Define the OSC Address, e.g. /1/fader1 or /?/fader?
Widget Designer supports "OSC Message Dispatching and Pattern Matching" as defined by the OSC protocol. The only exception is that the '!' character cannot be used for negation.
The '?' wildcard, for example, matches any single character and '*' matches any sequence of zero or more characters. For instance:
address "/fader?" matches fader0, fader9, faderZ, ...
address "/fader*" matches fader, fader999, faderAnything, ...
address "/{fader,rotary}1 matches fader1 or rotary1
Next, the parameters are described. Per default, each Alias starts with one parameter; more can be added with the "+ Type" button. OSC addresses can also be sent or received without further values, e.g. "/PlaybackDevice/Pause". They act as a trigger and do not carry more data. The small X button to the right of each parameter entry deletes it again.
Add the number of expected / requested parameters and select their type with the drop-down list. This is important if you would like to send values. For incoming messages, see the scripting field / value description further down.
"Int32" like the "integer" type in Widget Designer,
"Float32" accords to the "double" type,
"String" accords to the "string" type and
"Blob" is a byte array.
The text field to the right shows a default name for the parameter based on the data type, such as "Float 1". This name is also displayed in the OSC input and output nodes.
It is good practice to change the name to a more descriptive one. This gives you (and others) a good overview and understanding of the arguments and helps reducing errors. Once an Alias is set up nicely in the OSC Table, one does not need to refer to the device manual ever after to understand the list of arguments.
The Execute on receive option de-/activates whether the script is triggered upon receiving a message from the defined address.
Enter commands into the scripting field, if you would like to trigger them when a message from the specified address is received. The following Parameters can be used as local variables:
deviceName, tableName and address refer to your settings in Widget Designer and return a string with the name of the OSC TCP / UDP device that is connected to the sender, the name of the triggered OSC Table and lastly the Address.
For example, the command DebugMessage(deviceName,tableName,address,value) would return:
["OSC_TCP1","OSC_Table1","/1/fader1",[0.12573671340942383]]
value returns a list of all arguments / parameters. You can access individual list values by using their index which starts with 0. To assign the first argument to another Widget or variable etc., use "value[0]":
Fader1.Value = value[0]
Each argument has the "object" data type which means it is (yet) neither a number nor string for Widget Designer. When assigning it to a Fader or Label, Widget Designer tries to convert it to the correct type automatically. So in fact, in most cases, you do not need to worry about the data type. If you would like to convert it manually, use the according object member, e.g. "ToDouble". The following script assigns the first argument of the list to a local variable called "first" and defines the double data type. Then, it is assigned to a Label. "Round" is a member available for doubles; in the example the double is rounded to 2 digits.
var first = value[0].ToDouble
Label1.Text = first.Round(2)
Press Apply to confirm your settings.
After adding an OSC Table, it can also be scripted which allows to perform actions on the Table object as well as retrieve information from it.
First create a CustomScript button or use anything else with a scripting field. Enter the table's identifier name into the script field (per default that is e.g. "OSC_Table1") and Script Assist will offer a list of all available OSC Table members.
You can for example send OSC messages as follows. "Alias" refers to the Alias name under which you saved the OSC Address and parameter types, "OSC_TCP1" refers to the device that is connected to the receiver and "0.5" is the value:
OSC_Table1.Send("Alias","OSC_TCP1",0.5)
A complete list of all stored addresses can be retrieved with the GetAliasNames member, for example to be displayed in a DropDownList:
var list = OSC_Table1.GetAliasNames
DropDownList1.SetItemsFromArray("list")
As an alternative to explicitly naming the device, the "Project" object can be used. Choose the device type and address the device by entering its ID or name. Script Assist then offers you the same list of members. This is the alternative for the first example from above:
Project.OSC_Table(1).Send("Alias","OSC_TCP1",0.5)
Substituting the ID with a dynamic variable allows automation. Actions can be performed on many connections of the same type simultaneously, e.g. by using for-loops:
For i = 1 to 10 {
Project.OSC_Table(i).Send("Alias","OSC_TCP1",0.5)
}
The chapter "Project and Context Member" shows more examples with for-loops and if-clauses; of course, normal variables can also be used.
The OSC TCP input node (or UDP) shows incoming messages; optionally you can use the OSC Table here instead of entering the OSC address and parameters manually. The OSC TCP output node (or UDP) sends messages out. In difference to the input node, the OSC Table is not only optional but essential.
Please see the chapter "Tutorial: Nodes" for information about the node system.