Recent changes to OSC_API

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Wed, 13 Feb 2013 04:28:22 -0000

--- v9
+++ v10
@@ -2,7 +2,7 @@

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

-updated 2013-02-08
+updated 2013-02-12

 OSC docs and code are in development, this is a DRAFT!!!
 ----
@@ -12,9 +12,11 @@

 READ THIS FIRST: [Everything-About-OSC.mov - DOWNLOAD](http://opensoundcontrol.org/files/Everything-About-OSC.mov)

-[Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [osculator](http://www.osculator.net), [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).
+[Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [osculator](http://www.osculator.net), [TouchOSC](http://hexler.net/software/touchosc), [Mrmr](http://mrmr.noisepages.com) or [LEMUR](http://liine.net/en/products/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.

@@ -28,9 +30,8 @@
 - OSC over UDP supports multicast
 - AVB devices can provide quality-of-service (QoS) for OSC
 - Inter-operability with 3rd party OSC hardware and software
-- Mapping custom control interfaces and MIDI
 - OSC-JSON Bridge for web services
-- Cross-Platform libraries for C, C++, Python and Java
+- Cross-Platform libraries for C, C++, Python, Java and more

 ----
 Issues:
@@ -43,7 +44,7 @@
 Packets, Bundles & Messages

 - OSC Client sends OSC Packets to the OSC Server(s)
-- An OSC Packet contains at least on Message(s) and/or Bundle(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
@@ -63,16 +64,24 @@
 ----
 OSC Address Schema

-Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. In general the base data types are more compatible with 3rd parties. We also support spefiic 3rd party schema's as plugins.
+Our 3 Core OSC Handlers

-- Future support planned for dynamic mapping of 3rd party OSC schemas.
+- 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](http://www.osculator.net)

-Base Data Types are 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.
+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 sending 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.
+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

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Sat, 09 Feb 2013 01:13:30 -0000

--- v8
+++ v9
@@ -1,6 +1,6 @@
 [Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at [openANTz.com](http://openantz.com/)

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

 updated 2013-02-08

@@ -18,7 +18,7 @@

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

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

 [oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library we use for low-level OSC message handling by our [Core C-API]([C_API]) using a C wrapper for C++ calls.

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Sat, 09 Feb 2013 01:12:47 -0000

--- v7
+++ v8
@@ -1,9 +1,8 @@
-
 [Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at [openANTz.com](http://openantz.com/)

-also see: [OSC_Schema] - [OSC_Spec] - [Database]
+also see: [OSC_Schema] - [OSC_Spec] - [OSC_JSON_Bridge] - [Database]

-updated 2013-02-05
+updated 2013-02-08

 OSC docs and code are in development, this is a DRAFT!!!
 ----
@@ -11,15 +10,15 @@
 ----
 OSC API - OSC over UDP

-[Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).
-
 READ THIS FIRST: [Everything-About-OSC.mov - DOWNLOAD](http://opensoundcontrol.org/files/Everything-About-OSC.mov)

-Our [OSC_Schema] defines the address space to access to scene data and control commands.
+[Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [osculator](http://www.osculator.net), [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).

-[OSC_Spec] - OSC 1.0 Spec and 1.1 addendum. Also a proposed Query System.
+[OSC_Schema] - Our message Address Space for access to scene data and control commands.

-[JSON_OSC_Bridge] - Translator between OSC Message address space and JSON.
+[OSC_Spec] - We use OSC 1.0 Spec and 1.1 Spec addendum, plus an OSC Query System.
+
+[OSC_JSON_Bridge] - Translator between OSC Message address space and JSON.

 [oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library we use for low-level OSC message handling by our [Core C-API]([C_API]) using a C wrapper for C++ calls.

@@ -30,7 +29,7 @@
 - AVB devices can provide quality-of-service (QoS) for OSC
 - Inter-operability with 3rd party OSC hardware and software
 - Mapping custom control interfaces and MIDI
-- JSON-OSC Bridge for web services
+- OSC-JSON Bridge for web services
 - Cross-Platform libraries for C, C++, Python and Java

 ----

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Tue, 05 Feb 2013 09:05:49 -0000

--- v6
+++ v7
@@ -1,3 +1,4 @@
+
 [Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at [openANTz.com](http://openantz.com/)

 also see: [OSC_Schema] - [OSC_Spec] - [Database]
@@ -6,17 +7,19 @@

 OSC docs and code are in development, this is a DRAFT!!!
 ----
+
+----
 OSC API - OSC over UDP

 [Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).

 READ THIS FIRST: [Everything-About-OSC.mov - DOWNLOAD](http://opensoundcontrol.org/files/Everything-About-OSC.mov)

-[OSC_Schema] - Defines our message address schema to access data and control commands
+Our [OSC_Schema] defines the address space to access to scene data and control commands.

-[OSC_Spec] - OSC 1.0 Spec and 1.1 addendum. Also a proposed Query System
+[OSC_Spec] - OSC 1.0 Spec and 1.1 addendum. Also a proposed Query System.

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

 [oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library we use for low-level OSC message handling by our [Core C-API]([C_API]) using a C wrapper for C++ calls.

@@ -49,8 +52,6 @@

 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.

-Each OSC Bundle contains a Time Tag
-
 ----
 OSC Time Tag - implementations vary!!

@@ -61,23 +62,23 @@
 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 Schemas
+OSC Address Schema

-Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. In general the base data types are more compatible with 3rd parties. We also support specific 3rd party schema's as plugins.
+Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. In general the base data types are more compatible with 3rd parties. We also support spefiic 3rd party schema's as plugins.

-- Future support planned for dynamic mapping of 3rd party OSC schemas
-- 3rd party OSC schema mapping middleware exists and MIDI bridges such as [osculator](http://www.osculator.net)
+- Future support planned for dynamic mapping of 3rd party OSC schemas.
+- Note 3rd party mapping middleware applications exist and MIDI bridges such as [osculator](http://www.osculator.net)

-Base Data Types are 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 is because an entire message is constructed for each element, such as an integer, float or string.
+Base Data Types are 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 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 numbers. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with the CSV file structures. Note that CSV tables can be directly imported or exported with MySQL.
+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 sending 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.

 ----
 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 JavaScript or PHP....
+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)

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Tue, 05 Feb 2013 08:38:11 -0000

--- v5
+++ v6
@@ -2,51 +2,90 @@

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

-updated 2013-02-01
+updated 2013-02-05

 OSC docs and code are in development, this is a DRAFT!!!
 ----
-OSC API - OSC over UDP (with planned JSON bridge.)
+OSC API - OSC over UDP

 [Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).

 READ THIS FIRST: [Everything-About-OSC.mov - DOWNLOAD](http://opensoundcontrol.org/files/Everything-About-OSC.mov)

-Our [OSC_Schema] describes the way in which 3rd party OSC enabled systems can communicate with us.
+[OSC_Schema] - Defines our message address schema to access data and control commands

-[oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library currently used for low-level OSC message handling by our [Core C-API]([C_API]) using a C wrapper for C++ calls.
+[OSC_Spec] - OSC 1.0 Spec and 1.1 addendum. Also a proposed Query System
+
+[JSON_OSC_Bridge] - Translator between OSC Message address space and JSON
+
+[oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library we use for low-level OSC message handling by our [Core C-API]([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](http://emotiv.com) to [Arkaos GrandVJ](http://www.arkaos.net). It has become the main communication standard for realtime VR, DJ and VJ environments.

-Key Advantages:
-- Time-Tag Synchronization
+- 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
 - Mapping custom control interfaces and MIDI
-- OSC to JSON bridge for web services
+- JSON-OSC Bridge for web services
 - Cross-Platform libraries for C, C++, Python and Java

+----
 Issues:
-- Inconsistent implementations of Time-Tag Sync
-- Does NOT guarantee bandwidth or latency
+
+- 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 least on 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.
+
+Each OSC Bundle contains a Time Tag
+
+----
+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.

-Time-Tag implementations vary. 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 or preferably using hardware based gen-lock from a common house-sync such as a black-burst generator.
+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.

-Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. 
+----
+OSC Address Schemas

-Base Data Types are 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.
+Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. In general the base data types are more compatible with 3rd parties. We also support specific 3rd party schema's as plugins.

-Encapsulating data 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 numbers. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with the CSV file structures. Note that the CSV tables can be directly imported or exported with MySQL.
+- Future support planned for dynamic mapping of 3rd party OSC schemas
+- 3rd party OSC schema mapping middleware exists and MIDI bridges such as [osculator](http://www.osculator.net)
+
+Base Data Types are 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 is because an entire message is constructed for each element, such as an integer, float or string.
+
+Encapsulating data 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 numbers. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with the CSV file structures. Note that CSV tables can be directly imported or exported with MySQL.

 Further performance can be achieved by sending 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.

 ----
-OSC - JSON Bridge
+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....
+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 JavaScript 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
@@ -54,6 +93,3 @@
 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].
-
-----
-OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or the more advanced Lemur.

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Sat, 02 Feb 2013 00:52:58 -0000

--- v4
+++ v5
@@ -2,13 +2,15 @@

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

-updated 2013-01-31
+updated 2013-02-01

-OSC docs and code are currently in progress, this is a DRAFT!!!
+OSC docs and code are in development, this is a DRAFT!!!
 ----
 OSC API - OSC over UDP (with planned JSON bridge.)

 [Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).
+
+READ THIS FIRST: [Everything-About-OSC.mov - DOWNLOAD](http://opensoundcontrol.org/files/Everything-About-OSC.mov)

 Our [OSC_Schema] describes the way in which 3rd party OSC enabled systems can communicate with us.

@@ -25,8 +27,9 @@

 Issues:
 - Inconsistent implementations of Time-Tag Sync
+- Does NOT guarantee bandwidth or latency
 - Only specifies a simple set of data types
-- Does NOT guarantee bandwidth or latency
+- OSC Query System methods NEED A STANDARD

 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.

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Fri, 01 Feb 2013 00:53:17 -0000

--- v3
+++ v4
@@ -1,12 +1,16 @@
-[Home] - [Developer_Guide] - [Network_API] hosted at [openANTz.com](http://openantz.com/)
+[Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at [openANTz.com](http://openantz.com/)

-also see: [OSC_Schema] - [Database]
+also see: [OSC_Schema] - [OSC_Spec] - [Database]
+
+updated 2013-01-31

 OSC docs and code are currently in progress, this is a DRAFT!!!
 ----
 OSC API - OSC over UDP (with planned JSON bridge.)

 [Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).
+
+Our [OSC_Schema] describes the way in which 3rd party OSC enabled systems can communicate with us.

 [oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library currently used for low-level OSC message handling by our [Core C-API]([C_API]) using a C wrapper for C++ calls.

@@ -50,16 +54,3 @@

 ----
 OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or the more advanced Lemur.
-
-----
-OSC 1.1 Base Data Types (required)
-
-i - Integer: two’s complement int32
-f - Float: IEEE float32
-s - NULL-terminated ASCII string
-b - Blob, (aka byte array) with size
-T - True: No bytes are allocated in the argument data.
-F - False: No bytes are allocated in the argument data.
-N - Null: (aka nil, None, etc). No bytes are allocated in the argument data.
-I - Impulse: (aka “bang”), used for event triggers. No bytes are allocated in the argument data.
-t - Timetag: an OSC timetag in NTP format, encoded in the data section

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Fri, 01 Feb 2013 00:15:43 -0000

--- v2
+++ v3
@@ -4,12 +4,13 @@

 OSC docs and code are currently in progress, this is a DRAFT!!!
 ----
-OSC over UDP (with planned JSON bridge.)
+OSC API - OSC over UDP (with planned JSON bridge.)

-Open Sound Control (OSC) is our primary network protocol to communicate peer-to-peer and with 3rd parties.
-It provides direct support to [NeatTools] and other OSC systems such as TouchOSC.
+[Open Sound Control (OSC)](http://opensoundcontrol.org) is our primary network protocol to communicate peer-to-peer and with 3rd parties. It provides direct access to [NeatTools](https://sourceforge.net/projects/neattools/) and other OSC systems such as [TouchOSC](http://hexler.net/software/touchosc) or [LEMUR](http://liine.net/en/products/lemur/).

-OSC is primarily used for networking digital media control signals. It is supported by many multimedia related hardware and software systems, ranging from Emotiv's EEG headset to Arkaos GrandVJ. It has become the main communication standard for interactive systems used for VR, DJ and VJ environments.
+[oscpack](http://www.rossbencina.com/code/oscpack) is the C++ library currently used for low-level OSC message handling by our [Core C-API]([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](http://emotiv.com) to [Arkaos GrandVJ](http://www.arkaos.net). It has become the main communication standard for realtime VR, DJ and VJ environments.

 Key Advantages:
 - Time-Tag Synchronization
@@ -48,7 +49,7 @@
 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].

 ----
-OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or Vxxxx. 
+OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or the more advanced Lemur.

 ----
 OSC 1.1 Base Data Types (required)

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Thu, 31 Jan 2013 07:27:09 -0000

--- v1
+++ v2
@@ -1,6 +1,6 @@
 [Home] - [Developer_Guide] - [Network_API] hosted at [openANTz.com](http://openantz.com/)

-also see: [OSC_Schema] - [Database] - [MySQL_API] - [SNMP_API] - [FC_API] - [IP_API]
+also see: [OSC_Schema] - [Database]

 OSC docs and code are currently in progress, this is a DRAFT!!!
 ----
@@ -23,31 +23,32 @@
 - Only specifies a simple set of data types
 - Does NOT guarantee bandwidth or latency

-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-stamp to enable proper re-ordereding of the data which allows events to be synchronized.
+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.

-Time-Tag implementations vary. 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. Preferably all clocks are synced or gen-locked to a common house-sync such as a black-burst generator.
+Time-Tag implementations vary. 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 or preferably using hardware based gen-lock from a common house-sync such as a black-burst generator.

 Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated. 

-Base Data Types are 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.
+Base Data Types are 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 as CSV tables or JSON trees allows for greater performance. This can be done with the OSC 's' base type (ASCII string,) using human-readable numbers. Further performance can be achieved by sending blocks of binary data as an OSC Blob, base type 'b' is an array with 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.
+Encapsulating data 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 numbers. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with the CSV file structures. Note that the CSV tables can be directly imported or exported with MySQL.

-OSC provides no standard for video/images or sound, in general we can package image sequences as individual files and send them as a binary Blob with audio separately packaged on a per frame bases. Its up to the application to know how to interpret them and it may be better to use other protocols that have various bandwidth strategies.
+Further performance can be achieved by sending 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.

-The other is in packaging the CSV tables as long (OSC Blob type) strings. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with CSV file structures. Note that the CSV tables can be directly imported or exported with MySQL. The data tree structure though is not formally defined this way, in the future we plan to use the same table structure for a full JSON (tree) This may later be extended into a OSC-JSON schema. JSON would enable communications with web services driven by such things as Java Script or PHP,...
+----
+OSC - JSON Bridge

-Future support is planned for an OSC - JSON bridge. JSON is similar to XML with enhanced methods for describing data types and tree structures. One advantage will be the ability to talk directly with web applications based on PHP or other languages.
+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....

-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, see [SNMP_API].
+----
+Audio / Video

-OSC over UDP transports numbers, text and tables as human-readable CSV strings. The CSV tables are directly compatible with MySQL.
+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].
+
+----
 OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or Vxxxx. 
-
-OSC is used for transporting several data types, including CSV, JSON and binary. This is in addition to the OSC schema base types. That is the entire scene state can be transported by either encapsulated files as OSC strings or directly access each component by base type through the OSC schema.
-
-This allows sending node and channel data between systems using the same format.

 ----
 OSC 1.1 Base Data Types (required)

WikiPage OSC_API modified by Shane Saxon

Shane Saxon — Thu, 31 Jan 2013 06:43:12 -0000

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

also see: [OSC_Schema] - [Database] - [MySQL_API] - [SNMP_API] - [FC_API] - [IP_API]

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

OSC over UDP (with planned JSON bridge.)

Open Sound Control (OSC) is our primary network protocol to communicate peer-to-peer and with 3rd parties.
It provides direct support to [NeatTools] and other OSC systems such as TouchOSC.

OSC is primarily used for networking digital media control signals. It is supported by many multimedia related hardware and software systems, ranging from Emotiv's EEG headset to Arkaos GrandVJ. It has become the main communication standard for interactive systems used for VR, DJ and VJ environments.

Key Advantages:
- Time-Tag Synchronization
- Inter-operability with 3rd party OSC hardware and software
- Mapping custom control interfaces and MIDI
- OSC to JSON bridge for web services
- Cross-Platform libraries for C, C++, Python and Java

Issues:
- Inconsistent implementations of Time-Tag Sync
- Only specifies a simple set of data types
- Does NOT guarantee bandwidth or latency

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-stamp to enable proper re-ordereding of the data which allows events to be synchronized.

Time-Tag implementations vary. 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. Preferably all clocks are synced or gen-locked to a common house-sync such as a black-burst generator.

Two methods for sending data over OSC are implemented, Base Data Types and Encapsulated.

Base Data Types are 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.

Encapsulating data as CSV tables or JSON trees allows for greater performance. This can be done with the OSC 's' base type (ASCII string,) using human-readable numbers. Further performance can be achieved by sending blocks of binary data as an OSC Blob, base type 'b' is an array with 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.

OSC provides no standard for video/images or sound, in general we can package image sequences as individual files and send them as a binary Blob with audio separately packaged on a per frame bases. Its up to the application to know how to interpret them and it may be better to use other protocols that have various bandwidth strategies.

The other is in packaging the CSV tables as long (OSC Blob type) strings. This makes for a direct way to transmit the entire scene and animation in a way that is byte compatible with CSV file structures. Note that the CSV tables can be directly imported or exported with MySQL. The data tree structure though is not formally defined this way, in the future we plan to use the same table structure for a full JSON (tree) This may later be extended into a OSC-JSON schema. JSON would enable communications with web services driven by such things as Java Script or PHP,...

Future support is planned for an OSC - JSON bridge. JSON is similar to XML with enhanced methods for describing data types and tree structures. One advantage will be the ability to talk directly with web applications based on PHP or other languages.

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, see [SNMP_API].

OSC over UDP transports numbers, text and tables as human-readable CSV strings. The CSV tables are directly compatible with MySQL.

OSC tends to be supported by areas of technology focused on interactivity with live sound and video. Including motion capture, EEG and VJ software. There are a variety of tools including customizable control interfaces such as TouchOSC or Vxxxx.

OSC is used for transporting several data types, including CSV, JSON and binary. This is in addition to the OSC schema base types. That is the entire scene state can be transported by either encapsulated files as OSC strings or directly access each component by base type through the OSC schema.

This allows sending node and channel data between systems using the same format.

OSC 1.1 Base Data Types (required)

i - Integer: two’s complement int32
f - Float: IEEE float32
s - NULL-terminated ASCII string
b - Blob, (aka byte array) with size
T - True: No bytes are allocated in the argument data.
F - False: No bytes are allocated in the argument data.
N - Null: (aka nil, None, etc). No bytes are allocated in the argument data.
I - Impulse: (aka “bang”), used for event triggers. No bytes are allocated in the argument data.
t - Timetag: an OSC timetag in NTP format, encoded in the data section