Pure Data (PD) is a visual programming language for MIDI and audio signals. It is similar in design to and somewhat interoperable with the proprietary MAX/MSP software for Mac and Windows.

Install and Launch the Application

As this is a basic tutorial, we will only deal with running PD itself. It can be expanded, by the use of the GEM package, to include visual editing capabilities but this tutorial will not deal with that. We could also explain every technical detail of the language but this is a quick tutorial on how to use PD, not a documentation of the program.

First, grab the PD package:

 sudo apt-get install puredata

Then simply click on the PureData icon in the Applications>Sound&Video menu section or open a terminal and type:


You will be greeted with a grey window - this is the message or PD window - where the output of any 'print' commands or errors can be viewed. The program is now up and running.

Create your First Patch

To create a blank canvas to work in you will need to click the 'File' menu and select 'New'. You will notice keyboard shortcuts throughout the menu system (e.g. 'Ctrl+n'), these are extremely useful in speeding up productivity but I will guide you through with the mouse in this tutorial.

There are two methods of working in PD; the default when you create a new patch is edit mode on, to start using a patch you must turn edit mode off. Edit mode can be turned on or off freely by selecting it at the bottom of the Edit menu at any time - even when the patch is running (this allows for live coding). Leave Edit mode on for now.

The first object I will introduce you to is the bang. Click on the Put menu and select 'Bang', your mouse should now have a blue square following it around. Click anywhere on the white canvas area. You have now created an object (a bang) in your patch. A bang object sends a trigger (or bang) message out when it is clicked on or displays a flash when a bang is received by it.

Next click on the Put menu, select 'Object', and click in a blank space on your canvas. You will see a blue dashed rectangle with a text cursor appear (this is a blank object waiting for a command). Type in this box "print" and click away from the box. You have now created a print object. To make these objects interact we will have to connect them with a patch cord.

Patch cords are signal carriers, there are different types depending on what types of signals they carry but the program will select the right one for the job - not you. You will notice that at the top left of the print object you just created that there is a small dark rectangle. These rectangles are places where patch cords connect; the ones on the top of an object are called inlets (because they let the signal in) and the ones on the bottom of an object are called outlest (because they let the signal out). Patch cords will always travel from the outlet of an object to the inlet of another object (or same object in some circumstances, but watch out for logic loops!!!). To connect a patch cord, hover your mouse over the outlet of an object - do this with the bang object you created - you will see your mouse cursor turn into a circle, click, hold, and drag your mouse onto the inlet of another object - we'll use the print object - until your cursor turns into a circle, and let go. You should now have a line joining the outlet of your bang object with the inlet of the print object and it should look like this:


You have finished building one of the most basic patches in PD. Now switch out of Edit mode (in the Edit menu), click on the bang button, and watch the PD window. Fun, isn't it.

Elaborating on the Basics

Now that you're bored with that, we'll take a look at number objects (in the 'Put' menu). These come in very handy as error-checking devices, user interface readouts, and storage places to name a few uses. A number object will take a number in its inlet, release it directly out its outlet and display that number until a new one replaces it. It will also accept numbers in the form of keyboard input (must be selected first), and by clicking on it and dragging your mouse up or down. Number boxes will also release it's stored number out its outlet when a bang is recieved in its inlet. To better understand these concepts build a patch that looks like this and play around, watching the PD window:


Before I continue any further I should make note of PD's excellent documentation and help files. These can be accessed through the help menu on the upper right of any window in PD or by right clicking on any object and selecting help from the dropdown menu. I frequently refer to these files to clarify questions I have about objects, and I would suggest you do the same. What I can teach you in this tutorial is very limited whereas what you can teach yourself is almost limitless with the documentation PD provides. That being said, here's a few more basic objects that I find very useful in my programming.

Message objects (also in the 'Put' menu) are similar to number objects in concept but have much fewer functions. They store a message - that is usually given to them at time of creation - until any signal is given to their inlet or they are clicked on, at which time the message is sent out their outlet.

A Vslider (in the 'Put' menu) is a vertical slider that releases a number from 0 to 127 (default values) when it is moved by the mouse, recieves a number in its inlet, or recieves a bang. The default values can be changed by right clicking the slider and selecting 'properties' - this is a feature that exists for modifying many objects - though these values are set to assist with MIDI programming.

Math objects are some of the most commonly used objects. To create them simply follow the steps above for a print object but instead of typing print, type any of the following:

  • +
  • -
  • *
  • /
  • pow
  • ==
  • !=
  • >

  • <

  • >=

  • <=

  • mtof
  • ftom
  • powtodb
  • rmstodb
  • sin
  • cos
  • tan
  • sqrt
  • log
  • exp
  • abs
  • random

This is not a complete list, there are about twice as many. They should be mostly self explanitory, the ftom converts frequency to midi pitch, the rmstodb converts root mean squared to decibel and so on (check the help files of each for more details).

MIDI objects are mostly in/out based objects such as:

  • notein
  • noteout
  • pgmin
  • pgmout
  • bendin
  • bendout

There are a few other MIDI objects but I'll let you look them up. A basic note about MIDI: a note-on message is a note message (pitch, velocity, and channel) with a velocity above zero and a note-off message is a note message with the same pitch and channel but with a velocity of zero. To work in musician's terms of a note with a designated duration, we'll regularly invoke the makenote object. Take a look at makenote and stripnote object help files to better understand MIDI in PD.

Audio objects are denoted in PD by ending in a tilde (~). Audio in PD is merely single data points (a number) sent 44100 times per second (this rate can be changed in the 'media' menu in the PD window). Even if the audio signal is silent, a zero will be sent every 1/44100th second (look at the help file for print~ for more info). This should be kept in mind when manipulating these signals. Oh, and before any of the audio objects will begin processing, you must turn audio on in the PD window (or by using the swith~ object). Here are a few basic audio objects:

  • +~

  • -~

  • dac~
  • adc~
  • osc~
  • line~
  • tabwrite~
  • tabplay~
  • noise~
  • env~
  • vcf~
  • hip~
  • lop~
  • samphold~
  • delwrite~
  • delread~

Please make sure to check out the PD documentation as there are many more very useful objects documented there.

One last note before we really begin creating patches is that computation will always occur in a top-to-bottom rigt-to-left manner (i.e. if two patch cords leave the same outlet, the one going farthest right will recieve a signal first and if an object has two outlets both connected to a print object, the rightmost outlet's signal will be printed first).

MIDI Patches

In this section I assume you have at least a basic MIDI setup.


The first patch we will create will be nice and simple, we will elaborate further later. Here is what it will look like in the end:


This patch contains a Vslider with it's default 0-127 values, connected to the pitch inlet of a makenote object, and the output of the makenote object is being routed to a noteout object. Makenote is given two arguments at time of creation (separated by a single space) the first gives all the notes a velocity of 60 (on a 0-127 scale), the second gives all the notes a duration of 500 miliseconds (a half note at 120bpm). Both of these given arguments can be overridden by passing a number from the respective number objects into makenote's inlet (a note of warning, stay away from excessively long duration values).


In the next step up, we automate the above patch and add a simple pattern to it. Our patch will now look like this:


We have taken the same basic patch as above (note one the duration paramater of the makenote object has been altered), added a couple metronomes that are controlled by a single toggle box, a comment to explain that toggle box, a random number generator, a basic counting system (underneath the 'metro 250'), and a way of controlling the global tempo.

The basic counting system works by taking the output of the Vslider into the 'set $1' message box (the $1 is a special character that is replaced by whatever comes in the inlet), which sets the number box without the number box letting the number out its outlet; the 'metro 250' object then sends a bang to the number box every 250 milliseconds thus sending the number out to the '+ 2' math operator that then adds a whole tone (two steps in MIDI) and sends the signal to the Vslider.

The global tempo controller is much simpler to understand. It uses the existing number box that controls the note duration, sends the same signal to the 'metro 250' object, and sends a number three times the size to the 'metro 750' object. Really all that is needed to maintain the patch's pattern is for both the metro objects to remain at the same ratio; the duration of the notes does not have to be controlled by the same number object, but for simplicity's sake we've used the existing control.

When running this patch it will most likely sound like there is a major second played, followed by two whole tone steps up from the top note of the major second. This is caused by the fact that both metro object hit at the same time and the 'metro 250' then hits twice more before the next cycle in the pattern. If you follow the top-to-bottom right-to-left data flow with this in mind you'll understand why the musical pattern is the way it is (the 'metro 750' is what creates the bottom note in the major second).

More MIDI to Come...


A few basic notes about audio data handling in PD: when two patch cords come to the same inlet the signals are added together (like mixing two tracks to a single mono track), all patch cords are mono and I'm pretty sure all objects are too, and always make sure the PD window is computing audio before you start. If audio produces any errors or doesn't work for you, play around with the settings in the 'Media' menu of the PD window.


Here is a basic introduction to volume control in PD:


To hear this, plug a microphone into your soundcard, raise the Vsliders and talk into the microphone. A note about 'adc~' and 'dac~', these can take an argument (i.e. 'adc~ 3') to denote how many ins/outs you'd like to use on your soundcard - the default is 2.

Here is a basic audio synthesis patch with both volume and pitch controls built in:


More to come...

HowToPureDataIntroduction (last edited 2012-06-27 04:06:11 by c-24-99-1-230)