oscMessage: Construct OSC Message from OSC Address Pattern and Data

View source: R/oscMessage.R

oscMessageR Documentation

Construct OSC Message from OSC Address Pattern and Data

Description

Constructs a string formated as an Open Sound Control (OSC) message, from user supplied OSC Address Pattern, data, and optional OSC Type Tag String.

Usage

oscMessage(address = "/", data = NULL, logical = "logical",
  typestring = "auto", integer = "i", double = "d", character = "s",
  null = "N", typecomma = TRUE)

Arguments

address

character. The OSC Address Pattern (see Details).

data

list or vector.

logical

character. R datatype that data of type 'logical' should be converted to prior to processing. Default: logical='logical'

typestring

character. OSc Type Tag String: a string of non-space characters representing data types, beginning with ",".

integer

character. Tag to use for R data type "integer". Default = "i", specifying a 32-bit signed big-endian 2'S compliment integer. (Identical to the R "integer" type.)

double

character. Tag to use for R data type "integer". Default = "d", specifying a 64 bit IEEE 754 double (Identical the R "double" type.)

character

character. Tag to use for R data type "character". Default = "s", specifying a string.

null

character. Tag to use for R data type "NULL". Default = "N", specifying a "Nil" or null.

typecomma

logocal. If typestring='auto' and typecomma=TRUE (the default), a leading comma "," is added to the beginning of the type tag string.

Details

oscMessage returns a string representation of an OSC message in the format ADDRESS_PATTERN TYPE_TAG_STRING ARGUMENTS. (see http://opensoundcontrol.org/spec-1.0 for details.)

It is up to the function accepting this string representation to implement the actual binary encoding of the OSC Message.

Encoded OSC itself is transport-independent, but is often sent over UDP or TCP connections.

ADDRESS_PATTERN

The OSC Address Pattern is a forward-slash delimited string represented a heirarchical user-defined address space (tree), with wildcards for pattern matching. The minimal OSC Address Pattern "/" represents the root of the tree. In OSC parlance, each tree node is referred to as a "container" and the final node is an "OSC method". The address is a means of dispatching data to a specified method in a heirarchical tree.

Wildcards:

? matches any single character
* matches any sequence of zero or more characters
{} Curly braces containing a comma-separated list of strings (e.g., {foo,bar} )
matches any string in the list.
[] Brackets containing a string (e.g., [asdfq]) matches any character in the string.
- (dash) In square brackets, separating two characters (e.g. [a-d] )
matches a range of characters in ASCII collating sequence.
! In square brackets, preceding a string (e.g. [!xz] ) negates the entire string.
e.g. 'a[!xz]' matches 'ay' but not 'ax' or 'az')

Parsing of OSC Address Patterns and wildcards and proper dispatching of data is left to the recipient of the OSC Message.

ARGUMENTS

Input data is flattened into a one-level list with all elements length 1, converted to a space-delimited argument string ('ARGUMENTS' in the OSC Message). oscMessage currently does not support array arguments, OSC-blobs or OSC-bundles. Nested lists and vectors of length > 1 will all be flattened.

TYPE_TAG_STRING

You can supply your own OSC Type Tage String via the typestring argument. oscMessage is agnostic about the legality and interpretation of type tags. You must ensure that the encoding function and end recipeint of the message understand the type tags used. (See below.)

If typestring='auto', oscMessage passes the data to oscType to generate the string. The R datatypes of the input data are mapped to OSC type tags as specified by additional arguments to oscMessage. Currently, only R data types "integer," "double," "character," "NULL," and "logical" are supported. See oscType for additional details.

A minimal set of OSC type tags for 32 bit integers, 32 bit floats, and strings is standard across implementations. However, other data types and corresponding tags depend on the OSC version specification and OSC implementation.

For reference, the OSC 1.0 and related "libo" typ tag specifications are included here:

OSC 1.0 TYPE TAGS, including extended types http://opensoundcontrol.org/spec-1.0

tag definition
i 32-bit signed integer (big-endian 2'S compliment; equivalent of R type "integer")
u 32-bit unsigned integer (big-endian)
h 64 bit signed integer (big-endian two’s complement)
f 32 bit float (big-endian IEEE 754)
d 64 bit double (IEEE 754; equivalent of R type "double")
c an ascii character, sent as 32 bits
r 32 bit RGBA color stored, each channel stored as an 8-bit value: e.g.:
rgba(1.0,0.8,0.0,1.0) = 11111111 11001100 00000000 11111111 = 4291559679
m 4 byte MIDI message. Bytes from MSB to LSB are: port id, status byte, data1, data2
s OSC-string (sequence of non-null ASCII characters followed by a null, followed by
0-3 additional null characters to make the total number of bits a multiple of 32.)
S Alternate type represented as an OSC-string
e.g. for systems that differentiate "symbols" from "strings"
b OSC-blob (int32 size count n, followed by n 8-bit bytes of arbitrary binary data,
followed by 0-3 zero bytes to make total number of bits a multiple of 32.)
T True (No data argument is passed)
F False (No data argument is passed)
N Nil or Null (No data argument is passed)
I Infinitum (or "Impulse")
[ Indicates the beginning of an array. The tags following are for data in the Array until a close brace tag is reached.
] Indicates the end of an array.
t OSC-timetag (64-bit big-endian fixed-point NTP timestamp.)
First 32 bits specify the number of seconds since midnight on January 1, 1900.
Last 32 bits specify fractional parts of a second. (Precision is ~200 picoseconds.)
Special case: 63 zero bits followed by one in least significant bit (000...0001)
means "immediately."

libo TYPE TAGS (an extension of OSC 1.0) http://www.cnmat.berkeley.edu/sites/default/files/attachments/2015_Dynamic_Message_Oriented_Middleware.pdf

tag definition
c 8-bit signed integer (big-endian 2'S compliment)
C 8-bit unsigned integer (big-endian 2'S compliment)
u 16-bit signed integer (big-endian 2'S compliment)
U 16-bit unsigned integer (big-endian 2'S compliment)
i 32-bit signed integer (big-endian 2'S compliment; equivalent of R type "integer")
I 32-bit unsigned integer (big-endian 2'S compliment)
h 64 bit signed integer (big-endian two’s complement)
H 64 bit unsigned integer (big-endian two’s complement)
d 64 bit double (IEEE 754; equivalent of R type "double")
s OSC-string
S Alternate type represented as an OSC-string
b OSC-blob
B odot bundle
A executable code
T True (No data argument is passed)
F False (No data argument is passed)
N Nil or Null (No data argument is passed)
t OSC-timetag

Value

character. A string representation of an OSC message in the format ADDRESS_PATTERN TYPE_TAG_STRING ARGUMENTS.

Examples

address <- "/thing/n1/red"
data <- list(list(3:4,"apple"), TRUE, list(list(5.1,"sphere"),NULL))
OSC_1 <- oscMessage(address = address, data = data); OSC_1

OSC_2 <- oscMessage(address = address, data = data, double = "f"); OSC_2

OSC_3 <- oscMessage(address = address, data = data, typecomma=FALSE); OSC_3

OSC_4 <- oscMessage(address = address, data = data, logical = "integer"); OSC_4

pattern <- "/{th,s}ing/n[2-4]/red*"
types <- ",iiSidSN"
data <- list(list(3:4,"apple"), TRUE, list(list(5.1,"sphere"),NULL))
OSC_5 <- oscMessage(address = pattern, typestring = types, data = data, logical="integer")
OSC_5


allopole/ROSC documentation built on May 9, 2023, 10:09 p.m.