Pure Data
Pure Data (or PD) is a real-time graphical programming environment for audio, video, and graphical processing. Because all of these types of media are handled as data in the program, many fascinating opportunities for cross-synthesis between them exist. Sound can be used to manipulate video, which could then be streamed over the internet to another computer which might analyze that video and use it to control a motor-driven installation. PD is commonly used for live music performance, VeeJaying, sound effects composition, interfacing with sensors, cameras and robots or even interacting with websites.
The core of Pd is written and maintained by Miller S. Puckette (http://crca.ucsd.edu/~msp/) and includes the work of many developers (http://www.puredata.org/), making the whole package very much a community effort.
The community of users and programmers around PD have created additional functions (called "externals" or "external libraries") which are used for a wide variety of other purposes, such as video processing, the playback and streaming of MP3s or Quicktime video, the manipulation and display of 3-dimensional objects and the modeling of virtual physical objects.
PD runs on Linux, Windows and Mac OS X, and there is a wide range of external libraries available which give PD additional features.
What is real-time graphical programming?
Traditionally, computer programmers used text-based programming languages to write applications. The programmer would write lines of code into a file, and then run it afterwards to see the results. While this way of programming is very efficient for skilled programmers, many sound or visual artists as well as other non-programmers find this a difficult and non-intuitive method of creating things.
Graphical Programming
Pure Data, on the other hand, is a graphical programming environment. What this means is that the lines of code, which describe the functions of a program and how they interact, have been replaced with visual objects which can be manipulated on-screen. Users of Pure Data can create new programs (patches) by placing functions (objects) on the screen. They can change the way these objects behave by sending them messages and by connecting them together in different ways by drawing lines between them.
This visual metaphor borrows much from the history of 20th Century electronic music, where sounds were created and transformed by small electronic devices which were connected together via patch cables.
The sounds that were heard were the result of the types of devices the composer used and the way in which she or he connected them together. Nowadays, much of this electronic hardware has been replaced by computer software capable of making the same sounds, and many more.
Real Time
The real advantage of Pure Data is that it works in "real-time". That means that changes can be made in the program even as it is running, and the user can see or hear the results immediately. This makes it a powerful tool for artists who would like to make sound or video in a live performance situation.
Installing on Mac OS X
Software name : Pure Data Extended
Homepage : http://puredata.info
Software version used for this installation : Pd-Extended 0.39.3
Operating System use for this installation : Mac OS 10.4.11
Recommended Hardware : Any Mac running OS X
To begin the installation visit the download page for Pure Data ( http://puredata.info/downloads ) :
You can download either Miller Puckette's version of Pure Data, or Pure Data Extended. Miller's version of Pure Data is called "pd-vanilla" because it does not contain any external libraries or any of the features developed by the Pure Data community which are included in Pure Data Extended. We will use Pure Data Extended for this manual, so chose your installer from the "pd-extended" section of this webpage.
Since there is not a "Universal Installer" for Pure Data Extended, you will want to select the Mac OS X installer that best suits your computer. Use the one labelled "Mac OS X 10.4 i386" for the newer, Intel-processor equipped Mac computers running Mac OS 10.4. Use the "Mac OS X 10.4 PowerPC" installer if you have a Powermac or PowerBook with a G4 or G5 processor running Mac OS 10.4 "Tiger", and use the "Mac OS X 10.3" installer if you are still running "Panther" or an even older version of Mac OS X.
Once you've downloaded the right installer, you'll have a .dmg (Disk Image) on your harddrive.
Double click to open and mount it, and you will have a chance to read and accept the License Agreement.
Once you click "Agree", the Disk Image will mount and automatically open. Then simply drag the Pd-extended.app to the provided shortcut to your Applications folder (or to another location of your choice.) This will copy Pd-extended to your harddrive.
After that, make sure to check the "ReadMe" file for important installation information.
As indicated, the Pd-extended.app is setup by default to load most of the included external libraries. If you want to change the libraries which are loaded at startup time, or any of the other startup settings, please notice the instructions here in the "ReadMe", and be sure to read the chapter "Configuring Pure Data" in this manual.
From here, you can open up your "Applications" folder in the Finder, and start PD by clicking the "Pd-extended.app" icon found there.
Installing on Microsoft Windows
Software name : Pure Data Extended
Homepage : http://puredata.info
Software version used for this installation : Pd-Extended 0.39-3
Operating System use for this installation : Microsoft Windows (XP)
Recommended Hardware : 300 Mhz processor (CPU) minimum
To begin the installation visit the download page for Pure Data ( http://puredata.info/downloads ) :
You can download either Miller Puckette's version of Pure Data, or Pure Data Extended. Miller's version of Pure Data is called "pd-vanilla" because it does not contain any external libraries or any of the features developed by the Pure Data community which are included in Pure Data Extended. We will use Pure Data Extended for this manual, so chose your installer from the "pd-extended" section of this webpage.
In the first group of links under "pd-extended'"click on the link marked "Microsoft Windows (2000/XP/Vista)" and you should see something like this (this example using Firefox) :
Press "OK" and the download should proceed, leaving you (hopefully) with a dialog box that informs you the download is complete. If you are using Firefox then the dialog may look something like this:
Now you can either browse your computer to look for the installer icon which will look something like this :
you can double click on this icon to start the installation process. Alternatively, you may wish to click Open in the download dialog :
If you choose to do it this way then you may see the following window :
if you see this click "OK" and continue. Either of the steps above should put you in the same place, which is this :
now press "Next >" and the installation process will begin. You will see this screen :
This is the standard license page. If you don't agree with the license you can't install the software. So, my recommendation is - click on the green button next to 'I accept the agreement' and then press 'Next >'. You will see the following :
The above assists you in deciding where to install Pure Data Extended. Unless you have a good reason to, leave the default settings as they are. If you have a good reason, and know what you are doing, you can press 'Browse' and choose another place to install Pure Data Extended on your computer. If you decide to change the defaults, or keep them, youy must then press 'Next >' to continue :
The above screen is merely choosing what to call the installation in the Windows 'Start Menu', Just leave it as it is and press 'Next >'.
You really don't want to uncheck the last two boxes as they are necessary for the installation. The first two choices are merely cosmetic and effect the 'shortcut' icons. It doesn't matter if you check these or leave them as they are. When you are ready press 'Next>'.
The above is the summary window. Press 'Install' and the installation will commence. It might take some time depending on how quick your computer is. While you wait the installer will present you with progress bars :
Then when the installation is complete you will see a final screen :
If you click 'Finish' your browser will open the (rather unattractive) Read Me page :
It is rather uncompelling material but it does have one useful hint...
"To make sure that all of the included libraries are loaded when Pd runs, double-click C:\Program Files\pd\pd-settings.reg"
This is rather important, so you need to open the 'Program Files' in your file browser. Usually you can right-click on the Windows Start Menu to open a file browser :
Then you will see something like this:
Double-click on 'Program Files' and the the directory called 'pd', in this window you should see a file called 'pd-settings':
Double-click on this file and you will see the following :
Press 'Yes' :
Then press 'OK' and that window will disappear. Now you probably want to actually open Pure Data. Click on the Windows Start Menu and slide across to 'All Programs' and 'Pure Data', then finally again to the 'Pure Data' icon :
Release the mouse button and Pure Data should open :
Installing Pure Data on Ubuntu
Software name : Pure Data Extended
Homepage : http://puredata.info
Software version used for this installation : Pd-Extended 0.39-3
Operating System use for this installation : Ubuntu 8.04 (tested also on 7.10)
Recommended Hardware : 300 Mhz processor (CPU) minimum
Installation on Ubuntu Gutsy (7.10) and Ubuntu Hardy (8.04) is the same process. It is made a little tricky because Pure Data Extended requires some software that is not normally part of these operating systems but is included in an older version of Ubuntu. So we must indulge a short work around to get Pure Data Extended working correctly. Thankfully it is quick and simple.
Installing libflac7 and libjasper
Pure Data Extended requires two software 'libraries' from an older version of Ubuntu - libflac7 and libjasper
To prepare Ubuntu to install them when you install Pure Data Extended, you first need to open the Synaptic Package Manager :
You will be asked for a password. Enter in your adminstrator password (not your user password) and you will see Synaptic open.
Now we need to add the older software repositories too install these 2 software libraries. Click on Settings and then Repositories and you will see the Synaptic Repository Manager :
Now click on the second tab entitled Third-Party Software. It is here that you will now need to enter information about these two repositories:
deb http://archive.ubuntu.com/ubuntu/ feisty main restricted
deb-src http://archive.ubuntu.com/ubuntu/ feisty main restricted
You need to add them one at a time by clicking on + Add and typing one of the above lines into the text field provided and then press Add Source. Then do the same for the next line.
Now close the repository manager window and you will be asked to reload the repository information because it has changed. This can be done by pushing the blue Reload button on the Synaptic interface. Then quit the Synaptic Package Manager.
Installing Pure Data
Now download the Pure Data Extended package. Visit the download page ( http://puredata.info/downloads ) :
You can download either Miller Puckette's version of Pure Data, or Pure Data Extended. Miller's version of Pure Data is called "pd-vanilla" because it does not contain any external libraries or any of the features developed by the Pure Data community which are included in Pure Data Extended. We will use Pure Data Extended for this manual, so chose your installer from the "pd-extended" section of this webpage.
In the very first section click on the link "Debian and Ubuntu (intel i386 processor)", this will forward you to a download page. Don't do anything else, the download should start automatically. When the file has downloaded browse to the files and right click on it and choose 'Open with "GDebi Package Installer"'
The package installer will open :
Now press Install Package - you will be asked to enter your password, and then Pure Data Extended will be installed. When the process is finished close GDebi and open Pure Data Extended:
Now it is important to open the Synaptic Package Manager again and disable the two new repositories so they don't cause issues with future software installations.
Installing Pure Data on Debian
Software name : Pure Data Extended
Homepage : http://puredata.info
Software version used for this installation : Pd-Extended 0.39-3
Operating System use for this installation : Debian Linux (4.0 rc3 stable)
Recommended Hardware : 300 Mhz processor (CPU) minimum
To install Pure Data Extended, first visit the download page ( http://puredata.info/downloads ) :
In the very first section click on the link "Debian and Ubuntu (intel i386 processor)", this will forward you to a download page. Don't do anything else, the download should start automatically. If you used the default Debian web browser (Ice Weasel) you will see the following :
Don't use the archive manager, instead choose 'Save to Disk' and press 'OK'. When your file has downloaded you must browse to it. The default download location is the Desktop, on my Desktop I see this :
Right-click on this icon and choose 'Open with "GDebi Package Installer"':
This will show something like this :
This is the general package (software) installer for Debian. Just click "Install Package" and you will be asked for the administrator ('root') password for your computer :
Enter the password and the installation process will start :
When the process has completed just open a terminal :
Type in the terminal 'pd' and press return :
and now Pure Data should appear :
Configuring Pure Data
Pd-Extended has done a lot to make installing and setting up Pure Data easier than ever before. But every computer system is different, and each Pd user will have different needs. This section shows how to configure the most basic parts of Pd, including the soundcard and MIDI devices, as well as some advanced configuration options for those wishing to customize their installation.
Basic Configuration
The first thing we'll want to do once Pd is running is make sure that the audio is configured correctly. This includes choosing the correct drivers, the correct soundcard and the proper latency for your system to be both responsive and glitch-free. Also, if you have any MIDI devices (such as keyboards or fader boxes), you can set Pd up to use those as well. After that, you can test the audio and MIDI to make sure it is working properly.
Audio drivers
Pd can use a variety of audio
drivers to connect to the soundcard. So our first step is to chose the correct ones. This can be done via the
"Media" menu:
OSX : Media -> portaudio/jack
Linux : Media -> OSS/ALSA/jack
Windows : Media -> ASIO (via portaudio)
This part of the menu should list the available audio drivers on your system, and allow you to switch between them. The drivers you have depend on your operating system, and what drivers you have installed on that operating system. Keep in mind you may not have all of these installed on your computer:
Linux
OS X
Windows
Linux users are encouraged to investigate JACK (Jack Audio Connection Kit), an audio server which allows different audio applications to be connected with virtual "cables" in your computer. JACK, and it's Graphical User Interface QJackctl, should be available from whatever Linux distribution you happen to be running.
Many OS X users have also reported that audio runs smoother and with less CPU load when using JackOSX, an implementation of the JACK server and user interface for the Mac OS. JackOSX can be found at http://jackosx.com/
And Windows users may find configuring their ASIO soundcards much easier by using ASIO4ALL, which can be downloaded from http://www.asio4all.com/
MIDI drivers (Linux only)
Linux : Media -> default-MIDI/ALSA-MIDI
This menu which allows you to switch between the built-in Pd MIDI drivers and the ALSA MIDI drivers, if they are installed. If the ALSA MIDI drivers are used, then JACK users can use the QJackctl application (available in most Linux distributions) to connect external MIDI devices and other MIDI applications running on the same computer to Pd.
Audio Settings
OSX : Pd-extended -> Preferences -> Audio Settings
Linux & Windows : Media -> Audio Settings
This is one of the most important configuration menus in Pd. Here you can change the sample rate, delay, input and output devices as well as the number of channels they use.
Sample rate
The sampling rate for CD quality audio is 44,100 Hz. Most computer soundcards run at this sampling rate, or at 48,000 Hz, by default. Choose the rate that matches the rate of your soundcard or audio drivers here.
Delay (msec)
Your computer needs a certain amount of time to process all the information coming out of Pd and send it to the soundcard for playback. Likewise, when you are recording, Pd needs a certain amount of time to gather all the information coming from the soundcard. The term for this delay is called latency, and it measures the amount of time between the moment when you tell Pd to do something (for example by playing a note on a keyboard), and when you hear the result of that action. A shorter latency means you will hear the results quicker, giving the impression of a more responsive system which musicians tend to appreciate. However, with a shorter latency you run a greater risk of getting an interruption or 'glitch' in the audio. This is because the computer does not have enough time to "think about" the sound before sending it to the soundcard. A longer latency means less chances of glitches, but at the cost of a slower response time. It is up to you to find the best balance for your own needs, but the default latency in Pd is 50 milliseconds. You can increase or decrease the latency of Pd by entering a value in milliseconds in this box.
Input Device
Choose the soundcard you wish to use with Pd and the number of channels you want to use. In the case of a normal, stereo soundcard you would enter the number 2. For a multichannel soundcard, you may choose some or all of the channels. Make sure this is checked if you would like to record sound into Pd.
Output Device
Choose the same soundcard as you selected for the Input Device, and a matching number of channels as you selected for the Input Device as well. Although it may be possible to use different soundcards and unmatched numbers of channels for input and output on some systems, this can also cause problems for Pd, so experiment first. Make sure the checkbox next to the device is checked.
MIDI Settings
OSX : Pd -extended -> Preferences -> MIDI Settings
Linux & Windows : Media -> MIDI Settings
On Linux, you have a choice of using the built-in MIDI drivers, or the ALSA-MIDI drivers if they are installed. If you are using the built-in drivers, you should be able to choose which devices to Pd will send and receive MIDI messages with. You may also select "use multiple devices" if you have several applications or devices using MIDI. This method is rather complex, because you must set up the devices by number using your startup flags and you will not be able to change them while Pd is running. Using the ALSA-MIDI drivers is easier to manage, and therefore recommended.
When using the ALSA MIDI drivers on Linux, you can tell Pd the number of In and Out Ports to use here. These are connections which other MIDI applications or devices can use to connect to and from Pd. To connect devices or applications, you can use ALSA MIDI with the JACK audio drivers and the Qjackctl if you have them installed. In Qjackctl, you will see a tab for MIDI, and be able to connect the inputs and outputs of MIDI devices and applications by clicking on them.
On Mac OS X, to use MIDI you must first open the "Audio MIDI Setup.app", which is located in your Applications/Utilities folder. Once this application is open, and you have connected your external MIDI devices (if any), you should be able to see your MIDI devices in this window. Minimize the "Audio MIDI Setup.app" and return to Pd and this "MIDI Settings" menu. Now you will be able to choose which devices with which Pd will send and receive MIDI messages. You may also select "use multiple devices" if you have several applications or devices using MIDI.
Test Audio and MIDI
OSX, Linux & Windows : Media -> Test Audio and MIDI
To make sure that you've configured your audio and MIDI correctly, Pd includes a patch to test your setup. If you open "Test Audio and MIDI", you will see this window:
First, click one of the radio buttons marked either "-20" or "-40" under "TEST SIGNAL". If your audio is set up correctly, you will hear a test tone and you will see some of the number boxes above "AUDIO INPUT" changing to measure any incoming audio signal from the line in or microphone of your computer. If you have any external MIDI devices or a piece of MIDI software connected to Pd, you can test the connection by sending MIDI data to Pd and watching to see if the number boxes connected to [notein] and [ctlin] change.
Advanced Configuration
Since Pd-Extended is installed with most of the settings, search paths and external libraries already configured, many users won't have to worry about configuring these parts of Pure Data at all. Advanced users, however, may be interested in customizing these settings. The settings which can be changed in Pure Data are the same as those available when starting from the command line:
audio configuration flags:
-r <n> -- specify sample rate
-audioindev ... -- audio in devices; e.g., "1,3" for first and third
-audiooutdev ... -- audio out devices (same)
-audiodev ... -- specify input and output together
-inchannels ... -- audio input channels (by device, like "2" or "16,8")
-outchannels ... -- number of audio out channels (same)
-channels ... -- specify both input and output channels
-audiobuf <n> -- specify size of audio 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)
-listdev -- list audio and MIDI devices
-oss -- use OSS audio API
-32bit ----- allow 32 bit OSS audio (for RME Hammerfall)
-alsa -- use ALSA audio API
-alsaadd <name> -- add an ALSA device name to list
-jack -- use JACK audio API
-pa -- use Portaudio API
-asio -- use ASIO drivers and API
-mmio -- use MMIO drivers and API
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
-nomidiin -- suppress MIDI input
-nomidiout -- suppress MIDI output
-nomidi -- suppress MIDI input and output
-alsamidi -- use ALSA midi API
other 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)
-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
-version -- don't run Pd; just print out which version it is
-d <n> -- specify debug level
-noloadbang -- suppress all loadbangs
-stderr -- send printout to standard error instead of GUI
-nogui -- suppress starting the GUI
-guiport <n> -- connect to pre-existing GUI over port <n>
-guicmd "cmd..." -- start alternatve GUI program (e.g., remote via ssh)
-send "msg..." -- send a message at startup, after patches are loaded
-noprefs -- suppress loading preferences on startup
-rt or -realtime -- use real-time priority
-nrt -- don't use real-time priority
-nosleep -- spin, don't sleep (may lower latency on multi-CPUs)
All of the Audio and MIDI configuration flags in this list are set using the menus described above. Note that not all settings are available on all platforms (for example, there are no -asio or -mme options on Mac OS X or Linux, nor the -alsa, -oss, -pa or -jack settings on Windows, etc...)
The next most-important configuration options have to do with the external libraries which Pd loads at startup time (and thus which objects you will be able to use), as well as the locations in your file system where Pd can search for these externals and for other resources the program uses to run.
Pure Data uses a system called pdsettings to store all these options and use them every time Pd starts up. The
We'll start by looking at the built-in menus for Startup and Path, and then we'll look at other methods to change the configuration options.
Startup Flags
OSX : Pd-extended -> Preferences -> Startup
Linux & Windows : File -> Startup
The things we want to pay attention to in this menu are the externals we load, which are listed as "Pd binaries to load (on next startup)", and whether or not we "defeat real-time scheduling".
Under "Pd binaries to load", you can make a list of the external libraries which you have installed on your system which you would like to be available in Pd. You will then be able to run these externals the next time you start Pd. Because you are using the Pd-extended distribution, this section should be completed for you with a list of the externals which come with the distribution.
If you would like to add more libraries to the ones listed, the simplest way is to add them to an existing line of the Startup menu, like so:
Gem:my_new_lib
And then click "Save all settings" and "OK". However, Pd-Extended is still a program which is under development, and this method has been noted to have some problems lately, so you may wish to try the Platform-Specific Configuration Tools below.
If you are running Pd on Linux, you may want to experiment with using "real-time scheduling" to improve the audio quality by allowing Pd faster access to the soundcard. On some systems, however, you must run Pd as the administrator of the system (i.e. "root" or "su") to have permission to do this. To use "real-time scheduling", enter the following in your "startup flags"
-rt
But keep in mind that if Pd overloads or locks up your system by using too much of the processer's resources, it can be very difficult to quit the program when using "real-time scheduling".
Users on Mac OS X should not use the "real-time scheduling" flag, and should click the box which says "defeat real-time scheduling" for better audio quality.
Path
OSX : Pd-extended -> Preferences -> Path
Linux & Windows : File -> Path
Shown here is the Mac OS X menu for setting the Paths. These are the Search Paths that Pd will use to locate external libraries, help patches, and other any patches, fonts, soundfiles, videos ar anything else which you may need while working in the program. If you would like to add more directories to the ones listed, the simplest way is to add them to an existing line of the Path menu, like this:
/Library/Pd:/home/my_name/my_new_path
And then click "Save all settings" and "OK". However, as with the Startup menu, some people have had problems using this method, so you may wish to try the Platform-Specific Configuration Tools below.
Quite a bit of this configuration has been taken care of by Pd-Extended already, so let's look at some real-world examples of when you might want to add a path. One situation would be if you want to use an audio file or a collection of audio files in your patch, but you don't want to have to specify the whole location every time it's needed in any object or message.
So, instead of typing
/home/beaver/my_soundfiles/spoken/boy/geewhiz.wav
or
/home/beaver/my_soundfiles/spoken/girl/golly.wav
you could add
/home/beaver/my_soundfiles/spoken
to your Path, and then call these soundfiles by typing:
boy/geewhiz.wav
girl/golly.wav
Another very common situation is when you would like to use a Pd patch you have saved as an abstraction (which essentially treats the saved patch like another Pd object) inside another Pd patch. In this case, you must either have the patch you wish to use as an abstraction saved in the folder as the "parent" patch you wish use it in, or you must add the folder containing the abstraction to your Path. For example the path:
/home/pdfreek/puredata/abstractions/reverb_tools
might contain various kinds of reverb abstractions that the user "pdfreek" created to be reused in other patches. For more information about abstractions, please see the DataFlow Tutorials chapter.
Finally, if you want to compile your own external Pd libraries, or use ones which you have downloaded from the internet, then you need to place the binary files (which end in .pd_linux for Linux, .pd_darwin for OS X and .dll for Windows) in a folder and add that folder to your path, such as:
~/pd/extra
where ~/ means your home directory (i.e. /home/"username" on Linux and /User/"username" on Mac OS X). Please note that in the case of name clashes (where two objects or files have the same name), the one which is loaded last takes precedence over all others. An example of this is the object [counter], which exists in several external libraries, and which has a different function in each one!
Platform-Specific Configuration Tools
The locations for the pdsettings files in Pd are:
OS X: ~/Library/Preferences/org.puredata.pd.plist (~ means your home folder)
Windows: HKEY_LOCAL_MACHINE -> SOFTWARE -> Pd (using REGEDIT.EXE/REGEDIT32.EXE)
Linux
Linux users may edit the file directly via command line applications such as joe, vim, pico or nano, or with whatever other text editing application comes with your distribution:
$ nano /home/derek/.pdsettings
GNU nano 1.2.4 File: /home/derek/.pdsettings
audioapi: 5
noaudioin: False
audioindev1: 0 4
noaudioout: False
audiooutdev1: 0 4
audiobuf: 50
rate: 44100
nomidiin: False
midiindev1: 0
nomidiout: False
midioutdev1: 0
path1: /home/derek/pd/rradical/memento
path2: /home/derek/pd/ix_toxy
path3: /home/derek/pd/berlin
path4: /home/derek/pd/rradical/memento/tutorial
path5: /home/derek/workshop_patches
path6: /usr/local/lib/pd/doc/5.reference
path7: /usr/local/lib/pd/extra/xjimmies
npath: 7
standardpath: 1
verbose: 0
loadlib1: pool
loadlib2: iemlib1
loadlib3: iemlib2
loadlib4: iem_mp3
loadlib5: iem_t3_lib
loadlib6: OSC
loadlib7: zexy
nloadlib: 7
defeatrt: 0
flags: -alsamidi -rt
[ Read 31 lines ]
^G Get Help ^O WriteOut ^R Read File ^Y Prev Page ^K Cut Text ^C Cur Pos
^X Exit ^J Justify ^W Where Is ^V Next Page ^U UnCut Txt ^T To Spell
Remember that if you add a new path or loadlib, then you will need to give it a number higher than the last existing one, and you will need to change the npath or nloadlib to the number of new paths or loadlibs you have added. In the above pdsettings, to add the loadlib pdp, you would have to add/change the following:
loadlib8: pdp
nloadlib: 8
OS X
OS X users may wish to try using the Property List Editor.app, which can be installed from the XCode Tools or Server Tools CDs available for free from Apple:
http://developer.apple.com/tools/xcode/
Here is the Property List Editor, with the org.puredata.pd.plist file open:
You can click directly in the Value field to change a value, or use the New Sibling button to add a new line.
The command line utility defaults can also be used. The following line in the terminal lists all the pdsettings in org.puredata.pd.plist:
defaults read org.puredata.pd
The following command can be used to write a new line to pdsettings:
defaults write org.puredata.pd loadlib30 test
and this command can be used to delete one line from pdsettings:
defaults delete org.puredata.pd loadlib30
In this case, loadlib30 represents the next possible line that could be added to load a library (29 libraries are loaded already), and test represents a hypothetical library which we add to the startup in the first case using the write command, and remove from the startup in the second case by using the delete command. For more information about defaults, type:
defaults --help
Windows
Windows users may also use the REGEDIT program to edit their pdsettings. This program comes with the Windows operating system, and can be located under the name REGEDIT.EXE or REGEDT32.EXE (Windows XP or newer). Please note: manually editing the Windows Registry files using a text editor instead of REGEDIT is generally considered unsafe, since errors here can disrupt the entire operating system! Those interested in more details about the Registry should read:
http://en.wikipedia.org/wiki/Windows_Registry#Editing 
Starting Pure Data
Now that you have Pd-Extended installed on your computer and configured, let's look at different ways to start it--from simply clicking an icon through starting from the command line and adding different startup flags or using a script to save different sets of startup information.
Starting PD with the Clickable Icon
There are two ways of starting Pure Data. The way that will be used most commonly on Windows or Mac OS X will be to click on the icon which the installer put in your "My Programs" or "Applications" folder. On Windows, this is "Start -> Pure Data -> Pure Data".
On Linux, your system may also have a menu bar, such as "Programs/Multimedia" or "Programs/Sound" where Pd can be started by clicking the menu item.
Starting Pd via Command Line
The other way is to open Pd from the terminal or shell via a command line. This is most often done on Linux, but it can be done this way on any platform. To do this, one must know the location of the Pd application on his/her system, which can be different depending on where Pd was installed.
Linux (from xterm)
/usr/local/bin/pd
Mac OSX (from Terminal.app)
/Applications/Pd-extended.app/Contents/Resources/bin/pd
Windows (from the DOS shell or Command Prompt)
C:\Program Files\pd\bin\pd.exe
Why would we want to open Pd by command line? The most common reason would be is if we wanted to use a different set of flags than the default ones. For example, if you were using Pd in a live performance, and you wanted it to open up the same patch whenever you started it in this situation, you might use the command:
/usr/local/bin/pd -open /home/pdfreek/liveset.pd
Which would start Pd and open the patch liveset.pd. You could also add other startup flags, such as which soundcard and drivers to use, which external libraries to load or which search paths to add. Flags are additional pieces of information which can alter the configuration of Pd for that particular startup, rather than the pdsettings which we looked at in the ConfiguringPD chapter, which affect the program every time it starts.
Like almost any program launched by command line, you can add the flag "--help" to see a long list of configuration options, which gives you some idea of the different possibilities for starting up Pd:
$ /Applications/Pd-0.39.2-extended-test4.app/Contents/Resources/bin/pd --help
usage: pd [-flags] [file]...
audio configuration flags:
-r <n> -- specify sample rate
-audioindev ... -- audio in devices; e.g., "1,3" for first and third
-audiooutdev ... -- audio out devices (same)
-audiodev ... -- specify input and output together
-inchannels ... -- audio input channels (by device, like "2" or "16,8")
-outchannels ... -- number of audio out channels (same)
-channels ... -- specify both input and output channels
-audiobuf <n> -- specify size of audio 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)
-listdev -- list audio and MIDI devices
-jack -- use JACK audio API
-pa -- use Portaudio API
(default audio API for this platform: portaudio)
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
-nomidiin -- suppress MIDI input
-nomidiout -- suppress MIDI output
-nomidi -- suppress MIDI input and output
other 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)
-font <n> -- specify default font size in points
-typeface <name> -- specify default font (default: courier)
-verbose -- extra printout on startup and when searching for files
-version -- don't run Pd; just print out which version it is
-d <n> -- specify debug level
-noloadbang -- suppress all loadbangs
-stderr -- send printout to standard error instead of GUI
-nogui -- suppress starting the GUI
-guiport <n> -- connect to pre-existing GUI over port <n>
-guicmd "cmd..." -- start alternatve GUI program (e.g., remote via ssh)
-send "msg..." -- send a message at startup, after patches are loaded
-rt or -realtime -- use real-time priority
-nrt -- don't use real-time priority
To learn more about Pd's startup options, please see the ConfiguringPD chapter.
Starting Pd from a Script
Once you have created a command line for your specific situation, you can save that command as a script, which is a short file containing a list of commands, which can be run by typing its name in the terminal or shell. The exact format of your script depends on which operating system you use.
Windows
Windows uses the DOS language for its commands, so we must create a .bat (DOS batch) file containing the location of the Pd program and the startup flags we want to use. Using a simple text editor, make a file named "pdstart.bat", and place the following in it, for example
"c:\pd\bin\pd.exe" -font 10 -path "c:\pd\doc\vasp" -lib cyclone -lib iem_t3_lib -lib iem_mp3 -lib mjLib -lib OSC -lib percolate -lib vasp -lib xeq -lib xsample -lib zexy -lib iemlib1 -lib iemlib2 -listdev %1 %2 %3 %4 %5 %6 %7 %8 %9
Though it may appear to be many lines, this command must in fact be one long line with no breaks. If the version of Windows you are running has a "Save as type" option, choose the type "All files" to prevent your .bat file from being saved as a text file. Once this is saved, you can double-click on the file to run it.
Linux and OS X
Since both Linux and OS X use the same Unix-type system to interpret and run command lines, the process for creating a script is the same for both. In your favorite text editor, create a new file and start it with the line:
#! /bin/bash
which tells the operating system that what it is reading is a script, and that it will use the bash command line interpreter. On the line below that, copy this or a similar line:
/usr/local/lib/pd -font 10 -path /home/pdfreek/pd/my_abstractions -lib cyclone -lib iem_t3_lib -lib iem_mp3 -lib mjLib -lib OSC -lib percolate -lib vasp -lib xeq -lib xsample -lib zexy -lib iemlib1 -lib iemlib2 -open /home/pdfreek/pd/liveset3.pd
This should be all in one line, with no breaks. Please note that you should give it the correct path to the Pd program in the beginning (which could be different if you are running OS X for example), and you should replace the example flags with ones of your own.
Once you have written and saved this file with the .sh (shell script) file extension, such as "start_pd.sh", you must make it executable as a script with the following command:
chmod +x start_pd.sh
After you have done this, you can start this script, which will run Pd with all the flags you have added to it, by typing:
sh start_pd.sh
Some Linux window managers such as KDE or Gnome may support double-clicking to start shell scripts either by default or by selecting the default application. On OS X, you could configure the Finder to open .sh files with the Terminal.app by default (but then you would have to manually chose to open them with TextEdit.app for editing later on).
Advanced Scripting for Starting Pd
One of the beautiful things about the Unix system, which both Linux and OS X are based on, is that it is designed to allow many applications to communicate with each other and work together. This means that shell scripts can be constructed to do an enormous amount of tasks.
For example, the following script for Linux starts the JACK audio server (with some flags of its own), opens the Qjackctl interface for JACK and then starts Pd with the -jack flag and the -open flag listing two specific files:
#! /bin/bash
jackd -d alsa -d hw -r 44100 -p 1024 -s &
/usr/bin/qjackctl & sleep 5 ; /usr/local/bin/pd -jack -open /home/derek/pd/delnet/delaynet.pd:/home/derek/pd/echoplex_footswitches/midiswitches.pd
The ampersand (&) between the commands means that the command preceeding it will be run in the background. In other words, the previosu command will keep running while we execute the next ones, instead of quitting. The section "sleep 5" tells the shell to wait 5 seconds before running the next command, in this case in order to give JACK time to start up. The semicolon (;) is used to seperate jobs, meaning that the next command won't be run until the previous one is finished (in the case of "sleep 5") or sent to the background (in the case of the ampersand symbol).
This script could be expanded to open other applications (in the following case, the looping application SooperLooper), use the aconnect application to make ALSA MIDI connections from Pd to SooperLooper, and use the jack_connect command to make audio connections between Pd, SooperLooper and 6 channels of a sound card via the JACK audio server:
#! /bin/bash
jackd -d alsa -d hw -r 44100 -p 1024 -s &
/usr/bin/qjackctl & sleep 5 ; /usr/local/bin/pd -jack -open /home/derek/pd/delnet/delaynet.pd:/home/derek/pd/echoplex_footswitches/midiswitches.pd & sleep 5 ; /usr/local/bin/sooperlooper -L /home/derek/pd/echoplex_footswitches/3loops.slsess -m /home/derek/pd/echoplex_footswitches/3loops.slb & sleep 5 ; /usr/local/bin/slgui & sleep 5 ; aconnect 'Pure Data':1 'sooperlooper_1':0 ; jack_connect alsa_pcm:capture_1 sooperlooper_1:common_in_1 ; jack_connect alsa_pcm:capture_2 sooperlooper_1:common_in_2 ; jack_disconnect alsa_pcm:capture_1 pure_data_0:input0 ; jack_disconnect alsa_pcm:capture_2 pure_data_0:input1 ; jack_disconnect alsa_pcm:capture_3 pure_data_0:input2 ; jack_disconnect alsa_pcm:capture_4 pure_data_0:input3 ; jack_connect alsa_pcm:capture_3 pure_data_0:input0 ; jack_disconnect pure_data_0:output0 alsa_pcm:playback_1 ; jack_disconnect pure_data_0:output1 alsa_pcm:playback_2 ; jack_disconnect pure_data_0:output2 alsa_pcm:playback_3 ; jack_disconnect pure_data_0:output3 alsa_pcm:playback_4 ; jack_connect pure_data_0:output0 alsa_pcm:playback_7 ; jack_connect pure_data_0:output1 alsa_pcm:playback_8 ; jack_connect sooperlooper_1:loop0_out_1 alsa_pcm:playback_1 ; jack_connect sooperlooper_1:loop0_out_2 alsa_pcm:playback_2 ; jack_connect sooperlooper_1:loop1_out_1 alsa_pcm:playback_3 ; jack_connect sooperlooper_1:loop1_out_2 alsa_pcm:playback_4 ; jack_connect sooperlooper_1:loop2_out_1 alsa_pcm:playback_5 ; jack_connect sooperlooper_1:loop2_out_2 alsa_pcm:playback_6
Detailed syntax for aconnect and jack_connect can be found by typing:
aconnect --help
or
jack_connect --help
Bash shell scripting is a huge area to investigate, curious readers are encouraged to check out one of the many websites and books detailing the Bash environment.
The Interface
The main PD window
Now that we have PD configured and your audio and MIDI are working, let's have a look at the rest of the main PD window.
As of PD 0.39, all of the messages that PD produces are sent to the main PD window (before this, they were sent to the shell which was running PD). When you start PD, this main PD window should tell you important information, such as the externals you are loading and whether any errors occurred while loading them, as well as any errors connecting to the soundcard. Later, you will also use this main PD window to see information about the patch you are working on, as well as for debugging (correcting errors in your patch). So keep this window in a place where you can find it on your screen.
There are a few other important features about this main PD window. It has audio level indicators, so you can can a general idea of the loudness of the sound that you are sending to the soundcard. If this level goes to 100 or higher, you are sending to high a level and you will hear a distorted sound. The boxes marked "Clip" will also flash red. To use the audio level meters, check the box that says "peak meters" in the main PD window.
There is also a box marked "compute audio", which you can use to turn on and off audio processing. When you open the "Test Audio and MIDI" patch, PD will automatically turn audio processing on for you.
Last is a box marked "DIO". This stands for Digital In Out errors, and this box should flash red when PD has difficulties sending data to your sound card. If you click this box, PD will print a list of times when these DIO errors occurred in the main PD window.
The last thing to pay attention to is the "Help" menu. Under this drop-down menu, you can open the official PD manual, written by Miller S. Puckette in "HTML" format, which can be viewed in your web browser. You can also open a file "Browser", which will list the built-in help patches which come with PD. All of these documents are valuable resources, however many newcomers to PD can find them confusing. We will cover some of these basics in the "Dataflow", "Audio" and "Patching Strategies" tutorials in this manual, after which you can return to the built-in help files with a bit better understanding.
Starting a New Patch
Under the "File" menu in the main PD window, create a "New" PD patch. It should look something like this:
Unlike other software for creating audio or video media, such as
Ableton Live,
CuBase or
Final Cut Pro, where a new file shows you a variety of buttons, menus and timelines, PD gives you a blank, white space. Within that white space, you can make a synthesizer or video mixer, translate sensor input into the movements of a robot or stream movies to the internet, for example. The difference between PD and software like Live is that it doesn't start with any preconceived ideas about
how to make your artwork. Where Live provides you with a set of tools suited primarily for the production of loop-driven dance music, PD acts more like a text editor where anything is possible, so long as you know how to write it. It is this kind of possibility and freedom that attracts many artists to using PD.
To explore these possibilities, you must understand PD as being a written language like German or Chinese. As in any language, PD has a vocabulary (the words used in the language) and a grammar (the way to put these words together so that they make sense). And like learning any language, you first have to learn how to say simple things like "What is your name?" before you can write poetry! So let's start simple.
You will notice that once we have opened a new PD patch, there are a few new menu items to choose from. The "Edit" menu has all the kinds of functions you would expect from a text editor like
Notepad,
TextEdit,
OpenOffice or
Word, such as "Cut", "Paste", "Duplicate", "Select All", etc etc.
There is also a "Put" menu, containing a list of the kinds of things you will be putting in your patch, such as "Object", "Message", "Number", "Symbol", "Comment" and a range of GUI (Graphical User Interface) elements such as "Bang", "Toggle", "Slider", etc.
Interface Differences in Pure Data
While the main functionality of Pure Data doesn't change between operating systems, the locations and contents of some of the menus do. Depending on the system you are running, you will be able to do the following:
Linux
From the "File" menu, you can:
1) Create a "New" PD patch
2) "Open" a PD patch which is saved on your computer
3) Send a "Message" to the running PD application
4) Set the search "Path" which PD uses
5) Change the "Startup" flags which PD uses
6) "Quit" PD
From the "Find" menu, you can:
1) "Find last error" which occurred in the program
From the "Windows" menu, you can:
Change between the different open PD patches
From the "Media" menu, you can:
1) Turn audio "ON" and "OFF"
2) Change between the different available audio drivers
3) Change between the different available MIDI drivers
4) Change the "Audio Settings"
5) Change the "MIDI Settings"
6) "Test Audio and MIDI"
7) View the CPU "Load Meter"
And from the "Help" menu, you can:
1) Read information "About PD"
3) Open a "Browser" to see some help patches which are included in PD
Mac OS X
From the "Pd" menu (which should contain the version number as well), you can:
1) Read information "About PD"
2) Change the following "Preferences":
A) Set the search "Path" which PD uses
B) Change the "Startup" flags which PD uses
C) Change the "Audio Settings"
D) Change the "MIDI Settings"
3) "Quit" PD
From the "File" menu, you can:
1) Create a "New" PD patch
2) "Open" a PD patch which is saved on your computer
3) Send a "Message" to the running PD application
4) "Quit" PD
From the "Find" menu, you can:
1) "Find last error" which occurred in the program
From the "Media" menu, you can:
1) Turn audio "ON" and "OFF"
2) Change the "Audio Settings"
3) Change the "MIDI Settings"
4) "Test Audio and MIDI"
5) View the CPU "Load Meter
From the "Windows" menu, you can:
Change between the different open PD patches
And from the "Help" menu, you can:
1) View the author's documentation as an HTML file
2) Open a "Browser" to see some help patches which are included in PD
Placing, Connecting and Moving Objects in the Patch
Use the "Put" menu to place an "Object" in your patch. Click on the patch to drop the object in its place. You will see a box made of a broken blue line, with a flashing cursor inside indicating that you should type something there.
Objects are the "vocabulary" of PD. The more names of objects you know, the more complicated things you can do with PD. If you type the word "print" inside this object and click again outside the box, you will create the [print] object. If you right-click (or use the Control key and click on OS X), you will have the option to open the help file for that object. This is something like the "dictionary entry" for the object, and should define what it does and also show several examples of its use.
Return to the "Put" menu, and this time place a "Number" in your patch. Notice that the shape of the number box is different from the shape of the object box.
You should also notice that both the object and the number boxes have small rectangles at the corners. If these are at the top of the object, they are called "inlets", and at the bottom they are called "outlets". When you are working on your patch, your cursor is shaped like a pointing finger. If you put that finger over an outlet, it changes into a black circle which indicates that the outlet is selected.
Select the outlet of the the number box, click and drag that black circle until it reaches the inlet at the top of the [print] object. When you have done that, you will see the cursor change from the pointing finger to the black circle again. If let go of the mouse button now, you will make a connection from the outlet of the number box to the inlet of [print]. If you want to remove this connection, place your cursor over the connection until you see a black X and then click. The connection will turn blue and you can remove it with the Backspace or Delete key on your keyboard.
If you click on the patch away from the number box and [print] object and drag, you can draw a box which selects them. You will see they are selected because they will turn blue. Single objects can be selected by clicking once on them.
Once the objects on screen are selected, you can:
- Move them by dragging them with the mouse
- Move them in small increments with the Arrow keys
- Move them in larger increments with the Shift and Arrow keys
- Delete them with the Backspace or Delete keys
- Copy them by using the Control and C keys (Apple and C keys on OS X) or the Copy menu item under Edit
- Cut them by using the Control and X keys (Apple and X keys on OS X) or the Cut menu item under Edit
- Once Cut or Copied, you can Paste them with the Control and V keys (Apple and V keys on OS X) or the Paste menu item under Edit
- You can also Duplicate the selected items with the Control and D keys (Apple and D keys on OS X) or the Duplicate menu item under Edit
It is recommended to use the duplicate function rather than the paste function, because pasted objects are placed directly on top of the previous object, making it difficult to see them. Duplicated objects are placed to the lower right side of the original, making them easier to find and move.
Pasted or duplicated objects are automatically selected together, so you can grab ahold of them and move them immediately after placing them in the patch.
Edit Mode and Play Mode
So far we've been able to put objects in the patch, connect them, move them around or delete them. But how does one get some results from this patch? In this case, we have connected a number box to a [print] object, which should print the numbers we send to it in the main PD window.
To make this happen, we need to change out of "Edit Mode" and into "Play Mode". You can do this by clicking on the "Edit Mode" item in the Edit menu, or by using the Control and E keys (Apple and E keys on OS X).
When you do this, you will see that the pointing finger cursor changes into an arrow cursor.
If you click and drag inside the Number object now, you can change the numbers inside of it. Any changed number is sent to the outlet, which then goes on to the inlet of the [print] object, and the number is printed to the main PD window.
If you click once on the number box in Play Mode, you can also use your keyboard to change the value, and the Enter key to send the value to the outlet. If you hold the Shift key while using the mouse to change the number, you will have decimal numbers. Using the Alt key plus a mouseclick will toggle the Number box between 0 and 1.
If you would like to make any changes to this patch, you can use the "Edit Mode" menu item, or the key combination Control (or Apple) and E to change back and forth between Edit and Play modes. Note that you are automatically placed in Edit Mode whenever you add any new item from the "Put" menu to your patch.
Messages, Symbols and Comments
The "Message" box is used to store and send information to other objects, and can contain numbers or text. It also has a unique shape, which resembles an envelope like you would use to send a letter. Place two different messages above the number box in our exercise. Like the object, messages also give a flashing cursor indicating that you should enter some information when you create them. Enter "2" in one of the messages and "4" in the other, and connect both to your number box. Switch to Play Mode and click on each of the messages. When you do, you will see that the number box changes according to the message that you send it, and that the message is also sent onwards to the [print] object.
You can also send numbers and other information to the message box. Create a message with the text "$1 is a beautiful number", and connect it to the [print] object. Then connect a Number to the inlet of the message, and in Play Mode change the value of the number. You will see in the main PD window that whatever number you send to this message replaces the $1. This is because $1 is a "variable", and will take the value of whatever you send to it. This is important because different objects need to be sent different messages in order to do things. We will look at more uses for messages and variables later in the Dataflow Tutorial.
A "symbol" is another way of storing and sending information. Once created, you can use it to display the output of some objects, or you can type directly into it and hit Enter to send the text out. Please note that no spaces will appear in the symbol box when you type into it, since separate words would be considered separate symbols.
A "comment" is simply a way of making a note to yourself so that you (or someone else) can understand what you were trying to do later on. You can make as few or as many as you want, and they have no effect on the patch itself.
GUI Objects
PD has a number of GUI objects you can use to graphically control your patch and to improve its visual appearance. These are:
- Bang: this GUI object sends a Message named "Bang" every time it is clicked. "Bang" is a special message, which many Objects interpret as "do an action right now!". Using the Bang GUI object is the same as creating a Message box with the word Bang in it. The Bang GUI object can also be used to receive and display Bang messages. For more information on this, see the "Counter" chapter in the Dataflow Tutorial.
- Toggle: when clicked, the Toggle sends out one of two values--a zero when it is unchecked and a non-zero number when it is checked. The non-zero number is 1 by default, however this can be changed in the "Properties". The Toggle also has an inlet, which can be used to display whether an incoming number is zero or not.
- Number2: this is almost identical to the Number box, however it has further options in its "Properties", including the ability to save its current value when the patch is saved (by changing the "no init" box to "init"). The Number2 has in anlet which can be used to display incoming numbers as well.
- Vslider and Hslider: these are Vertical and Horizontal sliders which send out their current value when moved with the mouse. The default range of a slider is 0-127, which can be changed in the "Properties". Both sliders have an inlet which can be used to display incoming numbers within the range of the slider.
- Vradio and Hradio: these are Vertical and Horizonal "radio buttons", which send out their current value when one of the buttons in them is clicked with the mouse. The default size of a radio button is 8 buttons, which can be changed in the "Properties". Both radio buttons have an inlet, which can be used to display integer (whole) numbers within the range of the radio buttons.
- VU: a VU meter displays the average volume level of any audio signal which is connected to it in Decibels. You may switch the value scale on the right side on and off in the "Properties".
- Canvas: a canvas is a rectangular area of pixels, whose size and color may be changed under its "Properties". Canvases are useful as backgrounds in your patch to improve its visual appearance and readability. Canvas also can be used as movable GUI objects that gather information about their position (x,y) inside a patcher. Keep in mind that PD remembers the order in which anything is placed in the patch, so if you want your canvas to be behind certain objects, you must either create it first, or you must Select, Cut and Paste the objects you want in the foreground so that they appear in front of the canvas.
GUI Object Properties
If you right-click (or Control and click on OS X) on any GUI object, you will see the "Properties" menu. Here, you can change many aspects of each GUI object, such as its default values, size in pixels or its color. To change colors on Linux and Windows you should see a selection of available colors. On OS X these boxes are empty, so you must click on the "Compose Color" button. You can also add a label to your GUI object as well as set the Send and Receive symbols. For more information on Send and Receive, please see the Send/Receive chapter of the Patching Strategies tutorial.
Arrays and graphs
An "array" is a way of graphically saving and manipulating numbers. It works in an X/Y format, meaning you can ask the table for a value by sending it a value representing a location on the X (horizontal) axis, and it will return the value of that position value on the Y axis.
To create an Array, use the "Put" menu. When the new array is created, you will see two menus where you can change the properties of the array.
In the "canvas" properties menu, you can set the "X range" and "Y range", which represent the length in units of each axis, as well as the visual size of the array in pixels. In the "array" properties menu, you can set the "size" of the Array, which represents its length on the X axis, as well as it's name. Each Array you create must have a unique name, otherwise you won't be able to read from them.
Once an array is created and you are in Play Mode, you can click on the line inside and draw curves into the array. Arrays can also be filled with information from datafiles or soundfiles on your computer, as well as with mathematical functions. We'll discuss arrays in more detail in the arrays chapter of the Dataflow Tutorial.
Graph
A "graph" is simply a container a graphical container that can hold several arrays. An array needs a graph to be displayed, so whenever you create an array from the menu, you will be asked whether you want to put it into a newly created graph or into an existing graph.
A Note on using GUI Objects
PD uses a "vector-based" system for drawing the user interface. That means that every element on the screen is defined by a set of numbers rather than an image, and every change to these elements means that your computer must recalculate that part of the screen. For this reason, having a lot of GUI elements which are constantly changing is not recommended, as it can cause interruptions in the audio or slow down the response time of the interface.
In particular, be careful not to use too many of the following:
- VU meters
- Graphical bangs, number boxes, sliders or radio buttons with rapidly changing inputs
- Arrays which are visible on the screen and which are redrawn
For a way of "hiding" GUI elements when they are not in use, please see the Subpatches and Abstractions chapters of the Patching Strategies Tutorial. And for a way of "hiding" the connections between GUI elements, please see the Send/Receive chapter of the Patching Strategies Tutorial.
Troubleshooting
I don't hear any sound!
First make sure that the box marked "compute audio" is checked in the main PD window. Then check to see that you have selected the right soundcard and drivers for your system, and that the soundcard is connected and operating. On OS X, make sure the check-boxes next to your selected soundcard have been checked in "Audio Settings". On Linux or OS X with Jack, make sure the Jack application is running. On all platforms, check the audio control panel which comes with your Operating System and make sure the proper output is enabled there, and that it's playback volume is turned up. Also make sure you are using the correct sampling rate in PD to match that of your soundcard.
There are clicks, glitches or crackles in the test tone!
More than likely you have chosen a latency that is too fast for your computer and soundcard to handle. Return to the "Audio Settings" menu and increase the "delay" time there. On Linux, it is also possible that other processes running on your computer, or even a badly configured or slow graphics card, can affect the performance of PD. Consider running PD with the "-rt" flag enabled (Linux only!). This can be done from the command line, or by adding "-rt" to the "startup flags" under the "Startup" menu. On Linux or OS X with Jack, it is possible to set the latency of the Jack application to a greater amount and reduce glitches (called "xruns" in Jack) there as well.
The test tone sounds distorted!
It is possible that you are playing the sound too loud for your soundcard. Using the controls of your soundcard to reduce the playback volume. Also make sure you are using the correct sampling rate in PD to match that of your soundcard.
I'm not seeing any audio input!
Perhaps you did not enable sound input. On OS X, make sure the check-boxes next to your selected soundcard have been checked in "Audio Settings". Also, some cards with an uneven number of in and out channels can have problems in PD. Try setting the number of channels the same for the input and output. On all platforms, check the audio control panel which comes with your Operating System and make sure the proper input is enabled there, and that it's recording volume is turned up.
I don't see any MIDI input!
Check to see that your MIDI devices or programs are actually sending data, and that your Operating System is correctly sending this data to PD. On OS X, check to see that you have selected the proper MIDI devices, and that the "Audio MIDI Setup.app" was running before you started PD. On Linux using the default MIDI drivers, check to see that you selected the proper MIDI device at startup. On Linux with the ALSA-MIDI drivers, make sure you have properly connected your MIDI devices or MIDI programs to PD. Using Jack with the "QJackctl" application is recommended for this purpose. On Windows, consider using an application like MIDI Ox/MIDI Yoke Junction to see, analyze and manage your MIDI connections.
I get the message "... couldn't create" when I type an object's name and there's a dashed line around my object!
The reason for this error is that you have asked PD to create an object which does not exist. There can be several reasons for this error, and the most common one is spelling. Object names in PD must be spelled correctly, and they are case sensitive. [Osc~] or [OSC~] will not create in place of [osc~], for example, nor will [osc] without the tilde. Sometimes users accidentally combine the creation argument and the object name, such as [+1] instead of [+ 1]. New PD users also often get confused between Objects and Messages, which are very different types of elements which can be placed in the patch from the "Put" Menu. You can use the "Find last error" function under the "Find" menu to track down which objects did not create. Please see the chapter called "The Interface" for more details.
I get the message "... couldn't create" when I open a patch and there's a dashed line around my object!
If you get this error when opening a patch which you're pretty sure works otherwise (i.e. you've downloaded it from the internet or you created it in a previous PD session), then it's likely that there is an External Object which was available when the patch was created, but is not available now. You can use the "Find last error" function under the "Find" menu to track down which objects did not create. PD will preserve the location and connections of an object which fails to create, but it will not function. While most of the PD Externals are available in the PD Extended distribution, some are not, or require additional configuration of the "Path" and "Startup" settings. Please see the relevant sections in the "Configuring PD" chapter. If the External is not available in PD Extended, you may need to install it yourself.
I get the message "error: signal outlet connect to nonsignal inlet (ignored)" when I open a patch.
This error tends to go with the previous error "I get the message '... couldn't create' when I open a patch...". Often this error means that an object has failed to create, usually because it uses an External Object which is not available in the current installation or configuration of PD. PD will preserve the location and connections of an object which fails to create, but it will not function. You can use the "Find last error" function under the "Find" menu to track down which objects caused errors. PD will treat uncreated objects as Dataflow Objects even if they were originally Audio Objects, so this error will follow the previous one. Please see the relevant sections in the "Configuring PD" chapter for information about setting the "Path" and "Startup" options. If the External is not available in PD Extended, you may need to install it yourself.
I get the message "error: can't connect signal outlet to control inlet" and I cannot connect two objects together!
The output of Audio Objects (those with a tilde ~ in their name) normally cannot be connected to Dataflow Objects (those without a tilde ~ in their name). So PD will not allow these connections to be made. You might want to look at your patch and make sure that you are using the proper combination of objects.
I get the message"error: DSP loop detected (some tilde objects not scheduled)" when I click "Audio ON", and the sound is not working!
In an analog electronic system, you can easily connect the output of a mixer back to one of the inputs, turn up the channel and get feedback. This is because everything in an analog system happens pretty much simultaneously. Computers do not work like this, however, and therefore you cannot ask a PD patch to compute results based on it's own simultaneous output. PD works in what are called Blocks (i.e. a group of samples, such as the default number of 64 samples), and all the Samples in each Block must be computed before they are output. So a DSP loop occurs when a patch needs information which is calculated inside the same Block in order to create output. You can use the "Find last error" function under the "Find" menu to track down which objects are causing the DSP loop. The easiest way around this problem is to create at least a one Block delay between the objects which are connected together. The objects [send~] and [receive~] are useful for this, because they have a built-in delay of one Block. To change the number of Samples computer in each Block, you can use the [block~] object.
I get the message "error: stack overflow" when I connect two Dataflow Objects together!
A "stack overflow" happens when you have asked PD to compute a recursive operation, and this operation causes PD to run out of memory. Often this is the first step before crashing PD! A common example of a recursive operation which could cause this error is the classic counter, using [float] and [+ 1]. If the output of [float] is connected to the input of [+ 1], and the output of [+ 1] is connected to the right-most ("cold") inlet of [float], then a "bang" message sent to the left-most ("hot") [float] will output a number which increases by one every time that message is sent. If, however, the output of [+ 1] is connected to the left-most ("hot") inlet of [float], then sending the message "bang" to the left inlet of [float] will have a different effect. It will ask [float] and [+ 1] to add numbers together as fast as the computer will let them do it. Because PD will not stop and ask you "are you sure you want to do this?", this operation will quickly use up all the memory resources which PD has, and cause a stack overflow. Please see the sections on "Hot and Cold" as well as on "Trigger" in the "Dataflow Tutorials" section for more information on how to avoid stack overflows.
I get the error message "connecting stream socket: Network is unreachable" when I start Pd!
If you are using the Linux operating system, and see this message when you start Pd, it means your machine cannot make a network connection to itself. You must configure your loopback network device. In many Linux distributions, you can do this by answering "yes" when the system configuration tools ask if the machine will be a "network" (even if it won't).
What is digital audio?
Since we'll be using Pure Data to create sound, and since PD treats sound as just another set of numbers, it might be useful to review how digital audio works. We will return to these concepts in the audio tutorial later on.
Frequency and Gain
First, imagine a loudspeaker. The move the air in front of it and make sound, the membrane of the speaker must vibrate from it's center position (at rest) backwards and forwards. The number of times per second it vibrates makes the frequency (the note, tone or pitch) of the sound you hear, and the distance it travels from it's resting point determines the gain (the volume or loudness) of the sound. Normally, we measure frequency in Hertz (Hz) and loudness or gain in Decibels (dB).
A microphone works in reverse - vibrations in the air cause its membrane to vibrate. The microphone turns these acoustic vibrations into an electrical current. If you plug this microphone into your computer's soundcard and start recording the soundcard makes thousands of measurements of this electric current per second and records them as numbers.
Sampling Rate and Bit Depth
To make audio playable on a Compact Disc, the computer must make 44,100 measurements (called samples) per second, and record each one as a 16-bit number. One bit is a piece of information which is either 0 or 1, and if there are 16 bits together to make one sample then there are 216 (or 2x2x2x2x2x2x2x2x2x2x2x2x2x2x2x2 = 65,536) possible values that each sample could have. Thus, we can say that CD-quality audio has a sampling rate of 44,100 Hz and a bit-depth or word length of 16 bits. In contrast, professional music recordings are usually made at 24-bit first to preserve the highest amount of detail before being mixed down to 16-bit for CD, and older computer games were famous for having a distinctively rough 8-bit sound. By increasing the sampling rate, we are able to record higher sonic frequencies, and by increasing the bit-depth or word length we are able to use a greater dynamic range (the difference between the quietest and the loudest sounds it is possible to record and play).
The number we use to record each sample has a value between - 1 and 1, which would represent the greatest range of movement of our theoretical loudspeaker, with 0 representing the speaker at rest in the middle position. When we ask PD to play back this sound, it will read the samples back and send them to the soundcard. The soundcard then converts these numbers to an electrical current which causes the loudspeaker to vibrate the air in front of it and make a sound we can hear.
Speed and Pitch Control
If we want to change the speed at which the sound is played, we can read the samples back faster or slower than the original sampling rate. This is the same effect as changing the speed of record or a tape player. The sound information is played back at a different speed, and so the pitch of the sound changes in relation to the change in speed. A faster playback rate increases the pitch of the sound, while a slower playback rate lowers the pitch.
Volume Control, Mixing and Clipping
If we want to change the volume of the sound, we have to multiply the numbers which represent the sound by another number. Multiplying them by a number greater than 1 will make the sound louder, and multiplying them by a number between 1 and zero will make the sound quieter. Multiplying them by zero will mute them - resulting in no sound at all. We can also mix two or more sounds by adding the stream of numbers which represent them together to get a new stream of sound. All of these operations can take place in real-time as the sound is playing.
However, if the range of numbers which represents the sound becomes greater than -1 to 1, any numbers outside of that range will be truncated (reduced to either -1 or 1) by the soundcard. The resulting sound will be clipped (distorted). Some details of the sound will be lost and frequencies that were not present before will be heard.
The Nyquist Number and Foldover/Aliasing
A similar problem occurs if one tries to play back a frequency which is greater then half the sampling rate which the computer is using. Thus, if one is using a sampling rate of 44,100 Hz, the highest frequency one could theoretically play back without errors is 22,050 Hz. This number which represents half the sampling rate is called the Nyquist number.
If you were to tell PD to play a frequency of 23,050 Hz, what you would hear is one tone at 23,050 Hz, and a second tone at 21,050 Hz. The difference between the Nyquist number (22,050 Hz) and the synthesized sound (23,050 Hz) is 1,000 Hz, which you would both add to and subtract from the Nyquist number to find the actual frequencies heard. So as one increased the frequency of the sound over the Nyquist number, you would hear one tone going up, and another coming down. This problem is referred to as foldover or aliasing.
Block Size
Computers tend to process information in batches or chunks. In PD, these are known as Blocks. One block represents the number of audio samples which PD will compute before giving output. The default block size in PD is 64, which means that every 64 samples, PD makes every calculation needed on the sound and when all these calculations are finished, then the patch will output sound. Because of this, a PD patch cannot contain any DSP loops, which are situations where the output of a patch is sent directly back to the input. In such a situation, PD would be waiting for the output of the patch to be calculated before it could give output! In other words, an impossible situation. PD can detect DSP loops, and will not compute audio when they are present. For more information, see the "Troubleshooting" section.
It's All Just Numbers
The main thing to keep in mind when starting to learn Pure Data is that audio and everything else is just numbers inside the computer, and that often the computer doesn't care whether the numbers you are playing with represent text, image, sound or other data. This makes it possible to make incredible transformations in sound and image, but it also allows for the possibility to make many mistakes, since there is no 'sanity checks' in Pure Data to make sure you are asking the program to do something that is possible. So sometimes the connections you make in PD may cause your computer to freeze or the application to crash. To protect against this save your work often and try not to let this bother you, because as you learn more and more about this language you will make fewer and fewer mistakes and eventually you will be able to program patches which are as stable and predictable as you want them to be.
Building a Simple Synthesizer
Introduction
These tutorial uses the concept of very simple electronic music instruments to introduce some of the core concepts of synthesizing and processing audio in Pure Data. Those who are already familiar with audio synthesis should quickly grasp how it is done in PD, while those with no previous knowledge will be introduced to its theory alongside its practical application in PD.
A synthesizer is one of the most fundamental instruments in electronic music. Its essential function is to generate a musical tone when it receives a note from either a keyboard or a sequencer. In analog electronic music, a synthesizer is built from several modules, or parts:
1) The Oscillators, which generates the tones.
2) The LFO (Low Frequency Oscillator), which usually modulates either the frequency or gain of the Oscillator(s), or the frequency of the Filter.
3) The Filter, which emphasizes and/or removes certain frequencies.
4) The Envelope Generator, which controls changes in frequency or gain over the duration of the note.
5) The Amplifier, which controls the gain of the synthesizer.
Synthesizers can be capable of playing one note at a time (monophonic), or several notes at a time, allowing for chords (polyphonic). The number of simultaneous notes that a synthesizer can play are called its voices. Originally, the word "Voltage" was used (i.e. Voltage Controlled Oscillator, Voltage Controlled Filter or Voltage Controlled Amplifier) because in an analog synthesizer each of these modules was controlled by electrical voltage from the keyboard, sequencer or another module. Because we're working in the digital domain, this voltage is replaced by data in the form of numbers, messages and streams of digital audio.
For this tutorial, we will construct a monophonic synthesizer in PD based roughly on the design of the famous MiniMoog analog synthesizer (but much simpler!), and with a sound which is useful for generating basslines. It will take input from the computer keyboard, a MIDI keyboard or the sequencer we will build in the the next tutorial. This synthesizer will be based on two Oscillators to produce the note, another oscillator (the Low Frequency Oscillator) which will change the gain of the sound, a Filter which will only allow only certain frequencies of the sound to pass, an Envelope Generator which will control the "shape" of the gain of the note, and a final Amplifier which will be controlled by the Envelope Generator and a volume setting on the screen.
Downloads
The patches used in this tutorial can be downloaded from:
http://en.flossmanuals.net/floss/pub/PureData/SimpleSynthesizer/simple_synth.zip
Oscillators
Oscillators are the basic signal generators in electronic music. By combining, filtering or modulating them, almost any imaginable sound can be created. In Pure Data, audio signals are represented by a stream of numbers which are between the values of -1 and 1. So the waveform of each oscillator has been programmed to send out values within this range.
The name of each oscillator refers to their waveform, which is the shape of one period (or one Herz) of that oscillator. Different waveforms make different sounds.
Sine Wave Oscillator
The Sine Wave Oscillator makes a pure tone with no harmonics. The shape of the wave smoothly moves from 0 up to 1, back down through 0 to -1 and back up to 0.
Sawtooth Wave Oscillator
The Sawtooth Wave Oscillator sounds harsher in comparison to the sinewave, and it contains both odd and even harmonics of the fundamental frequency. This makes it ideal for filtering and for synthesizing string sounds. The shape of this wave ramps up sharply from 0 to 1, then immediately drops back to 0.
Square Wave Oscillator
And the Square Wave Oscillator has a "hollow" sound, and contains only odd harmonics and is useful for synthesizing wind instrument as well as "heavy" bass sounds. It's shape alternates instantly between 0 and 1. Since there is no square wave object in PD, we create a square wave by checking to see if the output of the Sawtooth Wave object [phasor~] is greater than 0.5. If it is, the Expression object [expr~] outputs a 1, otherwise it outputs a zero. This creates the "high" (1) and "low" (0) states of the square wave, as you can see in the graph.
Other Waveforms
Other possible waveforms include a triangle wave as well as many other mathematical shapes.
Frequency
In order to to create sound, each oscillator object, takes an input of a number which represents a frequency in Hertz. This number determines the number of times the oscillator will make its waveform during one second. By using an creation argument (a default setting typed into the object box when the object is first created), we can set the initial frequency of an oscillator. And by using an [hslider] (Horizontal Slider), a Number or a Message, we can send numerical messages to change the frequency of the oscillator.
In all the examples so far, notice the difference between the cable for numbers and messages, which is thin, and the cable for audio, which is thicker. Numbers and messages can be sent to audio objects (those with a ~ in their name), but usually audio cannot be sent to dataflow objects (those without a ~ in their name). Attempting to do so will cause PD to print "error: can't connect signal outlet to control inlet", and it will not allow the connection to be made.
MIDI and Frequency
For many musical applications, the MIDI scale is a useful way of controlling the frequency of an oscillator. One can imagine the MIDI scale as a piano keyboard with 128 keys on it, and each key has been marked with a frequency in Hertz which represents that musical note. Below is a part of the table which makes up the MIDI scale. Three octaves are shown. The most important thing to notice is that a note which is one octave higher than another note (for example, the three A notes of 110 Hz, 220 Hz and 440 Hz) has a frequency which is twice that of the lower note.
MIDI MIDI MIDI
Note Frequency Note Frequency Note Frequency
C 36 65.4063913251 48 130.8127826503 60 261.6255653006
Db 37 69.2956577442 49 138.5913154884 61 277.1826309769
D 38 73.4161919794 50 146.8323839587 62 293.6647679174
Eb 39 77.7817459305 51 155.5634918610 63 311.1269837221
E 40 82.4068892282 52 164.8137784564 64 329.6275569129
F 41 87.3070578583 53 174.6141157165 65 349.2282314330
Gb 42 92.4986056779 54 184.9972113558 66 369.9944227116
G 43 97.9988589954 55 195.9977179909 67 391.9954359817
Ab 44 103.8261743950 56 207.6523487900 68 415.3046975799
A 45 110.0000000000 57 220.0000000000 69 440.0000000000
Bb 46 116.5409403795 58 233.0818807590 70 466.1637615181
B 47 123.4708253140 59 246.9416506281 71 493.8833012561
For the complete table, see http://www.borg.com/~jglatt/tutr/notefreq.htm
The object in PD which turns a MIDI note into a frequency in Hertz is called [mtof], or MIDI to Frequency. When the MIDI note "69" is sent to it, for example, it will output the number "440". Looking at our examples, you can see that each slider has a range of 0-127, and this is converted by an [mtof] object to a frequency which tells the oscillator what to do.
Of course, you aren't limited to the notes that Western music schools teach you are correct. So-called "microtonal" notes are possible as well. If you hold down the Shift key while using the mouse to change a Number, decimal numbers are possible, so that you can tell an [osc~] to play MIDI note number 76.89, for example.
Additive Synthesis
Because PD adds together the audio signals which come to the inlet of any audio object, it's simple to add two or more signals together into a single waveform. Below, we can see what happens when a Sawtooth Wave and a Sine Wave are added together. The resulting waveform is a combination of the shapes of both, added together. Note that the two waveforms are sent to an Audio Multiplication [*~] object, which multiplies the combined signal by half to reduce the total range of values sent to the soundcard.
Remember that, at full volume, each oscillator is going from either 0 or -1 to 1 many times a second. Because most everything in PD is simply numbers, any number of signals can be added together. However, if the combined values of those signals go outside the -1 to 1 range when they reach the Digital to Analog Converter [dac~] object (i.e. the line out to the sound card), then clipping and distortion will occur. Any value outside of the accepted range will simply be treated as a -1 or a 1. You can see how two combined signals can go outside this range on the graph in the patch below.
An interesting thing happens when we combine two waveforms whose frequencies are very close to each other. The combined values of the two waves interfere with each other, causing a periodic modulation of the sound. The frequency of this modulation is equal to the difference of the two original frequencies in Hz. This is known as a "beating frequency", or "phase interference". The sound of two oscillators slightly "de-tuned" from each other is often used for different kinds of electronic music sounds, such as a "fat" bass effect.
Low Frequency Oscillators & Modulation
Low Frequency Oscillators (or LFOs) are used to control many aspects of a synthesizer, including the frequency of the Oscillators, the gain of the synthesizer or the cutoff frequency of the Filters (see below), and a complex synthesizer can contain many LFOs.
Amplitude Modulation
For a typical LFO, we can use the [osc~] object. By connecting the output of the LFO [osc~] to an Audio Multiplier [*~], we can modulate (i.e. change over time) the gain of any signal which passes through it. This effect is commonly called Amplitude Modulation, or AM Synthesis, and it gives additional character to the sound of a synthesizer.
Unlike the sound-generating Oscillators, we will not use MIDI note numbers to control this oscillator. This is because the speed of this oscillator must be much slower than that of musical notes. A typical LFO oscillates at speeds close to or even slower than once a second. So to control this [osc~], we will use a Number connected directly to its left-most inlet. By changing the number is this box, we send a frequency in Herz directly to the [osc~]. To send numbers smaller than one (where 0.5 would equal a speed of two seconds, for example), or numbers with any decimal place, use the Shift key while changing the Number with the mouse.
Ring Modulation
You can also modulate one audio signal with another audio signal. This effect is called Ring Modulation. If you have a microphone connected to your computer, try the following patch. The sound of your voice will enter PD through the Analog to Digital Converter [adc~] object (the line in from the soundcard), and be modulated by a Sawtooth Wave [phasor~] object. Notice that there is no sound when only one audio signal is present (i.e. when you are not speaking). This is because one audio signal multiplied by zero (no audio signal) will always be zero. And the louder the input signal is, the louder the output will be.
The Ring Modulation effect was often used in Science Fiction movies to create alien voices. You may want to use headphones when running a microphone into PD to prevent feedback (the output of the speakers going back into the microphone and making a howling sound).
Frequency Modulation
While Amplitude Modulation Synthesis changes the gain or volume of an audio signal, Frequency Modulation Synthesis, or FM Synthesis, is used to make periodic changes to the frequency of an oscillator. In it's simplest form, Frequency Modulation uses two oscillators. The first is the "carrier" oscillator, which is the one whose frequency will be changed over time. The second is the "modulator" oscillator, which will change the frequency of the "carrier".
For the "carrier", we only set the base "carrier frequency" using a Number box and a MIDI to Frequency [mtof~] object. Because all the adjustments afterwards will be done by audio signals, it's best to use the audio version of [mtof], hence the tilde is added to its name.
The "modulator" is where we do most of the adjustments. The first thing we want to do is set the frequency of the "modulator", i.e. how fast it will change the frequency of the "carrier". We do this with a Number box. The second thing we want to set is how much change we will make in the base frequency of the "carrier". So the output of the "modulator" [osc~] is multiplied by another Number box using an Audio Multiplier [*~] object to get the "modulation amount".
When this stream of numbers, which is changing with the speed the "modulator" and in the range set by the "modulation amount", is added to the "carrier frequency", then the "carrier frequency" will change as well. This stream of numbers is sent to the second [osc~], where it produces a complex sound which you can see in the graph.
Even more complex sounds can be created by using further "modulators" to make changes in the frequency of the main "modulator" oscillator.
Pulse Width Modulation
We've already seen how a simple mathematical check ("is the value of this audio ramp greater than 0.5?") can be used to turn a Sawtooth wave into a Square wave. This produces a Square Wave which is 1 half the time, and 0 the other half of the time. This is called the Pulse Width of the Square Wave. Different Pulse Widths make a different sound. And when we use a Square Wave as an LFO, different Pulse Widths will have different effects on the sound it is modulating.
When the Square Wave is 1 half the time and 0 the other half, it is said that it has a Pulse Width of 50%. To change the Pulse Width, it is necessary to send a new number to replace the "0.5" in the [expr~] object. The [expr~] object current has one Variable, which is written as $v1, and one constant, "0.5". If the constant is replaced with a second variable, $v2, then we can use a Number box to change the Pulse Width. Sending the number 0.25 will result in a Pulse Width of 25%, i.e. the Square Wave will be 1 a quarter of the time, and 0 three quarters of the time.
It is also possible to modulate the Pulse Width of the Square Wave with an LFO, which creates a unique sound. Instead of using a Number box, the output of a Sine Wave Oscillator is sent to an Absolute audio [abs~] object, which converts any negative values from the [osc~] into positive ones, and this stream of numbers is sent to the second inlet of the [expr~] object.
Math & Logic Operations
Once we are working with Square waves, whose value is either a 0 or a 1, then we can also use Logic operations to create patterns. Logic operations take as their inputs either a 0 or a 1 (and nothing in between!), and compare the two numbers, giving either a 0 or a 1 as an output.
The AND operation works like this:
0 AND 0 = 0
0 AND 1 = 0
1 AND 0 = 0
1 AND 1 = 1
In short, this means that the output is 1 only when both inputs are also 1, otherwise the output is 0. In PD, this is represented by the [&&] object for numbers, and the [&&~] object for audio.
The OR operation works like this:
0 or 0 = 0
0 or 1 = 1
1 or 0 = 1
1 or 1 = 1
In short, this means that the output is 1 only when both inputs are also 0, otherwise the output is 0. In PD, this is represented by the [||] object for numbers, and the [||~] object for audio.
And the EQUAL operation works like this:
0 or 0 = 1
0 or 1 = 0
1 or 0 = 0
1 or 1 = 1
In short, this means that the output is 1 only when both inputs are the same, otherwise the output is 0. In PD, this is represented by the [==] object for numbers, and the [==~] object for audio.
In the following patch, different logic operations are used to make patterns from two Square Wave Oscillators, which are then compared with a final Square Wave Low Frequency Oscillator. What you will hear is a pattern of Square Waves which are switched on and off by each other. The final LFO makes a recognizable rhythm in the sound.
Try replacing any of the AND [&&~] or OR [||~] objects with an EQUAL [==~] object to hear the difference it makes in the sound. Or add further Logic operations to the output of the LFO to make more complex rhythmic patterns. You can also experiment with changing the Pulse Width as described in the previous patches.
Filters
A filter works by allowing some frequencies through, while reducing or eliminating others.
A filter which allows only low frequencies to pass is called a Low Pass Filter. The object for this kind of filter in PD is [lop~]. It has one inlet for audio and one inlet for a number which determines the frequency in Hertz where the filter starts to reduce the audio (the Cutoff Point). Frequencies above the Cutoff Point are reduced or eliminated.
While one which allows only high frequencies is called a High Pass Filter. The object for this kind of filter in PD is [hip~]. It has one inlet for audio and one inlet for the the Cutoff Point. Frequencies below the Cutoff Point are reduced or eliminated.
A filter which allows some range of frequencies between highest and lowest is called a Band Pass Filter. The object for this kind of filter in PD is [bp~]. It has one inlet for audio, a second inlet for the center frequency that it will allow to pass and a third inlet for the Resonance, which determines the width of the range of frequencies it allows to pass (the Pass Band). The Center Frequency will pass unchanged, and frequencies higher or lower than that will be reduced or eliminated. How much they will be eliminated depends on the Resonance. Useful numbers for the Resonance tend to be between 0 and 10.
The three filters we've seen so far all take numbers to control their Cutoff or Center Frequencies as well as their Resonance (in the case of [bp~]. However, there are times when you might want to control the frequency of a filter with an audio signal. A typical situation is when a filter is "swept" by an LFO.
[vcf~] (Voltage Controlled Filter) is a filter whose Center Frequency and Resonance can be controlled by audio signals. The way this is done is quite similar to the tutorial on Frequency Modulation. A Slider sends a MIDI note to a MIDI to Frequency audio [mtof~] object to provide the Center Frequency to be swept, or modulated. Then we have an LFO [osc~] object, whose output is multiplied by the amount in Hertz which we want to sweep the filter frequency. This stream of numbers is added to the Center Frequency coming from the [mtof~] object and sent to the Frequency inlet of the [vcf~]
The Envelope Generator
The Envelope of a sound refers to changes in either its pitch or gain over the duration of a note. A gain envelope is the most common, because it is used to synthesize the dynamics of acoustic instruments. For example, a piano has a very sharp or percussive attack, with the note becoming loud quite quickly before gradually fading out. A violin, on the other hand, takes a longer time for the sound to build up as the strings begin to vibrate, and then fades away relatively quickly. A gain envelope has five main characteristics:
1) Attack: the length of time it takes the note to reach it's loudest point.
2) Decay: the length of time after the Attack it takes the note to reach it's Sustain volume.
3) Sustain: the volume of the note which is held until the note is Released.
4) Release: the length of time it takes the note to fade to zero after the key on the keyboard has been released.
This is commonly abbreviated as ADSR, and can be drawn graphically like this, where the horizontal axis represents time and the vertical axis represents volume:
An additional parameter which comes from the MIDI world is called "Velocity", and it refers to how hard the key of the keyboard has been pressed. In our synthesizer, Velocity will refer to the volume of the note at its loudest point, i.e the peak of the Attack.
The simplest Envelope Generator can be made using the object [line]. This object takes two numbers, a target and a time (in milliseconds), and interpolates numbers to that target in the time given. If it is sent a single number, the time of the ramp is assumed to be zero, and [line] "jumps" to that value. It remembers that last value that it reached, so the next pair of numbers will start a new ramp from the current value. If a new pair of numbers is sent to [line] while it is still making a ramp, it will immediately stop that ramp and start the new one.
To make a simple up/down, or Attack/Decay envelope, we need to send two different messages to [line]. The first will tell it to go to "1" in a certain amount of time, the second will tell it to go back to "0" in a certain amount of time. These two messages can be triggered with a single "bang", as long as we delay the triggering of the second message long enough for the first ramp to finish, using the [delay] object.
A more complex envelope can be created with the [vline~] object. This object can be programmed to make sequences of ramps in order, and with a delay in between them. For example, the message "10 1000, 0 0 1000, 1 1000 3000" would tell [vline~] to do the following:
Ramp up to 10 in 1000ms, then jump to 0 in 0ms after waiting 1000ms (from the start of the ramp), and finally ramp back up to 1 in 1000ms after waiting 3000ms (from start of the ramp).
Because it accepts more complex messages, [vline~] is useful for the traditional Attack/Decay/Sustain/Release envelope. Also, [vline~] is an audio object rather than a dataflow object, which means it is more suitable for audio multiplication, as we will see in the next section.
