OpenSound Control (OSC) is "a protocol for communication among computers, sound synthesizers, and other multimedia devices that is optimized for modern networking technology." It has several features that one does not find in traditional music-oriented protocol like MIDI, including a hierarchical dynamic URL-style addressing scheme (i.e., similar to the naming of patches, transforms and variables in OSW) and the ability to send just about any kind of data. Using OSC, you can bundle up messages to send between different patches, including patches running on different computers (indeed, you can communicate between OSW patches running on different platforms). You can also use OSC to communicate between OSW and other applications such as Max/MSP, Pd and Csound. More information about OSC, including a detailed specification and a list of applications that support it, can be found at the OpenSound Control home page.

Creating OSC Messages

An OSC message consists of an address followed by one or more arguments. The simplest way to construct an OSC message in OSW is using the OSCMessage transform:

The argument to OSCMessage is the address. The address is a hierarchical, URL-style name beginning with a forward-slash ("/") character. Note that the address is not the name of the OSCMessage transform instance. You can add arguments to your message by attaching various other transforms to the inlets of OSCMessage, which will dynamically add more inlets to accommodate your message (e.g., similar to FanIn).

In the above example, the OSC message has the address /foo/bar followed by an Integer argument and a Float argument. You can use a MessageBox to specifiy a variable number of arguments to your OSC messages:

In this example, the first argument is always an Integer (i.e., because of the attached IntBox transform. The remaining arguments are based on the contents of the MessageBox, in this case an Integer- 3- followed by two Strings: "more" and "args"

The output of OSCMessage is an "OSCPacket". This is a binary representation of the message that conforms to the OSC specification. You can "unpack" an OSC packet and view its contents as an OSW list using the OSC2List transform:

Creating OSC Bundles

OpenSound Control allows several messages to be bundled together into a single packet. Use the OSCBundle transform if you want to group several messages together.

Using OSC Messages

Since the address of the OSC message is /foo, the OSCDispatch transform will match the variable /foo in the Get transform and set the value of the variable /foo to the argument of the OSC message (in this case, the floating-point number 0.08).

Of course, you could do this more easily using the Put transform. But OpenSound Control does have some advantages when you start using wildcard characters in addresses. Consider the following example:

The OSC address contains asterisk ("*") characters, which can be used to match any number of characters in the corresponding OSW variable. The address can match any patch name plus any transform whose name begins with "intbox" and contains a variable named intIn. Now it just happens that the integer boxes at the bottom of the patch are named /somepatch/intbox1 and /somepatch/intbox2 and (like all IntBoxes) each have an inlet named intIn. Thus, both IntBoxes have inlets that match the pattern and will be set to the argument of the message (i.e., the integer 7).

The following wildcard characters are supported in OSC addresses:

1. '?' in the OSC Address Pattern matches any single character
2. '*' in the OSC Address Pattern matches any sequence of zero or more characters
3. 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.)
4. 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 combination of characters in an OSC address can only match those characters (Refer to the OSC Specification for a more complete discussion of address pattern matching in OSC).

Now that you have been thoroughly convinced that OSC pattern matching is extremely cool, we are going to advise you not to use OSCDispatch. If you want to use OSC pattern matching within a group of patches running together (i.e., with one or more OSW patches on the same computer), use Put* instead. Put* supports the full range of OSC pattern matching with one additional feature: like Put, you can use relative paths that do not begin with a '/' character. Additionally, you do not pay the performance penalty of constructing and parsing OSC packets.

Using OSC for inter-process communication

So when should you use OSCDispatch? Suppose you wanted to communicate between OSW patches running on different computers, or between OSW and another application. OpenSound Control acts as a form of inter-process communication when combined with a networking protocol, such as TCP/IP or UDP. You can set up a patch to act as an OSC server that listens for incoming packets and dispatches them to the appropriate transforms:

The UDPListen transform waits for incoming packets on network port 7005 and sends them to OSCDispatch. Assuming the incoming packets are well-formed OSC packets, they will then be routed to any transforms inlets/outlets or variables that match the address pattern(s).

If you want to receive and dispatch OSC messages as in the above example, you don't even have to create any patches! OSW includes a builtin OSC dispatcher on port 7017. So you can have your OSW patches respond to OSC packets from any application that can send OSC messages (e.g., Max/MSP) by routing packets to UDP port 7017. Exactly how you route packets to a UDP port depends on the application, but it can be easily done in OSW with the UDPSend transform. Refer to the Port 7017 Tutorial patch.

OSCRoute

You can use the OSCRoute transform to route messages with different address to different paths. Unlike OSCDispatch (or Put*), the addresses need not correspond to any OSW transform or variable. But like OSCDispatch, it can be used along with UDPListen to receive and route OSC messages from other processes or computers.

OSC and data types

As long as you are communicating exclusively between OSW patches, you can use any valid OSW data type as an argument to an OSC message. The arguments are automatically converted to and from their corresponding OSC formats. However, if you communicate with other applications, you will probably want to limit yourself to the standard data types, such as integer, floating-point numbers and strings. Refer to the OSC Specification for a complete list of supported data types. OSW can only communicate with applications that support OSC type tags!

Since audio signals are a valid OSW data type, just like integers or strings, you can route audio signals between OSW patches using OSC messages, even on different computers. Routing of audio signals between OSW and other applications is not currently supported.