Unify Manual

Your complete reference to PlugInGuru's creative playground!

User Tools

Site Tools


osc-support

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
osc-support [2021/11/12 15:45] – created shaneosc-support [2023/05/08 18:59] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== OSC Support in Unify ====== ====== OSC Support in Unify ======
 +[[wp>Open_Sound_Control|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 [[https://pluginguru.com/forums|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, go to the [[settings|Settings view]] and locate the OSC section:
 +
 +{{::osc-1.png|}}
 +
 +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:
 +
 +{{::osc-2.png|}}
 +
 +The recommended setting (allow Unify to communicate on Private networks only) should already be selected. Click the **Allow access** button to confirm it.
 +
 +===== 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:
 +  - **Parameter-set messages** use a path exactly as used in Unify's linked parameters (see [[realtime-params|Using Unify's Macro Knobs for real-time control]] and [[param-paths|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.
 +  - **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.
 +  - **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 [[realtime-params|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 [[https://hexler.net/touchosc|TouchOSC]]. C++ code to create such messages (using the [[https://github.com/mhroth/tinyosc|TinyOSC library]] looks like this:
 +
 +<code c++>
 +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);
 +}
 +</code>
 +
 +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.)
 +
 +==== OSC messages to embedded Unify instances ====
 +**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//.
 +
  
osc-support.1636731910.txt.gz · Last modified: 2023/05/08 18:59 (external edit)