Installation
The easiest way to get up and running is to use one of the available binary packages, see below. But it is also possible to compile Purr Data from source if needed.
Mac and Windows packages are available from the Github releases page. Most releases are packaged as zip files; the package name will indicate what operating system and cpu architecture they have been built for. "macos" indicates a macOS, "mingw" a Windows package, "x86_64" denotes an Intel 64 bit package. You'll have to unzip the package first, which will give you a disk image (.dmg file) for macOS, or an executable installer (.exe file) for Windows.
-
macOS / OSX (10.11 or later): Double-click the dmg file and install the application into your Applications folder as usual. All Mac packages are for 64 bit Intel Mac systems, we don't have any native packages for Apple Silicon Macs (yet). But the latest builds for x86_64 will run fine on M1/M2 Macs via Rosetta 2.
-
Windows (Vista, 7, 8, 10+): Double-click the installer executable and run through the installation as usual. We only ship 64 bit (x86_64) packages with the latest releases, but older releases still offer 32 bit packages as well, which should work on legacy 32 bit Windows systems.
Note that depending on your OS you may have to go through the necessary incantations to allow the OS to install and run an unsigned application. On macOS with Gatekeeper enabled, to run the application for the first time, choose "Open" on the application icon and then confirm that you in fact want to run the application. Likewise, on Windows, you may have to click on "More Information" and confirm that you want to install anyway.
On macOS, Gatekeeper can be a major nuisance trying to get an unsigned application to work, so here are some known workarounds that may help if the app refuses to launch, or you can't get access to the microphone.
First, if xattr /Applications/Purr-Data.app reveals that Purr Data has the com.apple.quarantine flag set, then you can remove that flag with the following command (this needs to be run with sudo):
sudo xattr -r -d com.apple.quarantine /Applications/Purr-Data.appAfterwards, the app should launch without any further ado, but you may still have trouble accessing the microphone input. Normally, the system should prompt you to give access to the microphone when the app is first launched, but if that doesn't happen, and Purr Data refuses to show up in the System Settings / Privacy & Security / Microphone settings, then you may have to self-sign the application as follows:
codesign --force --deep -s - /Applications/Purr-Data.appRelaunching the app afterwards should hopefully show the prompt so that you can enable microphone access.
A zipped-up Debian package for Ubuntu (22.04 LTS and compatible distributions) is offered along the Mac and Windows packages on the Github releases page. (These are a recent addition, so don't expect to find this package in older releases.)
In addition, Albert Gräf from the Johannes Gutenberg University (JGU) at Mainz/Germany maintains a large collection of packages hosted on SuSE's Open Build Service (OBS). For want of a catchier name, these are also called the JGU packages. You can find them in the purr-data-jgu project. To install any of these, go to the OBS Download page, pick your Linux system, and follow the instructions.
Note that the OBS maintains package collections for different distributions in different package repositories. The precise set of distributions and their versions keep changing over time. You can find the full list by clicking on the OBS Download link above. At the time of this writing, we have repositories for Arch Linux, the most recent Debian and Ubuntu releases, Raspbian which is the Debian derivative running on the Raspberry Pi, and recent Fedora releases.
These will be for you if you like to test out things early to help with development, or just need a new feature or bugfix that isn't available in the published releases yet. The latest development builds can always be found on the Actions tab. They resemble what you find on the Releases page, but are built from recent commits to the master, release and testing branches in the source repository (these builds are only kept around for two days, so better grab them while they are hot). In addition, test builds from the testing branch are also available on the OBS in the test project. Please note that these are intended for testing purposes only, so it's usually not advisable to use them live on stage.
NOTE: Purr Data is a complicated package with many parts and many dependencies. Depending on the operating system that you use, getting all the dependencies installed can be a laborious process, and the compilation itself can take quite a while, even on modern hardware. That said, compiling Purr Data is a lot less scary than it used to be.
NOTE: If you're building on an Apple Silicon Mac, make sure that you have your build environment set up so that it compiles for Intel x86_64 (e.g., arch -x86_64 make). The native M1/M2 port of Purr Data doesn't work at present.
To build Purr Data from source, you'll have to clone the git repository as follows:
git clone https://github.com/agraef/purr-data
Or, if you prefer to build straight from Wilke's upstream repository:
git clone https://git.purrdata.net/jwilkes/purr-data.git
Make sure that you have all the requisite dependencies installed (Linux, Mac, Windows), then run make in the toplevel source directory:
make
On Debian/Ubuntu, Mac and Windows this should leave the ready-made package in the toplevel source directory. Install this as usual. On other Linux systems you can run the following command instead (this also works on Debian/Ubuntu, if you prefer this method or if you don't have the Debian packaging tools installed):
sudo make install
After a make install, you can uninstall the software again as follows:
sudo make uninstall
Afterwards, to clean the source directory:
make realclean
Note that this puts the source into pristine state again, like after a fresh checkout, so that you can run make from a clean slate again. Also, all build artifacts will be gone, and hence you won't be able to run make install or make uninstall any more. So you want to do this only after you've finished the installation process.
There are some ways to speed up the build, please check the Makefile for details. In particular, try running:
make light
This will build a minimal, no-frills, vanilla-like Purr Data system with just the essential externals included. This build finishes much faster. It will also lack the everything-and-the-kitchen-sink collection of externals which a Purr Data installation normally includes. But vanilla Pd users might actually prefer it that way.
You can still include whatever additional externals you want by using the addons variable when running make:
make light addons='pdlua fluid mrpeach'
Since even the light build includes the libdir loader, most externals added in this way will just work without any further ado, although some externals might still require some post-install setup to make them work as expected, such as adding search paths or startup libraries on the Startup tab in the Preferences.
nw.js is the JavaScript runtime environment that Purr Data uses for its graphical user interface. Purr Data can be built against different nw.js versions; the default varies with platform and cpu architecture, but on Linux, Mac, and Windows our latest packages use nw.js 0.55.0, which seems to work best across modern releases of these systems. However, when running make you can choose which nw.js version to use with the nwjsver variable; make will download that version and use it for the build, and all subsequent builds in the same directory (the downloaded and extracted version will be cached in your working copy in the pd/nw/nw directory). For instance, to build with nw.js 0.67.1, you can run make as:
make nwjsver=0.67.1A few caveats are in order here since not all nw.js versions work equally well with Purr Data. Specifically, versions 0.42.4 and later have NW2, the new browser window implementation for nw.js, as default. Unfortunately, NW2 suffers from a substantial degradation in JavaScript execution performance which can make Purr Data's user interface slow and unresponsive in certain situations. Therefore our latest packages all have NW2 disabled by default. But this means that Purr Data can't be used with nw.js versions 0.68.0 and later which have another bug that breaks Purr Data's window management if NW2 is disabled. Moreover, on Linux nw.js versions 0.56.0 and later have another serious regression which causes Purr Data's file dialogs to show the wrong directories. That's why we stick to nw.js 0.55.0 for now, but this version also suffers from yet another (albeit cosmetic) bug on Linux which causes the menu bar to be displayed incorrectly when using a dark theme on your desktop.
So at present there is no version of nw.js which just works for everyone and everywhere. Therefore we provide a little shell script which lets you patch the nw.js in an existing installation of Purr Data without a recompile. By these means, you can easily tweak Purr Data's GUI so that it works best for your purposes.
The script needs bash, sudo, and wget. These are readily available on Linux and Mac. On Windows, you can use the msys2 shell. Which also has wget, but not sudo, which is why the script has been set up to work with gsudo, a sudo replacement for Windows which works nicely with the msys2 shell. (The script needs sudo/gsudo in order to be able to gain the administrator rights required to write into the system directories containing your Purr Data installation.)
The way this works is that you download the shell script, make sure that it's executable, and run it, e.g., as follows:
./patch-nwjs.sh 0.67.1If the nw.js version and your Purr Data installation can be found, this downloads the given nw.js version, unpacks it, fixes up the permissions so that it will work with Purr Data, and installs it in your Purr Data installation (at which point you may be prompted for your administrator password).
This assumes that the script is in your current working directory, otherwise you'll have to adjust the path accordingly, or make sure that the location of the script is on bash's PATH. In any case, the script needs to be run in a directory that's writable, because that's where it downloads the nw.js package.
You can also invoke the script without any arguments to have it revert to the default nw.js version (0.55.0 at the time of this writing):
./patch-nwjs.shYou can also use the script to switch NW2 mode in your existing installation on and off, by running the script as ./patch-nwjs.sh -nw2 and ./patch-nwjs.sh -nw1, respectively. Both the nw.js version argument and the -nw1 or -nw2 option can also be combined in order to perform both changes at once:
./patch-nwjs.sh 0.71.0 -nw2Note that using the -nw2 option isn't recommended for reasons explained in the previous subsection, but it will be required to make nw.js versions 0.68.0 and later work with Purr Data (keeping in mind the caveats from the previous subsection). Also, using -nw1 isn't necessary with the latest Purr Data releases, as it is the default, but you can retroactively disable NW2 in an older installation (Purr Data 2.19.3 and earlier) by running the script as follows:
./patch-nwjs.sh -nw1If you have the Debian package toolchain installed on your system, you can easily create your own source and binary deb packages in an automatic fashion by running something like make debchange and then make deb or make debsrc in the debuild directory in the sources. Details can be found in the comments at the beginning of debuild/Makefile. That's also the way we build our own Debian and Ubuntu packages on GitHub and the Open Build Service, so the build process is fully automatic and is continually being tested. Note that you will have to do some initial setup work to get the Debian packaging tools up and running. If you're new to this, we recommend that you first read the Debian or Ubuntu packaging guide, depending on which system you use.
Having installed Purr Data, it's time to kick the tires. You can learn more about Purr Data and how to use it in our Meet The Cat tutorial. Or just run the application and launch the help browser (Ctrl+B on Linux and Windows, Cmd+B on the Mac, or choose "Help Browser" from the Help menu) to discover things and have fun!
Purr Data should provide you with some icon (named "Purr Data" or "Pd-l2ork") to launch the program, either in the start menu (Linux, Windows), or in the Launchpad and the Applications folder (Mac). On Linux, it's also possible to run the application from the command line, by executing the purr-data program (if you're using the JGU packages), or pd-l2ork (if you've installed Purr Data from source or a non-JGU package).
You will probably want to set up your audio and MIDI devices first. This is done in the Preferences dialog (Ctrl+P on Linux and Windows, Cmd+, on the Mac, or choose "Preferences" from the Edit or application menu). The first "Audio" tab has the audio settings, the second "MIDI" tab, you guessed it, lets you configure the MIDI settings.
Configure your audio and MIDI inputs and outputs by choosing the devices from the dropdown lists in the dialog. Note that you can configure multiple inputs and outputs (up to four different devices on the "Audio", and up to ten different devices on the "MIDI" tab).
In Linux the audio and MIDI interface is a bit different. First, on the Audio tab you select which kind of audio interface you want to use, ALSA or JACK. Jack is often used because it offers the possibility to route audio signals between different Jack-enabled applications, and in Pd it sometimes works better with lowly onboard sound cards. If you choose this option, you only configure the number of Jack inputs and outputs that you want. Routing the audio is then done through a Jack control application such as QjackCtl, which should be readily available on most Linux distributions.
You can also use the native ALSA audio interface, if your sound card works fine with it and you don't need Jack's routing capabilities. In this case you can choose your input and output devices from the dropdown lists like on Mac and Windows.
Finally, on the MIDI tab leave the default ALSA option enabled, and choose the number of MIDI input and output ports that you want (0 is the default). You then still have to use a tool like QjackCtl to route MIDI data from and to the "Pure Data" ALSA MIDI ports.
Note that there is no built-in Jack MIDI support in Purr Data right now. However, it is possible to route data from and to Jack MIDI ports by using an ALSA-Jack MIDI bridge. This is built into all recent Jack versions. In QjackCtl's setup, just make sure that you have selected seq as the MIDI driver:
This exposes the ALSA sequencer ports of Purr Data (as well as any other non-Jack ALSA MIDI applications) as Jack MIDI ports, so that they can easily be connected to your Jack MIDI applications.
As an alternative, you can also run a2jmidid as a separate ALSA-Jack MIDI bridge. This method works well with both Jack1 and Jack2. Jack's built-in bridge also does the job in Jack1, but in Jack2 it doesn't list the ALSA ports by their name, so it's better to use a2jmidid in that case. You can have QjackCtl autostart a2jmidid by placing the command a2jmidid -e & into the "Execute script after Startup" field which can be found under "Options" in QJackctl's Setup dialog. (Don't forget the trailing & character, otherwise QjackCtl will hang at startup! The -e option ensures that a2jmidid also bridges the hardware ports. You can also add -u to remove the MIDI device numbers which may cause trouble with patchbay applications since those numbers tend to keep changing. See the a2jmidid manual page for details.)
NOTE: None of the above is necessary on systems running Pipewire with the pipewire-jack module, which completely replaces Jack. Pipewire will have its ALSA-Jack MIDI bridge automatically enabled. (At least that's the case on my system, YMMV.) However, at the time of this writing, Pipewire is still under development, so you may want to stick to a traditional Jack setup until Pipewire becomes more mature and stable.
That's all for now, folks. Any questions, suggestions or comments? Just drop us an email on the DISIS Pd-l2ork mailing list, file an issue, or drop us a pull request!
Albert Gräf [email protected]