Chapter 1: Introduction

This is the official HTML manual for Pd (Pure Data), a patchable computer music environment for audio analysis, synthesis and digital signal processing in real time (aka "Live Electronics"). Pd can be extended with third-party libraries for additional computer music features, multimedia capabilities and more. The latest version of this manual is found online on http://msp.ucsd.edu/software.html, along with the downloads of the latest Pd releases.

1.1. Guide to Pd's documentation

Besides this HTML manual, you'll find the 'doc' folder with more documentation resources in Pd's installation folder, which is also accessible through the Help menu. Here's an overview of its structure:

Pd/
├── doc/
    ├── 1.manual/
    ├── 2.control.examples/
    ├── 3.audio.examples/
    ├── 4.data.structures/
    ├── 5.reference/
    ├── 6.externs/
    ├── 7.stuff/
    ├── 8.topics/

• The first subfolder 1.manual includes this HTML manual and consists of 6 sections:
  • This introduction
  • A theory of operations, explaining how Pd works
  • Instructions on installing and configuring Pd
  • Information on managing externals
  • The changelog
  • Instructions on building Pd from source
• Next, there's a series of tutorial patches, starting with 2.control.examples, which serve as an introduction to Pd's "control" structure (as opposed to audio functions which are covered next).
• 3.audio.examples includes a set of examples that are also part of Miller Puckette's book "The Theory and Technique of Electronic Music". The book is freely available online at http://msp.ucsd.edu/techniques.htm.
• 4.data.structures is the last tutorial, giving an introduction to Pd's Data Structures feature, also described in this manual in section 2.10 Data Structures.
• In the 5.reference folder, you find the help patches for all objects.
• The 6.externs folder includes instructions on how to write externals, including sample C code for different use cases. More information on externals is found in Chapter 4: Externals of this manual.
• In the 7.stuff folder, you'll find additional patches to explore.
• The last subfolder 8.topics includes extra documentation with more details on specific topics that is referred in the help files.

1.2. The Help menu

This section describes Pd's Help menu, which offers shortcuts to the documentation and other resources. "Pd Help" opens this HTML manual.

The "Browser..." entry opens Pd's internal file document browser. The "Pure Data" folder shown on top of this file browser points to the 'doc' folder (just explained above) and it's a quick way to navigate and open the manual, particular help files, examples from the tutorials, etc.

In this browser window, you'll also find the "externals" installed on your system. By default, Pd comes with an 'extra' library, so you'll find these externals here even if you have not yet installed anything.

The 'List of objects' entry of the Help menu opens a patch that includes a list of all native objects with brief explanations.

The 'puredata.info' entry opens pure-data.info, an extensive Pd community website that aims to be the central resource for Pd, from downloads to forums, member pages, extra documentation resources and a patch exchange.

The 'check for updates' entry just opens http://msp.ucsd.edu/software.html for you to check if there is a new Pd version for download.

The 'report a bug' entry opens the Pd issue tracker on github, where you can find known bugs and also report them.

The Help menu also allows you to find and download externals with the "Find externals" entry, which opens a Pd extension manager. This is described more detailed in 4.3.2 How to Download Externals from Pd.

1.3. Other resources

The Pd source code is found on github, on the Pd GitHub project page. This project also includes a repository that focuses on Pd's documentation, called pddp (Pure Data Documentation Project). This repository also has an issue tracker for issues related to the documentation.

Most of the interesting news related to Pd show up on the Pd mailing list, maintained by IOhannes zmölnig. To subscribe or browse the archives, visit: https://lists.puredata.info/listinfo/pd-list. This is the best source of recent information regarding installation problems and bugs. It is perfectly reasonable to post "beginner" questions on this list; alternatively you can contact msp@ucsd.edu for help. Many extensions for Pd also get announced on the mailing list.

Other community resources online include the Pd forum, a Pd telegram group, a Facebook group and a Discord channel. Here, you can find many users that can help you with basic instructions and troubleshooting as well as other interactions with the community.

1.4. Other flavors

Pure Data, being an open source project, can be forked into alternative projects that are developed independently. These forks are also known as "different flavors" of Pd. This manual covers the official Pure Data distribution by Miller Puckette, which is also known as the "Vanilla" flavor of Pd, so it's commonly referred to "Pd Vanilla".

Other Pd flavors mainly focus on two things, modifying the GUI to offer more user-friendliness and extending its default features with pre-installed externals. Notably, the PlugData fork also allows you to run Pd as a plugin in any DAW.

A very important and historical flavor of Pd was Pd-extended, which has been discontinued in 2014. This used to come with a vast collection of externals. Many Pure Data tutorials out there are based on this distribution. You can still follow Pd-extended tutorials if you install the necessary libraries, but note that these tutorials are very outdated and don't include many goodies that have been included in Pd Vanilla over the last years, like the [clone] object, [savestate], [file], multichannel connections and many more.

The currently active and main flavors of Pd are presented on the front page of https://puredata.info/. Note that some forks may introduce incompatibilities and not be fully up to date with Pd Vanilla. For forks that are fully compatible, the information in this manual should also apply for the most part.