Multimedia Programming with Pure Data

Every Pure Data program is a text file with an extension (.pd). In Pure Data's term, a program is called a patch. Electronic musicians often use cables to connect different devices to produce sound. The cables are referred as patch cables. Since Pure Data is originally a piece of software to produce electronic music, the name patch refers to a Pure Data program.

To create a new patch, navigate to File | New to make an empty patch. From the menu, choose File | Save to save the patch in the folder you plan to store your Pure Data material. Pure Data does not assume a default location for your patches. You can decide where to put them.

At this point, you will have an empty window with a cursor that appears to be a finger pointing to the left. Before we proceed to the notorious Hello World example, we need to go through the Pure Data interface first.

There are a number of terms we need to clarify before we proceed.

The Hello World example is straightforward. It involves one piece of data—a Hello World message, and one object to print out the message in the console window.

Create a new Pure Data patch. Save it to your folder with name helloWorld.pd. Clear the console window by navigating to Edit | Clear console. To create anything for your Pure Data patch, choose from the Put menu item.

It may take a few seconds for new comers to learn the operations of the Pure Data interaction sequence. First, we select a Message box (Command + 2 or Ctrl + 2). After you select Message, move your cursor back to the empty patch window helloWorld.pd. The message icon will move along with your cursor. You can click anywhere on the empty patch to fix the position of the message icon.

A data entry cursor (a blinking vertical bar) will appear in the left hand side of the message box. Now, you can type in Hello World inside this message box.

Click anywhere outside the message box to confirm the text. Note that the data entry cursor will disappear after you confirm the text. You can click on the message box again if you want to change the text later. You can also click-and-drag the message box to change its position within the patch window.

Now, we create the second item. Navigate to Put | Object (Command + 1 or Ctrl + 1) from the menu bar to create an empty object in the patch window.

Type the word print inside the object box. Note that the empty object box is a regular rectangle with dotted outline. After you type print, click outside the object box. The object box now has a solid outline. A message box is a rectangle with a curved right edge.

If you take a closer look at the message and object boxes, you will notice two tiny rectangles along the left edge of the message box on the top and bottom. For the object box, there is only one such rectangle on the top. They are the inlet and outlet mentioned earlier. Those on the top are inlets and those on the bottom are outlets.

Connecting one outlet to another inlet is the programming in Pure Data. Now, we connect the outlet of the Hello World message box to the inlet of the print object box. First, move your cursor towards the outlet of the Hello World message box. It will turn into a small circle.

Click-and-drag to draw a line from the outlet of the Hello World message box. While dragging, move toward the inlet of the print object box. The cursor will also turn into a small circle.

Release the mouse button to confirm the connection.

This is your first working Pure Data patch, the Hello World program. To execute the patch, we have to switch from Edit Mode to Run Mode by choosing Edit | Edit mode (Command + E or Ctrl + E). Note the mouse cursor changes into the regular pointer shape. Open the console window if it is hidden. You can do it by navigating to Window | Pd window (Command + R or Ctrl + R). Arrange the two windows side by side such that you can see the message in the console window when you work on the patch window. Move your cursor toward the Hello World message box. Note the cursor changes again. It is now an upward pointing arrow.

Click on the message box and note what happens in the console window. A message print: Hello World appears whenever you click on the message box. Yes, it is the Hello World program you have just achieved.

The message box in Run Mode functions like a button. When you click, it sends out the message text Hello World through its outlet along the connection line to the inlet of the print object box. A print object will just show the message it received onto the console window.

Besides the print object, Pure Data includes numerous objects catered to various purposes. You can check out those objects from the Help menu. To access the general help for Pure Data, you can choose Help | Browser from the menu bar.

Within the help browser, you can further select the topics you would like to reference. Double-click on the title; you will call up the help menu for that topic.

The first two items, Manuals and Pure Data are for general Pure Data reference. The rest are for external libraries shipped with the pd-extended software.

As all digital media elements are represented in numbers, the objects to perform numeric operations are essential. This section will introduce the use of common arithmetic computation. They are addition, subtraction, multiplication, and division. The programming symbols are: +, -, *, /.

Create an empty patch as described in the previous section and save it with name calculation.pd in your folder. Put a print object in the patch window. Put another object on the patch window. Type a plus sign + inside this object. Connect the outlet of this 'plus' object to the inlet of the print object.

Note that the plus object has two inlets, one on the left, one on the right. It is intuitive to think that addition involves two numbers. You need to have two numbers supplied through the two inlets for the calculation. Now, we put two message boxes with two numbers onto the patch and connect them to the inlets .of the plus object box.

Now, switch to Run Mode by selecting Edit | Edit mode. Click upon the right message box first and then click on the left message box. Note the message from the console window. The order of clicking matters, which we shall be covering in the coming section.

This example always adds the two numbers 7 and 11 together. Nevertheless, message boxes don't offer much flexibility when it comes to changing the numbers in real time for addition. We will replace the two message boxes with number boxes.

First, we delete the two message boxes. To delete items in Pure Data, we click-and-drag the left mouse button to draw a selection rectangle including the two message boxes and press the Delete key on the computer keyboard to delete them.

If you want to delete a connection without deleting the item, you can click upon the connection link. The cursor will change into a cross shape. Press the Delete key and you can delete the link without touching the two other objects.

Going back to our example, we can also delete the print object and replace it with a number box. The next step is to create three number boxes from Put | Number (Command + 3 or Ctrl + 3). Connect two of them to the plus object box inlets and the last one to its outlet. Note that the initial value for the number box is zero.

Now the addition program is ready. We can switch to Run Mode to test it. First, you click on the number box connecting to the right inlet of the plus object. Type in any number inside the number box; say 11. Note there are three dots after the number. Once you are fine with the number, press Return/Enter to confirm the number. The three dots will disappear. Note that the number box connecting to the outlet remains zero.

Next, you repeat the step with the left inlet number box. Type in a number and press Return/Enter. Note that once you press Return/Enter, the result number box will show you the correct result, 18 in this case.

We can conclude that the plus object performs an addition operation between two numbers, one in the left inlet and one in the right inlet. The result will be in the number box connected to the outlet. Nevertheless, the behaviors of the two inlets are different, the sequence is extremely important in Pure Data programming. In Pd terminology, the left inlet is the hot inlet. All other inlets are cold inlets. Only change of values in the hot inlet will trigger the operation, which in this example is an addition process. Change of values in the cold inlet (the right one in this case) will only store the new value in the inlet without initiating an addition process.

Sometimes, it is counter-intuitive to change the number value of the right number box and wait for the left number to change too. Pure Data has another object to tackle this behavior. It is the trigger object.

If you do not know how to use the trigger object, you can always right-click or Ctrl-click on it to display the help message. A trigger object will pass the message it receives to its outlets from a strictly right to left order.

The two float after the trigger are parameters indicating that the trigger object will pass numeric values to its outlets. All numbers in Pure Data are floating point numbers, that is with decimal. Integer or natural number is a special kind of floating point number that it does not have digits after the decimal point. When you key in a number in the inlet number box, you will see the output from the console window. The message right: 7 appears before the left: 7.

You can also change the value of the number box by clicking-and-dragging it upward or downward to increase or decrease the value by 1. If you press the Shift key and click-and-drag, you can increase or decrease its value by 0.01. In all cases, the right outlet always comes before the left one. With this function, we can enhance our addition operation.

The only difference is the right number box. It goes through a trigger object with two parameters: bang and float. Whenever we change the value of the right number box, its numeric value (float) will pass to the right outlet first (right to left order) and a bang message will then pass to its left outlet. The right outlet goes to the cold inlet of the plus object first with the new number value. After that, the left outlet sends a bang message to the hot inlet of the plus object to trigger the addition process to start. It will then perform immediately without waiting for the value change in the left number box.

Once you are familiar with the object, you can write trigger b f or even t b f instead of the long form trigger bang float. As an exercise, you can replace the plus sign with the minus -, multiplication *, or division / signs to try them out.

Most programming languages include the facility to store values in a place, and which can be referred afterward. It is usually called a variable. Pure Data uses a graphical object box for this purpose. The most common storage objects are float, int, and symbol. The objects, float and int store floating point and integer numbers respectively. The object symbol stores text without spacing in between, for example, Hello. Note that the descriptions we put next to the objects in the following screenshot are comments. Comments are textual descriptions for you to document your patch. You can add a piece of comment by navigating to Put | Comment. It is always good practice to document your patch for easy maintenance.

The following example will make use of a float object to function as a counter. Create an empty patch and save it with name counter.pd in your folder. Put the float and plus objects in the patch window.

Connect the outlet of the float object to the left (hot) inlet of the plus object. Connect the outlet of the plus object to the right (cold) inlet of the float object. It looks like a cross.

Add two more number boxes and connect one to the right inlet of the plus object and the other to the outlet of the float object. Note that the outlet of the float object is connected to two objects.

The last step is to put a bang object to the left inlet of the float object. To do this, choose Put | Bang from the menu bar. Connect it to the left inlet of the float object. Note that bang is one of the graphical user interface object and which functions like a push button.

We now switch to Run Mode. Click on the right number box and type in the number 1. Click on the bang button a few times. Each time you click on the bang button, the circle turns black and the bottom number box will increase its value by 1.

Now you can change the right number box value and click on the bang button again. The value determines how much the counter will increment whenever you click on the button.

When you setup this patch, the float object has an initial value of zero in its right inlet. Every time you click on the bang button, it sends out a bang message to the float object to output its value stored in the right inlet. That is the value in the bottom number box. At the same time, there is a connection from the float object outlet to the left inlet of the plus object. It causes the plus object to add 1 (or another value in the right number box) to it and sends the result back to the right inlet of the float object for temporary storage. The next time you click on the bang button, its value will increment again.

One last point to complete this counter is how you can reset the value to zero. You can achieve it by putting a 0 message to the right inlet of the float object. By clicking on this message, it sends the value zero to reset the counter. Note that we use message instead of a number box because there is no need to change the value 0.

As we noticed, in the last example, you need to click on the bang button to advance the counter. Can we do it automatically? The following example will provide you with the answer. It is another important concept in Pure Data. When you work on animation in later chapters, it requires the same technique.

Save As your last example with the name autoCounter.pd. We will now modify it with the auto-counting function. The new object we are going to use is metro. It is the metronome for counting the beat when you practice musical instruments. We add a metro object with a numeric parameter of 1000. This number is the duration of each beat, with units in millisecond. 1000 milliseconds will be one second. The second new object is a toggle box. You can choose it from Put | Toggle. It is another type of button, such as an on/off switch. We connect the toggle box to the inlet of the metro object and a bang box to the outlet of the metro object.

In Run Mode, click on the toggle box. You will notice a cross indicating the ON state. Note that the bang box flashes automatically once in every second. To stop, click on the toggle box again. The cross disappears.

The toggle box starts and stops the metro box. A cross in the toggle box sends out a value 1. An empty toggle box sends out a value 0. The number next to the metro box is the duration in milliseconds for every count. The number 1000 means one thousand milliseconds, that is one second. For every second, the metro box sends out a bang message through its outlet. To complete the patch, we can connect the bang message from the metro box to the bang input for the float object.

We can also use a number box for the right inlet of the metro object to control the counting frequency, instead of the fixed rate of 1000 milliseconds. The smaller the value, the faster the metro counts.

When there are more boxes in the patch window, the connection links grow messier. Pd provides a wireless connection for you to tidy up the links. They are the send and receive boxes. The following example makes use of send and receive boxes to eliminate the intersecting connection. The name cnt next to send and receive is a variable name you could use to describe the connection. You can use whatever appropriate name as long as it is unique and identical in both the send and receive boxes. You can imagine it is an invisible link connecting the send and receive boxes with the same variable name.

Once we have the tool to automate the counting process, we can make use of it to create an animation. Since we have not learnt to draw in Pure Data, we start by using the graphical user interface elements, such as the bang object, to create the graphics.

Save As the last example with the name animation1.pd. Simplify the patch like the following screenshot. Note that we move the metro box and its connections to the left-hand side and remove the send and receive objects. In this patch, we plan to animate a number of bang objects, say six of them, one by one in a sequence. This technique can be helpful when we create an animation loop later.

Then, we put six bang objects in the patch, arranging them in a row. To work with this, we also add a new object called select. It is similar to the conditional statement IF in text based programming languages.

In Run Mode, if you change the value in the number box above the select object, you will notice the relation between the number and the behavior of the bang boxes under the select object. A number 0 will flash the first bang. A number 1 will flash the second bang. A number 5 will flash the last one. In most programming languages, we count from zero instead of one. For example, if we have a count of 5, we count from 0, 1, 2, 3, and 4. Remember that you can click-and-drag the number box upward and downward to change the number value.

You can consider the select object a multiple conditional statement. In this example, if the number from the inlet is 0, it passes a bang to the first outlet. If it is 1, it passes the bang to the second outlet. If it is 2, it passes the bang to the third outlet. If it is outside the range of 0 to 5, it passes the bang to the last outlet, which is not connected to any bang box here. You can also specify non-consecutive numbers as the parameters in the select object. In later chapters, we will also use non-numeric parameters.

To complete the patch, we connect the counter output number box to the select object. In order to reset the counter, we also need to send the bang message to the message box containing the zero value, when the counter value exceeds 5.

In this version of the patch, the animation runs from left to right sequentially. It is due to the counter value changing from 0 to 5. In the next example, we modify it such that we can have a random movement. Pd comes with a pseudorandom number object called random. We'll use it to generate a number from 0 to 5. If you right-click or Ctrl-click on it to display the help menu, you can specify other parameters to control the range of the random value.

We put the number 6 here for the parameter. It will generate a random value between 0 to a number less than 6, that is 5. Again, it is common practice in programming languages for a value to start from 0, instead of 1. The next step is to combine this random object with the last example. It is pretty straightforward. We only need to send the bang message from the metro object to the random object in order to generate the next random number. The rest remains the same.

In previous sections, we came across a number of graphical interface objects such as bang, toggle. The following patch will introduce the slider and radio buttons. Slider is a numeric value represented visually. You drag the handle of the slider to alter the numeric value. Radio buttons are a group of options. You can only select one among the group.

To create a slider, navigate to Put | Hslider or Put | Vslider. To create a group of radio buttons, navigate to Put | Hradio or Put | Vradio.

When you click on the bang object, the console window will show the bang message. When you click on the toggle object, the number box value alternates between 0 and 1. When you drag the slider, the number box value changes from 0 to 127, that is the default range. You can change this range by right-clicking or Ctrl-clicking on the slider and opening the Properties window to modify the output range.

When you click on any square of the radio button group, the number box gives you a value from 0 to 7, depending on which square you click on. It is the default number of buttons in the radio group. You can also change the number of buttons by right-click on the radio button group and open the Properties window to modify the number.

Remember that you can always right-click or Ctrl-click on the object to choose the help menu in case you would like to understand more about the object.

This chapter covers the basic elements in a Pure Data patch. We have discussed the use of data in Pure Data, such as floating-point number, integer, and symbol. We covered the use of simple arithmetic calculation. We introduced the use of the trigger object to synchronize the hot and cold inlets. By using the float object, we understood how to store numeric values as variables in Pd. We used the metro object to create loop in Pure Data. Within the loop, Pure Data provides the select object for conditional processing. We used the random object to create chance-based operations. The last section also demonstrates the commonly used graphical user interface elements in Pure Data. Until now, everything is number. In the next chapter, we start off our adventure in the graphics world with the GEM library.