| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| osc-support [2021/11/12 16:40] – [Overview] shane | osc-support [2023/05/08 18:59] (current) – external edit 127.0.0.1 |
|---|
| |
| ===== Overview ===== | ===== 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 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. | 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: | |
| - //Parameter 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. | ===== 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. | * 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. |
| - //MIDI-over-OSC// messages use the path ''/midi'' and the non-standard format code "m". | - **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: | 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> | </code> |
| ===== 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 [[https://notepad-plus-plus.org/|Notepad++]] on Windows or TextEdit //in plain-text mode// on Macintosh. (DO NOT use Microsoft Word or any similar program; see [[midi-controller-files#about_plain-text_files|this discussion of plain-text files]].) | 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.) |
| |
| The //Unify.settings// file is an [[wp>XML|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. | ==== 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. |
| |
| 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: | 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//. |
| | |
| <code XML> | |
| <VALUE name="networkParams"> | |
| <networkParams> | |
| <osc ipAddress="0.0.0.0" portNumber="9001" connectAtStartup="0"/> | |
| </networkParams> | |
| </VALUE> | |
| </code> | |
| | |
| 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. | |
| |
| |
