oscMessage | R Documentation |
Constructs a string formated as an Open Sound Control (OSC) message, from user supplied OSC Address Pattern, data, and optional OSC Type Tag String.
oscMessage(address = "/", data = NULL, logical = "logical",
typestring = "auto", integer = "i", double = "d", character = "s",
null = "N", typecomma = TRUE)
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: |
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 |
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 |
character. A string representation of an OSC message in the format ADDRESS_PATTERN TYPE_TAG_STRING ARGUMENTS
.
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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.