Chapter 3: Installing and configuring Pd

The following are instructions on how to get Pd installed, configured and running on your machine.

Pd runs under Microsoft Windows, Linux, and macOS. How to get Pd up and running depends on your operating system, but the overall strategy is the same. 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. Installing Pd

Most commonly, you want to install Pd as a 64 bit application, which is available for download, but a 32 bit versions is also available for older OSes. The download page for Pd is https://msp.ucsd.edu/software.html. Binaries are provided for Windows and macOS, while Linux users can get Pd from package managers. The source code is also available in this link for you to build Pd yourself.

Note that Miller's website only offers Pd compiled for single precision, but Pd can also be compiled and run in double precision. An alternative to Miller's website we have https://puredata.info/downloads/pure-data with Pure Data downloads. Note that besides the official single precision application, this link also offers an experimental download for double precision. Note that the double precision application needs externals compiled speacially for it.

Installation instructions are platform-specific and described in each case in this section, but Instructions on how to build Pd yourself for all supported OSes in both single or double precision is provided in Chapter 6: Building Pd from source.

Note that you can have different versions of Pd and also Pd compiled for different architectures and float precision in the same machine/OS. The Pd application is named in a way that it distinguishes itslf from other versions in each case. The "regular" Pd is for 64-bit application and single precision. The double precision Pd application is named "Pd64", which can be confusing, meaning that it is for 64-bit architecture, but it means it uses double precision really (whose float size is "64").

If you run into any installation trouble you can also consult the Pd mailing list archive on https://lists.puredata.info/listinfo/pd-list, which often has late-breaking news about configuration problems and solutions.

3.1.1. macOS

Pd supports macOS from 10.7 and up. There is a version for 10.7 to 10.9 provided, but the main download binary for more modern OS versions supports 10.10 or newer and is the form of a .dmg file. This is a universal binary, for both intel or apple silicon chips. Just double click on this disk image so it opens and you can then drag the Pd app where you want (most likely in the Applications folder). An old 32-bit version is also provided for 10.7 up to 10.14, which is suited if you need to run some old external.

You might get various warnings about Pd trying to open an internet port. This is normal although some system administrators will prevent you from doing this (in which case you can't run Pd on that machine).

3.1.2 Microsoft Windows

For Windows, you can download a .zip package for manual install or an executable installer (a ".exe" file). Run the installer if you are not sure how to install manually and select a destination directory when prompted, such as \pd or Program Files\pd. The 64-bit executable works for Windows Vista or newer. An old 32-bit version is also provided and works for XP or later (this is suited if you need to run some old external or use a 32-bit machine).

If for example you install Pd in C:Program Files\pd, the executable program will be C:Program Files\pd\bin\pd/. You can simply adjust your path to include C:\pd\bin and then invoke "pd" in a command prompt window. You can also make a shortcut to the executable program (left-click on it and drag to the desktop, for example).

Pd requires "TCP/IP networking" to be turned on. This doesn't mean you have to be on a real network, but simply that Pd actually consists of two programs that make a "network link" (locally) to intercommunicate. The first time you run Pd the "Windows Firewall" will ask your permission to allow this intercommunication.

3.1.3. Linux

Pd is available via the package systems for some Linux distributions, but not always in the most recent version possible. In case you don't find it or want the very latest recent version, you need to compile Pd, which is described in 6.3. Building Pd for Linux.

3.2. Running Pd via the command line

Besides opening Pd by clicking on a user friendly icon as usual, you may open and run Pd as a "command line" program from your "terminal emulator", "shell", or "MS-DOS prompt". In Windows, if Pd is started using a "shortcut" it is also run from a command line which you can edit using the "properties" dialog for the shortcut. In any operating system, Pd can be called from a script (called a batch file on Windows or a shell script on macOS or Unix). The command line is just a line of text, which should be of the form:

    pd [startup flags] [patches to open]

Although you may have to specify a path (such as "~/pd/bin/pd" or "C:\program files\pd\bin\pd") so your command interpreter can find Pd.

The 3.4.1. Startup flags subsection describes all options.

3.3. Testing and configuring Audio and MIDI

To test audio and MIDI, start Pd and select "Test Audio and MIDI..." from the Media menu. You should see a window like this:

First, try to get Pd to play a sine wave over your speakers. The "OUTPUT MONITOR" section to the left allows you to set an output gain and a test sound (either noise or a sinusoid). By default, the first eight output channels are turned on so that when you should get output on them when you turn the test sound on. If you have fewer than eight output channels open, the extra channels aren't played; and if you have more, you need to use the radio button to test them. Note that the "AUDIO OUTPUT" toggles must be on (which they are by default) for you to hear anything.

If there's anything wrong, the most likely outcome is that you will hear nothing at all. This could be for any of at least three reasons: Pd might have failed to open the audio device; the audio card's output volume might be set to zero; or your audio system might not be set to amplify the computer output.

The "INPUT MONITOR" provides VU Meters and number boxes to indicated the levels of incoming audio, in dB, with 100 being maximum. Incoming signals may clip at RMS levels below 100 (for instance, a sinusoid clips at about 97 dB). Any DC present in the input (such as you get with cheap audio hardware) will show up as level unless you turn on the "input highpass" toggle at right; then the DC component is filtered out before metering. In order to hear and monitor the input you need to set the dB level in the "Input Monitor" number box. Whatch out for feedbacks if you have microphone inputs.

It is easy to get two copies of Pd running by accident; on most machines only one at a time may be inputting and outputting sound. (Some copy of Pd might have audio or MIDI devices open and prevent the copy you're trying to use from getting access to them). Having extra copies of Pd around will also eat CPU cycles uselessly.

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 may be specified using the Audio Settings dialog panel or Startup 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.

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 delay in "Audio Settings" dialog. For the second, start up your favorite performance monitor program; and for the third, try starting Pd up with ADCs disabled.

In addition to the "Test Audio and MIDI" patch, the Media menu contains items for controlling audio and MIDI settings. The first two items, "Audio on" and "Audio off", open or close the audio devices and start or stop Pd's audio computation.

If there is a choice of audio API to make, the Media menu will display them. On Linux, they are OSS, ALSA, Portaudio and JACK; on Windows, you get Portaudio and an 'old MMIO system'. In Windows, Portaudio offers ASIO and Windows WASAPI. On macOS the default one is Portaudio and you can also use JACK if you have it installed. The Media menu also displays choices for MIDI API. On Linux, they are OSS-MIDI and ALSA-MIDI.

3.3.1. Audio settings

The Media menu also calls the Audio or MIDI settings for the selected API. Clicking on the API to change it also opens the settings window for the newly selected API. If you click on the already selected API, you also open the settings window.

The exact choices you get depend on the operating system and API. The screenshot above is for when you select 'old MMIO system' in Windows. While the screenshot below is for 'portaudio' on macOS.

The sample rate controls both audio output and input. The "delay" is the nominal amount of time, in milliseconds, that a sound coming into the audio input will be delayed if it is copied through Pd straight to the output. Naturally you would like this to be as small as possible, but, depending on OS, API, and even the specific choice of audio hardware, there will be a limit to how small you can make this.

Next you get a choice of input and output device. If you don't need either the input or output device you can uncheck the toggle box to the left (which is on by default). Number of input and output channels is 2 channels by default, but you may specify just one if that's all you need or more if your hardware supports it.

In Linux you're allowed up to 4 input and 4 output devices (note the "Use Multiple Devices" button on the picture above). On Windows you can also do that but you need to be using the 'old MMIO system' API (shown above). On macOS, if you want more than a single device, there's a workaround by creating an aggregate device (via the system's "Audio MIDI Setup") and set it in Pd's Audio settings.

3.3.2. MIDI settings

There's also a MIDI settings dialog for you to configure one or more MIDI input and output devices. If more than one device is chosen for either input and output, they are registered in different MIDI ports. The "channel message" midi objects in Pd (such as [notein] or [pgmout]) will take channels 1-16. Note, however, that the MIDI port is encoded in the channel number, where channels 1-16 mean the first open MIDI port, 17-32 the second one, and so on. The [midiin], [midirealtimein] and [sysexin] objects output the port number in their right outlet and [midiout] has a separate inlet to specify which MIDI port you want.

System exclusive MIDI message input and output are theoretically supported but does not work uniformly across all operating systems..

3.4. Path and startup

In addition to the Audio and MIDI settings shown above, you can customize Pd to instruct it where to find files, what font size to use, and much more. Pd has a main "Preferences" window, which you can select from the Pd menu in macOS or the File menu otherwise. The "Preferences" entry opens a submenu with "Edit Preferences..." and more. By selecting this entry, you open the main preferences dialog with different tabs for: "Path", "Startup", "Audio", "MIDI" and "misc". The Audio and MIDI tabs are actually the same settings windows that you can open via the Media menu, so there's nothing really new but the fact they are also found here. There's one difference though, which is that you can get choices for API this way.

The above picture shows Audio Settings on Windows when you select it from the tabbed Preferences. The difference here is that you have a new wntry to select and change API (where 'old MMIO system' is selected.)

The first preference in the tabbed Preferences is the "Path" dialogs. This tab configures search paths that Pd will use to load externals and abstractions (spaces in the path are allowed by the way). This also used for files in objects that load them like [soundfiler], [text] and even arrays (aka tables). The path must be correctly set before you load a patch or it may fail to find anything. Filenames in Pd are always separated byc(Unix-style) forward slashes, even if you're on Windows (which uses backslashes). Also, note that objects that can load files do expand "~" to your home directory.

In a nutshell, Pd searches for files and externals relative to the patch directory and, if it fails, it searches next in the paths that are set in this tab. Note you can use things like "../samples" to point to folders and subfolders that are relative to the patch directory and other search paths. Note you can also use [declare] to add paths for particular patches - this and other details about path management is also covered in depth in Chapter 4: Externals, and summarized in 4.6. Search order in Pd for objects and files.

The "Startup" tab has configurations for initializing Pd and an entry for Startup flags. Most of the configurations in Pd may be changed using the various dialogs you can open from Pd's menus. For instance, you can use the Font entry from the Edit menu to set what font size size Pd will use for its main window (this is described in subsection 2.1.1., by the way). Nevertheless, this and every other configuration in Pd (from Audio and MIDI settings and whatnot) can also be configurable via startup flags. Other than that, some configurations are too cranky to put in a GUI dialog and must be only set via startup flags.

Startup flags initialize Pd in many ways, but many configurations can be changed while Pd is running. Some configurations, on the other hand, requires Pd to restart, such as setting which external binaries to load (more about external management in Chapter 4.

The "defeat real-time scheduling" control, if enabled, makes Pd run without its usual effort to become a real-time process (whatever this means in the operating system you are using.) In Unix, Pd must usually be setuid to allow real-time scheduling at all.

All of Pd's settings may be saved automatically between Pd sessions. Note the "Save All Preferences" entry in the submenu from "Preferences". It is also possible to save preferences to a file, load from one or forget it all.

Besides being able to set startup flags in "Preferences -> Startup", you can also invoke Pd via the command line using the same startup flags as arguments. Command line settings, if given, override the corresponding settings that were saved from Pd.

3.4.1. Startup flags

Here's a list of all startup flags that you can use in the "Startup" tab under "Preferences" or by running Pd from the command line.

audio configuration flags:
-r <n>           -- specify sample rate
-audioindev ...  -- sound in device list; e.g., "2,1" for second and first
-audiooutdev ... -- sound out device list, same as above
-audiodev ...    -- specify both -audioindev and -audiooutdev together
-audioaddindev   -- add an audio input device by name
-audioaddoutdev  -- add an audio output device by name
-audioadddev     -- add an audio input and output device by name
-inchannels ...  -- number of audio in channels (by device, like "2" or "16,8")
-outchannels ... -- number of audio out channels (by device)
-channels ...    -- specify both input and output channels
-audiobuf <n>    -- specify size of audio I/O buffer in msec
-blocksize <n>   -- specify audio I/O block size in sample frames
-sleepgrain <n>  -- specify number of milliseconds to sleep when idle
-nodac           -- suppress audio output
-noadc           -- suppress audio input
-noaudio         -- suppress audio input and output (-nosound is synonym)
-callback        -- use callbacks if possible
-nocallback      -- use polling-mode (true by default)
-listdev         -- list audio and MIDI devices

(Linux specific audio:)
-oss            -- use ALSA audio drivers
-alsa           -- use ALSA audio drivers
-pa             -- use portaudio (experimental version 19)
-alsadev <n>    -- obsolete: use -audiodev
-32bit          -- (probably obsolete) -- use 32 bit OSS extension
-alsaadd <name>  -- add a device to the ALSA device list

(Windows specific audio:)
-mmio           -- use MMIO drivers and API
-asio           -- use ASIO drivers and API
-pa             -- synonym for -asio

(Using the JACK API:)
-jack            -- use JACK audio API
-jackname <name> -- a name for your JACK client
-nojackconnect   -- do not automatically connect pd to the JACK graph
-jackconnect     -- automatically connect pd to the JACK graph [default]

MIDI configuration flags:
-midiindev ...   -- midi in device list; e.g., "1,3" for first and third
-midioutdev ...  -- midi out device list, same format
-mididev ...     -- specify -midioutdev and -midiindev together
-midiaddindev    -- add a MIDI input device by name
-midiaddoutdev   -- add a MIDI output device by name
-midiadddev      -- add a MIDI input and output device by name
-nomidiin        -- suppress MIDI input
-nomidiout       -- suppress MIDI output
-nomidi          -- suppress MIDI input and output
-ossmidi         -- use OSS midi API (Linux only)
-alsamidi        -- use ALSA midi API (Linux only)

general flags:

-path <path>     -- add to file search path
-nostdpath       -- don't search standard ("extra") directory
-stdpath         -- search standard directory (true by default)
-helppath <path> -- add to help file search path
-open <file>     -- open file(s) on startup
-lib <file>      -- load object library(s) (omit file extensions)
-font-size <n>      -- specify default font size in points
-font-face <name>   -- specify default font
-font-weight <name> -- specify default font weight (normal or bold)
-verbose         -- extra printout on startup and when searching for files
-noverbose       -- no extra printout
-version         -- don't run Pd; just print out which version it is
-d <n>           -- specify debug level
-loadbang        -- do not suppress all loadbangs (true by default)
-noloadbang      -- suppress all loadbangs
-stderr          -- send printout to standard error instead of GUI
-nostderr        -- send printout to GUI (true by default)
-gui             -- start GUI (true by default)
-nogui           -- suppress starting the GUI
-guiport <n>     -- connect to pre-existing GUI over port <n>
-guicmd "cmd..." -- start alternative GUI program (e.g., remote via ssh)
-send "msg..."   -- send a message at startup, after patches are loaded
-prefs           -- load preferences on startup (true by default)
-noprefs         -- suppress loading preferences on startup
-prefsfile <file>  -- load preferences from a file
-rt or -realtime -- use real-time priority
-nrt             -- don't use real-time priority
-sleep           -- sleep when idle, don't spin (true by default)
-nosleep         -- spin, don't sleep (may lower latency on multi-CPUs)
-schedlib <file> -- plug in external scheduler (omit file extensions)
-extraflags <s>  -- string argument to send schedlib
-batch           -- run off-line as a batch process
-nobatch         -- run interactively (true by default)
-autopatch       -- enable auto-patching to new objects (true by default)
-noautopatch     -- defeat auto-patching
-compatibility <f> -- set back-compatibility to version <f>

See next details on a few of the group of flag items.

3.4.1.1. Font flags

The flags offer more font configurations than just "size". Note that macOS has, by default, a "normal" font weight, while in Linux and Windows you have "bold" by default. Use "-font-weight" to change that if you don't like your default setting.

3.4.1.2. Path flag

Paths may contain any number of entries if separated by colons in Unix or semicolons in Windows. Filenames in Pd are always separated by (Unix-style) forward slashes, even if you're on Windows (which uses backslashes). This is so that patches can be ported more easily between operating systems. On the other hand, if you specify a filename on the command line (as in "pd -path c:\pdlib") the file separator should agree with the operating system.

3.4.1.3. Flags for Audio and MIDI multiple devices and sleepgrain

You can specify multiple MIDI input and output devices via flags. For example, "pd -midiindev 3 -midioutdev 4,2" asks for the third MIDI input device and the second and fourth MIDI output device.

In Linux, if you ask for "pd -midioutdev 1" for instance, you get /dev/midi0 or /dev/midi00 (or even /dev/midi). "-midioutdev 45" would be /dev/midi44. In Windows, device number 0 is the "MIDI mapper", which is the default MIDI device you selected from the control panel; counting from one, the device numbers are card numbers as listed by "pd -listdev".

The "sleepgrain" controls how long (in milliseconds) Pd sleeps between periods of computation. This is normally the audio buffer divided by 4, but no less than 0.1 and no more than 5. On most OSes, ingoing and outgoing MIDI is quantized to this value, so if you care about MIDI timing, reduce this to 1 or less.

Multiple audio device selection is similar, except that you can also specify channels by device: "-audioindev 1,3 -inchannels 2,8" will try to open device 1 (2 channels) and device 3 (8 channels). Note that multiple audio device selection is only possible for Linux and Windows, as noted earlier.

3.4.1.4. Sample rate flag

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.1.5. Audio buffer size and block size flags

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.

You can also specify the audio block size in sample frames. This is 64 by default (except for MMIO for which it's 256), and may be 64, 128, or 256.