Pd Documentation chapter 2: theory of operation

back to table of contents

The purpose of this chapter is to describe Pd's design and how it is supposed to work. Practical details about how to obtain, install, and run Pd are described in the next chapter. To learn digital audio processing basics such as how to generate time-varying sounds that don't click or fold over, a good reference is Dodge and Jerse, Computer Music .

2.1 overview

Pd is a real-time graphical programming environment for audio and graphical processing. It resembles the Max/MSP system but is much simpler and more portable; also Pd has two features not (yet) showing up in Max/MSP: first, via Mark Dank's GEM package, Pd can be used for simultaneous computer animation and computer audio. Second, an experimental facility is provided for defining and accessing data structures.

2.1.1. the main window, canvases, and printout

When Pd is running, you'll see a main "Pd" window, and possibly one or more "canvases" or "patches". The main Pd window looks like this:

There are peak level and clip indicators for audio input and output; these report peak levels over all input and all output channels. Note that DC shows up as an input level; many cards have DC levels which show up in the 50s. To see an RMS audio level, select "test audio and MIDI" from the help window. The main window display is intended only to help you avoid clipping on input and output. You can turn the peak meters on and off using the control at bottom left.

At bottom right is a control to turn audio processing on and off globally. Turning audio off does not relinquish the audio devices, it just stops the computation. The "audio" menu is also provided, with accelerators "Control-." to turn audio computation off and "Control-/" to turn it on. When audio is on, Pd is computing audio samples in real time according to whatever patches you have open (visible or not.)

The DIO (Digital I/O) error indicator flashes if there is a synchronization error for audio input or output. Click there to see a list of recent errors. This indicator is normally red at startup, and will turn red whenever the computation runs late (so that the DAC FIFOs fill and/or the ADC FIFOs empty) or if audio input and output are not running at the same rate. See audio and MIDI support .

Pd documents are called "patches" or "canvases." Each open document has one main window and any number of subwindows. The subwindows can be opened and closed but are always running whether you can see them or not. Here is a simple Pd patch:

There are four text items in this patch: a number box (showing zero), an object box showing "print," and two comments. The number box and the object box are connected, the number box's output to the print box's input. Boxes may have zero or more inputs and/or outputs, with the inputs on top and the outputs on bottom.

Pd's printout appears on its standard output. Normally, you'll run Pd in a "shell" or "terminal" window which you'll keep open to see any printout or error messages.

2.1.2. object boxes

Pd patches can have four types of boxes: object, message, number, and comment .

You make objects by typing text into object boxes. The text is divided into atoms separated by white space. The first atom specifies what type of object Pd will make, and the other atoms, called creation arguments , tell Pd how to initialize the object. If you type for example,

the "+" specifies the class of the object. In this case the object will be the kind that carries out addition, and the "13" initializes the amount to add. Atoms are either numbers or symbols like "+". The text you type into an object box determines how many and what kinds of inlets and outlets the object will have. Some classes (like "+" always have a fixed arrangement of inlets and outlets, and in the case of other classes, the inlets and outlets will depend on the creation arguments.

Here for example is a simple MIDI synthesizer:

This patch mixes control objects (notein, stripnote, and ftom) with tilde objects osc~, *~, and dac~. The control objects carry out their function sporadically, as a result of one or more type of event . In this case, incoming MIDI note messages set off the control computation. The result of the computation is, when the note happens to be a "note on" (and not a "note off", to compute the frequency in cycles per second and pass it on to the oscillator ("osc~").

The second half of the patch, the osc~, *~, and dac~ objects, compute audio samples, in the same way as an analog synthesizer works. The osc~ object is acting as the interface between the two regimes, in that it takes control messages to set its frequency but talks to "*~" using an audio signal. Audio signals aren't sporadic; they are continuous streams of numbers. As a result tilde objects act under very different rules from control objects. The audio portion of the patch is always running, whether MIDI messages arrive or not; the function of control computations is to insert calculations between the audio computation which may change audio computation parameters such as the frequency of an oscillator.

2.1.3. number and message boxes

The border of a box tells you how its text is interpreted and how the box functions. Object boxes use the text to create objects when you load a patch. Message boxes interpret the text as a message to send whenever the box is activated (by an incoming message or with the mouse.) In the example below the message box, when clicked, sends the message "21" to an object box which adds 13 to it.

Whereas the text in an object or message box is static when a patch is running, a number box's text changes to reflect the current value held by the box. You can also use a number box as a control by clicking and dragging up and down, or by typing values in it. (There are also shift- and alt-click actions; see getting help to find out how to look this up).

2.1.4. patches and files

When you save a patch to a file, Pd doesn't save the entire state of all the objects in the patch, but only what you see: the objects' creation arguments and their interconnections. Certain data-storage objects have functions for reading and writing other files to save and restore their internal state. Pd finds files using a path which can be specified as part of Pd's startup arguments. The path specifies one or more directories, separated by colons (semicolons if you're using windows.) Most objects which can read files search for them along the search path, but when Pd writes files they go to the directory where the patch was found.

2.2. editing Pd patches

2.2.1. edit and run mode

A patch can be in edit or run mode; this really only affects how mouse clicks affect the patch. In edit mode, clicking and dragging selects and moves boxes or makes and cuts connections; in run mode clicking on boxes sends them messages which they react to in different ways. In run mode, number and message boxes can be used as controls. Normally, when you are in a performance you will stay in run mode; to change the patch you go to edit mode.

2.2.2. making boxes

You can create the four classes of "text items" (objects, messages, numbers, and comments) using the "put" menu. (There are also "symbol", "array" and "graph" entries which you should ignore for now.) Note the handy accelerators. Boxes are empty at first; drag them where you want them and type in the text.

You will often find it more convenient to select a box and "duplicate" it (in the Edit menu) than to use the "Put" menu. If you select and duplicate several items, any connections between them will be duplicated as well.

2.2.5. changing the text

To change a text item, you can select it and then edit the text. If you only click once, the entire text is selected and your typing will replace everything. Click again and drag to select a portion of the text to retype.

If there's more than a small amount of text (in a comment, for example) you might want to select the text and choose "text editor" from the Edit menu, which opens a text editing window with a copy of the text in it. Hitting "send" in that window is exactly equivalent to retyping the text into Pd; you can send it to more than one box in sequence if you want.

If you click a box and move the mouse without releasing the button this displaces the entire box. If you wish to displace a box which is already sepected, first deselect the box by clicking outside it; otherwise you will be selecting text instead of moving the box. you displace the , you will

2.2.7. getting help

You can right click on a box to get help on it. Right click outside the boxes and you'll get a list of all the classes of object boxes. Right clicking a graph gives you a settings dialog.

2.2.8. miscellaneous

Control-q "quits" Pd, but asks you to comfirm the quit. To quit without having to confirm, use command-shift-Q.

2.4. audio signals

Using Pd you can build audio patches which can synthesize musical sounds, analyze incoming sounds, process incoming sounds to produce transformed audio outputs, or integrate audio processing with other media. This section describes how Pd treats audio signals.

2.4.1. sample rate and format

Pd's auddio signals are internally kept as 32-bit floating point numbers, so you have all the dynamic range you could want. However, on Linux and Windows systems, audio I/O is limited to 16 bits. Inputs all apepar between the values of -1 and 1; and output values will be clipped to that range. Pd does not report when the output is clipped.

Pd assumes a sample rate of 44100 unless you override this in Pd's command line. Pd doesn't check that this matches the sample rate of audio input or output, nor does Pd attempt to set your computer's audio sample rate to its own. If the audio system is running at the wrong sample rate, audio output will be transposed (you can check this using the "test audio and MIDI" patch; see the help menu).

Pd can read or write samples to files either as 16-bit binary or as floating-point in ASCII. This latter option is currently the only way to get high-resolution audio signals in and out of Pd. Guenter Geiger has apparently written an object which streams 16-bit samples from disk; I haven't tried this yet.

2.4.2. tilde objects and audio connections

Audio computations in Pd are carried out by "tilde objects" such as "osc~" whoswe names conventionally end in a tilde character to warn you what they are. Tilde objects can intercommunicate via audio connections. When audio computation is turned on, or when you change the audio network while audio is on, Pd sorts all the tilde objects into a linear order for running; then this linear list is run down in blocks of 64 samples each; at 44100 Hz. this means the audio network runs every 1.45 milliseconds.

Inlets or outlets are configured in Pd either for messages or audio; it's an error to connect an audio outlet to a non-audio inlet or vice versa; usually these errors are detected at "sort time" when audio is started or the network changed with audio running. An object's leftmost inlet may accept both audio and messages; any other inlet is either one or the other. There is no quick way to tell whether an inlet or output is for audio or messages; consult the help window for the object.

The audio network, that is, the tilde objects and their interconnections, must be acyclic. If there are loops, you will see the error message at "sort time." When errors are reported at sort time there is no easy way to find the source of the error. You can build algorithms with feedback using nonlocal signal connections.

Your subpatches can have audio inlets and outlets via the inlet~ and outlet~ objects.

2.4.3. converting audio to and from messages

If you want to use a control value as a signal, you can use the sig~ object to convert it. The +~, -~, *~, /~, osc~, and phasor~ objects can be configured to take control or signal inputs.

The other direction, signal to control, requires that you specify at what moments you want the signal sampled. This is handled by the snapshot~ object, but you can also sample a signal with tabwrite~ and then get access it via tabread or tabread4 (note the missing tildes!). There are also analysis objects, the simplest of which is "env~", the envelope follower.

2.4.4. switching and blocking

You can use the switch~ or block~ objects to turn portions of your audio computation on and off and to control the block size of computation. There may be only one switch~ or block~ object in any window; it acts on the entire window and all of its subwindows, which may still have their own nested switch~/block~ objects. Switch~ and block~ take a block size and an overlap factor as arguments; so for instance, "block~ 1024 4" specifies 1024 sample blocks, overlapped by a factor of 4 relative to the parent window. Switch~ carries a small computational overhead in addition to whatever overhead is associated with changing the block size.

Larger block sizes than 64 should result in small increases in run-time efficiency. Also, the fft~ and related objects operate on blocks so that setting the block size also sets the number of FFT channels. You may wish to use block sizes smaller than 64 to gain finer resolutions of message/audio interaction, or to reduce "block delay" in feedback algorithms. At the (untested) extreme, setting the block size to one allows you to write your own recursive filters.

You can use switch~ to budget your DSP computations; for instance you might want to be able to switch between two synthesis algorithms. Put each algorithm in its own subpatch (which can have sub-sub patches in turn, for a voice bank for instance), and switch each one off as you switch the other one on. Beware of clicks; if you have a line~ controlling output level, give it time to ramp to zero before you switch it off or it will be stuck at a nonzero value for the next time it comes back on.

When a subpatch is switched off its audio outputs generate zeros; this costs a fairly small overhead; a cheaper way to get outputs is to use throw~ inside the switched module and catch~ outside it.

2.4.5. nonlocal signal connections

You may wish to pass signals nonlocally, either to get from one window to another, or to feed a signal back to your algorithm's input. This can be done using throw~/catch~, send~/receive~, or delwrite~/delread~ pairs. Throw~ and catch~ implement a summing bus; throw~ adds into the bus and catch~ reads out the accumulated signal and zeros the bus for the next time around. There can be many throw~ objects associated with a single catch~, but a throw~ can't talk to more than one catch~. You can reset the destination of a throw~ if you want to.

Send~ just saves a signal which may then be receive~d any number of times; but a receive~ can only pick up one send~ at a time (but you can switch between send~s if you want.)

Don't try to throw~ and catch~ or send~ and receive~ between windows with different block sizes. The only re-blocking mechanisms which are well tested are inlet~ and outlet~.

When you send a signal to a point that is earlier in the sorted list of tilde objects, the signal doesn't get there until the next cycle of DSP computation, one block later; so your signal will be delayed by one block (1.45 msec by default.) Delread~ and delwrite~ have this same restriction, but here the 1.45 msec figure gives the minimum attainable delay. For nonrecursive algorithms, a simple flanger for example, you might wish to ensure that your delread~ is sorted after your delwrite~. The only way to ensure this is to create the delread~ after you created the delwrite~; if things get out of whack, just delete and re-create the delread~.