OSC messages in Aximmetry

Introduction

This document discusses how to use OSC messages in Aximmetry received from an OSC input and how to create and send OSC messages from Aximmetry.

You can read more on the OSC protocol in the OSC section of the general Controllers document.

There is a separate document that describes how to set up OSC In- and Outputs only: OSC In-, and Output Setup

OSC Message Structure

To understand how OSC messages work, looking at their core structure is useful.
An OSC message is made up of three components:

• an address
• a type tag
• argument(s)
  

These define how data is transmitted and interpreted between devices. While Aximmetry allows you to create these messages using a graphical interface, the underlying structure remains the same.

Address

An OSC Address is a unique identifier for a communication endpoint. When an OSC address is assigned to an output, incoming OSC messages are received at the same address.
NOTE: Multiple inputs can be assigned to the same OSC address. This means different controls (e.g., Button A and Button B) can send messages to the same destination, affecting the same parameter. Additionally, a single input can be sent to multiple receivers.

Type Tag

The type tag specifies the type of data being transmitted over the OSC protocol. It determines how the message’s arguments should be interpreted by the receiver.
It begins with a comma (,), immediately followed by a series of characters that match the OSC Arguments listed in the message.

There are four basic types that each OSC application is required to recognize:

Type tag	Corresponding argument	Definition
i	int32	32-bit big-endian two’s complement integer (signed 32-bit integer)
f	float32	32-bit big-endian IEEE 754 floating point number (signed 32-bit floating point number)
s	string	A sequence of non-null ASCII characters followed by a null
b	blob	Arbitrary data: int32 count followed by that many bytes of arbitrary binary data

Furthermore, additional types can be implemented in OSC applications, however, they must be encoded with the type tags in this table:

Type tag	Corresponding argument	Definition
h	int64	64 bit big-endian two’s complement integer (signed 64-bit integer)
t	timetag	Defines when the OSC message should be handled. 64 bit; first 32 bits = seconds, second 32 bits = fractions of a second. Measured from 01/01/1900 00:00.
d	double	64 bit (“double”) IEEE 754 floating point number (signed double [64-bit floating point number])
S	string	Alternative string, to allow for differentiation when handling should be done differently.
c	char	an ASCII character (as 32-bit)
r	color	32 bit RGBA color
m	MIDI message	4 byte MIDI message. Bytes from MSB to LSB are: port id, status byte, data1, data2
T	bool	boolean: TRUE
F	bool	boolean: FALSE
N	bool	boolean: Nil (NULL - no value)
I	impulse	Infinitum. No corresponding argument. Serves as signal only.
[		Beginning of array (of other types).
]		End of array (of other types).

NOTE: Boolean type tags contain the value itself, and they are not represented in the Arguments.
NOTE: In certain implementations, specifying a type tag is optional.

In Aximmetry, the use of these type tags is hidden. Instead, they are implied from the data types sent over via OSC modules, or handled internally when OSC controllers send messages with type tags implemented.

The following types are created/read by the OSC modules in Aximmetry:

• OSC Scalar Out / OSC Scalar: float32
  
• OSC Vector Out / OSC Vector: array of float32s
• OSC Trigger: when the received message's first value is a non-zero number or a boolean TRUE, converts it to impulse
• OSC Out / OSC Method: these modules use collections as their message arguments, which are created by the Set Collection x modules. Each collection is made up of a key, and a single element or an array of elements that correspond to the module's type:
  • Set Collection Text: string
  • Set Collection Color: array of 4 floats (3 for color, 1 for alpha)
  • Set Collection Double: double
  • Set Collection Scalar: float32
  • Set Collection Vector: array of float32s
  • Set Collection Integer: int32
  • Set Collection Logical: bool
  • Set Collection Transformation: array of 3 or 4 arrays of float32s (depends on which mode is used for the Value pin) 
    NOTE: An array of collections can be created from multiple collections.

Arguments

An argument is the actual value being sent in an OSC message. It carries the data that will be processed by the receiving endpoint.
NOTE: An OSC message can contain multiple arguments.

Examples

As an example, let's say we want to control the volume of a specific channel on an audio mixer.
The message would look like this: /audio/volume ,if 2 0.75
Breakdown:

• Address: /audio/volume (example address, a real audio mixer would have their own address)
• Type Tag: ,if
  • i: indicates the first argument is an integer
  • f: indicates the second argument is a floating-point number
• Arguments: 2 0.75
  • 2: to select Audio channel 2
  • 0.75: sets volume to 75%

As an alternative example, let's say this audio mixer has a dedicated address for controlling the master volume and we want to control that.
The message would look like this: /audio/masterVolume 0.75
Breakdown:

• Address: /audio/masterVolume (example address, a real audio mixer would have their own address)
• Type Tag: Not explicitly defined (the data types are inferred)
• Arguments: 0.75 -> sets the master volume to 75%

Input

Controlling Module Properties and Control Board Buttons

The usual scenario is that the incoming OSC messages only contain an address and a single floating-point number (or an integer, logical, or double value). This kind of message can be used to control properties and buttons, just like with MIDI or DMX controllers.

Right-click the name of a numeric or a logical property,

or a control board button and choose Assign OSC...
 

Then, simply send the appropriate OSC message from your controller device (e.g., move a fader or press a button), and the assignment is made.

NOTE: If you write your own controller software, please note that in order to turn on a button in normal mode, you have to send a value of 1, and to turn off, you have to send a value of 0.

To see and manage all the OSC assignments you made in your compound, go to File / Properties / OSC Assignments:

Controlling the Flow Graph

You can build controlling structures within the flow graph using the OSC modules.

Scalar Input

For the OSC messages containing a single floating point number (or an integer, logical, or double value), you can use the OSC Scalar module:

For the module, you have to specify an OSC Address:

It can be entered manually, but you can also use the Learn function. Turn On Learn:

then move/press a fader/button on your OSC controlling device. The address will be filled in automatically.

Vector Input

If the OSC message contains an arbitrary number of floating-point values representing a 2D or 3D position or any arbitrary series of numbers, you can use the OSC Vector module:

Trigger Input

The OSC Trigger module sends a signal each time an OSC message containing any non-zero value arrives:

General Input

OSC messages can contain any number of arguments of various types. To handle any general case, use the OSC Method module.

It outputs a collection, with each argument assigned to keys 1, 2, 3, etc. In this example below, we’ve received a message with 5 arguments of types float, string, Nil, integer, and a logical true (,fsNiT):

To access the individual arguments, you can use the standard Collection modules. E.g. if you need the second string argument, use the Collection Text module:

To access the second argument, enter 2 into the Key property.
NOTE: Please pay attention to not entering the number into the Index property, which is incorrect in this case.

You can access the other arguments similarly:

NOTE: To learn more about the handling of collection data type in general, please refer to the following document:

Sending OSC Output

For the opposite scenario, when you want to control external devices from Aximmetry via OSC, use the OSC * Out modules.

Scalar and Vector Output

For single numeric values or a series of numbers, use the OSC Scalar Out and OSC Vector Out modules:

For these, you have to specify an output Device (from the list you’ve created in the initial setup, see above), and a target address:

The actual sending of the message can be performed in two ways. You can send it at a specific time by triggering it via the Send pin. Alternatively, you can turn Auto Send On, in this case, each time the Argument value is changed, it is sent automatically.

General Output

For sending an arbitrary number of arguments of any type, use the OSC Out module in conjunction with modules that output collections, like the Set Collection x and Set Subcollection modules.

IMPORTANT: The OSC Out module requires collections to have a Key but instead of any arbitrary value, they must be integers (starting from 1) that represent the order Arguments are filled.

E.g. to achieve the message structure we’ve seen above, do the following:

NOTE: We did not add any argument for Key = 3 in this example. In this case, a Nil element will be inserted as the third argument.