|
|
User Guide |
| User Guide | Transform Guide | OSW on the Web | |
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.
An OSC message consists of an address followed by one or more arguments. The address and arguments are represented in OSW as a list. For example, the following list represents an OSC message with address /fruit/pear and arguments 4 and 5:
The address is a hierarchical, URL-style name beginning with a forward-slash ("/") character, and the arguments are any valid OSW types. Since OSC messages are lists, you can dynamically build complex messages using list transforms, such as Pack and Append.
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.
OK, so now you can create all sorts of exciting OSC messages, but what can you do with them? You may have noticed the obvious similarities between OSC addresses and the hierarchical names of OSW transforms, patches, and variables. OSC messages can be routed to OSW variables of the same name using the OSCDispatch transform:
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 3.14159).
The output of OSCDispatch is a return message. When an OSC message is handled, a message can be returned to the sender. In this example, the message is used to set the value of a variable, so the return message is simply an acknowledgement that the operation was successful.
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 8).
The following wildcard characters are supported in OSC addresses:
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.
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 using the networking protocol UDP. You can set up patches to act as OSC clients that send messages and servers that listen for incoming messages and dispatch them to the appropriate transforms:
The OSCListen 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). Acknowledgement messages will be returned via port 7006.
Visit the sendOSC patch for an example client and osc_server patch for an example server. If you want to simply view incoming OSC messages instead of dispatching them, you can try the dumpOSC server example.
If you want to receive and dispatch OSC messages, you don't even have to create your own server patch! OSW includes a built-in OSC dispatcher on port 7707. 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 7707, as well as from OSW patches using OSCSend. Visit the autoserver tutorial for examples using the built-in OSC server.
As demonstrated in the autoserver tutorial, the built-in dispatcher responds to a number of commands beyond those for querying and setting variables. For example, you can list all the transform types, load new externals, quit the application, and even build patches entirely using OSC messages (see the invisible_patch tutorial). The full set of available remote commands for OSW and strategies for building dynamic interfaces using these commands are discussed in Appendix A.
You can use the OSCRoute transform to route messages with different addresses 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 OSCListen to receive and route OSC messages from other processes or computers.
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.