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.

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

  1. Parameter 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. MIDI-over-OSC messages use the path /midi and the non-standard format code “m”.

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);
}

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-support.1636735256.txt.gz · Last modified: 2023/05/08 18:59 (external edit)