API OSC

Open Sound Control (OSC) UDP networking provides realtime access to multimedia software and hardware devices. Our OSC API allows bi-directional event commands and streaming object attritube tracks. Can directly use our native schema (such as ANTz<->ANTz) or map a 3rd party schema to ANTz using a table or learning-mode. There are literally hundreds of OSC devices, ranging from EEG headsets to LED concert lighting.

• Setup OSC UDP Networking
• Map 3rd Party OSC Schema to ANTz
• Understanding OSC

Setup OSC UDP Networking

OSC is typically streamed on an isolated LAN using UDP. You can connect through your existing IP router or setup an adhoc network. You will need to manually configure the OSC ports and IP addresses.

We reccomend using the Hexler TouchOSC tutorial for learning how to setup an OSC over UDP Network:

https://hexler.net/docs/touchosc-getting-started

You can test with your smartphone using the ($5) TouchOSC app or other (free) OSC apps. You can also use pD-extended on a PC or Mac, (based on MAX programming language).

To guarantee Quality of Service (QoS) for live events, you need to use specific hardware, preferably an AVB Ethernet Switch and certain brands of WiFi access points.

Mapping 3rd Party OSC Schema to ANTz

You can directly map a 3rd party schema to antz using the np_osc table. Or you can teach ANTz by sending OSC signals from a 3rd party and having ANTz learn what command to respond with.

Generally, 3rd party OSC Address Schema's are relatively simple and tend to normalize all values as a 32bit signed float from 0.0 to 1.0, for example:

• 1/sliderX f 0.33
• 3/button/4 f 1.0

There are exceptions of course, OSC can send a variety of data, such as raw acccelerometer values or multi-pad buttons:

• 1/accelerometerXYZ fff 0.0122123 -0.9987233 -0.0112332
• 1/pad fffffffffffffffff 0.0 0.0 1.0 0.0 1.0 1.0 0....

Understanding OSC

• Address Schema
• AVB Ethernet Swithces
• OSC to MIDI Bridge

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

Open Sound Control (OSC) is typically implemented over UDP networking.

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

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 <br>
Encapsulated CSV, JSON, JPG, 3DS...<br>
3rd Party Schema<br>

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 <br>
Note 3rd party mapping middleware applications exist and MIDI bridges such as osculator <br>

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.<br>
All devices in the (Gigabit Ethernet) network need to be AVB compatible.<br><br>

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.

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

also see: [OSC_Schema] - [OSC_Spec] - [OSC_API] - [MySQL_API] - [Database]

updated 2013-02-01

---

AVB API - IEEE 802.1 Audio Video Bridging (AVB)

• Our AVB API provides network configuration access to AVB devices.
• IEEE 802.1 Audio Video Bridging (AVB) standard is related to IEEE 1722 and IEEE 1733 standards

*update AVB links that meyersound.com has taken offline. AVB Intro - by Meyer Sound AVB for Professional A/V (PDF) - by Rick Kreifeldt and contributors

Audio Video Bridging (AVB) provides guaranteed quality-of-service (QoS) for bandwidth and low-latency (0.25-2ms) over a (Gigabit) Ethernet topology. All devices in the network path need to be AVB compatible.

Here's a list of AVB switches