OSC - Version 2.3.0.BETA2#

Module Summary#

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

Module Status#

Note: Please be aware that this is a beta version of this IO Module which has not yet been fully tested. We recommend testing before use.

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

Release Notes#

Version 2.3#

  •  Adds support for TCP connections

  •  Action format Type Value Pairs replaced with JSON This may require user action when updating

  •  Adds support for sending and receiving OSC bundles

  •  Renamed property Address to OSC Address

  •  Renamed property Hostname to OSC Host

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 OSC 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 OSC 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 OSC 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 OSC Host to specify the network address (IP or DNS address) to which the OSC message will be delivered.

Use the OSC 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 OSC Host to specify the network address (IP or DNS address) to which the OSC message will be delivered.

Use the OSC 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
JSON#

This Format uses a JSON 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. 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).

Multiple type/value pairs can be issued, surrounded by square brackets and separated by a comma
e.g. [{“type”:”s”,”value”:”String 1”}, {“type”:”i”,”value”:1}]

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

Bundles can be sent using the JSON syntax using the type "bundles". All bundles are sent with the time-tag immediately. The formatting is best described using examples:

Example 1 - To send a bundle containing only a single message, with the integer value 3, and the float value of variable 2 the following example would be used:

{
  "type": "bundle",
  "value": [
    [
      {
        "type": "i",
        "value": 3
      },
      {
        "type": "f",
        "value": <2>
      }
    ]
  ]
}

Example 2 - To send two messages in a bundle, message 1 with the string value Message 1, and message 2 with the string value Message 2:

{
  "type": "bundle",
  "value": [
    [
      {
        "type": "s",
        "value": "Message 1"
      }
    ],
    [
      {
        "type": "s",
        "value": "Message 2"
      }
    ]
  ]
}

Example 3 - Bundles can also be nested:

{
  "type": "bundle",
  "value": [
    {
      "type": "i",
      "value": 3
    },
    {
      "type": "bundle",
      "value": [
        {
          "type": "s",
          "value": "This is a nested bundle"
        }
      ]
    }
  ]
}

Support#

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