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 .
You can have one or more documents open. Each 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 class 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.
The Pd main window shows whether "audio" is turned on or off. When audio is on, Pd is computing audio samples in real time according to whatever patches you have open (visible or not.) Pd may also be reading samples in real time from one or more audio input devices and/or writing audio samples to audio output devices. You specify this on the command line you used to start Pd. How this works depends on what hardware and operating system you're using; see section 3, making Pd work .
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.
There are four classes of "text items" in Pd: objects, messages, numbers, and comments. The "starter" series (from the Help menu) describes what they are and do. You can make new ones using the "Put" menu and drag them where you want them.
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.
To change a text item, you can select it and retype the text. 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.
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.
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.
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.
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.