Introducing OSCQuery Protocol

One of the most useful technologies for artists working with audio and visual software is the OSC specification for sending control information from one application to another. While MIDI is great for a lot of situation, OSC was designed to be more extensible and allow for a variety of different datatypes, greatly expanding the possibilities within the community of real-time digital art. Over the years the ecosystem of tools that support the protocol has grown and now we are excited to release a new extension to help the community take OSC to the next level.

The OSC Query 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.

For those who are already familiar with OSC, the idea is very exciting: using OSCQuery, you can ask a piece of software for a description of its Address Space along with other useful information about the method such as its expected range and datatype. This makes it possible for applications such as VDMX to both automatically generate interface controls for remote systems and publish its own local controls so that they can be accessed by other software in the same way.

For those who haven't used OSC before, this concept will be even more exciting and doesn't require any advanced knowledge of how OSC works: the goal of OSCQuery is to make it possible for software tools to automatically communicate information about their control parameters over a local network so that other applications can access them remotely, with little or no additional setup. Behind the scenes the software you are using is sending / receiving OSC messages, but the goal of OSCQuery is to obfuscate this from during setup as much as possible.


What are OSC and OSCQuery?

If you've never used OSC before, it helps to start with some basic definitions from the OSC specification itself:

  • 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 builds on top of OSC to provide 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.

Within OSCQuery, a "client" refers to a piece of software that browses and interacts with a remote server's OSC address space.

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.

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.


Using OSCQuery in supported software

For specific information on how to use OSCQuery within a piece of software, consult its documentation or manual. Beyond VDMX and our related freebie apps, OSCQuery can already be found in other popular software including MittiMad Mapper and libossia.

Various demonstrations and examples related to using OSCQuery in VDMX can be found in our tutorials section and documentation pages.


Interactive HTML Interface

Another capability we have included in VDMX as part of OSCQuery protocol support is a built-in “Interactive HTML Interface” which can be loaded from most web browsers on desktop, tablets and mobile devices. Using this, anyone with a browser on your network can access this webpage, which displays interactive UI items for all of the UI items you’re publishing via OSCQuery. By default, this means that every UI item on every Control Surface plugin can be controlled remotely from a browser with zero setup.

 A Control Surface plugin and corresponding web controller views (in dark and light stylings) on a Mac...

A Control Surface plugin and corresponding web controller views (in dark and light stylings) on a Mac...

 ... the corresponding interface viewed in Safari on an iPhone.

... the corresponding interface viewed in Safari on an iPhone.

 Interactive HTML Interface in Dark and Light styles as viewed on Android tablets from Samsung / Asus.

Interactive HTML Interface in Dark and Light styles as viewed on Android tablets from Samsung / Asus.


Related OSCQuery Utility Apps

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.

 The free / open source  OSCQuery Browser  can be used to browse and remotely control apps with OSC messages.

The free / open source OSCQuery Browser can be used to browse and remotely control apps with OSC messages.

  • 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 or downloaded individually from their respective pages. The open source codebase for these tools can be found in the VVOSCQueryProtocol repository on GitHub.


How does OSCQuery work on a technical level? How can I add support for it to my own application?

The OSCQuery Protocol github page covers all of the technical details of the specification and includes links to several example implementations that other developers can use to get started with adding support in their own software.