[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 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.
Issues:
Packets, Bundles & Messages
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!!
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
Data and Commands are made compatible with 3rd parties using both the Element Address Tree and direct support of 3rd Party Schema's.
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)
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].
Wiki: AVB_API
Wiki: C_API
Wiki: Database
Wiki: Developer_Guide
Wiki: Home
Wiki: JSON_OSC_Bridge
Wiki: MySQL_API
Wiki: Network_API
Wiki: OSC_3rd_Party
Wiki: OSC_API
Wiki: OSC_Schema
Wiki: OSC_Spec
Wiki: Plugin_API