Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


osc-support

This is an old revision of the document!


OSC Support in Unify

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.

Overview

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.

Enabling and Configuring OSC

To set up OSC support in Unify v1.7 and later, you need to first locate the Unify.settings file.

  • Close all instances of Unify first, so the file won't get overwritten while you're editing it.
  • On Windows, open an Explorer window and type %appdata%\PlugInGuru into the address bar.
    • This will open the folder C:\Users\your user name\AppData\Roaming\PlugInGuru.
  • On Macintosh, open a Finder window and type ~/Library/Application Support/PlugInGuru into the address bar.
    • This will open the folder /Users/your user name/Library/Application Support/PlugInGuru.

Within this folder, locate the file Unify.settings, and open it in a true text editor such as Notepad++ on Windows or TextEdit in plain-text mode on Macintosh. (DO NOT use Microsoft Word or any similar program; see this discussion of plain-text files.)

The Unify.settings file is an XML file. You should ideally know about the structure of XML, and how to ensure that start/end tags and quotation marks are correctly paired. Be VERY careful about typing quotation marks, as many text editor programs (even true “text editors”) are often configured to convert these into typographical quote-marks, which will cause Unify to be unable to parse the XML correctly.

Unify v1.7 will automatically add a well-formed XML VALUE tag for OSC configuration, which you will usually find at or near the very bottom of the file:

  <VALUE name="networkParams">
    <networkParams>
      <osc ipAddress="0.0.0.0" portNumber="9001" connectAtStartup="0"/>
    </networkParams>
  </VALUE>

To enable Unify to listen for OSC commands, the least you need to do is to change the “0” after connectAtStartup to “1”.

If you wish, you may also adjust the portNumber and/or ipAddress settings.

  • The default ipAddress “0.0.0.0” 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 save and close the file, then re-open Unify.

OSC message types

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”.

Parameter-set messages

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.

Command 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.

Bidirectional messaging for patch-loading commands

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 messages

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.

osc-support.1636737738.txt.gz · Last modified: 2023/05/08 18:59 (external edit)