OSCQuery Protocol

The new OSCQuery Protocol is an extension to OSC that we have been working with along with several other developers as a way to make setting up connections between software easier by allowing applications that receive messages to also publish their namespace in such a way that other software can ask for. This makes it possible to do useful tasks such as automatically creating user interfaces to remotely control parameters of other tools.

Using the OSCQuery Browser."

Video Demo: OSCQuery Client and Control Surface

Using OSCQuery in VDMX

Within OSCQuery Protocol, an application can be a server (publishes a list of OSC parameters) or a client (requests information from the server and sends control data over OSC), or both.

VDMX is capable of being both a client and a server in OSCQuery Protocol – it can both publish a listing of any parameters you choose so that they can be remotely controlled and it can ask other applications for a listing of their address spaces so that you can automatically create control interfaces that send the appropriate OSC data type.

Within VDMX the OSCQuery Protocol can be used in several ways as described below.

Publishing parameters with the Control Surface Plugins

In the Control Surface plugin inspector there is a new option to publish the listing of UI elements using OSCQuery. When this is active, other software on the local network can automatically detect these controls and access them.

Additional settings for how individual UI elements are published can be found in the UI Inspector.

The basic parts of the Control Surface: a section preset UI item (at the very top), several standard UI elements, and related inspectors."

Using the built-in OSCQuery Web Controller

Along with support for using OSCQuery to publish Control Surface for other software to access, VDMX also now includes a built-in web controller interface that can be loaded from standard web browsers on desktops, mobile devices and tablets. This means that, by default, every UI item on every Control Surface plugin can be controlled remotely from a browser with zero setup.

At the top of the web controller are two options:

  • Listen for OSC: When enabled, the web page will work in 'bi-directional' mode and listen for OSC messages sent back from the server when values are changed from other clients.
  • Dark / Light style: Switch between dark and light stylings of the web page.

The URL to load to get the web interface can be found in the VDMX preferences in the OSC section under OSCQuery. The link will look something like this:

http://your-ip-address:port/index.html?HTML

(eg http://169.254.2.159:2345/index.html?HTML)

When loaded in a web browser, it will look something like this:

A Control Surface plugin in VDMX (top left) and the corresponding web controls in dark and light modes."

When loaded on an iPhone, it will look something like this:

The web control as viewed on an iPhone in dark mode."

When loaded on an Android tablet, the Interactive HTML Interface will look something like this:

The web control as viewed on Samsung and Asus Android tablets in dark and light modes."

Note: Open source developers curious to see how this works behind the scenes can visit the oscqueryhtml project on GitHub.

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.

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.

OSCQuery Client plugin"

Like with the Control Surface plugin, the inspector for the OSCQuery Client plugin is where you can select a remote server to connect to and which elements you'd like to remotely control:

OSCQuery Client inspector"

VDMX supports bi-directional OSC messaging and when using OSCQuery Protocol, changes made on one system can be reflected in the user interfaces of each piece of software that is connected to it as a server.

Note that while VDMX supports bi-directional OSC message sending, other applications using OSCQuery Protocol may not. In these cases the VDMX interface may not dynamically update to keep in sync with remote servers, it will only send control information to them.

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.

OSCQuery Browser Window" border="true"

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. Example video.

Templates and Examples

From the Templates menu in VDMX you can find starting points for projects that use OSCQuery to publish parameters.

Along with support for OSCQuery Protocol in VDMX itself we have created a handful of utility applications that can be used to with software that does not yet have its own native support for the specification.

  • OSCQuery Browser: Provides a simple interface for browsing available OSCQuery servers, displays their OSC node hierarchies, creates UI items for endpoints that advertise their type, and sends OSC data to the remote server when the UI items are used.
  • OSCQuery Helper: A simple app that makes it possible to use OSCQuery Protocol with applications that only support basic OSC receiving. This works by loading a template JSON file that describes the OSC namespace of another piece of software and directs clients to send their messages to the proper place.
  • MIDI OSCQuery Helper: A simple app that makes it possible to use OSCQuery Protocol with applications that only support MIDI input. This app can receive OSC messages and converts them into MIDI that gets sent to a specified destination app. Allows for creating templates (JSON files) to describe a set of MIDI receivers that are published via OSCQuery Protocol. This app can also be used to load in an Ableton Live Set file (.als) and parses them for potential any MIDI receivers. An address space is automatically created for each discovered element and the app serves as a bridge, converting OSC messages into the MIDI messages expected by Live.

These free utilities can be found in the Extras folder on the VDMX dmg.

An Open Specification

Developers interested in adding support for OSCQuery in their own software can visit the OSCQuery Protocol GitHub project page.