Using OSCQuery Helper.

OSCQuery Helper for macOS

OSCQuery Helper
The OSCQuery Helper interface.

OSC Query Helper (“OQH” from now on) creates an OSC query server for other applications that support OSC, but don’t support the OSC query protocol. This allows clients that support the query protocol to browse and send data directly to the other app’s OSC address space.

Downloading OSCQuery Helper

Latest release: OSCQuery Helper v0.4.3.2

The OSCQuery Helper application can also be found on the VDMX dmg in the Extras folder.

About OSCQuery Protocol

The OSCQuery Protocol is an agreed upon specification that extends the base functionality of OSC to make it easier to construct impromptu or improvisational interfaces between different systems.

Some definitions copied from the OSC spec:

  • An OSC server has a set of OSC Methods.
  • OSC methods are the potential destinations of OSC messages received by the OSC server and correspond to each of the points of control that the application makes available. “Invoking” an OSC method is analgous to a procedure call; it means supplying the method with arguments and causing the method’s effect to take place.
  • An OSC server’s OSC Methods are arranged in a tree structure called an OSC Address Space. The leaves of this tree are the OSC Methods and the branch nodes are called OSC Containers.

The OSCQuery Protocol provides a standardized way for systems to publish descriptions of their OSC Address Spaces in such a way that other environments can automatically interface with them with little or no setup.

Within OSCQuery, a “server” is a host that provides a JSON data blob that describes the hierarchy of an OSC Address Space in a format that is both easy for humans and machine to interpret. Descriptions can include the type of data that is expected, the range of values that are accepted and other information about each container and method within the address space.

Using OSCQuery Helper

How to use OSCQuery Helper

  1. Tell OQH what file to use- this file will be used to populate the OSC query server with the description of another application’s OSC address space. OQH will “watch” the file and if it is updated, the query server will automatically update itself, and then notify all connected clients that it has been updated. For more information about the supported file type(s), see “FILE TYPE”.
  2. Tell OQH how to send OSC data to the other app (the IP address and port the other app listens to for OSC data). When clients connect to OQH’s query server, they will retrieve this information so they can send OSC data directly to the other app.

If OQH is running, the OSC query server is running- you can check it with any OSC query client, or a web browser. The query server will stop when the app quits- if there’s a problem with the file you load (if it’s missing or malformed or corrupt) the query server will keep running, but its address space will be empty.

OSCQuery Helper File Format

JSON files can be imported- a sample file demonstrating a wide variety of OSC types is already installed on your machine in “~/Documents/OSCQuery Helper/SampleDocument.json”. The JSON files that you import should have a structure similar to the desired output of the OSC query server.

For more information, consult the OSC query protocol, defined here https://github.com/vidvox/OSCQueryProposal. You can include an optional HOST_INFO object in the root level of the JSON file’s object if you want to hard-code the connection details of the target app or device (port and, if desired, an IP address other than localhost) as detailed in the query protocol. If you don’t include this information, you can just use the UI in the app to specify the target.

Example JSON

For the most part, you can use the provided SampleDocument.json as a starting point for your own JSON files to use. It contains examples of working with each supported OSC data-type, as well as handling of vectors and arrays / tuples.

Additional examples and useful templates can be found in the OSCQuery Helper Templates repository on GitHub.

A basic example that involves two floats nested at different levels might look like this:

{
	"CONTENTS" : {
		"test" : {
			"CONTENTS" : {
				"my_float" : {
					"TYPE" : "f",
					"DESCRIPTION" : "float node",
					"RANGE" : [
						{
							"MAX" : 100,
							"MIN" : 0
						}
					],
					"TAGS" : [
						"float input"
					],
					"CLIPMODE" : [
						"none"
					],
					"UNIT" : [
						"percent"
					]
				}
			},
		},
		"test2" : {
			"CONTENTS" : {
				"test3" : {
					"CONTENTS" : {
						"my_float" : {
							"TYPE" : "f",
							"DESCRIPTION" : "float node",
							"RANGE" : [
								{
									"MAX" : 100,
									"MIN" : 0
								}
							],
							"TAGS" : [
								"float input"
							],
							"CLIPMODE" : [
								"none"
							],
							"UNIT" : [
								"percent"
							]
						}
					}
				}
			}
		}
	},
	"DESCRIPTION" : "root node"
}

Notes and Troubleshooting

  • Within VDMX, parameters in a Control Surface can be published with OSCQuery without using an external helper tool such as OQH.
  • The free MIDI OSCQuery Helper utility is a similar application for publishing OSC Address Spaces for software and hardware devices that do not yet support OSCQuery Protocol / OSC messages natively, but can receive control data over standard MIDI.
  • If the OSCQuery Helper does not appear in the list of servers in other software:
    • Make sure the client trying to connect to OQH is on the same local network.
    • Try using the free OSCQuery Browser utility to try to browse the address space.
    • Try to load the JSON data blob in a web browser by entering the IP address / port used by the server for OSCQuery. If it does not load, then the server is not publishing its information or there is a networking problem.