OSC - Version 2.2.1#

Module Summary#

Send and receive Open Sound Control (OSC) messages over UDP.

Module Status#

This IO Module is stable and has been tested internally.

If you encounter any issues with this module, or have any feedback regarding its operation, please contact our support team.

Module Scope#

Note: This module uses OSC versions 1.0 formatting.

Release Notes#

Version 2.2.1#

  •  Adds support for true (T) and false (F) type tags.

  •  Fixes parsing of JSON string type values.

Version 2.2#

  •  Adds support for address pattern matching.

Version 2.1#

  •  Fixed rounding error in received OSC values.

  •  Added new action, Output Using Values with the ability to define fixed values or insert trigger variables.

  •  Added condition, Convert Value, to convert an incoming value in to desired number format format (percentage, 8 bit or 0-1 float).

  •  Added new trigger, Button Input for receiving pressed or released (1 or 0) button values.

  •  Added Trigger Rate instance property to optimise controller performance in a network of high OSC traffic.

  •  Added Extended Logging feature for debugging.

  •  General performance improvements.

Version 2.0#

  •  Initial Version

Minor point releases (eg. 1.1.x) will be for small fixes and may not be listed here.

Operation#

Instance Properties#

Within the Instance Properties, specify the Input and Output Ports for communicating with OSC compatible hardware. If you have different devices set to communicate using different port configurations, use a new Instance for each port configuration.

Trigger Rate determines the frequency of processing incoming messages and firing the Input trigger. Normal is optimised for controller performance and reliability. High will process more messages and fire more triggers in a shorter timeframe but may have a significant impact on performance and potentially overload the controller. Low will process messages slower but may cause jitter when using sliders.

Checking the Extended Logging checkbox will provide more detailed log messages for fired Triggers and Actions as well as responses from the OSC Network. This is intended for problem solving and should be ideally be disabled during normal operation.

Triggers#

Triggers support Address pattern matching, where matches can be literal matches:
  e.g. /myAddress/button1 would match /myAddress/button1

or they could include matching patterns:
  e.g. /myAddress/button* would match /myAddress/button1, /myAddress/button2, /myAddress/button10

  • ‘?’ in the OSC Address Pattern matches any single character

  • ‘*’ in the OSC Address Pattern matches any sequence of zero or more characters

  • A string of characters in square brackets (e.g., “[string]”) in the OSC Address Pattern matches any character in the string. Inside square brackets, the minus sign (-) and exclamation point (!) have special meanings:

    • Two characters separated by a minus sign indicate the range of characters between the given two in ASCII collating sequence. (A minus sign at the end of the string has no special meaning.)

    • An exclamation point at the beginning of a bracketed string negates the sense of the list, meaning that the list matches any character not in the list. (An exclamation point anywhere besides the first character after the open bracket has no special meaning.)

Input#

This Trigger fires when an OSC message, of matching Address, is received by the Controller.

Trigger variables:

  •  Variables 1 to n: Matched address arguments (String). [Optional]

    • Number of address arguments equal to number of input patterns.
      e.g. /myAddress/button* would return 1 address argument
      e.g. /myAddress*/button* would return 2 address arguments

  •  Variables n+1 to …: Message arguments (Variant).

  •  Variable ‘Last’: Peer IP Address (IP Address).

Button Input#

This Trigger fires when an OSC button message, of matching Address, is received by the Controller.
If the button value (1 for pressed or 0 for released) matches the Button State, the trigger will fire and pass the button value as a trigger variable.
If the value is not a valid button value, the trigger will not fire and this will be logged.

  •  Variables 1 to n: Matched address arguments (String). [Optional]

    • Number of address arguments equal to number of input patterns.
      e.g. /myAddress/button* would return 1 address argument
      e.g. /myAddress*/button* would return 2 address arguments

  •  Variables n+1: Button state value (0 or 1) (Integer).

  •  Variables n+2: Button state string (‘released’ or ‘pressed’) (String).

  •  Variable ‘Last’: Peer IP Address (IP Address).

Conditions#

Convert Value#

This Condition allows the conversion of numeric value types to facilitate communication / integration between OSC devices and other systems. The Condition allows the conversion between Float, Percentage, and 8 Bit values for any received trigger variable.

Use the Variable Number to specify the variable to be converted by this Condition.

Use the Conversion Type to specify the desired conversion type for the variable.

It is important to understand that OSC communicates percentages as a decimal Float number between 0 and 1. However, by using this Condition, such a float value can be converted into either an 8 bit number or an integer percentage.

When converting from a 0-1 Float to either an integer percentage, or 8 bit number, values are rounded up to the nearest whole number. In 8 bit, the float is represented as an 8 bit percentage value, so a 0.5 float would be 128 as an 8 bit number because 128/256 = 0.5.

When converting to a 0-1 Float, values are rounded up to the nearest 2 decimal places.

The Conversion Type can be done in any direction between the 3 value types.

Note that when this Condition is used, it does NOT replace the variable, but rather appends the converted value to the end of the Trigger Variables Table. Please see the below example:

Example#

The Convert Value Condition receives a Trigger Variable Table containing a single variable:

  •  Variable 1 = 0.75

By using the Conversion Type: 0-1 Float to Percentage the value for variable 1 is converted from 0.75 to 75 (%).

The Convert Value Condition appends the converted value to the end of the Trigger Variable Table to be passed onto the Action. The Trigger Variable Table now has 2 variables:

  •  Variable 1 = 0.75

  •  Variable 2 = 75

Actions#

The two Actions available are both for outputting OSC messages.

Output Using Variables#

This Action takes all the trigger variables, and adds them to the OSC message being output as arguments.

Use the Hostname to specify the network address (IP or web domain) to which the OSC message will be delivered.

Use the Address to specify the OSC address to which the OSC message’s arguments will be delivered.

Output Using Values#

This Action, compared to Output Using Variables, allows both the use of trigger variables, and user-specified values to be used and passed on as an output OSC message.

Use the Hostname to specify the network address (IP or web domain) to which the OSC message will be delivered.

Use the Address to specify the OSC address to which the OSC message’s arguments will be delivered.

There are two types of Format available: Comma Separated Values and Type Value Pairs, see below for more details as the choice of Format dictates how the Values should be written.

NOTE that Comma Separated Values is more forgiving as it will assume any value that does not fit its expected type is a string value and still send the OSC message; whereas the Type Value Pairs format, being more explicit, will not send if the value does not fit its stated type.

Below is a summary of how values must be written to fit a given value type (for both Formats):

Value Type Syntax
string
  • Value must be surrounded by quotation marks (" ")
  • Examples: "Word", "12 Smith Street"
integer
  • Value is a number
  • Value has no decimal
  • Value is NOT surrounded by quotation marks (" ")
  • Examples: 1, 15000
float
  • Value is a number
  • Value HAS a decimal
  • Value is NOT surrounded by quotation marks (" ")
  • Examples: 0.5, 3.14

variables are specified using a number surrounded by angle brackets <NUM> Examples: <1>, <4>
Comma Separated Values#

The comma separated syntax is a simpler Format that allows the insertion of both user-specified values and variables to the OSC message. The value type for variables are already known when using this Format, so only user-entered values must have their type specified using the above explained syntax.

Values need to be comma separated. Any value that does not fit the abovementioned value type criteria is automatically assumed to be a string. See the following examples:

Value String Interpreted Value Types
1,2.7,"hello",world,"123"
  • 1 : integer
  • 2.7 : float
  • "hello" : string
  • world : string (assumed)
  • "123" : string
1,4.5,<1>,"hello",<3>
  • 1 : integer
  • 4.5 : float
  • <1> : variable 1
  • "hello" : string
  • <3> : variable 3
Type Value Pairs#

This Format uses a JSON type syntax to explicitly define the value type and value, and allows the insertion of both user-specified values and variables to the OSC message.

Each value is described using a type-value pair surrounded by curly brackets, all values are comma separated. The basic structure is as follows: {“type”:”<type>”,”value”:<value>}, where ”<type>” can either be:

  •  ”s” to specify a string value type

  •  ”i” to specify an integer value type

  •  ”f” to specify a float value type

  •  ”T” to specify a true value type, no value is required or expected

  •  ”F” to specify a false value type, no value is required or expected

The <value> syntax must match the above mentioned format (see 2 tables up).

Note this Format will NOT SEND if there is a mismatch between the stated value type, and the value syntax. See the following examples for more details:

Value String Interpreted Value Types
{"type":"s","value":"hello world"},
{"type":"i","value":3},
{"type":"f","value":55.2}
  • "hello world" : string
  • 3 : integer
  • 55.2 : float
  • No error, OSC message will send
{"type":"i","value":3.7},
{"type":"f","value":<2>},
{"type":"s","value":Smith}
  • 3.7 : ERROR: value does not have the correct integer syntax
  • <2> : variable 2 as a string provided it is a string value
  • Smith : ERROR: no quotation marks around value
  • Errors found, OSC message will NOT send

Support#

If you encounter any issues with this module, please contact our support team.