Using OSCQuery Browser.

OSCQuery Browser for macOS

OSCQuery Browser
The OSCQuery Browser interface.

OSCQuery Browser is a simple, free utility for exploring the OSC Address Space of applications that support the OSCQuery Protocol on the local network.

While VDMX already directly takes advantage of OSCQuery Protocol, at times it is useful to have a lightweight tool for quickly browsing and accessing published OSC controls on remote systems.

Downloading OSCQuery Browser

Latest release: OSCQuery Browser v0.4.3.2

The OSCQuery Browser 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 Browser

The OSCQuery Browser interface is broken into two main sections: On the left is a listing of detected OSCQuery “Servers” that can be browsed and the right contains the OSC address space listing returned from the currently selected server.

At the top of the OSC Address Space browser section of the interface is a text field that can be used to set the directory within the hierarchy to display. The default is to display the entire namespace from the root directory.

The UI Items tab includes interface controls such as sliders, buttons, color pickers and pop-up menus for each of the detected elements starting from the specified directory level. These UI controls can be used to send OSC messages of the appropriate type to the appropriate IP/port combination as described by the server info. Individual controls and directories can be hidden by using the disclosure triangles in the listing.

The Raw JSON displays an unmodified version of the JSON data that is returned from the host server. This data blob can be useful for developers who are adding support for OSCQuery into their own applications and general troubleshooting.

Notes and Troubleshooting

  • Note that while some applications support bi-directional OSC messages through OSCQuery for the purposes of keeping UI elements visually in sync across software, it is an optional part of the protocol. OSCQuery Browser which is designed to be a lightweight browsing tool, not a performance interface, and only supports the sending of OSC messages.
  • The free OSCQuery Helper application is useful for publishing OSC Address Spaces for software and hardware devices that do not yet support OSCQuery Protocol natively, but can receive control data over standard OSC.
  • The free MIDI OSCQuery Helper application is useful for publishing OSC Address Spaces for software and hardware devices that do not yet support OSCQuery Protocol natively, but can receive control data over standard MIDI.
  • Within VDMX, a built-in OSCQuery Browser window can be accessed from the Window menu (cmd+5 keyboard shortcut). Similar to the standalone OSCQuery Browser application, this window can be used to browse and quickly send OSC messages to a remote host. Additionally you can drag elements from the built-in listing to UI elements in VDMX such as slider and buttons to automatically setup OSC senders.
  • If an OSC Query Server does not appear in the list of servers:
    • Make sure the software / hardware device you are trying to detect supports the OSC Query Protocol extension.
    • Make sure the server is on the same local network.
    • 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.