Pure Data

PD (aka Pure Data) is a real-time graphical programming environment for audio, video, and graphical processing. It is the third major branch of the family of patcher programming languages known as Max (Max/FTS, ISPW Max, Max/MSP, jMax, etc.) originally developed by Miller Puckette and company at IRCAM. The core of Pd is written and maintained by Miller Puckette and includes the work of many developers, making the whole package very much a community effort.

A simple patch

We are not going to see all the functions offered by pd, they are numerous. On the other hand we're going to see some categories of elements that are essential to the good understanding of pd.

As announced before, pd is a dataflow/diagram based programming software. As a result you do not "type" lines of code, but instead you moves "boxes" around and draw connections in between.

When you create a new patch by going to the "file/new" menu, these different elements above can be placed where you want on the big empty white canvas that will define your diagram area. These items are called by choosing them in the "put" menu. Feel free to move them around, fill their content by typing inside, select them (they turn blue), delete them (backspace), duplicate them (Ctrl-e), select them all (Ctrl-a)...

You can notice that as soon as you have put a new item, your cursor turns into a "hand", this means you are in edit mode. During edit mode you can move, rename, link, unlink (etc..) elements but you can't interact with them. In order to click on a message or play around with a number box you need to quit the edit mode, either with the Ctrl-e combo or by going to the "edit/edit mode" menu.

While filling objects with names, typing in an non exsistant function name will result in an unsuable dashed object.

Tip: If you need to interact just for a short instant while in edit mode, maintain the Ctrl key. Release when you want to edit again.

Time to connect some objects! The most basic operation consists to send a message to the print object

The order of connection is from the message outlet (the little black thinggy on the bottom left of the message item) to the print object inlet (the little black thinggy on the top right of the print object). Connections are done by dragging a within these two items, the linking system is only available when you are in edit mode and put your cursor on the top of one outlet (if it works the hand will transform into a "donut", not a real one though.).

As the example shows, you're not limited to single links for inlets (the same goes for outlets).

Do not forget: in order to pass the "your machines" message to the print object, you need to click on it, but not in edit mode, so switch back to normal (Ctrl-e) or maintain the Ctrl key before clicking (same for the number box). If everything goes well, you should see your actions sent to the terminal window (or the main pd window, depends on your installation), and that's the function of the print object (Tip: At any time you can right click on an object and select help in order to display some examples and description of the functions proposed by this object)!

Congratulations, you just made your first pd patch. Don't apply for isea yet (even though...) because it's just the beginning.

My First Packet

Now that you certainly are more confident at creating and connecting those little "boxes", we're going to move on and see how video can be generated from these diagrams.

What is a packet ?

Well, actually a packet can be virtually anything, it's just a chunk of data that could be interpreted as anything you want. What is the relationship with video ? well if you consider a flow of packets, and isolate one, in a video language this is equivalent to a frame. In other words a packet can be defined as an image with color, width and height properties. A packet can be more of course but let's stick to the frame viewpoint in this tutorial.

How to create a packet ?

Here again, there is not one unique way to create packets, they can be imported, converted, made from scratch or extracted from audio signals and picture. For your mental health we will only stick to generated packets.

There are several packet generator (check the pdp documentation for the object list), the most commonly used is the noise generator. To call it you simply need to put an empty object in a new canvas and call it "pdp_noise" (Note: all the pdp objects start with pdp ... easy).

This object can now potentially generate packets, but as we have seen with the print object, some elements need to receive a message to be activated. That's the case here. In order to generate a packet you need to pass a message called "bang".

Everytime you click on "bang" (don't forget to quit the edit mode, Ctrl-e), a new noise packet is generated. Unfortunately we can't see it yet, to fix that we need an object that can reveal the content of the packet to the screen.

The "xv" stands for xvideo, it's a particular graphic display and it may not work with a wrongly configured graphic card. If you encounter some problems, try to replace "pdp_xv" by "pdp_glx" or "pdp_sdl". These two other objects have the same effects but they use other methods that could be more friendly to your graphic card and installed drivers.

If everything goes well, you should see something like that:

You can now notice that everytime you click on bang, a new packet is generated, if you click very fast you can produce animated noise, if you click faster you're going to get tired.

In order to produce a video stream, it would be quite helpful, if this flow could be maintained at a fixed "bangrate". This can be easily done with the metro object which task is to output a "bang" message every x miliseconds.

The "40" is a creation argument, it's telling the metro object to send a "bang" message every 40 miliseconds (1 bang / 40ms = 25 bang / s = PAL framerate). The "0" and "1" switches are simple on and off buttons to control the metro object.

You should see now an animated flow of video noise.

A simple video patch

Simple processing

Let's make things a bit more complex now.

In this example, you can now notice that two noise generators are used. One is running with a metro at 40ms (25fps) and the other at 1000ms (1fps). The first difference you can notice is the presence of a zoom object. Its function is to simply zoom in (or out) in a packet with a specified ratio, in our case 100. Don't forget, at any time you can right click on an object to access to some extra help informations.

These 2 packets, the normal one, and the zoomed one, are then mixed together to create a unique new packet. This is made possible with the pdp_mix object which take as creation argument the level of mixing between the two sources (value between 0 and 1).

Note: You can see an important particularity of dataflow processing, if you stop the right metro, the flow still works. If you stop the left metro, everything is stopped even if the right metro is on. This is due to the law of hot and cold inlet. Everything sent the hot inlet (in this case the top left inlet of the pdp_mix object) will be processed and output to the outlet. On the other hand packets sent to the cold inlet (in this case the middle inlet of pdp_mix) will just be stored but not processed. As a result the carrier flow defining the final packet rate (= frame rate), is directed by the incoming data in the hotlet. For example if you reverse the connections between the hot and the cold inlet, the frame rate will drop at 1fps as the hot inlet is receing only one packet per second.

Now Let's try now to apply to the resulting packet flow a small processing to smooth and soften the transitions between one zoomed packet to the other. This is possible by doing a sort of feedback mixing.

So what's happening here ? Basically to obtain a smooth transition in a movement, you need to mix the frame F with a bit of the frame F-1, the more the intensity of F-1 is important, the more the motion feedback effect will be noticable.

In this patch this simple process can be done by delaying the packet P and then mix it back with the new incoming packet P+1. The feedback can then be controlled by adjusting the value of the mixer. If you set the mixer to 1, this mean you are simply mixing the P packet with 0x(P+1), the new resulting packet is P = P + 0 x (P+1) = P. the image seems frozen.

The iTunes syndrom

Of course, nothing prevent you to manipulate the delayed packet to render a more complex feedback effet. Here you can simply add a rotation and zoom in the result before mixing it. The gain object is just here to amplify a bit the color intensity of the incoming packets.

What happens is that our beloved delayed packet is rotated of +5° before getting zoomed in with a ratio of 1.15. The new packet is then mixed with the new incoming "normal" packet, the result of the mix is then rotated and zoomed again, and .. etc.

As a consequence you keep on slightly rotate and zoom a packet which has already been rotated and zoomed a bit, the result is the top class fancy tunnel zoom effect very popular in popular audio visualization software.

Smoking crack

To amplify the twirling weirdness, you can for example send back the mixed packed earlier in the process and do an basic color-and operation with the old zoomed packet. This will amplify the feedback and make it visible by displaying nice patterns.

You can then modify the zoom with a 0.9 ration (>1=zoom out) and configure a rotation with an angle of 15°. Finally you can specify to the zoom object where the center should be (0=left, 1=right).

now it's time to play with your friends...

Sending and receiving packets

You are not alone

In order to play with your friends you need to be on the same network. Please make sure you have a proper IP address and your friends too. Although I assume you know how to do that, a good thing to do before going further is to verify you can be reached and you can reach your friends. A simple ping should do the trick.

Preparing the patch

As you may have also figured out, we need to add an object to send the packets to another machine, and we also need a similar object to receive packets from another machine. This is the role of pdp_netsend and pdp_netreceive.

The pdp_netsend object is pretty easy to place. You simply connect it in the part of your patch you want to transmit data. In this example we send the whole processed packet flow, but you could have chosen to only send the packets before they enter the magic feedback. The object doesn't need creation arguments but you need to send it a connection message composed of the target IP and port you want to send your stream.

On the other hand, the pdp_netreceive object just need a creation argument to work, the port of your machine you wish to receive the data (of course you also need that someone sends you something on this specific port, that's a bit the point of this tutorial after all).

An important point is, where and how you're going to process these new incoming packet, in the above patch, the net packets are equally mixed with some of your own packets somewhere before the feedback part. You could have placed it somewhere else, it's up to you but do not forget about the cold and hot inlet! If you look at this patch you'll notice the net packets are in the cold inlet of the mixer. This is done for a simple reason, if you don't receive yet anything your data flow is maintained by your own packets, moreover if some network congestion occurs, it will not disturb your local framerate.

Troubleshooting

If something goes wrong you may want to check:

• you are connected to the same network
• you can ping the other participants
• you are sending/receiving on the correct port number
• your firewall is not blocking your receive port
• you can telnet the target IP/port
• the packets received are visible in a separate pdp_glx
• you are sober enough to perform all these operations

Happy stream loop !!!

Further Readings

From this tutorial many extensions can be achieved. The packets can be formed from video files, images, imported chunks of data, audio files, 3d objects ... The processing possibilities are very vast and it's simply impossible list them all. From this point you should be able to investigate what other objects are suitable for your needs.

The video loop can be done locally or not. Try to process data in circle, star, pyramid or whatever. More possibilities are offered with pidip (an extension library for pdp written by Yves Degoyon). With pidip you could easily broadcast your experiments with an icecast server, add some simple color tracking to control a parameter or overlay some text (and more ...). You may also want to have a look at the freeframe plugin from lluis for high level ready made effects (pdp_freeframe, freeframe) .

Last but not least, you can interact with your settings by using GUI objects embedded in nice graph-on-parent abstractions.

Human-based help and support can be reached here:

• web: puredata.org
• mailling list: pd-list
• IRC: irc.goto10.org #data or irc.freenode.net #dataflow

Happy patching !