4.3.4 Handling Pattern Expansion
Use of address-pattern expressions with a query prompt is equivalent to sending the prompt to every complete matching address. The server’s response should be as if this were the case.

→ /*/#documentation
← #reply (ss) ’/patch1/#documentation’, ’A patch.’
← #reply (ss) ’/main_clock/#documentation’, ’A clock.’ ...

4.5.1 Namespace Exploration
Prompt to discover what addresses appear at the next level below a base address. Prompt address appears as a normal address pattern which ends with the ’/’ character.
→ /foo/bar/
← #reply (sss) ’/foo/bar/’, ’test1’, ’test2’
→ /foo/bar/test1/
← #reply (s) ’/foo/bar/test1/’ # is a terminal node.

4.5.4 Current Value

→ /patch1/gain1 100.0
→ /patch1/gain1/#current-value
← #reply (sf) ’/patch1/gain1/#current-value’, 100.0

Edited Excerpts from OSC 1.0 Spec and OSC 1.1 Spec - with added Comments

The Open Sound Control 1.0 Specification
Version 1.0, March 26 2002, Matt Wright

Intro
OSC is a transport-independent message protocol for networking multimedia devices.

An OSC Client sends OSC Packets to an OSC Server.
Our [OSC_Schema] typically uses an OSC Bundle in order to provide a Time Tag.

OSC Packet must be either an OSC Message or OSC Bundle. The first byte distinguishes the two alternatives.

OSC Bundle - starts with "#bundle" followed by a Time Tag, followed by zero or moreBundle Elements.

OSC Message - has an OSC Address Pattern followed by an OSC Type Tag String followed by zero or more OSC Arguments.

OSC Address Space Pattern - starts with a '/' and is similar to a URL path, ex: '/mix/input/1/gain'

OSC Type Tag String - each character after the comma specifies the OSC Arguments types, ex: '/mix/input/1/mute ,i'

OSC Arguments - are the actual data such as the gain value '22', ex: '/mix/input/1/gain ,i 22

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

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

Atomic Data Types

The size of every atomic data type in OSC is a multiple of 32-bits (4-byte aligned.)

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.

OSC Bundles
An OSC Bundle consists of the OSC-string "#bundle" followed by an OSC Time Tag, followed by zero or more OSC Bundle Elements. The OSC-timetag is a 64-bit fixed point time tag whose semantics are described below.

An OSC Bundle Element consists of its size and its contents. The size is an int32 representing the number of 8-bit bytes in the contents, and will always be a multiple of 4. The contents are either an OSC Message or an OSC Bundle.

Note this recursive definition: bundle may contain bundles.

This table shows the parts of a two-or-more-element OSC Bundle and the size (in 8-bit bytes) of each part.

OSC Semantics

This section defines the semantics of OSC data.

OSC Address Spaces and OSC Addresses
Every OSC server has a set of OSC Methods. OSC Methods are the potential destinations of OSC messages received by the OSC server and correspond to each of the points of control that the application makes available. "Invoking" an OSC method is analogous to a procedure call; it means supplying the method with arguments and causing the method's effect to take place.

An OSC Server's OSC Methods are arranged in a tree strcuture called an OSC Address Space. The leaves of this tree are the OSC Methods and the branch nodes are called OSC Containers. An OSC Server's OSC Address Space can be dynamic; that is, its contents and shape can change over time.

Each OSC Method and each OSC Container other than the root of the tree has a symbolic name, an ASCII string consiting of printable characters other than the following:

Printable ASCII characters not allowed in names of OSC Methods or OSC Containers:
character - name - ASCII code (decimal)
' ' - space - 32
# - number sign - 35
* - asterisk - 42
, - comma - 44
/ - forward slash - 47
? - question mark - 63
[ - open bracket - 91
] - close bracket - 93
{ - open curly brace - 123
} - close curly brace - 125

The OSC Address of an OSC Method is a symbolic name giving the full path to the OSC Method in the OSC Address Space, starting from the root of the tree. An OSC Method's OSC Address begins with the character '/' (forward slash), followed by the names of all the containers, in order, along the path from the root of the tree to the OSC Method, separated by forward slash characters, followed by the name of the OSC Method. The syntax of OSC Addresses was chosen to match the syntax of URLs. (OSC Address Examples)

OSC Message Dispatching and Pattern Matching

When an OSC server receives an OSC Message, it must invoke the appropriate OSC Methods in its OSC Address Space based on the OSC Message's OSC Address Pattern. This process is called dispatching the OSC Message to the OSC Methods that match its OSC Address Pattern. All the matching OSC Methods are invoked with the same argument data, namely, the OSC Arguments in the OSC Message...

A received OSC Message must be disptched to every OSC method in the current OSC Address Space whose OSC Address matches the OSC Message's OSC Address Pattern. An OSC Address Pattern matches an OSC Address if...

'?' in the OSC Address Pattern matches any single character
'*' in the OSC Address Pattern matches any sequence of zero or more characters

A string of characters in square brackets (e.g., "[string]") in the OSC Address Pattern matches any character in the string. Inside square brackets, the minus sign (-) and exclamation point (!) have special meanings...

Temporal Semantics and OSC Time Tags

An OSC server must have access to a representation of the correct current absolute time. OSC does not provide any mechanism for clock synchronization.

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

OSC Messages in the same OSC Bundle are atomic; their corresponding OSC Methods should be invoked in immediate succession as if no other processing took place between the OSC Method invocations.

When an OSC Address Pattern is dispatched to multiple OSC Methods, the order in which the matching OSC Methods are invoked is unspecified. When an OSC Bundle contains multiple OSC Messages, the sets of OSC Methods corresponding to the OSC Messages must be invoked in the same order as the OSC Messages appear in the packet. (example)

When bundles contain other bundles, the OSC Time Tag of the enclosed bundle must be greater than or equal to the OSC Time Tag of the enclosing bundle. The atomicity requirement for OSC Messages in the same OSC Bundle does not apply to OSC Bundles within an OSC Bundle.

ANTz Wiki

realtime 3D data visualization

OSC_Spec

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

Related