[Home] - [Developer_Guide] - [Network_API] - [OSC_API] - [OSC_Schema] - hosted at openANTz.com
also see: [OSC_Spec] - [OSC_3rd_Party] - [JSON_OSC_Bridge] - [MySQL_API] - [File_Types]
updated 2012-02-08
OSC Schema
OSC Schema based on our [OSC_Spec]
3rd Party Schema examples and issues at [OSC_3rd_Party]
This document describes our OSC schema Address Space and parameter Arguments.
Packets, Bundles & Messages
Guidelines:
Document Syntax - Type Tag Signatures are preceded by a comma:
'si' is really ',si' and there is padding for (32bit) 4-byte alignment
example: /np/node/42/translate/xyz fff 22.5 7.5 0.0
See [OSC_Spec] for details on Packet structure, Bundles and Time Tag semantics.
Our 3 Core OSC Handlers
The OSC Router directs messages to one of the 3 Core OSC Schema Handlers:
Element Address Tree
Mouse Move Update:
TX → /np/io/mouse/xy ii 876 186
Encapsulated
Request all nodes as a CSV string, breaks up into multiple 16KB OSC Packets
Last packet includes '../end' Message that provides Packet tally
TX → /np/csv/nodes/get i 1
...
RX ← /np/csv/nodes is 1 'id,type...size,..1,2,3...420'
...
RX ← /np/csv/nodes is 505 '8242,2,3...420'
RX ← /np/csv/nodes/end i 505
3rd Party Schema - Plugin
Set the 'amp' gain setting for a synthesizer:
→ /SYN/patch/1/amp i 22
3rd Party Schema examples and issues at [OSC_3rd_Party]
Time Tag
Time tags are represented by a 64 bit fixed point number. The first 32 bits specify the number of seconds since midnight on January 1, 1900, and the last 32 bits specify fractional parts of a second to a precision of about 200 picoseconds. This is the representation used by Internet NTP timestamps.The time tag value consisting of 63 zero bits followed by a one in the least signifigant bit is a special case meaning "immediately."
Time-Tag implementations vary. We define our Time-Tag as the source acquisition moment when events happened. If acquisition time is not available then the source transmission clock should be used. If no Time-Tag is available (such a with some 3rd party sources,) then all packets will be treated as immediate.
OSC does NOT provide a standard for synchronizing clocks. System clocks can be synchronized using an AVB master clock or video gen-lock with network methods such as by the Equalizer library.
We re-order Commands using the Time-Tag and process the oldest messages first. Commands with an identical Time Tag have an un-defined processing order for that time segment.
Flow Control
OSC Query System
We need to provide functionality similar to the OSC Query System outlined in 2004 by Andrew W. Schmeder and Matthew Wright.
Example that sends mouse position then requests it using '/get':
TX → /np/io/mouse/xy ii 876 322
TX → /np/io/mouse/xy/get i 1
...
RX ← /np/io/mouse/xy ii 876 322
Query the mouse parameters
TX → /np/io/mouse/
...
RX ← /np/io/mouse/xy/echo ii
RX ← /np/io/mouse/x/echo i
RX ← /np/io/mouse/y/echo i
...
RX ← /np/io/mouse/button/../echo
The '/../echo' indicates a branch folder, search deeper
TX → /np/io/mouse/button/
...
RX ← /np/io/mouse/button/1/echo i
...
RX ← /np/io/mouse/button/4/echo i
Request a jpg file used as a texture map:
TX → /np/jpg/map00001/get i 1
...
RX ← /np/jpg/map00001 ib 1 '...size, then jpeg file as binary blob'
RX ← /np/jpg/map00001 ib 2 '...size, then jpeg file as binary blob'
...
RX ← /np/jpg/map00001 ib 322 '..end of file'
RX ← /np/jpg/map00001/end i 322
...or report that the file does not exist:
RX ← /np/jpg/map00001/err i 3424
Control Commands
OSC Messages that start with '/np/cmd/...' call defined functions in the C-API by passing parameters as OSC Arguments. Some functions #reply using our OSC Query System syntax.
Individual data elements and commands can be directly accessed via the'/np/map/...' or '/np/cmd/...' portion of the schema.
Alternately data can be transmit as CSV strings that contain nodes, tags, channels and tracks. CSV files are sent as an OSC 's' string type (NULL-terminated ASCII string.) It is possible to use tracks for command event types including additional parameters, ie: mouse events.
Send or receive commands available to the user GUI, console and/or direct C-API.
→ /np/cmd/select/id i 42
→ /np/cmd/select/range ii 200 300
→ /np/cmd/select/id[200-300] ....note that this has same result as .../range ii
→ /np/cmd/select/filter i 1
→ /np/cmd/select/color_index/[1-5] i 0 (exclude objects with color index 1-5)
→ /np/cmd/select/branch_level/[3-28] i 1
→ /np/cmd/mysql/query s 'boolean logic, etc...'
→ /np/cmd/select/all i 1
→ /np/cmd/select/none i 1
Control Commands that Echo
Example that creates a new node attached to parent_id 42:
TX → /np/cmd/new/node ii 42 0
RX ← /np/cmd/new/node/echo ii 42 43
Triggers a reply that echoes the parent_id followed by the new node_id.
Alternately, can generate a new node based on the current selection without declaring a parent_id, akin to the user pressing 'N' key.
Example returns a root node with parent_id = 0 and new node id = 42
→ /np/cmd/event/new i 1
← /np/cmd/event/new/echo ii 0 42
Replies with the new node_id, but does not specify parent_id. However, can use the node_id to query its attributes.
MySQL example:
→ /np/cmd/mysql/refresh/node[42-256] i 1
← /np/cmd/mysql/refresh/node[42-256]/echo s 'done'
Scene Data
Address shortcuts are used:
'data->map.node[42]->hide' becomes '/np/node/42/hide'
Request a list of all attributes for node id 42:
→ /np/node/42/*/get
← /np/node/42/id i 42
← /np/node/42/type i 7
← /np/node/42/parentID i 41
....
← /np/node/42/size 420
Note the redundancy of the first reply with argument id 42. This is a natural result of converting the C-pointer data structures to OSC Address Space paths. The node stores its id as and integer so it shows up in both the address path and as argument parameter.
Alternate method that returns all attributes in one message:
→ /np/node/42/get
← /np/node/42 siii....i 42 1 2... 420
Sets the RGBA color using the color_index:
→ /np/node/42/color/index i 7
Alternate method that directly sets RGBA and by-passess the color_index
→ /np/node/42/color/rgba iiii 255 255 128 255
Alternate method that sets RGBA using floats 0-1.0
→ /np/node/42/color/rgba ffff 1.0 1.0 0.5 1.0
Example that sends 4 samples belonging to track 22:
→ /np/track/22 iiii 200 205 210 215
CSV over OSC
Request all nodes as a CSV string, 1 to start stream, 0 to cancel
Sends CSV with header followed with nodes in blocks of 16 node rows per OSC Packet
TX → /np/csv/nodes/get i 1
RX ← /np/csv/nodes s 'id,type...size,..16,2,3...420'
...
RX ← /np/csv/nodes s '17,...420'
RX → /np/csv/nodes i 0
Request a single node (row) as a CSV string:
→ /np/csv/node/42/get i 1
← /np/csv/node/42 s '42,2,3...420'
Request a range of nodes, can also query /np/csv/tags, chmap, etc...
→ /np/csv/node/[1-42]/get i 1
← /np/csv/node/1 s '1,2,3,...420'
← /np/csv/node/2 s '2,...420'
...
← /np/csv/node/42 s '42,...420'
/np/csv/node/42 - a single node (table row by id)
/np/csv/node/[1-42] - a specific range of nodes
Channel mapping and tracks can be encapsulated using JSON or CSV strings.
→ /np/csv/track/get is 16384 '...CSV string'
Binary Blob
equest a jpg file used as a texture map:
TX → /np/jpg/map00001/get i 1
RX ← /np/jpg/map00001 ib 1 '...size, then jpeg file as binary blob'
RX ← /np/jpg/map00001 ib 2 '...size, then jpeg file as binary blob'
...
RX ← /np/jpg/map00001 ib 322 '..end of file'
RX ← /np/jpg/map00001/end i 322
...or report that the file does not exist:
RX ← /np/jpg/map00001/err i 3424
Example of node id=42 sent as a C-struct, specifies size in bytes followed by binary data:
TX → /np/c/node/42/get
→ /np/c/id/42 ib 420 6A8B.... node as a binary C struct
*we may also support ranges '/np/id/[1-42]/color' send RGBA colors for nodes 1-42.
IO devices
Raw System Events:
→ /np/io/key/ascii/down/42 i 1
→ /np/io/key/linux/up/42 i 1
→ /np/io/key/linux i i 42 1 (key, eventType - up, down, repeat, modifier...)
→ /np/io/mouse/xy ii
→ /np/io/mouse/x i
→ /np/io/mouse/y i
→ /np/io/mouse/left i 1
→ /np/io/mouse/middle i 1
→ /np/io/mouse/right i 1
→ /np/io/mouse/wheel i -1 (wheel can be -1, 0 or +1)
Related Parameters:
/np/cmd/mouse/mode/cam i (target node type: cam, grid, node...)
/np/cmd/mouse/tool/combo i
/np/cmd/mouse/target/id i (the active selection)
HID Devices:
/np/io/hid/mouse/2/button/1....(Support for multiple mice)
/np/io/hid/6dof/1/rotate/z/... (Other HID devices)
3rd Parties as Plugins:
/np/io/iz/headtrack/position/x f
/np/io/aja/video/in/1/ b
JSON-OSC Bridge
The JSON-OSC Bridge converts between JSON-HTTP-TCP/IP streams and OSC-UDP/IP Packets. A bi-directional a-synchronous network protocol bridge. It also provide direct access to the C-API and all exposed C-Struct elements.
See [JSON_OSC_Bridge] for further details.
JSON over OSC
→ /np/json/nodes s '...JSON stream of all nodes in JSON format'
Wiki: AVB_API
Wiki: C_API
Wiki: Developer_Guide
Wiki: File_Types
Wiki: Home
Wiki: IO_Channels
Wiki: JSON_OSC_Bridge
Wiki: MySQL_API
Wiki: Network_API
Wiki: OSC_3rd_Party
Wiki: OSC_API
Wiki: OSC_Schema
Wiki: OSC_Spec
Wiki: OSC_mapping
Wiki: Plugin_API