oscit

The “oscit” service is based on OpenSoundControl for packet format and is transported over UDP. The actual protocol is made of a small set of methods and some conventions.

The conventions should ease inter-application communication by providing ways to get/set properties and to receive return values. The conventions should help the machines work together.

The goal of the “oscit” methods is to offer the equivalent of the ”.h” header files in C: find answers to the questions: “what is there ?” and “what does it do ?”.

Author

• Gaspard Bucher – Buma, rubyk.org

Contributors to the oscit protocol:

• Jamie Bullock – postlude, Integra
• Gabriel Finch – salsaman, LiVES

get properties

To get the value of a proprety, simply call the url with no argument:

/some/object/property

set properties

To set the value of a proprety, simply call the url with an argument matching the type discovered during the get query:

/some/object/property <value>

What we show here with <value> can be anything from a single float to a list of many different parameter types.

advice: If you want your application to be easily controlled by human interaction through sliders, buttons or keyboards, it is better to have a single argument as <value> since this is easier to map.

return values

The return value of a get or set query is the same and is made of the called url with the current value:

/.reply "/some/object/property" <value>

All replies to queries are sent to the ”/.reply” url.

Return values are sent to the calling application and to all observers (see /.register below).

root

The url for the root node is "", not "/". This is because the slash (”/”) is a separator between names meaning “parent of”.

/foo/bar means: object ‘bar’ is a child of ‘foo’ which is a child of object ’’ (empty string)

This is the list of methods an “oscit” service must implement. All these methods are considered “meta” methods in the sense that they query for information on the actual and useful methods of the system. To indicate their special meaning and in order to avoid name collisions, all these methods live at the root ”/” and start with a dot ”.”.

/.register

This registers the calling application (controller) as an “observer” of the current application (service). This means that all return values of the following queries will be sent to this controller’s port.

/.info ”/some/url”

Returns a human readable information on a node (what it is, what it does) as an utf8 string in the following format:

/.reply "/.info" "/some/url" "Blah blah blah, this and that."

The query /.info ”” (info on root) returns information on the application itself.

/.list ”/some/url”

Returns an array strings listing the names of the children nodes under the given url. Should return nil if there are no children. Reply example:

/.reply "/.list" "/some/url" "foo" "bar" ...

/.tree ”/some/url”

Return an array of strings listing all nodes under the given parameter. For each node, the path under the called url is listed. For example here is a description of a tree with the osc reply:

/animals
/animals/mammals
/animals/mammals/tiger
/animals/mammals/tiger/Siberian
/animals/mammals/tiger/Bengal
/animals/mammals/mice
/animals/insects
/animals/insects/bee

/.reply "/.tree" "/animals/mammals" "tiger" "tiger/Siberian" "tiger/Bengal" "mice"

Note that the urls don’t end with a ”/” even if they have children because the information on these children is given by the list. Note also that the part of the calling url /animals/mammals with the separator ”/” is removed from the urls.

Calling ”/.tree” on the root node would give:

/.reply "/.tree" "" ".error" ".info" ... "animals" "animals/mammals" ... "animals/insects" "animals/insects/bee"

/.type ”/some/url”

Returns the type of a property in the following format:

/.reply "/.type" "/some/url" <type description>

The <type description> follows the following conventions:

type	type tag	meaning	example
range	fffs	current, min, max, info	4, 1, 16, “midi channel for main synth”
discrete values	sss	current value, list, info	“hsv”, “rgba,hsv,grey”, “background color for the main image”
any float	fs	current value, info	37.82, “oscillator frequency”

/.views

This is not a method but a container that should contain views to present the server’s elements. See views for details.

/.schema

Returns a root url and its corresponding schema:

/.reply "/.schema" "" "/oscit/some_name"

Multiple schemas:

/.reply "/.schema" "/foo" "/oscit/foo_protocol" 
/.reply "/.schema" "/bar" "/oscit/bar_protocol"

Methods to be implemented in the querying applications (satellites).

/.registration_ttl

Informs client of the time to live for the registration with a server (sent when time to live becomes less then 60 seconds and less then 30 seconds). If the client does not register again, the registration is removed.

/.reply

to be continued…

There are two types of errors that can occur:

1. bad url

An inexistant url is called. The reply must contain the “not found” error code:

/.error 404 "/the/bad/url"

2. bad arguments

When a method is called with the wrong type tags, the reply contains the “bad request” error code along with the same info string as the ”/.info” query (human readable information).

/.error 400 "/called/url" "info string"

A view is used to present the methods provided by an oscit resource as graphical elements. Views should be stored under /.views.

A view is an xml document like this:

<view x='100' y='100' width='200' height='200'>
  <slider id='1' x='10'  y='10' width='30'  height='150' connect='/tempo'/>
  <slider id='2' x='50'  y='10' width='30'  height='150' connect='/velocity'/>
  <button id='3' x='90'  y='10' width='30'  height='30'  connect='/tempo' value='100'/>
  <pad    id='4' x='130' y='10' width='150' height='150' connect[x]='/velocity' connect[y]='/tempo'/>
</view>

Once the views have been properly implemented, we shall provide a DTD.

Open source (MIT license) implementation of the oscit protocol.

Source code

The source code can be retrieved with git on github.com/rubyk/oscit.

Bug tracking

If anything seems wrong with this library, please open a ticket (if this seems too much, sent an email to the mailing-list).

Current status: alpha (works, but API may change without notice).