Recent changes to OSC_Schema

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Wed, 13 Feb 2013 03:41:56 -0000

--- v9
+++ v10
@@ -1,20 +1,23 @@
 [Home] - [Developer_Guide] - [Network_API] - [OSC_API] - [OSC_Schema] - hosted at [openANTz.com](http://openantz.com/)

-also see: [OSC_Spec] - [JSON_OSC_Bridge] - [MySQL_API] - [File_Types]
+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 based on our [OSC_Spec]
+----
+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

-This document describes our OSC Schema address space and parameter arguments.
-
-example: /np/node/42/translate/xyz fff 22.5 7.5 0.0
+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
@@ -28,6 +31,11 @@
 - 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.

 ----
@@ -55,13 +63,17 @@
 - Includes both the scene state and channel tracks for streaming
 - Byte-for-Byte compatible with corresponding file types

-Request all nodes:
-TX → /np/csv/nodes/#current_value
-RX ← #reply ss '/np/csv/nodes/#current_value' 'id,type...size,..1,2,3...420'
-
-Request a jpg file used as a texture map:
-TX → /np/jpg/map00001/#current_value
-RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 '...jpeg file as binary blob'
+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
@@ -75,6 +87,8 @@

 - 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
@@ -105,30 +119,52 @@
 OSC Query System 

 - We may CHANGE our QUERY SYNTAX, there is currently a NEED FOR A STANDARD
-- Address Space used is valid, but not necessarily the syntax!
-
-We are using the [OSC Query System](http://opensoundcontrol.org/files/osc-query-system.pdf) outlined in 2004 by Andrew W. Schmeder and Matthew Wright.
+- 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](http://opensoundcontrol.org/files/osc-query-system.pdf) outlined in 2004 by Andrew W. Schmeder and Matthew Wright.

 - Namespace discovery that supports dynamically changing schema
-- Type Signature format descriptor
-- error handling
-- Documentation
-
-Example that sends mouse position then requests it using '/#current-value':
+- 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/#current-value
-RX ← #reply sii ’/np/io/mouse/x/#current-value’ 876 322
-
-See section '4.5.4 Current Value' of [OSC Schema System]([OSC_SPEC])
-
-NOTE that the query system is a draft and we may want to modify it.
-For example shorten '/#current-value' to perhaps just '#'.
-
-Also, assuming that '(si)' becomes just ',si' and remove comma after the address string... 
-
-doc ex: ← #reply (si) ’/np/io/mouse/x/#current-value’, 876
-becomes: #reply ,si ’/np/io/mouse/x/#current-value’ 876 - NEED TO VERIFY THIS!
+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
@@ -150,33 +186,38 @@
 → /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 T
-→ /np/cmd/select/color_index/\[1-5] F (exclude objects with color index 1-5)
-→ /np/cmd/select/branch_level/\[3-28] T 
+→ /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
-→ /np/cmd/select/none I
-
-----
-Control Commands that #reply
+→ /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 i 42
-RX ← #reply sii '/np/cmd/new/node' 42 43
+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 using the OSC 'I' Impulse type similar to a GPI-trigger:
-
-→ /np/cmd/event/new I
-← #reply si '/np/cmd/event/new' 44
+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
@@ -188,27 +229,30 @@

 Request a list of all attributes for node id 42:

-→ /np/node/42/*/#current_value
-
-← #reply si '/np/node/42/id/#current_value' 42
-← #reply si '/np/node/42/type/#current_value' 7
-← #reply si '/np/node/42/parentID/#current_value' 41
+→ /np/node/42/*/get
+
+← /np/node/42/id i 42
+← /np/node/42/type i 7
+← /np/node/42/parentID i 41
 ....
-← #reply si '/np/node/42/size/#current_value' 420
+← /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/#current_value
-← #reply siii....i '/np/node/42/#current_value' 42 1 2... 420
+→ /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
@@ -220,17 +264,32 @@
 - Can split files across multiple OSC Packets
 - Channel tracks are sent over time in chunks

-ex: /np/csv/nodes s 'id,type,parent_id....last node...420'
+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/id/\[1-42]/#current_value
-← /np/csv/id/\[1-42] s '1,2,3,...420'
-
-/np/csv/id/42 - a single node (table row by id)
-/np/csv/id/\[1-42] - a specific range of nodes
+→ /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/tracks is 16384 '...CSV string'
+→ /np/csv/track/get is 16384 '...CSV string'

 ----
 Binary Blob
@@ -240,18 +299,23 @@
 - Flow Control optimized Packet size and data rate
 - Ideal for Cluster Computing and HPC systems such as CAVE environments

-Get a JPG used for texture mapping:
-TX → /np/jpg/map00001/#current_value
-RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 'jpeg file as a binary blob'
-
-Example of node id=42 sent as a C-struct, first specifies the size in bytes followed by binary data.
-
+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

-Get the node as a binary C-struct (typically for peer-to-peer sharing):
-TX → /np/c/node/42/#current_value
-RX ← #reply sib '/np/c/node/42/#current_value' 420 'node C-struct as binary blob'
-
 *we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.

 ----
@@ -259,16 +323,16 @@

 Raw System Events:

-→ /np/io/key/ascii/down/42 I
-→ /np/io/key/linux/up/42 I
+→ /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/xy ii
 → /np/io/mouse/x i 
 → /np/io/mouse/y i
-→ /np/io/mouse/left T
-→ /np/io/mouse/middle F
-→ /np/io/mouse/right F
+→ /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:

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Sat, 09 Feb 2013 00:43:21 -0000

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

 also see: [OSC_Spec] - [JSON_OSC_Bridge] - [MySQL_API] - [File_Types]
@@ -74,7 +73,7 @@
 Set the 'amp' gain setting for a synthesizer:
 → /SYN/patch/1/amp i 22

-- Future support for [Plugin_API] architecture to extend [Core_API] functionality
+- 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]

 ----

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Sat, 09 Feb 2013 00:40:56 -0000

--- v7
+++ v8
@@ -1,30 +1,35 @@
-[Home] - [Developer_Guide] - [Network_API] - [OSC_API] - hosted at [openANTz.com](http://openantz.com/)
-
-also see: [OSC_Spec] - updated 2012-02-05
+
+[Home] - [Developer_Guide] - [Network_API] - [OSC_API] - [OSC_Schema] - hosted at [openANTz.com](http://openantz.com/)
+
+also see: [OSC_Spec] - [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 based on our [OSC_Spec]

-- Data, IO and Commands are externally accessible using OSC over UDP.
-- Support for 3rd Party OSC enabled systems and native peer-to-peer exchanges.
-- Query System for discovery and dynamic schema mapping
+- 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

 This document describes our OSC Schema address space and parameter arguments.

+example: /np/node/42/translate/xyz fff 22.5 7.5 0.0
+
 ----
 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.
-
-See [OSC_SPEC] for details on Packet structure, Bundles and Time Tag semantics.
+- 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
+
+See [OSC_Spec] for details on Packet structure, Bundles and Time Tag semantics.

 ----
 Our 3 Core OSC Handlers
@@ -38,9 +43,8 @@
 ---
 Element Address Tree

-1) Base Data Types (integer, float, string) where the OSC address specifies the element.
-
-- Access all scene parameters such as globals, nodes and control commands.
+- 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
@@ -48,14 +52,15 @@
 ----
 Encapsulated

-CSV, JSON, JPG... or C structure as an OSC string or binary Blob.
-
-- Includes both the scene state tables and channel tracks for streaming.
-
-Request all nodes, (can also query /np/csv/tags, chmap, etc...)
+- 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:
 TX → /np/csv/nodes/#current_value
 RX ← #reply ss '/np/csv/nodes/#current_value' 'id,type...size,..1,2,3...420'

+Request a jpg file used as a texture map:
 TX → /np/jpg/map00001/#current_value
 RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 '...jpeg file as binary blob'

@@ -63,13 +68,14 @@
 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.)
-- Future support for Plugin architecture to extend core functionality.
+- 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 a CSV table that maps any 3rd party schema, akin to [IO_Channels].
+- Future support for [Plugin_API] architecture to extend [Core_API] functionality
+- Future support for mapping 3rd party JSON schemas using our [JSON_OSC_Bridge]

 ----
 Time Tag
@@ -86,9 +92,21 @@
 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 

-- There is currently a NEED FOR A STANDARD. 
+- We may CHANGE our QUERY SYNTAX, there is currently a NEED FOR A STANDARD
+- Address Space used is valid, but not necessarily the syntax!

 We are using the [OSC Query System](http://opensoundcontrol.org/files/osc-query-system.pdf) outlined in 2004 by Andrew W. Schmeder and Matthew Wright.

@@ -97,32 +115,81 @@
 - error handling
 - Documentation

-Example that sets a value then requests the value using '/#current-value' for mouse x:
-
-TX → /np/io/mouse/x i 876
-TX → /np/io/mouse/x/#current-value
-RX ← #reply si ’/np/io/mouse/x/#current-value’ 876
+Example that sends mouse position then requests it using '/#current-value':
+
+TX → /np/io/mouse/xy ii 876 322
+TX → /np/io/mouse/xy/#current-value
+RX ← #reply sii ’/np/io/mouse/x/#current-value’ 876 322

 See section '4.5.4 Current Value' of [OSC Schema System]([OSC_SPEC])

 NOTE that the query system is a draft and we may want to modify it.
 For example shorten '/#current-value' to perhaps just '#'.

-Also, assuming that '(si)' becomes just 'si' and remove comma's... TRY TO VERIFY THIS!
+Also, assuming that '(si)' becomes just ',si' and remove comma after the address string... 
+
 doc ex: ← #reply (si) ’/np/io/mouse/x/#current-value’, 876
-becomes: ← #reply si ’/np/io/mouse/x/#current-value’ 876
-
-----
-Scene State Data
-
-Get or Set any parameter in the data tree including globals, nodes and channel track animation using an OSC Message address tree.
+becomes: #reply ,si ’/np/io/mouse/x/#current-value’ 876 - NEED TO VERIFY THIS!
+
+----
+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 T
+→ /np/cmd/select/color_index/\[1-5] F (exclude objects with color index 1-5)
+→ /np/cmd/select/branch_level/\[3-28] T 
+
+→ /np/cmd/mysql/query s 'boolean logic, etc...'
+
+→ /np/cmd/select/all I
+→ /np/cmd/select/none I
+
+----
+Control Commands that #reply
+
+Example that creates a new node attached to parent_id 42:
+
+TX → /np/cmd/new/node i 42
+RX ← #reply sii '/np/cmd/new/node' 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 using the OSC 'I' Impulse type similar to a GPI-trigger:
+
+→ /np/cmd/event/new I
+← #reply si '/np/cmd/event/new' 44
+
+Replies with the new node_id, but does not specify parent_id. However, can use the node_id to query its attributes.
+
+----
+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/id/42/*/#current_value
+→ /np/node/42/*/#current_value

 ← #reply si '/np/node/42/id/#current_value' 42
 ← #reply si '/np/node/42/type/#current_value' 7
@@ -130,37 +197,29 @@
 ....
 ← #reply si '/np/node/42/size/#current_value' 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/id/42/#current_value
+→ /np/node/42/#current_value
 ← #reply siii....i '/np/node/42/#current_value' 42 1 2... 420

-Set the Color for RGBA or just red:
-
-→ /np/node/42/color iiii 255 255 128 255
-→ /np/node/42/color/r i 255
-
-Binary Blob 'b':
-
-TX → /np/c/node/42/#current_value
-RX ← #reply sib '/np/node/42/#current_value' 420 'node C-struct as binary blob'
-
-TX → /np/jpg/map00001/#current_value
-RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 'jpeg file as a binary blob'
-
-----
-Channel Track Data
-
-Channel mapping and tracks can be encapsulated using JSON or CSV strings.
-→ /np/csv/tracks is 16384 '...CSV string'
-
-Or, they can be formatted as an OSC Address space, Example that adds 4 new samples to track 22 (buffer):
+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
+
+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. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.
+- CSV files encapsulated as an OSC String 's'
+- Can split files across multiple OSC Packets
+- Channel tracks are sent over time in chunks

 ex: /np/csv/nodes s 'id,type,parent_id....last node...420'

@@ -171,65 +230,30 @@
 /np/csv/id/42 - a single node (table row by id)
 /np/csv/id/\[1-42] - a specific range of nodes

-----
-C-Struct over OSC
-
-/np/c/id/42 ib 420 6A8B.... specific node as a binary C struct (a performance shortcut)
-
-/np/id - an entire node specifying each data element
-/np/id/42/translate_x - a specific element of node id = 42
+Channel mapping and tracks can be encapsulated using JSON or CSV strings.
+→ /np/csv/tracks 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
+
+Get a JPG used for texture mapping:
+TX → /np/jpg/map00001/#current_value
+RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 'jpeg file as a binary blob'
+
+Example of node id=42 sent as a C-struct, first specifies the size in bytes followed by binary data.
+
+→ /np/c/id/42 ib 420 6A8B.... node as a binary C struct
+
+Get the node as a binary C-struct (typically for peer-to-peer sharing):
+TX → /np/c/node/42/#current_value
+RX ← #reply sib '/np/c/node/42/#current_value' 420 'node C-struct as binary blob'

 *we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.
-
-----
-Control Commands 
-
-- 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.
-
-See '/np/cmd/...' examples below:
-
-Send or receive commands available to the console, app UI and user GUI.
-
-→ /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 T
-→ /np/cmd/select/color_index/\[1-5] F (exclude objects with color index 1-5)
-→ /np/cmd/select/branch_level/\[3-28] T 
-
-→ /np/cmd/mysql/query s 'boolean logic, etc...'
-
-→ /np/cmd/select/all I
-→ /np/cmd/select/none I
-
-----
-Messages that Call C-API Functions
-
-Data can be routed to defined function calls in the C-API by passing parameters. The set of Core API functions can be extended through runtime loadable plugins.
-
-Transmit request that calls npNewNode(parent_id, type):
-
-Create a new node, passes in type, parent id = 42 and returns (new) id, parent_id
-→ /np/cmd/event/new ii 0 42
-← #reply sii '/np/cmd/event/new' 42 43
-
-Triggers a response that returns parent_id and the (new) node_id:
-← #reply sii '/np/cmd/new/node' 42 43
-
-Generate a new node based on current selection without declaring parent.
-Uses trigger event OSC 'i' impulse type, returns parent 42 and the new node id = 43
-→ /np/cmd/event/new I
-← #reply sii '/np/cmd/event/new' 42 43
-
-NOTE that this would be a case for a query system extension for function call return parameters.

 ----
 IO devices
@@ -265,7 +289,19 @@
 /np/io/aja/video/in/1/ b

 ----
-Future support for [JSON OSC Bridge].
-
-/np/json/nodes (all nodes in JSON format.)
-/np/bin/id/42 (node id=42 as a binary C-struct.)
+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'

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Wed, 06 Feb 2013 07:29:59 -0000

--- v6
+++ v7
@@ -115,7 +115,7 @@
 ----
 Scene State Data

-Globals, nodes and channels using an OSC Message address tree.
+Get or Set any parameter in the data tree including globals, nodes and channel track animation using an OSC Message address tree.

 Address shortcuts are used:
 'data->map.node\[42]->hide' becomes '/np/node/42/hide'
@@ -264,18 +264,6 @@
 /np/io/iz/headtrack/position/x f
 /np/io/aja/video/in/1/ b

-
-----
-
-----
-
-EVERYTHING BELOW NEEDS TO BE FIXED... BUT YOU CAN GET AN IDEA OF THE ADDRESS SCHEMA
-
-----
-
-----
-Get or Set any parameter in the entire data tree which includes the scene state and track animation.
-
 ----
 Future support for [JSON OSC Bridge].

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Wed, 06 Feb 2013 07:20:19 -0000

--- v5
+++ v6
@@ -8,28 +8,59 @@

 - Data, IO and Commands are externally accessible using OSC over UDP.
 - Support for 3rd Party OSC enabled systems and native peer-to-peer exchanges.
-
-----
-3 Core OSC Handlers
+- Query System for discovery and dynamic schema mapping
+
+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.
+
+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
+
 1) Base Data Types (integer, float, string) where the OSC address specifies the element.

 - Access all scene parameters such as globals, nodes and control commands.

-Send the mouse x position:
-TX → /np/io/mouse/x i 876
-
-2) Encapsulated CSV, JSON or C structure as an OSC string or binary Blob.
+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 tables and channel tracks for streaming.

 Request all nodes, (can also query /np/csv/tags, chmap, etc...)
-→ /np/csv/nodes/#current_value
-← #reply ss '/np/csv/nodes/#current_value' 'id,type...size,..1,2,3...420'
-
-3) 3rd Party Schema as a plugin:
+TX → /np/csv/nodes/#current_value
+RX ← #reply ss '/np/csv/nodes/#current_value' 'id,type...size,..1,2,3...420'
+
+TX → /np/jpg/map00001/#current_value
+RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 '...jpeg file as binary blob'
+
+----
+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.)
@@ -43,11 +74,14 @@
 ----
 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.

-System clocks can be synchronized using an AVB master clock or video gen-lock with network methods such as by the Equalizer library.
+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.

@@ -57,6 +91,11 @@
 - There is currently a NEED FOR A STANDARD. 

 We are using the [OSC Query System](http://opensoundcontrol.org/files/osc-query-system.pdf) outlined in 2004 by Andrew W. Schmeder and Matthew Wright.
+
+- Namespace discovery that supports dynamically changing schema
+- Type Signature format descriptor
+- error handling
+- Documentation

 Example that sets a value then requests the value using '/#current-value' for mouse x:

@@ -67,11 +106,80 @@
 See section '4.5.4 Current Value' of [OSC Schema System]([OSC_SPEC])

 NOTE that the query system is a draft and we may want to modify it.
-Particularly to shorten the '/#current-value' to perhaps just '#'.
+For example shorten '/#current-value' to perhaps just '#'.

 Also, assuming that '(si)' becomes just 'si' and remove comma's... TRY TO VERIFY THIS!
 doc ex: ← #reply (si) ’/np/io/mouse/x/#current-value’, 876
 becomes: ← #reply si ’/np/io/mouse/x/#current-value’ 876
+
+----
+Scene State Data
+
+Globals, nodes and channels using an OSC Message address 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/id/42/*/#current_value
+
+← #reply si '/np/node/42/id/#current_value' 42
+← #reply si '/np/node/42/type/#current_value' 7
+← #reply si '/np/node/42/parentID/#current_value' 41
+....
+← #reply si '/np/node/42/size/#current_value' 420
+
+Alternate method that returns all attributes in one message:
+
+→ /np/id/42/#current_value
+← #reply siii....i '/np/node/42/#current_value' 42 1 2... 420
+
+Set the Color for RGBA or just red:
+
+→ /np/node/42/color iiii 255 255 128 255
+→ /np/node/42/color/r i 255
+
+Binary Blob 'b':
+
+TX → /np/c/node/42/#current_value
+RX ← #reply sib '/np/node/42/#current_value' 420 'node C-struct as binary blob'
+
+TX → /np/jpg/map00001/#current_value
+RX ← #reply sib '/np/jpg/map00001/#current_value' 16384 'jpeg file as a binary blob'
+
+----
+Channel Track Data
+
+Channel mapping and tracks can be encapsulated using JSON or CSV strings.
+→ /np/csv/tracks is 16384 '...CSV string'
+
+Or, they can be formatted as an OSC Address space, Example that adds 4 new samples to track 22 (buffer):
+→ /np/track/22 iiii 200 205 210 215
+
+-----
+CSV over OSC
+
+CSV files encapsulated as an OSC string. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.
+
+ex: /np/csv/nodes s 'id,type,parent_id....last node...420'
+
+Request a range of nodes, can also query /np/csv/tags, chmap, etc...
+→ /np/csv/id/\[1-42]/#current_value
+← /np/csv/id/\[1-42] s '1,2,3,...420'
+
+/np/csv/id/42 - a single node (table row by id)
+/np/csv/id/\[1-42] - a specific range of nodes
+
+----
+C-Struct over OSC
+
+/np/c/id/42 ib 420 6A8B.... specific node as a binary C struct (a performance shortcut)
+
+/np/id - an entire node specifying each data element
+/np/id/42/translate_x - a specific element of node id = 42
+
+*we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.

 ----
 Control Commands 
@@ -87,52 +195,41 @@

 See '/np/cmd/...' examples below:

+Send or receive commands available to the console, app UI and user GUI.
+
+→ /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 T
+→ /np/cmd/select/color_index/\[1-5] F (exclude objects with color index 1-5)
+→ /np/cmd/select/branch_level/\[3-28] T 
+
+→ /np/cmd/mysql/query s 'boolean logic, etc...'
+
+→ /np/cmd/select/all I
+→ /np/cmd/select/none I
+
 ----
 Messages that Call C-API Functions

 Data can be routed to defined function calls in the C-API by passing parameters. The set of Core API functions can be extended through runtime loadable plugins.

 Transmit request that calls npNewNode(parent_id, type):
-→ /np/cmd/new/node i 42
+
+Create a new node, passes in type, parent id = 42 and returns (new) id, parent_id
+→ /np/cmd/event/new ii 0 42
+← #reply sii '/np/cmd/event/new' 42 43

 Triggers a response that returns parent_id and the (new) node_id:
 ← #reply sii '/np/cmd/new/node' 42 43

+Generate a new node based on current selection without declaring parent.
+Uses trigger event OSC 'i' impulse type, returns parent 42 and the new node id = 43
+→ /np/cmd/event/new I
+← #reply sii '/np/cmd/event/new' 42 43
+
 NOTE that this would be a case for a query system extension for function call return parameters.
-
-----
-Scene State Data
-
-Request a list of all attributes for node id 42:
-
-→ /np/id/42/*/#current_value
-
-← #reply si '/np/id/42/id/#current_value' 42
-← #reply si '/np/id/42/type/#current_value' 7
-← #reply si '/np/id/42/parentID/#current_value' 41
-....
-← #reply si '/np/id/42/size/#current_value' 420
-
-Alternate method that returns all attributes in on message:
-→ /np/id/42/#current_value
-← #reply siii...i '/np/id/42/#current_value' 42 1 2... 420
-
-Set the Color for RGBA or just red:
-→ /np/id/42/color iiii 255 255 128 255
-→ /np/id/42/color/r i 255
-
-Address shortcuts are used:
-'data->map.node\[42]->hide' becomes '/np/42/hide I'
-
-----
-Channel Track Data
-
-Channel mapping and tracks can be encapsulated using JSON or CSV strings.
-→ /np/csv/tracks iiis 1 16 210 215
-
-Or, they can be formatted as an OSC Address space, Example that adds 4 new samples to track 22 (buffer):
-→ /np/track/22 iiii 200 205 210 215
-

 ----
 IO devices
@@ -143,6 +240,7 @@
 → /np/io/key/linux/up/42 I
 → /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 T
@@ -176,64 +274,10 @@
 ----

 ----
-Control Commands
-
-Send or receive commands available to the console, app UI and user GUI.
-
-/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 T
-/np/cmd/select/color_index/[1-5] T
-/np/cmd/select/branch_level/[3-28] T 
-
-/np/cmd/mysql/query s 'boolean logic, etc...'
-
-/np/cmd/select/all i
-/np/cmd/select/none i
-
-Create a new node, passes in the parent id = 42 for the attachment point
-→ /np/cmd/event/kNPcmdNew ii 42 0
-← #reply sii '/np/cmd/event/kNPcmdNew' 42 43
-
-Generate a new node based on current selection withou declaring parent.
-Uses trigger event OSC 'i' impulse type.
-→ /np/cmd/event/kNPcmdNew i
-← #reply sii '/np/cmd/event/kNPcmdNew' 42 43
-
------
-CSV over OSC
-
-CSV files encapsulated as an OSC string. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.
-
-ex: /np/csv/nodes s 'id,type,parent_id....last node...420'
-
-Request a range of nodes, can also query /np/csv/tags, chmap, etc...
-→ /np/csv/id/\[1-42]/#current_value
-← /np/csv/id/\[1-42] s '1,2,3,...420'
-
-/np/csv/id/42 - a single node (table row by id)
-/np/csv/id/\[1-42] - a specific range of nodes
-
-----
-C-Struct over OSC
-
-/np/c/id/42 ib 420 6A8B.... specific node as a binary C struct (a performance shortcut)
-
-
-/np/id - an entire node specifying each data element
-/np/id/42/translate_x - a specific element of node id = 42
-
-*we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.
-
-----
 Get or Set any parameter in the entire data tree which includes the scene state and track animation.

-/np/map/node/id/42/translate/x 3.14
-
-----
-Future support for JSON schema and binary C data structures.
+----
+Future support for [JSON OSC Bridge].

 /np/json/nodes (all nodes in JSON format.)
 /np/bin/id/42 (node id=42 as a binary C-struct.)

WikiPage OSC_Schema modified by Shane Saxon

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

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

-also see: [OSC_Spec] - updated 2012-01-31
+also see: [OSC_Spec] - updated 2012-02-05

 OSC docs and code are currently in progress, this is a DRAFT!!!
 ----
@@ -101,7 +101,7 @@
 NOTE that this would be a case for a query system extension for function call return parameters.

 ----
-DATA
+Scene State Data

 Request a list of all attributes for node id 42:

@@ -123,6 +123,16 @@

 Address shortcuts are used:
 'data->map.node\[42]->hide' becomes '/np/42/hide I'
+
+----
+Channel Track Data
+
+Channel mapping and tracks can be encapsulated using JSON or CSV strings.
+→ /np/csv/tracks iiis 1 16 210 215
+
+Or, they can be formatted as an OSC Address space, Example that adds 4 new samples to track 22 (buffer):
+→ /np/track/22 iiii 200 205 210 215
+

 ----
 IO devices
@@ -197,11 +207,11 @@

 CSV files encapsulated as an OSC string. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.

-ex: /np/csv/nodes s {id,type,parent_id....last node...420}
+ex: /np/csv/nodes s 'id,type,parent_id....last node...420'

 Request a range of nodes, can also query /np/csv/tags, chmap, etc...
-→ /np/csv/id/\[1-42]
-← /np/csv/id/\[1-42] (s) '1,2,3,...420'
+→ /np/csv/id/\[1-42]/#current_value
+← /np/csv/id/\[1-42] s '1,2,3,...420'

 /np/csv/id/42 - a single node (table row by id)
 /np/csv/id/\[1-42] - a specific range of nodes

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Sat, 02 Feb 2013 01:44:40 -0000

--- v3
+++ v4
@@ -47,7 +47,7 @@

 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.

-System clocks can be synchronized using video gen-lock or with non-OSC defined network techniques.
+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.

@@ -171,15 +171,26 @@
 Send or receive commands available to the console, app UI and user GUI.

 /np/cmd/select/id i 42
-/np/cmd/select/range ii 200 300.... or .../select/id\[200-300]
-/np/cmd/select/filter/clear
-/np/cmd/select/color
-/np/cmd/select/branch_level
+/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 T
+/np/cmd/select/color_index/[1-5] T
+/np/cmd/select/branch_level/[3-28] T 

 /np/cmd/mysql/query s 'boolean logic, etc...'

 /np/cmd/select/all i
 /np/cmd/select/none i
+
+Create a new node, passes in the parent id = 42 for the attachment point
+→ /np/cmd/event/kNPcmdNew ii 42 0
+← #reply sii '/np/cmd/event/kNPcmdNew' 42 43
+
+Generate a new node based on current selection withou declaring parent.
+Uses trigger event OSC 'i' impulse type.
+→ /np/cmd/event/kNPcmdNew i
+← #reply sii '/np/cmd/event/kNPcmdNew' 42 43

 -----
 CSV over OSC
@@ -195,16 +206,18 @@
 /np/csv/id/42 - a single node (table row by id)
 /np/csv/id/\[1-42] - a specific range of nodes

-/np/c/id - specific node as a binary C struct (a performance shortcut)
+----
+C-Struct over OSC
+
+/np/c/id/42 ib 420 6A8B.... specific node as a binary C struct (a performance shortcut)
+

 /np/id - an entire node specifying each data element
 /np/id/42/translate_x - a specific element of node id = 42

-/np/cmd/event - trigger event specified by integer or string
-/np/cmd/event/kNPcmdNew - trigger event using an OSC 'i' impulse type.
-
 *we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.

+----
 Get or Set any parameter in the entire data tree which includes the scene state and track animation.

 /np/map/node/id/42/translate/x 3.14

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Fri, 01 Feb 2013 10:29:36 -0000

--- v2
+++ v3
@@ -4,76 +4,147 @@

 OSC docs and code are currently in progress, this is a DRAFT!!!
 ----
-OSC Schema
+OSC Schema based on our [OSC_Spec]

 - Data, IO and Commands are externally accessible using OSC over UDP.
-- Support for both 3rd Party OSC Enabled systems and native peer-to-peer exchanges.
-- An OSC router directs messages to one of the 3 Core OSC Schema Handlers:
-
-1) OSC base data types (int, float, string) where the address specifies the specific element and type(s). Access is provided to specific globals, nodes and commands. Commands are processed in order using the Time-Tag.
-- '/np/io/mouse/x i 876'
+- Support for 3rd Party OSC enabled systems and native peer-to-peer exchanges.
+
+----
+3 Core OSC Handlers
+
+The OSC Router directs messages to one of the 3 Core OSC Schema Handlers:
+
+1) Base Data Types (integer, float, string) where the OSC address specifies the element.
+
+- Access all scene parameters such as globals, nodes and control commands.
+
+Send the mouse x position:
+TX → /np/io/mouse/x i 876

 2) Encapsulated CSV, JSON or C structure as an OSC string or binary Blob.
+
 - Includes both the scene state tables and channel tracks for streaming.
-- '/np/csv/id/[1-42]' - specific range of nodes (also /np/csv/tags, chmap, etc...)
+
+Request all nodes, (can also query /np/csv/tags, chmap, etc...)
+→ /np/csv/nodes/#current_value
+← #reply ss '/np/csv/nodes/#current_value' 'id,type...size,..1,2,3...420'

 3) 3rd Party Schema as a plugin:
-- Default handler for all messages other then '/np/...'
+
+- Default handler for all messages that do NOT start with '/np/...'
 - Direct support for TouchOSC, Lemur and GrandVJ (for now hard-coded.)
 - Future support for Plugin architecture to extend core functionality.
-- '/SYN/patch/1/amp i 22' - example of a synthesizer gain setting.
-
-- Future support for a CSV table that maps any 3rd party schema, akin to [chmap000x.csv]
-
-Control commands can be sent as individual messages or streamed as a (command) track.
-- Most user commands are simple triggers using the OSC 'i' Impulse type.
-- Mouse movements and events are sent using a HID compatible format.
-- Direct API access using commands with additional parameters to create, delete...
-
-State based elements and Time based track data
-
-Individual data elements and commands can be directly accessed via the'/np/map/...' portion of the schema. I addition to transmitting CSV files that contain nodes, tags, channels and tracks. CSV files are sent as OSC 's' string type (NULL-terminated ASCII string.)
-
-TX/RX methods and syntax depend on the core schema type, see examples below:
-
-----
-Message Processing
-
-Data can be directly accessed to get and set parameters or be routed to defined function calls by passing parameters:
-
-TX request:
-- '/np/cmd/new/node i 42' calls npNewNode(parent_id, type, data)
-
-RX response:
-- '/np/cmd/new/node i i 42 43' returns the parent id and the new node id
+
+Set the 'amp' gain setting for a synthesizer:
+→ /SYN/patch/1/amp i 22
+
+- Future support for a CSV table that maps any 3rd party schema, akin to [IO_Channels].
+
+----
+Time Tag
+
+- OSC has inconsistant Time Tag implementations!
+
+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.
+
+System clocks can be synchronized using video gen-lock or with non-OSC defined network techniques.
+
+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.
+
+----
+OSC Query System 
+
+- There is currently a NEED FOR A STANDARD. 
+
+We are using the [OSC Query System](http://opensoundcontrol.org/files/osc-query-system.pdf) outlined in 2004 by Andrew W. Schmeder and Matthew Wright.
+
+Example that sets a value then requests the value using '/#current-value' for mouse x:
+
+TX → /np/io/mouse/x i 876
+TX → /np/io/mouse/x/#current-value
+RX ← #reply si ’/np/io/mouse/x/#current-value’ 876
+
+See section '4.5.4 Current Value' of [OSC Schema System]([OSC_SPEC])
+
+NOTE that the query system is a draft and we may want to modify it.
+Particularly to shorten the '/#current-value' to perhaps just '#'.
+
+Also, assuming that '(si)' becomes just 'si' and remove comma's... TRY TO VERIFY THIS!
+doc ex: ← #reply (si) ’/np/io/mouse/x/#current-value’, 876
+becomes: ← #reply si ’/np/io/mouse/x/#current-value’ 876
+
+----
+Control Commands 
+
+- 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.
+
+See '/np/cmd/...' examples below:
+
+----
+Messages that Call C-API Functions
+
+Data can be routed to defined function calls in the C-API by passing parameters. The set of Core API functions can be extended through runtime loadable plugins.
+
+Transmit request that calls npNewNode(parent_id, type):
+→ /np/cmd/new/node i 42
+
+Triggers a response that returns parent_id and the (new) node_id:
+← #reply sii '/np/cmd/new/node' 42 43
+
+NOTE that this would be a case for a query system extension for function call return parameters.

 ----
 DATA

-- '/np/id/42 i i i i.... f f f... i {42 1 2 3... 420} (full set of node attributes)
-- '/np/id/42/color i i i i '255 255 128 255' (all elements of the color struct)
-- '/np/id/42/color/r i '255'
+Request a list of all attributes for node id 42:
+
+→ /np/id/42/*/#current_value
+
+← #reply si '/np/id/42/id/#current_value' 42
+← #reply si '/np/id/42/type/#current_value' 7
+← #reply si '/np/id/42/parentID/#current_value' 41
+....
+← #reply si '/np/id/42/size/#current_value' 420
+
+Alternate method that returns all attributes in on message:
+→ /np/id/42/#current_value
+← #reply siii...i '/np/id/42/#current_value' 42 1 2... 420
+
+Set the Color for RGBA or just red:
+→ /np/id/42/color iiii 255 255 128 255
+→ /np/id/42/color/r i 255

 Address shortcuts are used:
-'data->map.node[42]->hide' becomes '/np/42/hide'
+'data->map.node\[42]->hide' becomes '/np/42/hide I'

 ----
 IO devices

-System Keyboard and Mouse:
-
-/np/io/key/ascii/a
-/np/io/key/code/42
-
-/np/io/mouse/x i
-/np/io/mouse/y i
-/np/io/mouse/left T
-/np/io/mouse/middle F
-/np/io/mouse/right F
-/np/io/mouse/wheel i -1 (wheel can be -1, 0 or +1)
-/np/io/mouse/mode/cam i (mouse keeps
-/np/io/mouse/tool/freeze i
-/np/io/mouse/target/id 42 (the active selection)
+Raw System Events:
+
+→ /np/io/key/ascii/down/42 I
+→ /np/io/key/linux/up/42 I
+→ /np/io/key/linux i i 42 1 (key, eventType - up, down, repeat, modifier...)
+
+→ /np/io/mouse/x i 
+→ /np/io/mouse/y i
+→ /np/io/mouse/left T
+→ /np/io/mouse/middle F
+→ /np/io/mouse/right F
+→ /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:

@@ -82,40 +153,47 @@

 3rd Parties as Plugins:

-/np/io/iz/headtrack/position
-/np/io/aja/video/in/1
+/np/io/iz/headtrack/position/x f
+/np/io/aja/video/in/1/ b
+
+
+----
+
+----
+
+EVERYTHING BELOW NEEDS TO BE FIXED... BUT YOU CAN GET AN IDEA OF THE ADDRESS SCHEMA
+
+----

 ----
 Control Commands

-Send or receive commands available to the GUI and console
-
-/np/cmd/new (parent id)
-/np/cmd/color {255 128 0}
-
-/np/cmd/select/id 42
-/np/cmd/select/range d d 200 300.... or .../select/id[200-300]
+Send or receive commands available to the console, app UI and user GUI.
+
+/np/cmd/select/id i 42
+/np/cmd/select/range ii 200 300.... or .../select/id\[200-300]
 /np/cmd/select/filter/clear
 /np/cmd/select/color
 /np/cmd/select/branch_level

 /np/cmd/mysql/query s 'boolean logic, etc...'

-/np/cmd/select/all 'i'
-/np/cmd/select/none 'i'
+/np/cmd/select/all i
+/np/cmd/select/none i

 -----
-CSV format
-----
 CSV over OSC

 CSV files encapsulated as an OSC string. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.

 ex: /np/csv/nodes s {id,type,parent_id....last node...420}

-/np/csv/nodes - all nodes as a CSV (also /np/csv/tags, .../chmap, etc...)
+Request a range of nodes, can also query /np/csv/tags, chmap, etc...
+→ /np/csv/id/\[1-42]
+← /np/csv/id/\[1-42] (s) '1,2,3,...420'
+
 /np/csv/id/42 - a single node (table row by id)
-/np/csv/id/[1-42] - a specific range of nodes
+/np/csv/id/\[1-42] - a specific range of nodes

 /np/c/id - specific node as a binary C struct (a performance shortcut)

@@ -125,14 +203,11 @@
 /np/cmd/event - trigger event specified by integer or string
 /np/cmd/event/kNPcmdNew - trigger event using an OSC 'i' impulse type.

-*we may also support ranges '/np/id/[1-42]/color' send RGBA colors for nodes 1-42.
-
+*we may also support ranges '/np/id/\[1-42]/color' send RGBA colors for nodes 1-42.

 Get or Set any parameter in the entire data tree which includes the scene state and track animation.

 /np/map/node/id/42/translate/x 3.14
-
-

 ----
 Future support for JSON schema and binary C data structures.

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Fri, 01 Feb 2013 00:54:02 -0000

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

-CSV over OSC
+also see: [OSC_Spec] - updated 2012-01-31

-State Based:
-scene state files - globals, nodes and tags
-...more types to be added...
+OSC docs and code are currently in progress, this is a DRAFT!!!
+----
+OSC Schema

-Time Based:
-channel track animation - channel map and tracks
+- Data, IO and Commands are externally accessible using OSC over UDP.
+- Support for both 3rd Party OSC Enabled systems and native peer-to-peer exchanges.
+- An OSC router directs messages to one of the 3 Core OSC Schema Handlers:

-Data components and commands can be directly accessed via the OSC schema. I addition to transmitting CSV files that contain nodes, tags, channels and tracks. CSV files are sent as OSC 's' string type (NULL-terminated ASCII string.)
+1) OSC base data types (int, float, string) where the address specifies the specific element and type(s). Access is provided to specific globals, nodes and commands. Commands are processed in order using the Time-Tag.
+- '/np/io/mouse/x i 876'
+
+2) Encapsulated CSV, JSON or C structure as an OSC string or binary Blob.
+- Includes both the scene state tables and channel tracks for streaming.
+- '/np/csv/id/[1-42]' - specific range of nodes (also /np/csv/tags, chmap, etc...)
+
+3) 3rd Party Schema as a plugin:
+- Default handler for all messages other then '/np/...'
+- Direct support for TouchOSC, Lemur and GrandVJ (for now hard-coded.)
+- Future support for Plugin architecture to extend core functionality.
+- '/SYN/patch/1/amp i 22' - example of a synthesizer gain setting.
+
+- Future support for a CSV table that maps any 3rd party schema, akin to [chmap000x.csv]
+
+Control commands can be sent as individual messages or streamed as a (command) track.
+- Most user commands are simple triggers using the OSC 'i' Impulse type.
+- Mouse movements and events are sent using a HID compatible format.
+- Direct API access using commands with additional parameters to create, delete...
+
+State based elements and Time based track data
+
+Individual data elements and commands can be directly accessed via the'/np/map/...' portion of the schema. I addition to transmitting CSV files that contain nodes, tags, channels and tracks. CSV files are sent as OSC 's' string type (NULL-terminated ASCII string.)
+
+TX/RX methods and syntax depend on the core schema type, see examples below:

 ----
-CSV files encapsulated as an OSC string
+Message Processing

-/np/csv/nodes s {id,type,parent_id....last node...420}
-/np/csv/tags s 
-/np/csv/chmap s 
-/np/csv/channels s 
+Data can be directly accessed to get and set parameters or be routed to defined function calls by passing parameters:
+
+TX request:
+- '/np/cmd/new/node i 42' calls npNewNode(parent_id, type, data)
+
+RX response:
+- '/np/cmd/new/node i i 42 43' returns the parent id and the new node id

 ----
-IO for keyboard mouse and other devices
+DATA
+
+- '/np/id/42 i i i i.... f f f... i {42 1 2 3... 420} (full set of node attributes)
+- '/np/id/42/color i i i i '255 255 128 255' (all elements of the color struct)
+- '/np/id/42/color/r i '255'
+
+Address shortcuts are used:
+'data->map.node[42]->hide' becomes '/np/42/hide'
+
+----
+IO devices
+
+System Keyboard and Mouse:

 /np/io/key/ascii/a
 /np/io/key/code/42
@@ -29,45 +70,72 @@
 /np/io/mouse/left T
 /np/io/mouse/middle F
 /np/io/mouse/right F
-/np/io/mouse/wheel i -1   wheel can be -1, 0 or +1
+/np/io/mouse/wheel i -1 (wheel can be -1, 0 or +1)
+/np/io/mouse/mode/cam i (mouse keeps
+/np/io/mouse/tool/freeze i
+/np/io/mouse/target/id 42 (the active selection)

-other IO devices will be added:
-/np/io/hid/....
+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
+/np/io/aja/video/in/1

 ----
-Commands
+Control Commands

-Send or receive commands available to user interface
+Send or receive commands available to the GUI and console

 /np/cmd/new (parent id)
 /np/cmd/color {255 128 0}

 /np/cmd/select/id 42
-/np/cmd/select/range 200 300
+/np/cmd/select/range d d 200 300.... or .../select/id[200-300]
 /np/cmd/select/filter/clear
 /np/cmd/select/color
 /np/cmd/select/branch_level

-/np/cmd/select/all T or F
+/np/cmd/mysql/query s 'boolean logic, etc...'
+
+/np/cmd/select/all 'i'
+/np/cmd/select/none 'i'

 -----
-Data 
+CSV format
+----
+CSV over OSC
+
+CSV files encapsulated as an OSC string. Can be split files across multiple OSC bundles, Channel tracks are generally transmitted using fixed sized chunks in realtime.
+
+ex: /np/csv/nodes s {id,type,parent_id....last node...420}
+
+/np/csv/nodes - all nodes as a CSV (also /np/csv/tags, .../chmap, etc...)
+/np/csv/id/42 - a single node (table row by id)
+/np/csv/id/[1-42] - a specific range of nodes
+
+/np/c/id - specific node as a binary C struct (a performance shortcut)
+
+/np/id - an entire node specifying each data element
+/np/id/42/translate_x - a specific element of node id = 42
+
+/np/cmd/event - trigger event specified by integer or string
+/np/cmd/event/kNPcmdNew - trigger event using an OSC 'i' impulse type.
+
+*we may also support ranges '/np/id/[1-42]/color' send RGBA colors for nodes 1-42.
+

 Get or Set any parameter in the entire data tree which includes the scene state and track animation.

-/np/data/map/node/id/42/translate/x 3.14
+/np/map/node/id/42/translate/x 3.14

 ----
-Future support for JSON schema an binary C data structures.
+Future support for JSON schema and binary C data structures.

-/np/json/
-/np/bin/data/
-
-shortcuts
-
-/np/node/id/translate/x {1}
-or ...../id/translate {1 2 3}
-
-
+/np/json/nodes (all nodes in JSON format.)
+/np/bin/id/42 (node id=42 as a binary C-struct.)

WikiPage OSC_Schema modified by Shane Saxon

Shane Saxon — Thu, 31 Jan 2013 08:49:54 -0000

CSV over OSC

State Based:
scene state files - globals, nodes and tags
...more types to be added...

Time Based:
channel track animation - channel map and tracks

Data components and commands can be directly accessed via the OSC schema. I addition to transmitting CSV files that contain nodes, tags, channels and tracks. CSV files are sent as OSC 's' string type (NULL-terminated ASCII string.)

CSV files encapsulated as an OSC string

/np/csv/nodes s {id,type,parent_id....last node...420}
/np/csv/tags s
/np/csv/chmap s
/np/csv/channels s

IO for keyboard mouse and other devices

/np/io/key/ascii/a
/np/io/key/code/42

/np/io/mouse/x i
/np/io/mouse/y i
/np/io/mouse/left T
/np/io/mouse/middle F
/np/io/mouse/right F
/np/io/mouse/wheel i -1 wheel can be -1, 0 or +1

other IO devices will be added:
/np/io/hid/....

Commands

Send or receive commands available to user interface

/np/cmd/new (parent id)
/np/cmd/color {255 128 0}

/np/cmd/select/id 42
/np/cmd/select/range 200 300
/np/cmd/select/filter/clear
/np/cmd/select/color
/np/cmd/select/branch_level

/np/cmd/select/all T or F

Data

Get or Set any parameter in the entire data tree which includes the scene state and track animation.

/np/data/map/node/id/42/translate/x 3.14

Future support for JSON schema an binary C data structures.

/np/json/
/np/bin/data/

shortcuts

/np/node/id/translate/x {1}
or ...../id/translate {1 2 3}