Using the OSCQuery Helper tool with Processing

Download the completed project files for this tutorial

The OSCQuery Helper and OSCQuery Browser being used alongside a Processing sketch to render a cube.

In our introduction tutorial for working with Processing and VDMX we examined how to manually configure sending OSC messages from VDMX interface items to control properties of a Processing sketch running in the background. For this follow up lesson we will look at how the OSCQuery Helper tool can be used to publish the OSC address space for a sketch so that they can be remotely accessed by other software like VDMX or the OSCQuery Browser tool.

Tip: Read more about the new OSCQuery Protocol in our blog post.

Step #1 – Download the free OSCQuery Helper tool.

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

The interface has two main areas of settings to configure:

  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.

Step #2 Add OSC receiving to your Processing sketch

As demonstrated in the Introduction to Connecting VDMX and Processing with Syphon and OSC tutorial, add OSC receiving and parsing to your sketch.

The OSCQuery protocol supports working with lists of values and generally client software will generate user interfaces using the Data Types and UI Item conventions found in the specification proposal.


Tip: Don’t forget to import the oscP5 library and to configure the OSC receiving port in the setup() function as well;

Step #3 Create a JSON file that describes the OSC address space for the Processing Sketch and load it into the OSCQuery Helper

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.

OSCQuery supports singleton datatypes as well as lists of values. In this example we demonstrate representing the x and y rotation in two different ways: As individual address paths for “x” and ”y” and as a combined “xy rotation” list of two floats.

Tip: Make sure to match the port specified in the setup() {} method from the Processing sketch in the OSCQuery Helper interface. If running on the same computer you can set the target IP address to “127.0.0.1” to send local OSC messages.

Step #4 Use the OSCQuery Browser, VDMX, or other supported software to remotely control the sketch while it is running

Download the free OSCQuery Browser tool and launch it.

Published parameters from the sketch can be browsed and remotely controlled over the local network without any additional configuration.

Tips and Notes:

The OSCQuery Client plugin in VDMX can be used to create interface controls for remotely published properties and includes its own browser.

The OSCQuery Client plugin in VDMX can be used to create interface controls for remotely published properties and includes its own browser.