Introduction to Pure Data

This page was set up by Edward Kelly to provide an introduction to Pure Data (Pd).

Pd was created by Miller Puckette and many others have contributed to its development over the years. The community site is at puredata.info.

Pure Data was originally created as a computer music dataflow programming environment, but it has been expanded and enhanced to include objects for manipulating video and 3D graphics, neural networks and a huge variety of sound and image analysis and creation tools. You can begin learning Pure Data techniques for any object or library of objects by searching the help files and examples from the help -> browser -> Pure Data, and also for any externals you have downloaded (more on this later) but there are several online tutorials and books available. Here are some of them:

1. www.pd-tutorial.com is an online version of the book Loadbang by Johannes Kreidler. It is concerned solely with sound synthesis techniques in Pure Data, but is a good place to start learning.
2. Floss Manuals have a good beginners tutorial for Pure Data. You can find it here and it covers audio, dataflow, GEM 3D graphics and video programming for beginners.
3. The manual to Pure Data can be found at Miller Puckette's website here. Miller has also written a book, Theory and Techniques of Electronic Music - a comprehensive guide to computer music theory with applications in Pure Data.
4. Dr Raphael Hernandez has a series of tutorials for beginners on YouTube.
5. I have created a some video tutorials on this Vimeo site.

You can download the latest stable releases of PD at puredata.info/downloads

Pd is extendable using libraries of externals - objects created by programmers around the world. It used to be the case that a distribution with most of the available externals, called Pd-extended was available, but this is now dead. Instead, there is Purr Data that implements many of the available externals. In fact, Purr Data has taken over from pd-l2ork now and you will find that installers are named pd-l2ork (l2ork stands for Linux Laptop Orchestra) but will run on any platform. This page will first describe the process of setting up Pd Vanilla on your system, followed by a discussion concerning Purr Data.

While Purr Data offers a much more aesthetically pleasing GUI, Pd Vanilla is generally the most stable platform. Pd itself comes with a few externals by Miller Puckette himself, and it used to be the case that you needed to engage with compiling software yourself if you wished to augment the functionality of Pd with externals from other authors. However, the newest versions of Pure Data have a relatively new feature called the Deken system for installing externals, accessed via the Find Externals entry in the help menu.

Using External Libraries in Pd Vanilla

If you've been used to working with Pd-extended, or compiling external libraries into the pd/extra folder and adding their locations to the search patch, or if you're new to this, there are some changes to the way libraries of externals are used in the latest Pure Data distributions that you should be aware of.

As of Pd-0.48.1, when you first start Pd it will create a folder in your Documents folder into which Pd patches may be saved and externals installed. The big change in recent years is that you have to declare the use of a library before you can use it.

---

Path Setting in Preferences

When you download a library in Pd-0.48 it will ask you if you want to create a path to the library in preferences.

You can also add libraries of abstractions to the search paths, such as the wavefolding objects, ninja tools or Metastudio abstractions from this site (Beware - I am currently updating Metastudio and other files to work with the new system - I will change this text when this is complete).

There used to be a distribution of Pd called Pd-extended maintained by Hans Cristoph-Steiner on which Purr Data is based. The basis of Pd-extended was to provide a distribution with as many externals as possible that was easy to install and use. For a number of years there wasn't a working replacement for Pd-extended, and patches built with Pd-extended were difficult or impossible for new users to use with Pd vanilla. But now at last there is Purr Data, created and maintained by Jonathan Wilkes

There are arguments for and against starting to learn Pd with Purr Data rather than the core Pd, and it is up to you which route you take. Certainly the students in Fine Art I have taught much prefer the ease and simplicity of installing and using Purr Data (and the Node.js interface) so this may suit you. You can read more about Purr Data here.

---

Getting Purr Data

You can download releases of Purr Data from https://github.com/agraef/purr-data/releases. There are distributions for Mac, Linux, Windows and even Raspbian (Raspberry Pi). A major difference between Pd Vanilla and Purr Data is that Purr Data comes with many of the available libraries pre-installed and ready to use.

---

Tcl/Tk vs Node.js Interface

Pd Vanilla uses Tcl/Tk as the platform on which the user interface is built. While this gives it a distinctly clunky look, it is very reliable and solid. The interface for Purr Data is completely re-written in javascript and incorporates Scalable Vector Graphics (SVG). The interface is essentially a stand-alone webkit-based browser engine built on the Chromium platform.

---

Functions for Speeding-up the Process

If you work with Pd a lot there are some procedures that are particularly irksome! Purr Data has a couple of tricks that take some of the drudgery out of patching.

One-to-many Connections

If you have to connect a single object to a large number of objects, it is very time-consuming to connect each one by hand, one-by-one. In Purr Data, you can select the objects you want to connect to, and then by connecting another object to one of them they are all connected automatically. Note that objects here means objects, messages, numbers, GUI items and so on. There are three ways in which Purr Data implements time-saving connection schemes to speed up editing.

Select destination objects to connect to...

...connect an outlet to one of these, and all are connected.

Many Objects to Many Inlets

Select both the source objects and the object with many inlets...

...and by connecting the first, all the connections are made.

Many-to-one Connections

Select a group of objects to connect to one...

...connect one to an object and they all connect.

A Pd patch saved to disk may be loaded inside another patch if the other patch is in the same folder, or if the folder in which it is contained is in the Pd search path (see above in the section about Pd vanilla with externals, although this also applies to Purr Data). This is known as an abstraction. There are many libraries of abstractions available and you might want to create new abstractions to carry out procedures that are frequently used. It is a good idea to have these to hand so that you don't have to keep repeating the same process in each patch.

A simple abstraction (mix~.pd) loaded inside another Pd patch. The wavevoice~ object is also an abstraction.

Pd has an excellent feature for using abstractions called graph-on-parent. Right-click (or CTRL-click if you have a one-button mouse) on empty space inside a patch, and select properties. You can then check the box for graph-on-parent, specify x and y margins and sizes, and create graphical objects within that space which is shown as an orange box within the patch with GOP (graph-on-parent). This also works for subpatches, and every time the abstraction is invoked within a Pd patch, the GUI will appear provided that the patch is either saved in the same folder as the patch from which it is invoked, or the folder location of the patch is specified in the Path preference within Pd.

The abstraction above is actually this patch. The orange box shows the area where GUI objects will appear in the master patch.

Subpatches and Abstractions

An abstraction is a patch loaded within a patch by either placing it in the same folder as the master patch, or adding the folder containing the patch to the search paths in Pd. However, you can compartmentalise elements within a patch by creating subpatches.

To create a subpatch within the master patch, create an object and type pd - you can give the subpatch a name if you wish, and subpatches' audio can be switched on and off using the switch~ obect.

A Pd patch with some subpatches.

Locality and $0

When creating abstractions, you can still use send and receive objects and arrays. If your messages and arrays (e.g. soundfile tables) are only referenced within the abstraction, you can use $0 to make them local to the abstraction.

Why do this? Well one example is given here. Normally each array is visible to the entire Pd environment, and each array (such as that used to store a soundfile) has to have itsw own unique name. Another approach to the soundfile player discussed further on (in the arduino section of this page) is shown below, using the tester~.pd object from the metastudio-0.5 library of abstractions available on this site (or click here). It has localized tables ($0-test) and variables ($0-play) so that multiple tester~ abstractions can be loaded, each with a different audio file.

Abstractions with $0 locality. Note the use of route to extend the functions available from outside. Control inlet and outlet, and signal inlet~ and outlet~ objects are used to interface to the outside world.

To Do: $1 $2 etc arguments to an abstraction.

While Pure Data was originally designed to create computer music and interactive audio work, it has been expanded in many directions to include libraries for working with 3D graphics, video, artificial intellingence and more.

• GEM is a 3D graphics library, and you can also work with images and video using the pix_ objects. You can project movies, textures, color and lighting onto 3d objects, interact with particle generators, simulate elasticity (with PMPD by Cyrille Henry) and import 3D model meshes (wavefront .obj files - a number of software packages support this format). GEM works on Windows, Linux and Macintosh operating systems. There is also a library for dealing with Open Computer Vision (pix_opencv) and augmented reality (pix_artoolkit).
• PDP is a library for manipulating data packets, i.e. video frames.
• Cyclone is a library of cloned Max/MSP objects for Pure Data. While Pure Data itself is not a direct copy of Max/MSP (The original patching system by Miller Puckette) the cyclone objects reproduce the functionality of many of the most useful objects from Max/MSP.
• Zexy is a very useful library of objects from Iohannes Zmoelnig.
• The mrpeach and osc libraries allow you to send messages, data, parameters etc using Open Sound Control (OSC) over a network, i.e. to another computer or to another piece of software running on your computer (e.g. Processing).

This is not an ehxaustive list - it is only by getting a library and playing with the help files that you can understand what they do. Note that the links above mostly point to source code - you should get these objects using the Deken system (see above) or use the ones that come with Purr Data (note: updates to Purr Data should be available from time-to-time).

If you are familiar with compiling software and working with build systems, you can get hold of the source code for Pd, externals and pretty much everything else by following the instructions on this page. It is also worth investigating the abstractions folder within this repository, as it contains many libraries of Pd patches that may be useful to you. Sources for Gem, Libpd (embeddable Pd), ofxPd (Pd as an addon to openFrameworks) are also available. The Pd-extended repository is quite old and should be skipped in favour of Purr Data. Purr Data sources can be downloaded from the Github site.

If you are already coding (or learning to code), you can start with the document HOWTO write an external for Pure Data. This won't teach you all the coding tricks you need, and you can learn a lot by looking at other people's source code.
It's generally advisable to work with what you have. If you can make what you need within Pd it's probably the best way, but if you find something that you simply cannot do with Pd or with an already existing library, then you may need to create your own library. This is not for those new to coding, or to Pure Data.

Alternatively, if what you need to do is easier, more possible or only available in another programming environment (processing, openFrameworks) there are some objects that embed within Pd (e.g. Csound) or ways of embedding Pd in the other environment (ofxPd) but much of the time you will need to use network sockets using the netsend object in Pure Data, or the UDP and TCP objects in the mrpeach library, and often some protocol to handle data formatting and retrieval (OSC - Open Sound Control objects) and a similar library in the other software environment or package (such as the oscp5 library for Processing).

Pduino is a set of abstractions and arduino firmware that allows you to use the arduino board with Pure Data.

Programming the Arduino Board

Arduino can be configured to accept a wide variety of digital and analogue inputs, and the boards can drive motors, solenoids and other electronic actuators.

Modern arduino boards have flash memory onboard, so that the programming (sketch) code will persist if the board is unplugged. To use arduino when it is not connected to a computer you need a +5V or greater (up to +9V) power supply to power the board.

To use the arduino with Pd you need a copy of the arduino IDE from https://www.arduino.cc/en/Main/Software. To use Pduino, which is the Pure Data arduino library, you also need the comport library installed in Pure Data (this is installed by default in Purr Data). You can get Pduino from https://github.com/reduzent/pduino, or if you're using Pd vanilla you can install it with Find Externals (the Deken system) in the help menu.

Before diving into the Pduino interface, the arduino Standard Firmata code needs to be uploaded to the board. Open the arduino IDE and you will see a blank sketch as shown below.

You need to check that your board is connected from the Tools menu.

Then you need to select the Standard Firmata from the Examples in the File menu.

If everything is configured correctly, click the upload button in the IDE and you should see some lights flash on your arduino board. If not, red warnings will appear in the black panel at the bottom of the IDE. Check your port and board settings - if necessary, try another port. Port names on Mac OS X are often a confusing jumble of letters and numbers. Your arduino may show up as a "USB modem" or some other device in the port settings.

Pduino

Once you have the standard firmata uploaded you can open the Pduino interface, called arduino-help.pd.

The Pduino-0.6 interface.

The subpatches of the help patch show you difference applications of the arduino interface, so for example clicking the subpatch labelled pd INPUT_ANALOG will bring up the window shown below.

The INPUT_ANALOG subpatch, with a sensor connected to analog 0.

Minimal Pduino

While this is useful for testing, it makes sense to strip the interface down to its basic components once you have determined what inputs and outputs your project will need.
The [arduino] object in the top-right part of the patch is an abstraction - a patch that sits in the same folder as the master patch, and is used as though it were an object. It is an interface to the Standard Firmata running on the arduino, connected via the comport Pd library. Click on the [arduino] object and you will see the patch shown below.

Inside the arduino.pd patch. You can see the comport object in the middle.

You can save this patch and use it in your project folder.

Although there are GUI objects in the arduino-help.pd patch, the [arduino] object is configured entirely using messages, and outputs from the object corresponding to inputs to the board are directed to Pd objects using [route analog digital] objects followed by [route 0] [route 1] etc. Similarly, arduino output modes, pin states and other aspects of the arduino can be configured using messages, so once your setup is configured you can copy the relevant messages to your master Pd patch (with the arduino.pd patch inside it as an abstraction) and get rid of the unnecessary functions you don't need.

[open 0( will open the connection to the arduino if it is on COM0 or the first USB connection. You can check which connection the arduino is on from the arduino IDE, from the Tools -> Serial menu. The order of the list of ports starts from 0 and enumerates up. However, in Pduino-0.6 there is a [devices( message at the top of arduino-help.pd that will print out the port number in the Pd console.

This shows that the port number of the connected arduino board is 33.

By discovering what messages you need to send to arduino within a Pd patch in order to set it up, you can create a minimal interface that only includes the features that you need to use. The patch shown below uses 4 proximity sensors to trigger sound events. Note that by using bangs, there is not indication as to which sound will be triggered (in fact it was random in this patch) - you could use numbers instead to implement multiple, specific triggers with the select object in Pd.

An arduino patch to setup 4 analog sensors as triggers for a random soundfile player (not shown).

This time the sensors would be used to trigger specific audio files (tables).

Pd patches such as those shown above are initialised on load using the loadbang object, and so in the patch above the pd LOADING subpatch looks like this.

Note the loading mechanism is also automated.

If you are installing into a gallery, it is possible to create scripts for something like a Raspberry Pi computer running Pd, so that the entire system boots up, launches Pd, loads the patch and initialises itself just by turning on the power. In this way, complex setup procedures for setting up installation work can be avoided.

Here I will provide links to other resources, and hard-to-find code for working with Pure Data.

pd-wiringpi is a library for working with the GPIO pins on the Raspberry Pi.

Here are the workshop examples from the Low Residency session at Camberwell in February 2018

Camberwell-2018.zip