Once you have started Pd, the main Pd window appears on the monitor. Open a new programming window by clicking the File menu and then New.

A new window opens. Add an object box under Put Object, or with the keypad, using the listed key command: Ctrl-1 (this is for Windows; other platforms may have different key commands).

... you should see a blue box attached to the mouse cursor ...

Then click somewhere on the blank white surface in the new window to decouple the mouse from the object box. 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:

(The sign "~" means "tilde"; you'll need to use this often in Pd.)

You 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 (which resembles an open socket for a cable).

Now click on the rectangle and move the mouse while keeping the mouse button pressed. This draws a line that can be thought of as a cable.

But because you haven't created an object to which you can attach this cable yet, the cable vanishes when you release the mouse button. Make another object just as you did the previous one and call it "dac~". Position it below the "osc~" object by clicking it once so that it turns blue and moving the mouse with the mouse button held. Then start a cable from the outlet on "osc~" and connect it to the left inlet on "dac~". The cursor changes into a circle when it is over the inlet.

Release the mouse button. The "cable" now connects "osc~ 440" to "dac~". You should hear a tone. If not, verify in the Pd main window that there is a check next to "compute audio" (in Linux: check if the field is red). If not, check the box with a mouse click:

(The "compute audio" function allows you to program in Pd without generating sound. This can save the computer much unnecessary processing power — though this is probably a non-issue with most computers these days.)

We hear a tone. To be specific, it is A4 (a' in the German system), also called the A440, the standard concert tuning pitch that has a frequency of 440 Hertz (the meanings of "Frequency" and "Hertz" will be explained later). 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. Now create a number box (Put Number or with key command Ctrl-3) and attach its outlet to the inlet on the object named "osc~". Then you need to change into what is called "Execute mode" (Edit Edit mode, or with key command Ctrl-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. The value should be at least 100; this range can be more finely adjusted by holding SHIFT while clicking and moving the mouse as described above.

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.

Now change back to the other mode, the "Edit mode" (Edit Edit mode, or key command Ctrl-E). Move the cursor, which should have changed back to a hand, over the connection between "osc~" and "dac~". The cursor becomes an X. Click on it, which will turn the cable blue.

Then go to Edit Cut or simply press BACKSPACE. This terminates the connection. Cut the other connection to "dac~" as well. Now create a new object where the cables used to be: "*~ 0" and connect it to the other objects as shown:

Let's make some more room: Enlarge the window by clicking on its lower right corner, holding the mouse button, and pulling it down and to the right.

Then 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. (You can also delete boxes this way. After selecting a portion of the patch, go to Edit Cut or simply press BACKSPACE.)

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.

Then create two "Message" boxes (Put Message or Ctrl-2) as below and enter "0" in one and "1" in the other.

Change back to execute mode (Edit Edit mode or Ctrl-E) and click on the two message boxes in turn: clicking 1 turns the sound on, clicking 0 turns it off.

The previous example covers most of the elements in Pd. Let's take a closer look at them – we used three different kinds of boxes: Object, Message, and Number.

Object boxes are rectangular, message boxes have an indentation on the right side, and number boxes have a flat upper right corner.

All of these 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). There is an edit mode and an execute mode. 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:

Let's take a closer look: There are two kinds of "cables", thick and thin. A thin cable connects the number box to the "osc~" object and a thick cable runs out of the "osc~" object. Thick cables transmit signals, while thin cables transmit only control data. With "compute audio" in the Pd main window, we determine whether the signals should be sent by marking or removing the checkmark. Moreover, 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! These two levels are called the "control level" (where only control data flows, also called the "message domain") and the "signal level" (where signals flow, also called the "signal domain").

The first object you created was "osc~ 440", which is an "oscillator", and you heard a sine tone at 440 Hertz (the meaning of "Hertz" will be explained later). Then you made a number box and entered new values there, which caused the frequency of the tone you heard to change. That is the basic structure in Pd: 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 (in this case, the initial 'argument' was "440"). With most objects, the arguments can be replaced with new values that are connected to the inputs (unlike with the "osc~" object here, the changed value usually goes into the far right inlet).

If new values are entered this way, the argument written in the object box is ignored (in this example, 300 instead of 440).

We 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 (for more on atoms, see 2.1.5).

Another important term: 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.

A few additional things that can make your work in Pd easier:

2.1.4.1 List of all objects

If you click on the white surface ("Canvas") with the right mouse button and open the Help menu, a list with all Pd objects appears.

---

2.1.4.2 Help file

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.

---

2.1.4.5 Comments

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 Ctrl-5). Here you can write whatever you like to explain your patch.

If you've understood everything thus far, then you understand the essential fundamentals of Pd's user interface. Now we can get into the structure of programming itself.

---

A message for an object has two parts: a method designation (selector) and zero, one, or several values (arguments). For example, if the message is "5", then the actual message is "float 5" and is comprised of the atoms "float" and "5". The message "bang" is comprised only of the selector "bang" and contains no arguments. The message "1 2 3 4 5" is actually the message "list 1 2 3 4 5".

There are three kinds of atoms: a number (programming language = "float") with a 32-bit value, a symbol, which is a string of letters, or a pointer, which is a kind of address (this will be covered in Chapter 5.2.3).

The message "float 5" is composed of the two type designations symbol and float. The type symbol has a value of "float" (a string) and the type float has a value of "5".

The selector is always a symbol. Since objects can react differently to different messages, the selector first makes a more precise preliminary determination.