The OSCQuery Protocol is an extension to the OSC specification designed to make setup of communication between applications easier. Within VDMX this new protocol can be used in severals ways that we'll be covering in this tutorial. You can also read more about OSCQuery in the blog post announcing its official release.

The basic steps to using OSCQuery Protocol in VDMX are as follows:

Use Control Surface plugins to publish local parameters for other software to access.
Published parameters from VDMX can be controlled from web browsers on desktop, mobile and tablet devices on the local network by entering the URL provided in the preferences under OSC.
Use the OSCQuery Client plugin to access parameters published by other software, including other copies of VDMX.
The OSCQuery Browser window can be used for quickly browsing remote address spaces and creating OSC sending assignments for UI items in VDMX.

In the sections below we'll investigate each of these in a little more detail along with links to more in depth tutorials and documentation.

Though in this tutorial we will focus on using OSCQuery to control and sync parameters between different copies of VDMX these same techniques can also be used in a similar fashion with other software such as Mad Mapper and Mitti. Additionally, along with the built-in access to OSCQuery within VDMX we have released several related free / open source utilities, including a standalone OSCQuery Browser and a tool for bridging MIDI and OSC. These are bundled in the Extras folder on the VDMX dmg or can be downloaded individually from the freebies page.

1. Publishing Parameters to OSCQuery with the Control Surface Plugin

Along with being able to create data-sources to be used within VDMX itself, each Control Surface plugin can serve as an interface for publishing parameters to the address space that other applications can access through OSCQuery protocol.

The "OSCQuery Enabled?" toggle in the Control Surface inspector can be used to publish its parameters for other apps to access.

From the inspector panel for a Control Surface plugin the provided "OSCQuery Enabled?" toggle can be used to set whether or not the plugin is included when the address space is requested through OSCQuery. Once enabled for an individual Control Surface plugin, each of its UI elements will be automatically published and remotely accessible by other software.

When using OSCQuery in the Control Surface, certain UI items may have additional custom properties that can be set on a per element basis:

Sliders: Publish Normalized – Sets if the published value is normalized 0 to 1 or uses the provided local range.
Multi-Sliders: Publish Normalized – Sets if the published value is normalized 0 to 1 or uses the provided local range.
2D Point: Publish Normalized – Sets if the published value is normalized 0 to 1 or uses the provided local dimensions.
Pop-Up Button: Publish as single index / Publish as string – Sets the datatype for the pop-up button to integer or string.

2. Loading the VDMX OSCQuery Tool Web Page

Tip: You can find the Interactive HTML Interface URL in the VDMX Preferences under OSC in the OSCQuery tab.

One of the special use cases of OSCQuery Protocol is that it can be used with any type of application that can send OSC messages – this includes web pages. Along with support for the protocol itself, VDMX now also automatically provides a web interface that provides interface controls that match with the published parameters in your Control Surface plugins. This webpage can be loaded by most standard web browsers such as Safari, Chrome and Edge on mobile and desktop devices on your local network.

PS. This is an open source project, more information can be found on the GitHub project page for oscqueryhtml.

3. Using the OSCQuery Client Plugin

Using the OSCQuery Client plugin you can browse the address spaces of other software and quickly create UI controls that are automatically configured to send / receive data from other systems.

Using the OSCQuery Client plugin to remotely control parameters on another computer.

The main interface is similar to a Control Surface plugin except that the interface elements added represent parts of other applications that are being remotely controlled from VDMX.

From the inspector for the OSCQuery Client plugin you can select a remote server to connect to and which elements you’d like to remotely access.

The '+' button will create UI items for the specified node and all of its sub-nodes.
The '-' button will delete any UI items that were created for an OSC node and all of its sub-nodes.

In some cases OSCQuery Servers may send updates when their address space changes in some way. If an OSC address is deleted from the server, it will automatically disappear from your local interface to reflect this. When possible VDMX will automatically recreate the UI items again if the address path reappears later on.

Additional information can be found on the OSCQuery Client video tutorial page and in the VDMX documentation.

4. Using the OSCQuery Browser Window

The OSCQuery Browser Window can be opened from the Window menu or by using the cmd+5 keyboard shortcut. From this panel you can access, browse and search the namespaces of other applications. For each of the listed OSC address destinations at the remote server you can:

Use the provided interface control to quickly send test data.
Dragged the listed item on to UI elements in VDMX (such as sliders, buttons, and color wheels – this also works with the list of variables in the Cue List plugin inspector) to automatically configure OSC sending to the remote hosts.

These examples are just the beginning of what is possible with OSCQuery – there are more tutorials, demos and examples coming soon, but most of all we are excited to see how the community makes use of this new protocol. Please send us links to information about your own projects by email, social media or in the comments for us to check out!