Skip to main content

Introduction to Open Sound Control

Configuration​

Each and every HOLOPHONIX parameters can be controlled or monitored via OSC (Open Sound Control) commands.

To configure the OSC Receive and Sends, open the OSC tab in the Preferences.

OSC Receive​

Send the OSC messages to the processor’s IP address on the default port 4003. However, you can change that port number. See the OSC tab in the Preferences.

OSC Send​

To send OSC commands from HOLOPHONIX to an external device, you first need to activate and configure the destination IP address and port. See the OSC tab in the Preferences.

You can now set multiple OSC destinations, and choose what coordinate format will be output for source positioning.

danger

Ports 4002, 4001 and below 1024 are not allowed.

When a parameter's value is changed (such as source position or any source or bus setting for example), its new value is sent to the destination.

Message Structure​

OSC messages are structured in two parts: first the address (whose elements are separated by slashes: /), followed by the argument (the value) to transmit.

/{element}/{id}/{path/to/the/parameter} {argument#1} {argument#2} ...

Example​

To set the second spatialization bus level to -2.5 dB, one would send the following command:

/bus/2/gain -2.5

Address​

The address itself contains first the type of object (mono source /track, stereo source /stereo, spatialization bus /bus, etc.), then the index of the object, and finally the parameter to control. When selecting an object, its header in the inspector displays the OSC address to use to control it, with its index included.

Depending on the type of object to control, the address can start with one of the following:

  • /track (mono object)
  • /stereo (stereo object)
  • /multi (multichannel object)
  • /tree (mic tree object)
  • /aformat (A-Format ambisonics stream source)
  • /bformat (B-Format ambisonics stream source)
  • /zylia (Zylia microphone stream source)
  • /eigenmike (Eigenmike microphone stream source)
  • /hoastream (Higher Order Ambisonics stream source)
  • /bus (sound spatialization bus)
  • /reverb (reverberation associated with each bus)
  • /d2m (direct to master source)
  • /d2b (direct to bus source)
  • /thru (bus through)
  • /lfe (LFE bus)
  • /monitoring (monitoring bus)
  • /master (master bus)

Arguments​

Argument Types​

The "argument" is the value that is sent to a specific parameter. There are four types of arguments:

  • integer numbers (1, 2, 3, etc.)
  • decimal numbers (1.1, 1.2, 1.3, etc.)
  • string of characters (abc, xyz),
  • booleans (true or false, 0 or 1)

Rounding​

When a decimal value is sent instead of an integer, the value will be rounded to the closest integer (for example, 1.5 will become 1, and 1.6 will become 2).

Angular Scales​

Regarding the values expressed in degrees, they can be sent to HOLOPHONIX on the native -180° to +180° scale, but also from 0° to 360°. For exemple, if you set an angle to +190°, it will be converted to -170°, its equivalent direction on the native scale.

Non Case-Sensitive​

When the argument is a string of characters, the messages will not be case-sensitive.

Example: Those two messages will be strictly equivalent:

/bformat/1/norm FuMa
/bformat/1/norm fuma

Pattern Matching (Groups and substitutions)​

Specific structures of messages allow controlling several elements together:

  • Use the ? character as a substitution element for a single character in the addresses,
  • Use the * character as a substitution element for several characters,
  • Use straight brackets [ ] with a dash - to control a range: [1-4] for 1, 2, 3 and 4 for example,
  • Use curvy brackets { } with a coma , to control a list: {1,4,5} for 1, 4 and 5 only; it also works with strings of characters: {stereo, multi} for example

Example 1: If you want to set the azimuth position of all the mono sources to +10°, you could send:

/track/*/azim 10

Example 2: If you want to set the level to -6 dB for stereo sources 1 to 5, you could send either of these two messages:

/stereo/[1-5]/gain -6
/stereo/{1,2,3,4,5}/gain -6

Example 3: If you want to mute all mono and stereo sources, send:

/{track,stereo}/*/mute 1

Retrieve parameter status​

Use the /get message to retrieve the status of a specific OSC parameter, or status of multiple parameters.

Example: If you want to know the gain level applied to stereo source 5, send:

/get /stereo/5/gain

This will return /stereo/5/gain -6.

tip

/get uses the mentioned above message structure and pattern matching.

Example: If you want to know the gain level applied to stereo sources 1 to 5, send:

/get /stereo/[1-5]/gain

This will return /stereo/1/gain -6 [...] /stereo/5/gain -6

NOTE

/get only works with indexed elements in the project. As such, it cannot retrieve any paramater status for the Master, the Monitoring, or the LFE.