Personal tools
You are here: Home documentation Start Here

PourCommencer(fr) - StartHereJapanese(ja) - ComeceAqui(pt) - ComienzaAqui (es)

If you're just getting started with Pd, read through this page for the basics.

Getting Started with Pd

The easiest place to start is to install Pd-vanilla. Versions for all platforms can be downloaded here:

Install Pd-vanilla and launch the application. You'll see the Pd window appear. The Pd window provides helpful feedback but you don't need to pay attention to it right now.

Exploring a Patch

Pure Data files are called "patches". Let's have a look at a very simple one. Under the Help menu in Pd-vanilla, open the Browser..., click on the first item in the list, Pure Data/, then click on 2.control.examples/. Open the first example patch, 01.PART1.hello.pd.

There you can click and test a simple "hello world" patch! (check the results at the Pd window)

Interesting huh? Pd patches work in realtime, so you interact with the code and get some result immediately. This is perfect to implement some ideas on the fly and create musical instruments that react to user input. But to do these things, we need to know how to create something, and what we can create, right?

How Patching in Pd works?

Before continuing, beware that here we will give you a very simplified overview about the topic. If you want to read a more in depth text, the official manual has an wonderful section about that, and you can read it here: Theory of Operation (you can try to read it now or read it later, but it is very important that you check it at some time to understand very important concepts about patching in pd).

Creating a Simple Patch from Scratch

Having said that, let's create a very simple patch from scratch to hear some audio from pd!

Go to File -> New and a blank window (or canvas) will appear. How intimidating!

Before creating anything in this new canvas, let's learn something very important. Pd patches has two Modes of Operation, one of them we call Edit Mode and the other doesn't have a name inside the software, but you can call it Run Mode or Performance Mode or Interactive Mode (it is just "not Edit Mode", the manual for example calls it Run Mode just by convenience).

To change in which mode we are, we have two options. The first is going to the Edit menu and clicking on Edit Mode. But this isn't very fast, and we will need to change the modes a lot when patching, so, this is a good moment to learn by heart the shortcut for edit mode: Ctrl + E (or command + e if you are on mac). The title bar and the mouse icon will change depending on which mode you are, as you can see:

So let's create something! Go to the Put Menu and select Object. By doing that Pd will automatically change to Edit Mode, and the mouse will carry a dotted box around. Click somewhere in the patch to put it there, and then write "osc~ 440", and after that click somewhere blank on the patch to instantiate the object. If everything goes well, you will have a box just like this one:

If for some reason you give a wrong name to the object (missing the tilde for example), the object won't create and will generate an error on the pd window:

But this isn't such a big problem, just re-edit the box by clicking on it and typing the correct name, click outside and the box will be created correctly (be sure to be on Edit Mode, otherwise you won't be able to edit the box, test it if you want). In the section List Of Objects we will show you how to find all the names for the objects and how to see the helpfiles of the objects, for now, let's just continue.

osc~ is a sinusoid oscillator, an object that generates an audio signal using a cosine function. 440 is the first argument for that object, that in this case set its frequency to 440 hz. This argument is optional and just set the start frequency of that oscillator (we can change it later by sending a message to its first inlet, as we will see in the section about interaction with objects).

But as you can see (or hear) there is no audio (yet). Before hearing anything we need 3 more steps. First, to train our "creation of objects" brain muscle memory, create *~ 0.2 and dac~ and put the objects like this image:

*~ is an object that gives us a way to multiply signals in Pd ( * is used as multiplication operator in many programming languages). 0.2 is the argument for the object, in this case the number which we will use to multiply the signal. This means we will reduce the gain of the signal to 20% of the original (which is roughly a 14db reduction). This will make the signal quieter (just for precaution, we don't want to blow your speakers with a loud sound).

dac~ is the object in Pd that represents your actual speakers, DAC means Digital to Analog Converter, so its function is to send the digital signal (from pd) to your audio interface (where the true dac exists and then sends the signal for the speakers).

Ok, for the second step (we are almost there, I promise!), we need to connect these objects. To do that, while in Edit Mode (probably you never left it yet, right?) we need to hover the mouse over the black rectangle that exists on the bottom of the objects (we call it an outlet) until the mouse icon changes, than drag the mouse to another black rectangle on top of the next object (we call that an inlet). For the first tries it may be difficult to do this so you may need some practice to find the right spots. Note that the connections only happen from an outlet to an inlet, never the opposite:

No Sound... How to Turn DSP on

Nice! Everything connected, but no sound yet... I did this on purpose, sorry, but for a good reason. The last step consists in telling pd that we want it to process signals. By default pd opens with "DSP off", so every object whose name ends with a tilde (~) won't generate nothing until you turn DSP On (btw, DSP means Digital Signal Processing). We can turn DSP on in four ways:

# You can go to the Media Menu and click on DSP On, and then turn it off by clicking on DSP Off

# You can find the DSP toggle on the pd window (top-right) and click on it.

# You can memorize the shortcuts for DSP On (ctrl + /) and DSP Off (ctrl + .) (People who use supercollider will recognize ctrl + . to stop all sounds)

# (advanced for now, but exists and it is important to be aware of) You can send the message "dsp 1" to "s pd", some helpfiles have this approach to turn dsp on automatically, that's why sometimes you will get dsp on without having changed it manually. No need to worry about this now, though.

Amazing. If you turn dsp on and heard our 440 hz sinusoid everything worked! If not, maybe there is some audio settings missing, you can read here on the official manual to see if everything is right: Audio and Midi

Auto Patching

There is also another way to create objects and connect them automatically that is useful to learn, so let's modify our patch a little using the auto patching feature!

To start, let's learn the shortcut to create an object. It is Ctrl + 1 (or command + 1 in mac).

So let's create an osc~ with a different frequency, osc~ 442, do Ctrl + 1, type inside the box and Wait!

The ~ trick ~ now is that when typing the name of the object, we won't click outside to instantiate it, instead we will do the shortcut again, and that will create another new object below the one we just created, and it will be already connected to the first one. For this one we can do *~ 0.2 again, and finally click outside to end the chain, see the image:

Nice, objects created, so let's now insert that signal on the second inlet of dac~ to create a nice beating effect, but before doing that, let's learn how to delete a connection: To delete a connection, while in Edit Mode, click on the connection (or cord, or black line) and it will turn to blue, showing that is being selected. With the connection selected, press delete, and the connection will disappear. so try to insert our new objects as in the image:

A small curiosity here: If you pay attention when doing the auto patching, when you pressed the ctrl (or command) and hold it (before pressing the 1 to finish the shortcut) the mouse icon changed just as if we were changing the mode (you can check the previous gifs that the mouse changed before the new object was created). This is another feature, in which when you are on Edit Mode you can go to Run mode for just a moment while holding the ctrl, and come back to Edit Mode after releasing the ctrl, this may became useful later!

But anyway, let's train more our new skills with ctrl + 1 and auto patching, try to make this next patch, just for fun:

The Objects are:

# phasor~ 0.5 : this generates a ramp signal from 0 to 1 with frequency 0.5 (which is the same as a period of 2 seconds, the period is the reciprocal of frequency), this continuous ramp can be regarded as a sawtooth oscillator (but we use it more as a phase generator to index tables... hence its name, there are better oscillators to use as sawtooth oscillator for audio in some libraries), but since its frequency is very low, it is acting as an LFO (low frequency oscillator).

# *~ 12 multiplies the signal by 12, transforming its range from 0 to 1 to 0 to 12.

# +~ 60 ads 60 to the signal, so its range now is from 60 to 72

# mtof~ converts values in midi note format (60 is middle C and each step is 1, so C# is 61 D is 62 and so on) to frequency numbers, so it takes our signal 60 to 72 and creates a ramp with frequencies of one octave, starting at middle C

The rest we already know, it is osc~ -> *~ 0.2 -> dac~ . Note that we didn't put any initial frequency on osc~ because it would be useless in this example. That frequency argument just initializes the oscillator, but as soon as it receives another number (from a message) or a signal, it will replace its internal frequency and the argument won't do nothing anymore.

Fantastic! And now it is a very good moment to learn how to get help on each object, so you can discover what every one does by yourself, let's go!

Help Files

For every object you want to know more about, you can check its helpfile! It is easy. Right click inside the object and a little menu will appear. Click on Help on that menu and voila, its helpfile will open. And the good news, since the help is another patch, you can interact with it, copy and paste just as a regular patch!

For example, right clicking inside of an osc~ object wil show this menu:

And then selecting Help will open osc~ helpfile:


If instead of right clicking on a box (being an object or not) you right click on any blank space on the patch, the menu will also open with a help entry, but clicking on this help will show you the List of Objects! This list has all the objects available in pd-vanilla, so you can go from there to their helpfiles and discover new objects to use!

This list of objects is also available on the Help Menu -> List Of Objects

Ok, but where is the interaction?

(TODO add examples with messages, number boxes and sliders to change the frequency of the oscillators)

About Externals

In addition to the objects pd-vanilla comes with, you can also add more functionality to pd by adding externals to it. This is specially relevant since Pd-extended (another distribution that is dead long ago, and had many additional libraries) had many tutorials that are still alive on the internet, but unfortunately these tutorials rely on these externals and you will probably get some "couldn't create..." errors on the pd window when trying to create those objects.

But installing and searching for these objects and libraries are easy with the Deken tool, that can be found on Help -> Find Externals. You can read more about that in the official manual, here: Help > Find externals


(TODO: get the links about other tutorials here and say that flossmanuals are for pd-extended)

You're now on your way to programming in Pd. Move on to the Pure Data Floss Manual for a more in-depth introduction.

Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser