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)

Need update to change ’/.foo” into ”/osc/foo”.

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).

/osc/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.

/osc/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:

/osc/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).

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

The attributes are needed as meta information on the osc methods. Attributes are fetched with the /osc/attributes method. Example:

get

/osc/attributes "/some/url"

Reply:

/osc/reply "/osc/attributes" "/some/url" { hash with attributes }

set

/osc/attributes "/some/url" { some attributes to set }

Reply:

/osc/reply "/osc/attributes" "/some/url" { changed attributes }

Note that missing attributes in the hash are not removed or set to null: they are just ignored.

attributes schema

Here is the list of attributes currently used by oscit (note that “root” attributes that could be confused with methods in a serialized object have an ”@” sign):

• @info: human readable information describing the method
• @type: contains type information
  • name: type name such as “float”, “midi”, “range” (used to create default widgets)
  • signature: string containing the type tags signature like “f”, “m” (used for slot/call compatibility)
  • min: minimal value (optional, used by “float” type)
  • max: maximal value (optional, used by “float” type)
• @source: information to subscribe to a data source (can be a Hash or simply “true”)
  • uri: resource identifier to get data like “rtp://10.0.0.8:3488/stream1”
  • ...: other attributes to describe the data stream (depends on protocol)
• @view: information to display the object on a view or patch (an object/method without this information is not displayed in a view or patch)
  • widget: view widget to use in patch or view such as “Slider”, “Button”, “Script”, etc.
  • x : x position in patch or view
  • y : y position in patch or view
  • width: widget width
  • height: widget height
  • hue: widget color
• @targets: Hash containing the list of subscribed targets
• @class: class url to create Node (”/class/Metro” for example)

If the @source parameter is just “true”, this means that the subscription location is the object’s path, the protocol is “OSC” and the data stream will be encoded with OSC packets.

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

A view simply contains a list of methods that cannot be called and store the widget’s view information (class is null, type is not used):

/views/base {"view":{"widget":"Device", "x":100, "y":100, "width":200,
                     "height":200, "widget":"Device"}
/views/base/1 {"view":{"widget":"Slider", "x":10, "y":10, "width":30,
                       "height":150, "connect":"/l/tempo"}}
/views/base/2 {"view":{"widget":"Slider", "x":50, "y":10, "width":30,
                       "height":150, "connect":"/l/velocity"}}
/views/base/3 {"view":{"widget":"Pad""x", "x":50, "y":10, "width":30,
                       "height":150, "connect_x":"/l/velocity",
                       "connect_y":"/l/tempo"}}

Subscribing to a data source means that you will receive all data coming out of this source. This is different from notifications where you only receive values that are changed by an explicit call (from an interface usually).

In order to support subscriptions, a path must have the @source attribute. As noted above if this attribute is simply “true”, this means that the source can send OSC values and that subscription must be made by calling:

/osc/subscribe "/some/source", "osc://'device name'/path/to/target"

Once the subscription has been accepted, /some/source will send all values to the target:

osc://'device name'/path/to/target [value]

Subscriptions are serialized in the source’s attributes with the @targets key (a hash with keys as target URIs):

@targets:{"local/url":{}, "osc://'device name'/path/to/target":{}}

If the link to the target cannot be made, the link is kept in the “pending links” list and the server will retry when the target appears on the network.