Pd is free software. Versions exist for Win32, IRIX, GNU/Linux, BSD, and MacOS.
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.
But what is a graphical programming environment?
Programmers usually write lines of code and then have the computer execute that code. However, in a graphical-programming environment, the programmer describes how the program works by manipulating objects on the screen. You can change the way the objects behave by sending them messages and by connecting them together in different ways by drawing lines between them.
What is cool about Pure Data, or Pd is that it works in real-time. The programmer can change the program, even when it is running, and you can see and hear the results immediately.
The program that you write is called a patch. A patch first appears as a blank white background on which you write a program. This white background is also called a canvas.
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:
CTRL-E allows you to toggle between Execute and Edit mode.
This is the main window:
This is where messags are sent and what you will use to debug your programs. This is also where you can test whether Pd is functioning properly:
In the main menu, click on Media Test Audio and MIDI:
In testtone, click first on the box next to
80, then on the box next to 60:
You should hear a sine tone coming out of the computer's
loudspeaker.
In the beginning...
Before you can use Pd to control music and video, you should understand the way that computers and Pd handle data.
Open Pd
In the main window make sure that Compute Audio is selected
Select New from the File menu (⌘+N)
To add an object press ⌘+1 or navigate to the Put menu and select Object You should see a blue box attached to the mouse cursor
To decouple the mouse from the object box, click somewhere on the blank white surface
Type this into the box:
osc~ 440
To accept what you have typed into the box, click anywhere outside the box on the white surface:
You should now see a rectangular box with little black rectangles in the top and bottom corners. The upper rectangles are called inlets, the bottom rectangle is an outlet:
If you place the cursor onto the outlet rectangle, it changes to a circle:
Clicking on the rectangle and moving the mouse while keeping the mouse button pressed draws a line that can be thought of as a cable:
Unless you connect the cable to another object, it will disappear.
Make another object and call it dac~. dac stands for digital to audio converter
Position dac~ below osc~ 440 osc stands for oscillator.
Connect a cable from the outlet of osc~ to the left inlet of dac~ (Don't worry, you'll know if you did this correctly)
You can deselect Compute Audio in the main window to stop the tone.
The tone is A4 (a' in the German system), also called the A440, the standard concert tuning pitch that has a frequency of 440 Hertz.
Now connect the outlet from osc~ 440 with the right inlet of dac~ as well.
You should hear sound from both of the computer's speakers
Create a Number box ⌘+3.
Attach the Number box's outlet to the inlet of osc~
You need to change into what is called Execute mode (Edit> Edit mode, or ⌘-E;. The cursor turns into an arrow.
Click on the number box, hold the mouse button, and move the mouse up and down. This changes the numbers and the pitch/frquency. The value should be at least 100; this range can be more finely adjusted by holding SHIFT while clicking and moving the mouse.
Another way to enter values into the number box is to click on the number box, enter a value on the keyboard, and press ENTER.
Return from execute mode by pressing ⌘+E again.
Move the cursor, which should have changed back to a hand, over the connection betweenosc~ anddac~. The cursor becomes an X. Click on it, which will turn the cable blue.
Press BACKSPACE to terminate the connection
Do the same with the cable connected to the right inlet
Create a new object in between osc~ and dac~ and call it *~ 0
Make the following connections:
Enlarge the window by clicking on its lower right corner, holding the mouse button, and pulling it down and to the right.
Click on the lower right part of the white background near the dac~ object, hold the mouse button, and draw a rectangle that includes the dac~ and the *~ objects.
This is how you select a part of a patch.
When you release the mouse button, both objects appear in blue. Click on one of these selected objects, hold the mouse button, and pull them down to free up more space.
To deselect these objects, just click anywhere on the white background.
Create two Message boxes (Put>Message or ⌘-2).Enter 0 in one and 1 in the other.
Connect the outlets of the message boxes to the right inlet of the *~ 0 object
Make sure Compute Audio is selected in the Main window. Change back to execute mode. Click on the two message boxes and see what happens. If you don't hear anything make the number in the Number box larger.
More about the Interface
Pressing ⌘+B opens the help browser:
//Surface Elements
Object, Message and Number
boxes have inlets and outlets. The inlets are always on top, the outlets on bottom. You can always connect an outlet to an inlet (in this order).
Edit mode is for programming and Execute mode
is for running the program. You can tell which mode you're in by looking at the cursor.
The cursor looks like a hand in Edit mode and an arrow in Execute mode.
There are two kinds of cables, thick and thin. Thick cables transmit signals, while thin cables transmit only control data. All objects that produce signals or that work with signals as an input (input = that which goes into an inlet; output = that which comes out of an outlet), have a tilde (~) after their name; other objects don't have this!
There are two levels —control and signal. The control level is where control data flows, and is also called the message domain.
The signal level is where signals flow, and is also called the signal domain.
To duplicate parts of a patch, select an area so that the selected boxes appear in blue and go to Edit>Duplicate or ⌘-D. This duplicates the selected area and the copy appears as a selected area that you can move (click on a selected box, hold, move to desired location with the mouse, release).
Programming can get complicated fast. To help remind you of the meaning of a certain patch, it is recommended that you add comments to your patch. Comments can be added under Put Comment (or with ⌘-5). Here you can write whatever you like to explain your patch.
Objects
Object boxes are rectangular.
An object has a name (if it produces signals, a tilde follows the name), then there is a space, and then one or several arguments follow
If new values are entered for the input, that value replaces the argument: .
In this case 293 instead of 440.
If you click on the Canvas with the right mouse button and open the Help menu a list with all Pd objects appears:
If you right-click on an object, a pull-down menu opens where you can select the help file for that object for a detailed explanation:
A bang is like a mouse click.
You can click it and have it pass on this click—
it can receive a click as input and then in turn sent
a click as output. However, this input doesn't have to be a click.
The bang object converts any control
input that it receives into a bang. For example, you could use a number:
bang stands for the letter combination b-a-n-g. Letter combinations as symbols are the second form of data (besides numbers) that Pd uses. Some objects recognize certain words and work with their input. Many objects react to the symbol bang. Since it occurs so frequently, there is a special graphic representation for bang, a circle that flashes when active (Put>Bang or SHIFT+⌘+B). This is called a GUI object. It is a graphical user interface, a graphic representation of something and/or a graphic that can be changed to produce and send new values.
Numbers
Number boxes have a flat upper right corner.
When in Execute mode hold the mouse down and move it up or down to select a number. Holding SHIFT while you drag will scroll through decimal numbers. Hold ALT to go back to 0. You can click once in the box, type your number then press ENTER to send the value to the outlet.
Messages
A Message box is used to store and send information to other objects, and can contain numbers or text. It
also has a distinct shape, with two flags on the right side.
You can enter information in number boxes or message boxes. Message boxes also allow letters, which are called symbols. All of this information is referred to as atoms. An atom appears in a message box or in a number box.
Messages with variables
Variables can be integrated in a message box's contents. Variables are called $1, $2, etc. If you enter a number as input for the message number $1, the output from the message box will be the complete expression with this number.
Ordinarily it is not possible to include a variable without a space to separate it. The makefilename object, however, makes this possible. Variables that can be included in arguments are%d for digits and %s for symbols:
A message box with several elements is a list. A message box with several elements separated by commas
becomes several messages, which are sent one immediately after the other. The comma breaks the message, creating a new instance.
You can also send messages to receive objects (or to the Pd engine) by including a receive symbol, the message,
followed by a semicolon. This technique is usually used to initate several parameters simultaneously:
You can create complex messages by joining several elements together using pack . You can create lists by joining several numbers, or numbers and
symbols:
Symbols
A symbol is another way of storing and sending information. Once created, you can use it to display the
output of some objects, or you can type directly into it and hit Enter to send the text out. No
spaces will appear in the symbol box when you type into it, since separate words would be considered
separate symbols.
Summary
When working with Pd, there are two modes: Edit mode and Execute mode (you switch between them with ⌘-E or Edit>Edit mode). You program all the parts of a patch in edit mode and start all operations and sounds in execute mode.
Within a patch, there is the control level and the signal level (control objects do not have a tilde after their names and are connected with thin cables; signal objects have a tilde at the end and are connected with thick cables). The signal level is only active if compute audio has been activated in the Pd main window.
The elements of a patch are objects, messages, and numbers.
An object often has one or several arguments, which can be changed using an input.
A message is a fixed value in execute mode and is stored with the patch. When a message box is clicked, its contents are sent to all objects connected to its outlet. In contrast, number boxes can be altered in execute mode and their values are not saved.
//Control Level
Mathematical operations and order
Computers can only work with numbers. Pd works with both numbers and symbols, or letters.
So how does Pd process numbers in the control level?
In this level you can enter numbers in both number boxes or message boxes. Some objects allow mathematical operations to be performed using these numbers:
In this example the + object adds the numbers in the connected number boxes.
The right inlet is a cold inlet. If you connected one number box to the right inlet and one to the left, the output will not change until the left box is modified.
Cold inlets do not cause an immediate change.Hot inlets trigger an immediate visible change when data is entered into them:
Here is how you would multiply by a certain number:
This lets you multiply by a variable, but the output wil not update until you change the left inlet:
If you want to perform two different calculations at the same time,
you have to transform one mouse click into several using a bang
(Put>Bang or Shift+⌘+B).
Click the bang in Execute Mode:
trigger can receive a bang, a number, a symbol, a pointer or a list as input, . Once started in this way, trigger gives this input or transforms it into a bang as output from right to left. The output from a trigger object is determined by its arguments (bang, float, symbol, pointer, list). In this case, the arguments are two bangs and two outlets are created (an outlet is created for every argument you enter).
The trigger object is usually abbreviated as t and instead of typing out the arguments bang and float, you can use just b and f:
To save space, you can omit the number boxes from the first operations for the results you want to add, simply using the outputs from above directly as inputs below. If you ever want to know what value is being sent, just attach a print object to the output.
You can pass print an argument that labels the output:
Complex mathematical expressions can be programmed using the expr object. The argument in this case is the expression itself:
You can also use variables; they are called $f1, $f2, $f3 etc. (counting begins with 1). This creates inlets from left to right in which values for the variables are entered (as always, the output is generated only once the leftmost inlet receives a value. So you have to ensure that all other values have been entered before the leftmost one).
Moses
moses: The input is a number; moses decides, by evaluating whether this input is smaller than / larger than/equal to the argument, which outlet will receive it. If you give moses an argument of 10 and give it an input that is smaller than 10, this input comes out of the left outlet. If the input is 10 or greater, it is sent to the right outlet.
select (usually abbreviated to sel): Input is a number, output is a bang only when the input is the same as the argument. Any other numbers received as input come out the bottom right outlet.
Division, Modulus and Rounding
The result of a division operation (the quotient) can be expressed
in decimal form (17 / 7 = 2.428) using div
or in the form of a remainder 17 / 7 = 2
remainder 3 by using mod
[mod] and [div] are helpful objects to determine whether
or not a fraction produces a remainder, or to determine
the value of the remainder.
[div] takes a number in its left inlet and will divide that number by either the creation argument or the number given at its left inlet and will produce the result without a remainder. If no creation argument is given, then the default value is 1.
This patch rounds float values to the next integer:
Float and counter
The float object is used to store numbers. When you enter a number into the right input, it is saved in the object for later use. If you send a bang to the left inlet, the number stored in the object is sent as output:
Often in Pd, you'll want to use a counter that counts in whole numbers starting from a given input value. Here's an example:
These counters counts only from 0 to 6; after the 6, it starts again at 0:
Relational Tests
==
If the left input is the same as the argument or the right input, the output is 1, otherwise 0
>=
If the left input is greater than or equal to the argument or the right input, the output is 1, otherwise 0.
>
If the left input is greater than the argument or the right input, the output is 1, otherwise 0.
!=
If the left input is not equal to the argument or the right input, the output is 1, otherwise 0.
<
If the left input is less than the argument or the right input, the output is 1, otherwise 0.
<=
If the left input is less than or equal to the argument or the right input, the output is 1, otherwise 0.
random
Random creates a random number within a given range. The lower limit has a default value of 0, the upper limit is entered as an argument (whole numbers only). The upper limit is exclusive; i.e., if you enter random 4, every time the object receives a bang as input it will randomly select an output of 0, 1, 2, or 3.
//Applications
Two frequencies – two volume levels
If you want to switch between two frequencies - a low quiet tone and a high
loud one - you could use the following patch. Switch between tones by clicking
on their respective bangs:
intervals
To produce a dyad (a set of two notes or pitches), you'll need two osc~
objects. In the following patch, moving the values in the number box up and down
will produce a vertical interval (here, a perfect fifth) at various pitches:
Random melody
Every bang you send will generate a pitch between 200 and 1000 Hertz – a random melody.
How long is this score
A value that composers need to calculate again and again: you've written a piece with 324 quarter notes at a tempo of quarter = 72. How long is the piece in seconds?
Sliders
The slider (Put>HSlider or Put>VSlider) is a graphic representation of a number box. It is, however, restricted to a range (with a default setting of 0 to 127):
Radios
The radio (Put>Hradio orPut> Vradio) is also a graphic representation of a number box, but extremely limited: only a few numbers (by default from 0 to 7) can be sent out, which is accomplished by simply clicking on a box.
//Exercise 1
Create two random melodies that run simultaneously.
By default, objects and connections are (currently) carried out in the sequence (in time) in which they are created:
This cannot be seen and should be avoided
.
