Open Sound Control (OSC) is a network-based protocol for remote control of many types of software and hardware (primarily sound and lighting equipment). Unify has had built-in support for OSC for a long time, but this was only exposed in release versions in Unify v1.7.

Unify's OSC support remains highly experimental, subject to change, and essentially unsupported. OSC itself is a bit complicated, and really only suitable for technically-inclined users. If you are interested in experimenting with OSC in Unify, refer to the PlugInGuru User Forums. This manual page provides only minimal details.

Unify v1.7 and later can be configured to listen for OSC connections on a specified UDP port; see “Configuration” below.

Only the Unify stand-alone Unify app can use OSC; the plug-in versions cannot.

Unify uses only UDP for OSC connections; it cannot use TCP at all. At present, it basically only receives OSC messages; its support for sending them is extremely limited.

To set up OSC support in Unify v1.7 and later, go to the Settings view and locate the OSC section:

To enable Unify to listen for OSC commands, the least you need to do is to check the “Enable” box.

If you wish, you may also adjust the portNumber and/or ipAddress settings. You must disable OSC (un-check the “Enable” box) before editing these values, then re-enable OSC (check the box again) to accept the changes, and finally re-start Unify for the changes to take effect.

• The default ipAddress “0.0.0.0” (shown as “ANY IP”) configures Unify to listen on ALL available network interfaces.
  • If you want it to listen only for local connections, from other programs on the same computer, change this to “127.0.0.1”.
  • If you want it to listen on a specific interface only, enter the IP address to use.
• On most computers, the default portNumber 9001 should not interfere with any existing network services.
  • If you need to change it, you'll need to determine a suitable port number, between 1024 and 65535.
• Changes you make will only take effect after you quit Unify, then re-start Unify.

On Windows, the first time you re-start the Unify stand-alone app after enabling OSC, a pop-up window will appear, asking you if it's OK to allow network access:

The recommended setting (allow Unify to communicate on Private networks only) should already be selected. Click the Allow access button to confirm it.

OSC messages take the form of a “path” and some associated data. At present, Unify can handle three kinds of OSC messages:

1. Parameter-set messages use a path exactly as used in Unify's linked parameters (see Using Unify's Macro Knobs for real-time control and Parameter paths reference), but with a single slash character / prepended at the start.
   • The associated value (to which the parameter is set) must be a floating-point value (format-code “f”). No other data types are supported at this time.
2. Command messages have the same structure as parameter-set messages, but instead of setting actual parameter values, these trigger actions based on the path.
   • All command messages include a floating-point value, but the value itself is ignored for most commands.
3. MIDI-over-OSC messages use the path /midi and the non-standard format code “m”.

All parameters which can be linked to Unify's Macro Knobs can also be set via OSC messages. The paths are almost the same, but the OSC versions have a single slash-character (“/”) added at the beginning.

Note that Unify's parameters ONLY accept floating-point values between 0.0 and 1.0. Many parameters (especially plug-in parameters exposed for host-automation) have an apparent range which is different, e.g. 0 to 100%, -60 to 0 dB, etc., but internally, the plug-in always maps between the “normalized value range” 0.0 to 1.0 and these “human-readable” values. It is up to you to determine what normalized values to use in OSC messages.

Unify also supports OSC “commands” which are basically like pseudo-parameters, but instead of identifying a specific parameter to be set, the path specifies a specific action to be triggered.

Unify v1.7 supports the following “command paths”:

• /init is the same as clicking the INIT button.
  • The associated floating-point value must be present, but is ignored.
• /load triggers loading of a patch.
  • The associated floating-point value is cast to an integer, and should be equal to the value of the id field for the desired patch's row in the Unify patch database.
  • If the value does not exactly match a valid patch ID, the command will be ignored.
• /embed also triggers patch loading, but the specified patch is loaded as a new Unify layer.

As described above, the /init, /load, and /embed commands allow a remote-control program to trigger loading of patches. Because this is often a time-consuming operation, it's desirable to have a way for Unify to let the remote-control program know when the load operation completes. Unify supports a very limited bi-directional messaging protocol for this purpose.

A remote-control program can optionally send the OSC message /hello/IP address to Unify, with an integer value (format-code “i”). The IP-address string indicates the address on which the remote-control program itself is listening for OSC messages, and the integer value indicates the port-number. An example might be /hello/127.0.0.1 with value (port number) 9000.

If Unify has received a valid /hello messages, it will acknowledge the completion of any patch-load command (including /init) by sending an OSC message /presetLoaded to the specified UDP address and port number. This message includes an integer argument (format-code “i”), whose value is always zero. Note that Unify will also send these messages even when patches are loaded manually by the user, through the GUI.

Before shutting down, a remote-control program which has previously sent a /hello message should also send a /goodbye message, to indicate that Unify should no longer send out /presetLoaded messages. The /goodbye message also requires an integer value (format-code “i”), but the actual value is ignored.

MIDI-over-OSC message formats are not standardized in OSC. The format Unify uses is based on that used by TouchOSC. C++ code to create such messages (using the TinyOSC library looks like this:

void OscSender::sendRawMidi(uint8 byte1, uint8 byte2, uint8 byte3)
{
    if (oscPort < 0) return;
 
    uint8 data[4];
    data[0] = 0;
    data[1] = byte3;
    data[2] = byte2;
    data[3] = byte1;
 
    int len = tosc_writeMessage((char*)oscData, sizeof(oscData), "/midi", "m", data);
    while (!socket.waitUntilReady(false, -1)) Thread::sleep(1);
    socket.write(oscAddr, oscPort, oscData, len);
}

Note the reversed byte-order, and how 3-byte MIDI messages are encoded as 4-byte integers. (2-byte MIDI messages are encoded the same way, but the byte3 value will be 0.)

As of Unify v1.9, it is possible to direct OSC commands to specific embedded Unify instances. The required path syntax is similar to that for sending parameter-update messages to plug-ins, but the word unify is used instead of plugin, and this is followed by the OSC command to be sent to the Unify instance.

For example, to send the command /master/mixLevel to an embedded Unify instance on layer INST1, the full OSC path would be /inst/1/unify/master/mixLevel.