LJ Archive

A Pure Data Miscellany

Dave Phillips

Issue #217, May 2012

An introduction to Pd—a graphic patching environment designed for audio production and processing, with extensibility for the addition of other media-related features.

After reviewing recent trends in the world of SuperCollider3 for LinuxJournal.com, I decided to investigate activity in the world of Pure Data, better known to its users and abusers as Pd. However, instead of offering up yet another tutorial on this or that aspect of Pd, I've opted for a nonlinear account of my experience with the system.

What Is Pure Data?

Pd often is described as an example of a “visual programming language”, a definition that is at least broad enough to avoid inaccuracy. Personally, I define Pd as a graphic patching environment designed for audio production and processing, with extensibility for the addition of other media-related features, such as tools for processing images, text and video. Pd's graphic patching capabilities consist of a small collection of basic units—objects, messages, numbers, symbols and comments—that are placed on a canvas-like work area and graphically connected (patched) into signal processing networks (Figure 1), a process similar to constructing a sound-producing arrangement of modules on an old-school modular patching synthesizer. Of course, Pd is a little more modern and a lot more flexible. Its basic units are not predefined synthesis or audio processing primitives. They can be those things (and much more), but you need to define them as such, and you need to know what definitions and values are allowable for each type of unit. Figure 1 illustrates a small Pd patch with four basic units and some typical values in place.

Figure 1. A Simple Pd Patch

This patch creates the sound of a sine wave at 338Hz. The waveform and its amplitude are defaults for the osc~ object. The frequency value is supplied by the number box. The dac~ audio output object receives sound data from the osc~ object and can be switched on or off by clicking on the message boxes. The GUI clearly indicates the connections between the patch's components and the signal's path through them. The patch is complete, but no amplitude envelope is present. When the Compute Audio button is checked, the patch immediately will play at the default amplitude and continue until switched off (the message box with the 0 value).

The example is here merely to present a picture of Pd's GUI. I could go on to add an envelope generator and an on/off switch, and I could proceed to inform my readers about details like hot and cold inlets, the order of the processing graph, how to add GUI elements and myriad other things you can learn by studying Pd's extensive documentation.

Incidentally, many users hear about Pd with some reference to the famous Max/MSP program commercially available from Cycling 74. The reference is understandable—Miller Puckette, Pd's author, is also the author of the original Max/MSP. I'm not sure why he would create an open-source alternative to his (very successful) commercial software, but I'm comfortable with his decision. In fact, Max/MSP and Pd are not identical programs. The developers at Cycling 74 have created an environment related to and similar to Pd in many ways, but it's not a for-sale version of Pd, and Pd is not a free version of Max/MSP.

The Flavors Menu

Pd comes in a variety of flavors, all based on the “vanilla” Pd release maintained by Miller Puckette. The other flavors differ primarily in their packaged extensions and their GUI enhancements, but some deeper changes may be made as well, typically to accommodate performance requirements. Notable extensions to Pd include GEM (OpenGL graphics), iemlib (library of GUI, math, filters and other DSP code), zexy (a package of “objects that provide functionality missing in plain Pd”) and the PDP/PiDiP/GridFlow packages (more tools for manipulating images and video). Incidentally, the original vanilla GUI is built on Tk, a widget set commonly associated with the Tcl scripting language. The unmodified interface is certainly usable, but both the Pd-extended and Pd-L2Ork Projects have contributed improvements to its appearance and usability.

The package repositories for many mainstream distributions include packages for Pd in either the vanilla or Pd-extended flavors. The Pd-L2Ork Project maintains packages for various Linux distributions, and of course, all versions of Pd are available in source code packages. If you want to try Pd in an optimized risk-free environment, check out the Puredyne distribution. Puredyne is a live Linux system designed for multimedia artists and musicians who want a fast, light system that's also loaded with some of the best audio/video programs available in the free software universe.

For my re-introduction to Pd, I decided to use the packages available from the L2Ork site maintained by Professor Ivica Bukvic at Virginia Tech. This flavor is based on the Pd-extended package, with customizations for the hardware used by the L2Ork performance group. Pd-L2Ork includes almost all the extra packages I needed for this article. The Tech group's flavor works well, but I encountered some significant problems when I tried to run examples from those extra libraries (see below).

Getting Into It

Regardless of which Pd package you choose, your first step into its world should be taken in the Media menu. First, configure your audio and MIDI devices—JACK audio and ALSA MIDI are recommended for Linux users—then select the Test Audio And MIDI item from the menu. This selection runs the testtone.pd patch, a suite of tests to verify your audio/MIDI configuration (Figure 2). When you're satisfied with its results, start opening and running the example files found in /usr/lib/pd/doc/ or /usr/local/lib/pd/doc/.

Figure 2. Pd's Audio/MIDI Test Suite

Learning Tools

Searching on Google and Google Videos provides plenty of tutorials and presentations on Pd (see Resources for some of my favorites); however, Pd's on-line documentation is one of the system's great strengths. Cool and useful example files abound in /usr/lib/pd/doc/ (or /usr/local/lib/pd/doc/), complete and ready to run. They include a wonderful variety of synthesis techniques, effects and dynamics processors, GUI methods and so forth. I find the synthesis examples of special interest. Many techniques are presented that are not so easily accessed in other systems—for example, SSB modulation and four different FM synths. Users are encouraged to use the example instruments as the basis for their own instrument designs and compositions, a matter accomplished with simple cut-and-paste operations. Editing patches is equally simple, with all edits done directly on the patch canvas. Pd patches can be represented as plain-text files, but they rarely are edited directly and more often are used for exchanging patches between users. The GUI is where the editing action takes place in Pd.

By the way, when you don't want to break your work flow to look up a module's definition, simply right-click over any box to summon a pop-up menu that includes a selection for the object's Help window. The Help file describes the object's functions and provides a summary of its parameters. New users should note that the Help file itself is an active patch, so be careful about changing its default values.

Given Pd's longevity, it's no surprise to find a rich set of third-party resources for its study and expansion. If the program's own documentation isn't enough, you can find a great FLOSS Pd manual on the Net, and other Pd-oriented books abound (see Resources). I recommend especially Designing Sound, by Andy Farnell. Apart from its great significance to users of Pd, Designing Sound is a most engaging and deeply fascinating book. Ostensibly targeted toward game sound designers, this book is a treasure for anyone who works with digital audio. It covers a vast range of subject material, all relevant to his topic at large, much of which is potentially difficult to impart to a non-specialist reader. However, Mr Farnell is a master of exposition and explanation, and I'm absorbed by whatever I read in his book. Designing Sound has a particular appeal for Pd people—every example in the book is presented in Pd, and although the author states it is not a Pd tutorial, beginners may find his presentation especially enjoyable.

Making Connections

Pd loves external connections. Indeed, it's all just pure data to Pd—if you can get the data into Pd, the program will make every attempt to process it. That's good news for me, because I want to use it for processing input from a variety of external devices.

For external MIDI control over my patches, I have a Behringer BCF2000 control surface and an Akai LPK25 2-octave keyboard, both of which were instantly recognized by my Arch system and by QJackCtl. I used QJackCtl's ALSA connections panel to hook the hardware into Pd where notein and ctlin objects receive data from my MIDI hardware (Figure 3). Thus, when I move a slider on the BCF, the slider in my Pd patch moves in smooth sync with the hardware controller. I use the LPK to make sudden changes in visual displays, and sometimes I use it simply to play notes into a Pd synthesizer patch.

Figure 3. Hardware Controller Inputs in a Pd Patch

I tested Pd's OSC support by connecting it to the IanniX OSC sequencer. Thanks to user/developer codex99, I tested a pre-release of IanniX that includes a neat example for working with Pd. The screenshot in Figure 4 shows the connection at work. Pd controls the speed of the sequencer while IanniX controls the animation in the gemwin display window. It's all very cool, and it opens the way to some fascinating possible uses. Perhaps you'd like an OSC-enabled arrangement of Pd + IanniX + Ardour3? No problem, and you might as well throw in connections with Processing and Renoise too, perhaps with a machine per program and everything connected by netsend/netreceive objects.

Figure 4. Pd Plays with IanniX

I also have a Webcam and a miniDV camera that I wanted to hook into Pd. As I've noted already, Pd itself has no video processing capabilities, but many of its externals are dedicated to visual data acquisition and massage. The good news is that the physical connections—USB and FireWire ports and drivers (V4L2 and IEEE1394)—are well supported by those externals. The bad news is that I had to jump through more than a few hoops to make it all work.

Video Problems and Solutions

The packaged version of GEM worked well for everything except patches involving my cameras. Video file playback worked well enough, but I had troubles with live video input. Neither my Webcam nor my miniDV camera were recognized, although both worked fine in the Cheese and Kino programs. A bit of research led me to conclude that my installed version of GEM was borked, so I decided to take the opportunity to upgrade. I built and installed GEM 0.93.3 (with support for its Pd external, of course), and my Webcam came to life in my experiments with the pix_video module. Alas, my miniDV camera remained moribund. Once again, a little research led to the discovery that my Arch system's 3.0 kernel introduced some changes in its support for FireWire devices. So, I ran this command:

chmod 666 /dev/fw1

Then, I specified /dev/fw1 as my FireWire device for pix_video. When I selected /dev/fw1 in my patch, the Pd console window complained with this error message:

error: Cannot open '/dev/fw1': 25, Inappropriate ioctl for device

However, the device worked perfectly in the patch, and now I have video I/O for both devices.

PDP, PiDiP and GridFlow similarly were crippled by problems with the relevant kernel modules. I rebuilt and re-installed all three externals, but I also needed to change my patches to accommodate pd-v4l2 instead of pd-v4l. At last, my test patch opened my Webcam with this series of informative messages:

pdp_v4l2: opening /dev/video0
pdp_v4l2: driver info: uvcvideo 1.1.0 / UVC Camera (046d:09a1) 
pdp_v4l2 : input 0 : Camera 1
pdp_v4l2: device has 1 inputs
pdp_v4l2: switched to input 0
pdp_v4l2: device supports 0 standards
pdp_v4l2 : format 0 : MJPEG
pdp_v4l2 : format 1 : YUV 4:2:2 (YUYV)
pdp_v4l2: device supports 2 formats
pdp_v4l2 : current format is : MJPG
pdp_v4l2 : setting format : index : 0 : pixel format : MJPG
pdp_v4l2 : capture format : width : 320 : height :240 : 
 ↪bytesperline : 0 : image size : 102400
control 9963776 active (i:0)
control 9963777 active (i:1)
control 9963778 active (i:2)
control 9963788 active (i:12)
control 9963795 active (i:19)
control 9963800 active (i:24)
control 9963802 active (i:26)
control 9963803 active (i:27)
control 9963804 active (i:28)
pdp_v4l2: got 8 buffers type 1 memory 1
pdp_v4l2 : mapped 8 buffers
pdp_v4l2 : queued 8 buffers
pdp_v4l2 : device initialized
pdp_v4l2 : created thread : 2412164864
pdp_v4l2 : capture started

Everything looked good up to this point, but then the console printed this line:

pdp_v4l2: unsupported color model: 1196444237

My patch's rendering window opened, the Webcam's LED was on, but I had no picture until I figured out that the “unsupported color model” resulted from the MJPG format setting. I changed the format value to 1 (for YUYV support), and voilà, my smiling face appeared in the patch's rendering display. Finally, I have support for my Webcam in my Pd video patches. Figure 5 shows the basic camera configuration for my PDP/PiDiP video patches.

Figure 5. The #dp-camera Abstraction

Incidentally, I use this patch now as an abstraction in my own versions of the tutorial patches.

Alas, the situation with my miniDV camera is not so good. PDP/PiDiP includes the pdp_ieee1394 object, but it doesn't like /dev/fw1, and my Arch system provides no other appropriate device node (such as /dev/dv1394). I ran Pd as superuser, but still got no joy with the camera. I'll continue to search for a solution, and in the meanwhile, I can use GEM when I want DV support.

It Takes Two

In one of my experiments, I created a patch that joined a video processor with an audio synthesizer, both of which elements were controlled by a single slider. The patch worked, but the video playback seriously interfered with the audio continuity. Fortunately, I found a solution: I separated the patch into two patches, then I ran those patches in two instances of Pd, launching one instance with the -noaudio option for the video processor and starting the other with the -rt flag for the audio synthesis. Both patches include a ctlin object that receives data from a slider on an external MIDI control surface (see above). With this arrangement, the graphics are updated smoothly, and the audio playback glitches are gone. This solution is not as elegant as the single-patch design, but it's definitely the better performer on my aged single-core CPU. I learned later that a two-machine solution is available with the netsend/netreceive objects. I haven't tried it yet, but it's on my short list of neat things to do with Pd.

The Pd Everywhere Project

Pd can be decoupled from its default GUI, a feature that has drawn the attention of developers Peter Brinkmann and Peter Kirn. Thanks to their libpd Project, Pd-based software can be run on mobile devices and systems, such as the Android and the iOS. The library can be embedded directly into devices, promising a new generation of Pd-based audio software for the little and not-necessarily-so-little things. You can keep up with libpd's development at the Pd Everywhere site and on Peter Brinkmann's blog (see Resources). It's cool—check it out.

As this article went to press, I received a copy of Making Musical Apps: Real-Time Audio Synthesis on Android and iOS, a new book written by Peter Brinkmann. It's a must-have item if you're looking for a way to use Linux to program audio applications for the new mobile devices. The book has also persuaded me that I really need to get an Android.

More Power Pd

Pd has its power users, and some of those users have Web sites dedicated to their Pd-related productions and investigations. Frank Barknecht is a true Pd wizard (and keen cyclist); you'll want to look at his footils.org site and check out his work on the RRADical and RjDj Projects. Chris McCormick's WebPd Project is very cool, as is his Squeakyshoecore music (made with Pd, of course), and longtime user/developer Guenter Geiger recently has expanded his Pd-related work into the PDa (Puredata anywhere) Project, an effort to bring Pd's power to Linux-friendly PDA devices.

Dr Albert Graef has lent his considerable talents to Pd in the form of his Pd-Faust software. The project includes a new system for running Faust plugins in Pd, with dynamic reloading and on-the-fly GUI generation. It's available from the Pure Web site (see code.google.com/p/pure-lang/wiki/Addons#pd-faust) for further details. Dr Graef notes that getting it all up and running may be a bit tedious—it has dependencies not usually found in the average package repos—but the latest release with all needed dependencies is available in the PlanetCCRMA repository at ccrma.stanford.edu/planetccrma/mirror/fedora/linux/planetccrma/14/x86_64/repoview/pd-faust.html.

These days, it seems everyone wants to get in touch with Pd. I've already noted that the Renoise tracker/DAW and the IanniX OSC sequencer include examples for connecting those worthies to the power of Pd, and even the mighty Csound provides a Csound-to-Pd bridge. These definitely are good days, and good company, for Pd.

By the way, if you're looking for a quick introduction to some of Pd's sonic capabilities, check out some of the offerings on Soundcloud and the contributions at Puredata.info. Soundcloud's Pure Data community has uploaded more than 60 recordings, and you're bound to find something of interest there.

The Wrap

As a veteran Csounder, I must say I am impressed with Pd's synthesis capabilities. However, I also must confess that I'm most attracted to Pd for its extended services, particularly in the graphics and video realms. I continue to look into the possibilities of the PDP/PiDiP and GridFlow packages, and I have so much more to learn about GEM's capabilities. I'm also interested in using it for poetry and prose text manipulation—Pd is that flexible, as evidenced by its many uses in real-world deployment.

Dave Phillips is a musician/author/teacher living and working in Findlay, Ohio. He has worked with computers for musical purposes since 1985. He discovered Linux in 1995 and created the linux-sound.org Web site shortly after. He has written on audio topics for Linux Journal and other publications since 1998 and wrote The Book Of Linux Music & Sound (NoStarch Press) in 2000. His extracurricular activities include practicing t'ai-chi, reading Latin poetry, walking a shar-pei named Maximus, and spending as much time as possible with a woman named Ivy.

LJ Archive