Skip to content

Tutorial – OpenSoundControl in PureData

I don’t know if it’s because I’m just too thick-headed, but I had some trouble getting OpenSoundControl set up in PureData. Typically in such a situation I rely on online documentation and tutorials to help me figure it out, but in this case I couldn’t find anything straight-forward enough to get me going. So here’s my drop in the proverbial bucket!
OpenSoundControl (OSC) is a cross-platform protocol for networked musical communication. It was developed at UC Berkley at the Center for New Music and Audio Technology. Their website,, contains tools for implementing OSC in various software and hardware environments, including PureData, Max/MSP, CSound, Java, and a ton of other applications. You could think of OSC as a more advanced and versatile implementation of the MIDI concept.
While OSC can be implemented in a variety of configurations, my particular needs led me to try to figure out how to setup a direct computer-to-computer network connection, using PureData (extended) on both ends for the interfacing. If you have Pd-extended, the objects you need are already included. If not, you will have to download the externals and install by hand. Check the site above for information on downloading these externals. I am working on a piece that features CPU-heavy audio processing as well as graphics rendering and physical modeling. Between these two processor-intense modules I was getting fairly poor performance from both the audio and the video. My goal was straightforward: connect two computers via ethernet cable to split up the processing needs. Because of the nature of the engine I was working on, the requirements for communication between the two processes were painfully simple. Since the graphics operate fairly autonomously, all I needed was to be able to send a single packet of numbers to the rendering process every couple of seconds.
The objects themselves are fairly self-explanatory. One side uses the sendOSC object with a list addressed to a specific port that is picked up on the other end by dumpOSC. In order to send the data, a port must be opened on each machine/program. The range is rather wide, the specifics of which can be seen on the above website or the wikipedia entry for OSC. I’ve had no problems sticking around the 7770 range, and I know that some people practice the admirable habit of a uniform numbering system when multiple ports are needed. I just need one, so that’s simple enough. So let’s look at what we need to do here to open up our lines of communication. As I said, this tutorial is specifically aimed at setting up OSC through Pd between two locally networked machines, although the instructions could likely be easily modified to apply to localhosting and internet communication.

1. Find your computer’s default static IP address.

I would actually recommend finding the addresses for both machines, just in case you will need two-way communication. Don’t forget that the number you need corresponds to the machine that is RECEIVING the data. In my case, I was sending the packets from my OS X machine to my XP machine, so I retrieved the IP address from the Windows machine. In OS X, open up System Preferences/Network and choose the “Configure” option with your network adapter selected. You should find it listed as the first address on that page. This website will help if you have any problems with this step:
On Windows (XP in this case, but likely to be useful for other versions) you need to open up the command prompt and enter “ipconfig /all” (without the quotation marks…) and look for your computer’s default network adapter, under which you will find a listing for “IP address”. This was the page on which I found this info:

2. Connect the computers using an ethernet cable

For reasons irrelevant, I have a huge surplus of enthernet cable at my disposal. I was able to make a direct connection from ethernet port to ethernet port. If you are using a router, this process may become somewhat more complicated, although the two sources I listed above may give you enough information to figure it out.

3. Plug the IP address into the appropriate sendOSC object

As I said before, you should have retrieved the IP address for the machine that will be receiving data. In my case, I will be transmitting to the XP machine. Open up Pd on the sending machine and either in a new patch or in your project create the sendOSC object. sendOSC does not take any arguments, so your new object should be ready and waiting for instruction. Connect a message box to sendOSC with the message “connect 7771″ (replacing the IP address with the one you retrieved earlier). The second number in the message is the port you will be opening on both ends. If 7771 is already being used by another app, you should have no trouble finding one that is free. Go ahead and create a “disconnect” message in a separate box for when you complete your session.

sendOSC connect

sendOSC connect

4. Call the dumpOSC object on the receiving machine

Take the port number you used earlier and use it to create the dumpOSC object with the port number as the argument. To check if everything is working up to this point, you could go ahead and “connect” on your transmitting machine and create a new message box that says “send test”. To send any data all you have to do is make a message box starting with the word “send” and connect it to the inlet of the sendOSC object. Any information in this message that follows will be sent across the line to the open port. If you connect your dumpOSC object to a print object and click your “send” message, you should see your transmission on the message window of the receiving machine. If not, you need to go back and make sure your ports match, you took the correct IP address (and not the address: this is a loopback that will send any packets back to the machine that sent it), and that all of your syntax is correct in the messages and objects. At this point I began to find the information in the built-in help files for the OSCx library useful.

send /vid/token

send /vid/token



5. Making OSC work for you

If you made it this far, congratulations on getting your connection up and running! It took me more time than I would like to admit… :) Now you can start to personalize your implementation for your specific project. There is one more very useful object included in the OSCx library that may help you. You are of course welcome to send your OSC packets in any format you choose, but included is an object to sort through the incoming messages with style and ease. OSCroute operates basically like the route object, except that it is able to parse tokens that are not separated by white space. So if you send a message that reads “send /vid/token hello world” you can set up a filter network on the other end that will first direct messages to “OSCroute /vid” and then to “OSCroute /token”. This diagram will explain the process a little better.



As I said, it’s not absolutely necessary to use this syntax, but it helps when setting up your routing network.

With that, you will hopefully be well on your way to using the OpenSoundControl protocol for whatever needs you might have. From what I’ve seen, this is becoming the de facto standard when it comes to networked musical communication. I hope you found this tutorial helpful! If you have any problems, feel free to leave a comment or send me a message.


Wikipedia entry for OpenSoundControl

  • Stella Taste

    If you were a student in my fall course, the tutorials would make up a big part of your learning assignment. Stella Taste

  • Aaron

    I’ll be honest with you… Even though I let the comment from “Stella Taste” through the filter, I’m not totally convinced it’s not spam. Any help, anyone?

  • hinkey

    It’s a bit fishy, yes. The tutorials would make up “a” component, hopefully being required completed by the first week, and then you’d get into practically applying the program while learning other things about science of sound and other softwares (not that, without a science background, you’ll be able to understand any of it, mathematically).
    But “a BIG part” of a semester course? Either a rip off and sad statement of current college education and its cost…or spam.

  • Dalia S.

    Thanks! This helped me a lot!