Pd Documentation chapter 3: Getting Pd to run

back to table of contents

How to get Pd up and running depends on your operating system. Pd runs under Irix, Windows, and Linux. You must first get and install it, and then untangle whatever problems arise in handling audio and MIDI input and output, and finally get Pd to meet its real-time obligations reliably.

3.1. how to get and install Pd

3.1.1. IRIX (SGI machines)

Download Pd, which will be a "tar.Z" file. You can unpack this by typing "zcat [name].tar.Z | tar xf -" to a shell. This creates a directory named "pd".

Starting with release 0.25, Pd should come in "n32" and "o32" versions. "o32" is the default and will run on IRIX 5.x and up. "n32" runs faster, but only on 6.x and up. Also, "externs" have to be updated for n32. The "pd" executable (bin/pd in the distribution) is a symbolic link to either "pd-o32" or "pd-n32."

Please note that the path to the Pd executable program can't contain space characters; don't put it in a directory named "Program Files" for example.

If for example you put Pd in ~, the executable program will be ~/pd/bin/pd. The program looks at its command line to figure out where it is, so it's best to invoke Pd by its full pathname. You should always invoke Pd from a Unix shell because many important messages appear on the standard error.

The simplest way to invoke Pd is to make an alias in your ".cshrc" file (assuming you use the "c" shell) such as:


    alias pd ~/pd/bin/pd

(assuming your Pd distribution landed in ~, for example).

Pd will open the "default" audio input and output devices, without regard for whether they are in sync or not. This will be bad if they aren't; use the "-noadc" or "-nodac" flag to disable either the input or output. Pd is supposed to handle up to 8 channels of audio in and/or out. (But at least one user had to recompile Pd on his Onyx to get 8 channels working.)

As to MIDI, Pd simply attempts to open all available MIDI devices for input and output, which is probably very bad on anything more recent than my Indy. If any MIDI ports fail to open either for input or output, all MIDI is disabled.

Pd has not been fixed to request real-time priority from Irix; it will compete with all other processes on your machine for CPU time.

3.1.2. Microsoft Windows

Pd is compiled under NT, but sort of works under windows 95/98 as well. Pd will appear as a "zip" file. Unzip this, creating a directory such as \pd. (You can put it wherever you like but the path should have no spaces in it; so "Program Files" would be a bad place.)

If for example you put Pd in C:\pd, the executable program will be C:\pd\bin\pd. You can simply adjust your path to include C:\pd\bin and just invoke "pd" in a command prompt window. You can also make a "command prompt" shortcut to start Pd.

3.1.2.1. The special joys of Windows 95

On Windows 95 you can expect a hard time. Every user who tries it seems to encounter a new problem. The best way to run Pd is to get into the "MSDOS Prompt" program and type \pb\bin\pd to it (or whatever the path ends up being.) You can probably put pd's "bin" directory in your path so that you just type "pd" to the prompt.

You don't want to run Pd from the "run" menu because if it fails to start up the window holding the error message will disappear instantly. Ditto for clicking on "batch files" or on the Pd executable itself.

The most common reason Pd might fail to start up in W95 is not having "networking" turned on. Pd is actually two programs that establish an IP interconnection. Beware that this sometimes fools Windows into calling your ISP for no reason.

It is often necessary to specify a huge audio buffer to get steady audio output in W95; see the command line arguments below.

3.1.3. Linux

What to do depends on which flavor of Linux you are running (e.g., Debian or Red Hat). The instructions here should work for Pd 0.33 and up regardless of your situation, but if you have any trouble just mail msp@ucsd.edu and I'll try to figure out what's wrong and update the instructions accordingly.

Before you start, you might want to check that you have the resources Pd needs. The main things you need are the C compiler, X windows (including the X development package for Pd to link against) and TK. If you're running Redhat or Mandrake 7.x or up, I think these are all present by default. The RedHat X client developer "RPM" package is called XFree86-devel.

You don't absolutely have to have the X server package running; you can run Pd on the microprocessor in your refrigerator as long as it can connect to an X server on another machine.

If you're running RedHat you might want to use RPM to install Pd. For other linux distributions, download the "tar.gz" version and compile it.

Getting Pd as an RPM

Download Pd, perhaps from http://www.crca.ucsd.edu/~msp/software.html , to a file such as "pd-0.33-0.i386.rpm". Open a "shell" window, cd to the directory containing the file, and type the command,

    rpm -i pd-0.33-0.i386.rpm

(substituting the real file name.) Then you should be able to type "pd" to a shell and watch the Pd main window appear.

Getting Pd as a .tar.gz

Download Pd, perhaps from http://www.crca.ucsd.edu/~msp/software.html , to file such as "pd-linux-033.tar.gz". Open a "shell" window, cd to the directory containing the file, and type the command,

    zcat pd-linux-033.tar.gz | tar xf -
which creates a directory named "pd". I do this from my home directory. Next, compile it. "CD" to pd and read the INSTALL.txt, or else just cd to "pd/src" and type
./configure
make depend
make

Then you can type "~/pd/bin/pd" to run it.

Alternatively, as superuser, you can run "make install" after "make depend" and then anyone on your system can just type "pd" to run it.

Testing audio and MIDI.

Next try audio. We want to know whether audio output works, whether audio input works, and whether they work simultaneously. First run "aumix" to see audio input and output gains and which device is "recording". Then test audio output by running

    pd -noadc
and selecting "test audio and MIDI" from the "help" menu. You should see a patch. Turn on the test tone and listen. Do the usual where's-the-signal business.

Then quit Pd and test audio input via

    pd -nodac
Re-open the test patch and hit "meter"; look at the levels. 100 dB is a hard clip; arrange gains so that the input signal tops out around 80 or 90, but no higher.

Now see if your audio driver can do full duplex by typing "pd" with no flags. If you see error messages involving /dev/dsp or /dev/dsp2, you're probably not able to run audio in and out at the same time. If on the other hand there's no complaint, and if the audio test patch does what you want, you might wish to experiment with the "-audiobuffer" flag to see what values of audio latency your audio system can handle.

3.2. audio and MIDI support

Pd comes with multichannel audio support for IRIX, Windows, and Linux; on IRIX this should work without any trouble at all, but on the other two you have to be aware of many potential complications.

You may be interested in getting only audio output or audio input, or you may need both to run simultaneously. By default, Pd will try to run both, but if you don't need either input or output, you may find that Pd runs more reliably, or at least more efficiently, with the unused direction turned off. This is controlled by Pd's command line flags.

Depending on your application you will have a more or less stringent latency requirement. Ideally, when any input (audio, MIDI, keyboard, network) is available, the outputs (in particular the audio output) should react instantly. In real life, it is necessary to buffer the audio inputs and outputs, trying always to keep some number of milliseconds ahead of real time to prepare for the inevitable occasions where the CPU runs off to service some different task from Pd. How small this latency can be chosen depends on your OS and your audio driver.

To test audio and MIDI, start Pd and select "test Audio and MIDI" from the "help" menu.

TIP: If Pd starts up but you get distortion or glitches in the audio output, this could be either because the "audio I/O buffer" isn't big enough, or else because the CPU load of the patch you're running is too great for the machine you have, or else because the ADC and DAC are out of sync or even at different sample rates. To test for the first possibility, try increasing the "-audiobuf" parameter in the command line (but see also under your OS below.) For the second, start up your favorite performance monitor program; and for the third, try starting Pd up with ADCs disabled.

3.2.1. IRIX (SGI machines)

Pd takes command line arguments to set the number of input and output channels and the sample rate. These don't affect the SGI's audio settings, which you have to set separately using the "audio panel." Pd does detect the audio sample rate if you don't specify one on the command line.

On SGI machines, you have to work to get MIDI running. Before you start Pd, verify that least one MIDI port is configured open. Pd opens the FIRST MIDI port that's open. You might want to get rid of the "software" MIDI port if you're running 6.x. On Indys, the usual practice is to open serial port number 2 because some systems configure port 1 as "console" by default. You can use the GUI if you want, or else just type


    startmidi -d /dev/ttyd2

to get port 2 speaking MIDI, and

    stopmidi

to stop it. You can test whether MIDI is configured by typing,

    ps -dafe | grep midi

and looking for "startmidi" processes.

It's a good idea to connect your serial port to your MIDI interface before typing the "startmidi" command, not afterward, at least in 5.x. We use the Opcode Studio 3 interface but in principle any Mac-compatible one should work.

The O2 apparently has RS232 ports, not RS422. I think SGI's web site says something about how to deal with this.

3.2.2. Windows/NT (PC compatibles)

On PCs, you can ask for a list of audio and MIDI devices by typing "pd -listdev"; you can then specify which audio and MIDI device to use. Type "pd -help" (or make any mistake) to get the syntax for specifying which device to use.

Most PC sound cards seem to have MIDI built in; you don't seem to have to do anything special to get Pd to send and receive MIDI. You can list and choose MIDI devices in the same way as audio.

MIDI timing is very poor if you are using simultaneous audio input and output; if you suppress either audio input or output things will improve somewhat under NT; you can apparently get the jitter down to ~40 msec. On W95 performance is simply terrible. W98, with either audio input or output suppressed, offers fairly good MIDI timing (~5 msec jitter) but crashes occasionally.

Some NT and W98 drivers greet you with a constant trail of "resyncing audio" messages. Sometimes you can fix this by invoking Pd with the "-noresync" flag.

3.2.3. Linux (PC compatibles and Alpha)

Be forewarned: installing and testing audio and MIDI drivers in Linux can take days or weeks. There apears to be no single place where you can get detailed information on Linux audio. In addition to the information here, you should see what's posted on Guenter's page, http://gige.epy.co.at/ .

Depending on your hardware and software, you might or might not be able to run "full duplex," i.e., use audio input and output at the same time. For many applications it's important to be able to do this, but if by any chance you don't need simultaneous input and output you will have much less trouble than if you do.

There are two widely-used driver sets, called "OSS" and "ALSA". OSS is included in the standard Linux kernels since version 2.2. However, for some audio cards you can find newer versions than are included in the kernel releases. You can get ALSA from http://www.alsa-project.org/ .

(There is also a commercial version of the OSS drivers which costs $30 (slightly more for certain audio cards.) Hit http://www.opensound.com/ . These might be easier to use than the free OSS drivers, but I've never tried them.)

ALSA is able to emulate OSS, so that you can usually run Pd using the default "OSS" settings even if it's actually ALSA that's running.

3.2.3.1. Installing OSS

OSS is really a collection of loadable device drivers. THe commands for loading and unloading the drivers are "insmod" and "rmmod". You can see if the audio drivers are running using "lsmod" (as root.) If you see something like:


Module         Pages    Used by
eepro100           3            1 (autoclean)
opl3               3            0
opl3sa2            1            0
ad1848             4    [opl3sa2]       0
mpu401             5    [opl3sa2]       0
sound             15    [opl3 opl3sa2 ad1848 mpu401]    0
soundcore          1    [sound] 6
soundlow           1    [sound] 0
aic7xxx           23            2

then OSS is running, and if all you see is:

eepro100           3            1 (autoclean)
aic7xxx           23            2

then it isn't. You can turn OSS off by running "rmmod" repeatedly, starting with "opl3" (or whatever) so as not to remove any module before you remove all the modules that depend on it. In the above listing, "opl3*" is device dependent and you might see different names.

The file, "/etc/modules.conf" apparently controls which sound drivers are started at boot time. The sndconfig program updates this file but you can also change things manually, for instance to switch between two different sound cards. In Redhat 6.x and earlier, the file is named "conf.modules."

Here is a modules.conf file for OSS:


alias eth0 e100
alias parport_lowlevel parport_pc
alias char-major-81 bttv
alias usb-controller usb-uhci
alias sound-slot-0 i810_audio
alias sound-slot-1 es1371

Here the two sound cards are the (motherboard resident) i810 driver and an ensoniq es1371, probably on a soundblaster PCI128.

In RedHAt at least, the "sndconfig" program tries to automatically search for your soundcard. Unfortunlately it only finds the "first" one which is often not the one you want to use!

As of version 0.33, Pd doean't give you a choice of which soundcard to use; it opens them sequentially starting with sound device "0" depending on how many channels you ask for. In the above situation I would manually edit the modules.conf file to make the "es1371" card be the first one; then Pd will use it.

3.2.3.2. ALSA

ALSA is newer, hence less stable and harder use, than OSS. Some multichannel cards support only ALSA and not OSS (and ALSA's OSS emulation is apparently stereo only.) Alsa comes in a "finished" version (0.5.x) and a different, redesigned, "beta" version, 0.9. Installing ALSA can be tricky and/or confusing.

As of version 0.33 Pd works with either 0.5.x or 0.9.x versions. The RPM version of Pd is compiled for 0.9.x. If you're starting from the ".tar.gz" version, you have to "./configure --enable-alsa" to get it; see the "INSTALL.txt" file in the installation.

By default, Pd uses OSS. If you are running ALSA, Pd will use ALSA's OSS emulation. To make Pd use ALSA "natively", i.e., the way ALSA is designed to be used, include the "-alsa" flag in the command line.

3.2.3.3. stream and block mode (-frags flag)

Under OSS at least, programs can stream sound using either "block" or "stream" mode. Stream mode is the more modern and better of the two, but the majority of drivers, even for new sound cards, only support "block." Pd makes "block" the default.

3.2.3.4. Which sound card?

Here's a rundown on my experiences with sound cards so far. See also Guenter's audio page.

opl3sa

This is the old ISA "Yamaha" audio system. It comes on many Dell machines and seems to offer reasonable consumer quality audio, at least under NT. I believe the current version of OSS can get full duplex operation out of an OPL3sa audio system. This is an ISA ("plug and play" device and you have to deal with I/O addresses and all that.

cs4232

The 1999 vintage dual-processor Dell machines have "cs4232" audio, which I couldn't get working.

es1370 (old Creative PCI128s)

Guenter has the best info on this card at http://gige.epy.co.at/ .

(CAUTION -- newer Creative PCI128s are actually SBLive inside... get a generic one to be sure.)

The es1370 is the chip. There are other cheap audio cards that sport es1370s. Apparently the audio quality isn't great, but on the other hand, you can actually get it to output 4 independent channels---I've tried it an it worked. Street price for a PCI128 in the USA is $30.

The audio inputs and outputs on my PCI128 aren't clearly labelled and various documents give them inconsistent names. On my card there are 4 stereo mini jacks and a joystick port, in this order:

joystick    black            green       red       blue
            bidirectional    line-out    mic-in    line-in
I think you can load the es1370 driver on the fly simply by typing
    modprobe es1370
(perhaps after running "rmmod" on some other driver as described above.) To have your computer automatically load es1370 on startup, put the lines,
    alias sound es1370
    pre-install sound insmod sound dmabuf=1
    alias midi es1370
in /etc/conf.modules, or run sndconfig (as root) and get it to do it somehow.

To make the card do quad you have to download and compile Guenter's es1370 control program, which is part of the "small patch" you can download from http://gige.epy.co.at/pd/cards.html .

The really tricky thing about quad is that the regular "stereo" outputs move to the black jack and the new "back" channels appear on the regular line output (green.) What's more, the back channels are normally mixed into the front ones (or is it vice versa?) so you'll have to play blind man's bluff with aumix for an hour or so to get the four channels to emerge separately.

My own version of Guenter's control program can be downloaded from http://www.crca.ucsd.edu/~msp/Software/audio-es1370.tar.gz.

I believe I have the ALSA driver also working with es1370 now (0.31).

Creative SBLive

There is an OSS driver in the standard Linux distribution, but it doesn't support selecting for incoming MIDI so Pd will not see and MIDI input from it. If you need MIDI, you must install ALSA; you can run Pd using OSS emulation or native ALSA as you please.

Sonorus Stud I/O

This $1000 card is supposed to do multichannel digital I/O in Linux, via a beta version of a commercial OSS driver ($40). Sonorus's web site proclaims a new product called the "MedI/O" to appear shortly.

RME 9652 (Hammerfall)

This is the best sound card out there; it costs around $500 and has 3 ADAT I/O ports and one SPDIF. There is a "baby hammerfall" also, which I think is the "9632." DO NOT CONFUSE THE 9652/9632 WITH OTHER RME BOARDS WHICH MIGHT NOT WORK WITH PD.

Guenter has an OSS driver for Hammerfall for 2.4 kernels (such as RedHat 7.1). You have to download and compile it: http://gige.xdv.org/pages/rme .

For older RedHAt systems (6.x) you can also use Winfried Ritsch's RME driver. To do this, hit http://www.crca.ucsd.edu/~msp/Software/audio-rme.tar.gz for my version of Winfried's driver and test program which works with the current release of Pd (0.27).

With this card there is no FIFO size control at all within Pd; it's set using Winfried's test program.

With the RME option, you can use "-soundindev" and "-soundoutdev" flags to select which input and output devices to use (for instance, the AES/EBU ports are devices 25/26).

Word has it that Hammerfalls now have an ALSA driver; from what I hear it won't work yet with Pd.

MIDIMAN

Midiman sells devices with between 4 and 12 analog channels in and out, for which there are ALSA drivers. Seems to work fine with the old or the new ALSA.)

i810/i815

In RedHat 7.0, motherboards with native i810 audio systems don't work in full duplex (they crash linux). Either run Pd -noadc or else (better) install ALSA.

Yamaha YMF724

The OSS driver for this card appears not to support MIDI. I haven't tried with ALSA.

ES1371

In OSS, audio and MIDI seem both to work fine with this chipset.

3.3. graphics rendering using GEM

Mark Danks's GEM package is available from http://www.danks.org/mark . Download this to extend Pd to do 3-d graphical rendering using Open GL

3.4. starting Pd

Pd is a "command line" program. The best way to run it is from your "terminal emulator," "shell," or "MSDOS prompt." The command line is:

    pd [options] [patches to open]

although you may have to specify a path so your command interpreter can find Pd (OS dependent.) The options are as follows:

-r            -- specify sample rate
-audiobuf     -- specify size of audio buffer in msec
-sleepgrain   -- specify number of milliseconds to sleep when idle
-inchannels   -- number of audio input channels
-outchannels  -- number of audio output channels
-nodac           -- suppress audio output
-noadc           -- suppress audio input
-nosound         -- suppress audio input and output
-midiindev    -- specify MIDI input device number(s)
-midioutdev    -- specify MIDI output device number(s)
-nomidiout       -- suppress MIDI output
-nomidiin        -- suppress MIDI input
-nomidi          -- suppress MIDI input and output
-path      -- add to file search path
-open      -- open file(s) on startup
-lib       -- load object library(s)
-font         -- specify default font size in points
-verbose         -- extra printout on startup and when searching for files
-d            -- specify debug level
-noloadbang      -- suppress all loadbangs
-nogui           -- suppress starting the GUI
-guicmd "cmd..." -- substitute another GUI program (e.g., rsh)
-send "msg..."   -- send a message
with additional options for NT:

-listdev          -- list audio and MIDI devices
-soundindev    -- specify audio input device number
-soundoutdev   -- specify audio output device number

and for Linux:

-rt or -realtime -- real time priority (superuser or setuid only)
-frags        -- Overriding -audiobuf, specify number of audio I/O blocks
-blocksize    -- specify audio fragment size in sample frames
-fragsize     -- specify audio fragment size as bitshift (obsolete)
-stream          -- use audio stream mode
-alsa            -- use ALSA audio drivers
-alsadev      -- specify ALSA I/O device number (counting from 1)

Here are some details on some of the audio options (but see also the next section on file management.)

3.4.1. sample rate

The sample rate controls Pd's logical sample rate which need not be that of the audio input and output devices. If Pd's sample rate is wrong, time will flow at the wrong rate and synthetic sounds will be transposed. If the output and input devices are running at different rates, Pd will constantly drop frames to re-sync them, which will sound bad. You can disable input or output if this is a problem.

3.4.2. audio buffer size

You can specify an audio buffer size in milliseconds, typically between 10 and 300, depending on how responsive your OS and drivers are. If this is set too low there will be audio I/O errors ("data late"). the higher the value is, on the other hand, the more throughput delay you will hear from the audio and/or control inputs (MIDI, GUI) and the audio coming out.

In Linux, you can also specify the audio block size in sample frames.

3.4.3. MIDI devices

You can specify multiple MIDI input and output devices. For example, "pd -midiindev 3 -midioutdev 4,2" asks for the third MIDI input device and the fourth and second MIDI output device. The "channel message" midi objects in Pd such as notein or pgmout will take channels 1-16 to mean the first open MIDI port, 17-32 the second one, and so on. The midiin, sysexin, midiout objects give you a separate inlet to specify which of the open MIDI port numbers you want.

3.5. dealing with files

Pd has a search path feature; you specify the path on the command line using the "-path" option. Paths may contain any number of files. If you specify several files in a single "-path" option they're separated by colons in unix or semicolons in NT. When Pd searches for an abstraction or an "extern" it uses the path to try to find the necessary file. The "read" messages to qlists and arrays (aka tables) work the same way. NO SPACES MAY APPEAR ANYWHERE IN THE SEARCH PATH, e.g., "c:\my nonsense\goobers" won't work.