OSC_API

[Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at openANTz.com

also see: [OSC_Schema] - [OSC_Spec] - [JSON_OSC_Bridge] - [Database]

updated 2013-02-12

OSC docs and code are in development, this is a DRAFT!!!

---

OSC API - OSC over UDP

READ THIS FIRST: Everything-About-OSC.mov - DOWNLOAD

Open Sound Control (OSC) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to NeatTools and other OSC systems such as osculator, TouchOSC, Mrmr or LEMUR.

[OSC_Schema] - Our message Address Space for access to scene data and control commands.

[OSC_3rd_Party] - Examples of OSC Message Addresses and issues

[OSC_Spec] - We use OSC 1.0 Spec and 1.1 Spec addendum, plus an OSC Query System.

[JSON_OSC_Bridge] - Translator between OSC Message address space and JSON.

oscpack is the C++ library we use for low-level OSC message handling by our Core C-API using a C wrapper for C++ calls.

OSC was designed as a MIDI replacement and is primarily used for networking digital media control signals. It is supported by several types of multimedia related hardware and software systems, ranging from Emotiv's EEG headset to Arkaos GrandVJ. It has become the main communication standard for realtime VR, DJ and VJ environments.

• Time Tag Synchronization
• OSC over UDP supports multicast
• AVB devices can provide quality-of-service (QoS) for OSC
• Inter-operability with 3rd party OSC hardware and software
• OSC-JSON Bridge for web services
• Cross-Platform libraries for C, C++, Python, Java and more

---

Issues:

• OSC Time Tag implementations are inconsistent
• Only specifies a simple set of data types
• OSC Query System methods NEED A STANDARD

---

Packets, Bundles & Messages

• OSC Client sends OSC Packets to the OSC Server(s)
• An OSC Packet contains at one or more Message(s) and/or Bundle(s)
• Bundles can contain Bundles, allows recursion

OSC Spec 1.0
"The underlying network that delivers an OSC packet is responsible for delivering both the contents and the size to the OSC application. An OSC packet can be naturally represented by a datagram by a network protocol such as UDP. In a stream-based protocol such as TCP, the stream should begin with an int32 giving the size of the first packet, followed by the contents of the first packet, followed by the size of the second packet, etc."

The contents of an OSC packet must be either an OSC Message or an OSC Bundle. The first byte of the packet's contents unambiguously distinguishes between these two alternatives.

---

OSC Time Tag - implementations vary!!

• Each OSC Bundle contains a 64bit Time Tag in NTP format.

UDP (and other protocols) can cause packets to arrive out of order and at different intervals resulting in jitter caused by variable latency. OSC addresses this by providing a Time-Tag to enable proper re-ordereding of the data which allows events to be synchronized.

We define our Time Tag as the source acquisition moment when events happened. This is to allow for proper AV synchronization when tracks get separated, processed and then re-combined. If acquisition time is not available then the source transmission clock will be used. If no Time Tag is available (such a with some 3rd party sources,) then all packets will be treated as immediate. System clocks can be synchronized using network protocols such as AVB master clock and/or gen-lock from a common house-sync such as a black-burst generator.

---

OSC Address Schema

Our 3 Core OSC Handlers

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

Data and Commands are made compatible with 3rd parties using both the Element Address Tree and direct support of 3rd Party Schema's.

• Future support planned for dynamic mapping of 3rd party OSC schemas using CSV or Plugin
• Note 3rd party mapping middleware applications exist and MIDI bridges such as osculator

Element Address Tree is the most inter-operable through use of a standard [OSC_Schema] that provides direct access to each component of the complete data tree. This includes control commands and the entire scene state with animation. This method is best suited for 3rd party communication and querying individual states. However it is not the most efficient in terms of bandwidth and processor (parsing) time for large chunks of data. This because an entire message is constructed for each element, such as an integer, float or string.

Encapsulating data such as CSV tables or JSON schema allows for greater performance. This can be done with the OSC 's' base type (ASCII string,) using human-readable text. This provides a direct way to transmit the entire scene and animation in a way that can be directly read from or written to file. Note that the CSV tables can be directly imported or exported with MySQL.

Further performance can be achieved by Encapsulating blocks of binary data as an OSC Blob, base type 'b' is an array with defined size. Binary is ideal for peer-to-peer memory transfers used for shared environments and HPC systems. To go even faster requires working directly with a lower-level protocol such as UDP, FC or ATM.

3rd Party Schema support has ability to learn new address mapping and store templates. Also handles conversion of native node attribute range (-180 to 180, 0 to 360, 0 - 255, etc.) to OSC standard NORMALIZED 0.0 to 1.0 float. Optional format conversion using slope intercept 'y=mx+b' function(s).

---

JSON - OSC Bridge

In the future we plan to use the same table structure wrapped with a JSON schema using one of the standard types of JSON trees, (need to choose one.) JSON is similar to XML but with enhanced methods for describing data types and tree structures. This will facilitate creating an OSC-JSON Bridge to communicate with web services driven by such things as Java Script or PHP....

---

Audio Video Bridging (AVB)

• AVB can provide quality-of-service (QoS) for OSC networks.
• All devices in the (Gigabit Ethernet) network need to be AVB compatible.

See [AVB_API] for further details...

---

Audio / Video

OSC provides no standard for video/images or sound. We can package video using image sequences based on individual frame files and send them as a binary Blob. The corresponding audio segment can be contained within the same OSC bundle as a separate message. Will also need to pay attention to flow control and may be necessary to break up frames across multiple bundles to increase performance and stability. Its up to the application to know how to interpret them and it may be better to use other protocols that have various flow control strategies.

Bandwidth and latency can be addressed with other mechanisms in conjunction with OSC such as AVB based networks. Though support is limited, often the solution is custom dedicated networks with direct configuration of the network hardware. This can be achieved through manual setup or remotely automated using SNMP to configure hardware, see [SNMP_API].