OSC_Schema

[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 docs and code are currently in progress, this is a DRAFT!!!

---

OSC Schema

• Data, IO and Commands are externally accessible using OSC over UDP
• Query System supports dynamically changing schemas
• 3rd Party communication and native peer-to-peer exchanges

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:

• Send message(s) in an OSC Bundle to provide a Time Tag
• Multiple messages per Bundle are okay
• Allow for generating multiple Bundles per Packet
• Avoid nesting Bundles within Bundles, though this is allowed by OSC
• Do support the ability to receive and parse bundles of bundles
• Pay attention to packet size, smaller packets are generally best for AV

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

• Element Address Tree
• Encapsulated CSV, JSON, JPG, 3DS...
• 3rd Party Schema

The OSC Router directs messages to one of the 3 Core OSC Schema Handlers:

---

Element Address Tree

• Base Data Types (integer, float, string) where the OSC address specifies the element
• Access all scene parameters such as globals, nodes and control commands

Mouse Move Update:
TX → /np/io/mouse/xy ii 876 186

---

Encapsulated

• CSV, JSON, JPG... or C structure as an OSC string or binary Blob
• Includes both the scene state and channel tracks for streaming
• Byte-for-Byte compatible with corresponding file types

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

• Can interrupt the stream: TX → /np/csv/nodes/get i 0

---

3rd Party Schema - Plugin

• Default handler for all messages that do NOT start with '/np/...'
• Direct support for TouchOSC, Lemur and GrandVJ (for now hard-coded)
• 3rd party address mapping stored as CSV/JSON files, akin to mapping [IO_Channels]

Set the 'amp' gain setting for a synthesizer:
→ /SYN/patch/1/amp i 22

• Future support for [Plugin_API] architecture to extend Core [C_API] functionality
• Future support for mapping 3rd party JSON schemas using our [JSON_OSC_Bridge]

3rd Party Schema examples and issues at [OSC_3rd_Party]

---

Time Tag

• 64bit integer in NTP format
• OSC has inconsistant Time Tag implementations!

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

• Large data structures and files are best broken up into multiple OSC Packets
• CSV and JSON should generally be separated per logical object or table row
• Data streams can be optimized for ideal network Packet Size (16KB)
• FC can handle the most IOPS about 250 thousand 16KB transfers
• High Bandwidth drives tend to work best at 4, 8 or 12MB read/write size
• Realtime AV networking tends to work best with smaller packet sizes
• Audio and Video IO devices require flow control

---

OSC Query System

• We may CHANGE our QUERY SYNTAX, there is currently a NEED FOR A STANDARD
• Commands that return parameters append '/echo' to the end of the address
• Requests append 'np/.../get' to the address

We need to provide functionality similar to the OSC Query System outlined in 2004 by Andrew W. Schmeder and Matthew Wright.

• Namespace discovery that supports dynamically changing schema
• Type Signature format descriptor for data containers and functions
• error handling: /np/.../err ,is 3424 'missing file'
• Documentation '/doc/name'
• Addresses Ending with a slash will echo a directory list of the branch

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.

• Commands are sent as individual messages or streamed as (command) tracks
• Most user commands are simple triggers using the OSC 'I' Impulse type
• HID devices such as keyboard and mice can have multiple parameters
• Direct C-API calls can be made to create new nodes, delete, etc.

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

• Get or Set globals, nodes and track animation using our OSC Address Space (Tree)

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

• C-Pointers are swapped for human-readable node ID's when externally exposed

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

• CSV files encapsulated as an OSC String 's'
• Can split files across multiple OSC Packets
• Channel tracks are sent over time in chunks

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

• End-of-Nodes signaled by sending ../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

• C-Struct over OSC and other binary data containers (JPG, 3DS....)
• Peer-to-Peer memory transfers of scene state and animation
• Flow Control optimized Packet size and data rate
• Ideal for Cluster Computing and HPC systems such as CAVE environments

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

• Translator between JSON streams and OSC Address Space
• Unified Schema with direct access to the Core [C_API]
• Unified Descriptor that is compatible with OSC, JSON and our [Plugin_API]

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

• JSON-OSC Bridge is NOT the same as encapsulating 'JSON over OSC'

→ /np/json/nodes s '...JSON stream of all nodes in JSON format'