OSC Remote Protocol

From behringerwiki
Jump to: navigation, search

Return to FAQ >> Third Party Documents >> OSC Remote Protocol


Preamble

This is an unofficial OSC protocol document for the X32 Digital Mixing Console

This document regroups data contained in version 1.01 of the OSC protocol for the X32 family of products released by Behringer in Oct. 2012, and a large number of additional OSC messages for communicating with the X32, their syntax and use, along with practical examples and explanations as to how and in which context they should be used.

Behringer is not associated to the redaction of this document and no support will be provided by the company.

The author has tried to make the information contained here as accurate as possible. A few areas are still prone to inaccuracies or uncertainties as to how to best use them. Please do not hesitate to provide feedback on the X32 user forum on errors or inaccuracies. They will be corrected in futures updates.

I also want to thank X32 user forums well known Paul Vannatto for his invaluable support during the redaction, his generous time and his advice in reviewing the numerous versions I provided him prior to this release.

As you read through this document, you may like a “hands on” experience with OSC commands, it is recommend you use a utility to send/ read commands to/from the X32. Such utilities ensure the commands will be properly formatted and offer better support for reading parameters back from X32.  

Patrick-Gilles Maillot

Description

  • The X32 is using a communication protocol that is compatible to standard OSC with some MUSIC Group specific extensions (e.g. parameter enquiry, subscriptions). OSC packets are received on UDP port 10023 and replies are sent back to the requester's IP/port.
  • In the following, the X32 (rack, console) is also called server, and a connected device or application is typically called client. Connections to the server take place over Ethernet network, UDP port 10023. The server replies on the UDP port specified by the client when establishing communication.

Different modes of X32 OSC communications

  • Immediate: a client such as a network connected tablet or PC application sends a request with or without parameters, and the server immediately acts or replies with the respective data.
Note: a single request from the client can result in several replies from the server (this is typically the case with /showdump)
  • Deferred: a client such as a network connected tablet or PC application sends a specific request without parameters (/xremote). When changes take place either from the server UI or from a connected client, several update messages (or replies) are returned for a period of time, until a timeout is reached.
Note: a single action at the server can result in several messages from the server
  • <OSC path>:= /config | /ch | /auxin | /fxrtn | /bus | /mtx |
/main | /dca | /fx | /outputs | /headamp |
/-show | /-prefs | /-usb | /-action | /-stat

Client initiated messages (client → X32 console)

Server replies or server initiated messages (X32 console → client)


Type rules (get/set parameter) and data formatting

  • all parameters must be big-endian and 4-byte aligned/padded, as per OSC specification.
  • padding is done with null bytes.
  • float parameters must be in range 0.0 – 1.0, e.g:
0.0 → 0x00000000 (big-endian)
0.5 → 0x3f000000 (big-endian)
1.0 → 0x3f800000 (big-endian)
  • integer and float parameters are signed 32-bit values.
  • boolean parameters will map to OSC integer type.
  • strings must be null-terminated .
  • blobs follow specific rules depending on the section they apply to (see later in this document)

Examples: (~ stands for null character)

  • Sending on port 10023 the UDP request « /info », will be replied with 48 bytes back to the sender’s UDP port :
 /info~~~,ssss~~~V2.05~~~osc-server~~X32C~~2.08~~~~ 


  • Sending on port 10023 the UDP request « /status », will be replied with 52 bytes back to the sender’s UDP port :
 /status~,sss~~~~active~~192.168.0.64~~~~osc-server~~ 


  • Sending on port 10023 the UDP request « /fx/4/par/23~~~~ », will be replied with 24 bytes back to the sender’s UDP port , for example:
  /fx/4/par/23~~~~,f~~[float with value 0.5]
  or, in hexadecimal:
  2f66782f342f7061722f3233000000002c6600003f000000 


Meter requests

Meter requests are used to get a specific set of meter values. Update cycle frequency for meter data is 50 ms, and may be variable according to console’s ability to fulfill requests. Timeout is 10 seconds. Meter values are returns as floats in the range 0.0 – 1.0, representing the linear audio level (digital 0 – full-scale; internal headroom allows for values up to 8.0 (+18 dBFS)).

The data returned by the X32 server for /meters is a “blob”, or set of unformatted binary data. As a result, the format differs from what is typically returned by the X32. This is essentially for efficiency/performance reasons. The format of a returned blob is as follows:

<meter id>,b~~<int1><int2><nativefloat>…<nativefloat>
<meter id> see possible values below (padded with null bytes)
,b~~ indicates a blob format, padded with null bytes
<int1> the length of the blob in bytes, 32 bits big-endian coded
<int2> the number of <nativefloats>, 32 bits ittle-endian coded
<nativefloat> data or meter value(s), 32 bits floats, little-endian coded </nowiki>


Example: The following meter request is sent to an X32 server:

/meters~,si~/meters/6~~~16

Where ~ stands for null character, and “16” is actually sent as a big-endian 32bit integer, i.e. 0x10000000.

The X32 server will returns for approximately 10 seconds and approximately every 50ms the 4 channel strip meters (pre-fade, gate, dyn gain reduction and post-fade) values of channel 17, in a single blob, as shown in the reply message below:

2f6d65746572732f360000002c6200000000001404000000fd1d2137fdff7f3f0000803f6ebbd534
/ m e t e r s / 6 ~ ~ ~ , b ~ ~< int1 >< int2 ><nfloat><nfloat><nfloat><nfloat>


X32 OSC Protocol Parameters

Types → [string, enum(integer), int(integer), linf(float), logf(float), level(float)]
Range → string A string of characters with up to [max. characters]
enum An int corresponding to an element in a [list of all possible strings]
int An int with value in [min. value, max. value], step size = 1
linf A float with value in [min. value, max. value, step size], following a linear scale
log A float with value in [min. value, max. value, steps], following a log scale
level A float with value in [0.0…1.0 (+10 dB), steps]:

The Range, level has 4 ‘linear’ dB ranges:

0.0…0.0625 (-oo, -90…-60 dB),
0.0625…0.25 (-60…-30 dB),
0.25…0.5 (-30…-10dB)
0.5…0.1 (-10…+10dB)

Server ↔ Client communications

The following tables describe communication messages that can be initiated by the client, or by the server as a response to the client or as update data

Server → Client communications

The following tables describe communication messages that are sent by the server, as long as a client registered to receive server updates using the /xremote command.

Effects Parameters

This section describes the parameters’ list, order, name, type and value range for the different effects available with the X32. The parameters described here correspond to the up to 64 parameters that can follow a /fx/[1..8]/par/[01…64] message.

Parameters can be sent one by one, or in multiples (generally more efficient) - alternating types as required.

Reverbs
Delays
The rest


User Definable Controls (ASSIGN Section)

This section describes the different settings and options linked to User Definable Contols using the OSC command /config/userctrl.

The User Control section is composed of 4 columns composed of a rotary encoder and two buttons. Encoders are numbered 1 to 4 and buttons are numbered 5 to 12.