Open Sound Control (OSC)

OSC Overview

• Open Sound Control (OSC) is a communication protocol that is independent from any specific transport mechanism.

• That said, OSC packets are most typically sent and received using UDP sockets.

• OSC uses an open-ended, dynamic, URL-style symbolic naming scheme.

• The OSC protocol features:
  • a pattern-matching language to specify multiple recipients of a single message
  • high resolution time tags
  • "bundles" of messages whose affect must occur simultaneously
  • a query system to dynamically determine the capabilities of an OSC server and get documentation

• The OSC data format is big-endian.

• The OSC specification can be found at http://opensoundcontrol.org/

OSC Data Types

• OSC supports the following message argument data types:
  • int32
  • float32
  • OSC-timetag (64-bit int representing Internet NTP timestamps ... seconds and picoseconds since midnight on 1 January 1900)
  • OSC-string (ascii characters followed by a NULL, then padded with 0-3 NULL characters so that total length in bytes is a multiple of 4)
  • OSC-blob (32-bit byte count followed by that many bytes and then padded with zeroes so that total length in bytes is a multiple of 4)

OSC Packets

• The fundamental unit of an OSC transmission is an OSC packet.

• Anything that sends an OSC packet is referred to as an OSC client.

• Anything that receives an OSC packet is referred to as an OSC server.

• The size of an OSC packet is always a multiple of 4 bytes (or 32 bits).

• The contents of an OSC packet must either be an OSC Message or an OSC Bundle.

OSC Messages

• An OSC message has the following general format:

  <address pattern>   <type tag string>   <arguments>
  

• The address pattern is a string that starts with a '/', followed by a message routing or destination.

• OSC addresses follow a URL or directory tree structure, such as /voices/synth1/osc1/modfreq.

• OSC messages can go to more than one destination and "wildcard" symbols such as '?', '*', characters inside '[brackets]', and comma-delimited lists of strings inside '{curly braces}' can be used to match multiple address strings (see "OSC Pattern Matching" below).

• When an OSC server receives an OSC message, the server invokes a method or procedure specified by the message address pattern.

• The type tag string specifies the data type(s) for the argument(s) to follow.

• OSC type tags begin with a comma (',') followed by one or more of the characters 'i', 'f', 's', or 'b' that correspond to the data types int32, float32, OSC-string, or OSC-blob.

• Example #1: "/oscillator/4/frequency 440.0" represented by 32-byte message:

   2f (/)  6f (o)  73 (s)  63 (c)
   69 (i)  6c (l)  6c (l)  61 (a)
   74 (t)  6f (o)  72 (r)  2f (/)
   34 (4)  2f (/)  66 (f)  72 (r)
   65 (e)  71 (q)  75 (u)  65 (e)
   6e (n)  63 (c)  79 (y)  0 ()
   2c (,)  66 (f)  0 ()    0 ()
   43 (C)  dc (Ü)  0 ()    0 ()

• Example #2: OSC Address Pattern "/foo" and 5 arguments: an int32 = 1000, an int32 = -1, the string "hello", a float32 = 1.234, and a float32 = 5.678:

   2f (/)  66 (f)  6f (o)  6f (o)
   0 ()    0 ()    0 ()    0 ()
   2c (,)  69 (i)  69 (i)  73 (s)
   66 (f)  66 (f)  0 ()    0 ()
   0 ()    0 ()    3 ()    e8 (è)
   ff (ÿ)  ff (ÿ)  ff (ÿ)  ff (ÿ)
   68 (h)  65 (e)  6c (l)  6c (l)
   6f (o)  0 ()    0 ()    0 ()
   3f (?)  9d ()   f3 (ó)  b6 (¶)
   40 (@)  b5 (µ)  b2 (”)  2d (-)

• More examples

OSC Bundles

• An OSC bundle consists of the OSC-string "#bundle", followed by an OSC-timetag and zero or more OSC Bundle Elements.

• An OSC Bundle Element consists of an int32 indicating the contents size in bytes (must be a multiple of 4) followed by the contents. The contents can be either an OSC Message or an OSC Bundle (bundles can contain other bundles).

OSC Pattern Matching

• A '?' in the OSC Address Pattern matches any single character.

• A '*' 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:
  • Two characters separated by a minus sign indicate the range of characters between the given two in ASCII collating sequence. (A minus sign at the end of the string has no special meaning.)
  • An exclamation point at the beginning of a bracketed string negates the sense of the list, meaning that the list matches any character not in the list. (An exclamation point anywhere besides the first character after the open bracket has no special meaning.)

• A comma-separated list of strings enclosed in curly braces (e.g., "foo,bar") in the OSC Address Pattern matches any of the strings in the list.

• Any other character in an OSC Address Pattern can match only the same character.

OSC Objects for Max

• The udpsend and udpreceive objects provide a means for sending and receiving data buffers using the UDP socket internet protocol.

• The OpenSoundControl object interfaces directly with the udpsend and udpreceive objects and is specifically designed for OSC message management.

• The OSC-route object is modeled after the Max "route" object and provides OSC address pattern matching functionality.

• OSC objects for Max/MSP can be downloaded from http://cnmat.berkeley.edu/downloads/ or here.