OSCQuery Proposal

Goal

To establish a protocol that allows a client to browse and interact with a remote server's OSC address space. The protocol should be capable of both describing the address space's structure/layout as well as the types of messages that destinations in the OSC address space are capable of both sending and receiving. The protocol should be easily human-readable to facilitate debugging, and should have a standard set of errors to describe commonly-encountered problems.

The intent of this goal is to provide baseline functionality that other developers may take advantage of to construct impromptu or improvisational interfaces for dynamic environments.

Implementations

• The ossia library fully implements the OSCQuery protocol. It's cross-platform, modern c++, and it supports a variety of other protocols, too- OSCQuery is just a facet of what it offers.
• VVOSCQueryProtocol.framework is a Cocoa framework that we wrote and maintain which fully implements the OSCQuery protocol. We also wrote and support a number of basic user-facing OSCQuery utilities, including an interactive browser, and some helper apps that create OSCQuery servers for other apps that only support OSC or MIDI. These utilities can be downloaded here.
• The oscqueryhtml project is a web app that renders an interactive GUI for the OSCQuery server hosting it, and supports bidirectional streaming (the UI items in your browser/phone respond if another app/device sends OSC data to the server).
• OSCQuery.framework is a Cocoa framework that supports the required portions of the OSCQuery protocol, but it doesn't support the optional portions (no websockets or bidirectional streaming).

Background

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.

Here are some existing / proposed specs for OSC querying:

• Schmeder/Wright proposed spec
• OSNIP
• Minuit
• QLAB
• libmapper
• oscit
• AVBC
• UBI-OSC (presented at ICMC/SMC/2014) is an interesting look at some of the possibilities that can be realized with a shared OSC interface that is standardized to allow interoperation between a number of independent devices : paper - poster - mailing list

This is the third revision of this proposal, which is in its later stages and probably won't change much between now and whenever we remove the "proposal" language and flag it as a 1.0 release. It is mostly similar to the second revision- the main difference is the addition of details about bi-directional communication, and clarification of some important details that weren't emphasized significantly in the prior draft.

Proposal

This protocol is intended to be minimal and extensible- at its heart is a simple HTTP server that provides structured data (JSON) describing methods in an OSC address space. This is referred to as the "core functionality", and it consists of a standard set of attributes that every server is required to provide about every OSC method it wants to expose for querying via this protocol. Clients can then use this information to determine how they want to send values to the server.

In addition to the "core functionality", this protocol establishes a set of optional attributes that clients and servers are strongly encouraged to support- these optional attributes provide a substantial amount of contextual information about OSC methods. They have been categorized as "optional" because if this information is not provided for any reason, clients will still be able to browse the address space of a remote server and interact with its methods- that interaction just won't be as rich or well-informed. Clients can query servers for their support for these optional attributes on a case-by-case basis by checking the "EXTENSIONS" object found in the server's "HOST_INFO" (more on this later).

This protocol also defines a simple way to establish optional bi-directional communication, which is used to exchange commands and notifications, and stream data between clients and servers. Like the optional attributes, this streaming functionality is part of the OSCQuery protocol and clients and servers are strongly encouraged to support it- but it isn't required. Clients can determine if a server supports this at runtime by checking the "EXTENSIONS" object found in the server's "HOST_INFO" (more on this later).

Modifying this proposal to support custom attributes specific to your software or situation is intentionally trivial- you just need your server to populate the JSON objects it returns with whatever extra data you want to share, and your client to look for these extra attributes. If you want to share your custom attributes in this document so that other people may build support for them, get in touch with me and we'll add them below.

Finally, this proposal also includes a listing of known data types and UI item conventions, as well as a variety of OSCQuery examples to help illustrate and clarify the topics discussed here. <BR><BR><BR>

Core Functionality

• The HTTP server should be an HTTP 1.1 server. If you want to be able to stream values from the server to its clients, the server needs to be capable of supporting websockets. The protocol also allows for running the two servers on different ports if there is a technical or deployment issue (HTTP server on one port, websocket server on another).

• HTTP is a request/reply protocol- a client is requesting a piece of information from a server, and a TCP connection is maintained until a reply is issued. HTTP requests are specified using URLs, the format of which is likely familiar:

  		foo://example.com:8042/over/there?name=ferret#nose
  		\_/   \______________/\_________/ \_________/ \__/
  		|           |            |            |        |
  		scheme   authority       path        query   fragment
  

  (ref: http://tools.ietf.org/html/rfc3986)

  • The "path" portion of the HTTP request's URL should be parsed and used to determine which method in the OSC address space is being requested. The URL http://localhost:1234/foo/bar refers to the method "/foo/bar" in the OSC address space- further examples are provided below.
  • The "query" portion of the HTTP request's URL should be parsed and used to indicate which attributes are to be returned. The URL http://localhost:1234/foo/bar?VALUE refers to the "VALUE" attribute of the method "/foo/bar" found in the OSC address space. If a query is made for an attribute that the server doesn't support, it should return an error of type 204. Further examples are provided below.
  • The "fragment" portion of the request's URL should be stripped and disregarded.

• The server provides JSON objects (content-type "application/json") in response to HTTP requests. Each JSON object describes the OSC method at the requested URL, which will either correspond directly to an OSC method in the address space (the "path" component of the URL corresponds to the OSC address path), or to some specific attribute of the OSC method exposed by the protocol (in the case of URLs that contain query components).

• Instances of this server should advertise their presence (and look for other servers) on the local network using bonjour/zeroconf using the service type "_oscjson._tcp.". Connections to clients on remote networks can be established by the traditional means (manually entering an IP address/joining a VPN/etc).

• Errors should be handled by returning the HTTP error that most closely corresponds to the nature of the error you encountered. Examples of errors could include:

  • 204 (no content- server received request, but the request is inappropriate in some way- querying VALUE when ACCESS returned 0, for example)
  • 400 (bad request/syntax error- corrupt message/packet, querying an unrecognized attribute or a recognized attribute that isn't supported by the server, etc)
  • 404 (no container or method was found at the supplied OSC address)
  • 408 (request time-out- this error should be generated by the client if it doesn't hear back from the server in a specified time period)

Required Attributes

When the HTTP server receives a request for a URL, it returns a JSON object describing the OSC method referred to by the URL. These JSON objects consist of key:value pairs- following is a list of the minimum attributes that clients/servers must support to implement the core functionality of this proposal. These attributes are categorized as "required" because if they're missing- or inaccurate- then this pro