Commit a481311c authored by Albert Gräf's avatar Albert Gräf
Browse files

More final touches.

parent 902abe0c
......@@ -27,30 +27,30 @@ Computer Music Dept., Institute of Art History and Musicology<br/>
Johannes Gutenberg University (JGU) Mainz, Germany<br/>
February 2017</p>
<p>Purr Data a.k.a. Pd-l2ork 2.x is an improved version of Miller Puckette&#8217;s Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data&#8217;s role in the Pd ecosystem and how it came about.</p>
<p><strong>Purr Data</strong> a.k.a. <strong>Pd-l2ork</strong> 2.0 is an improved version of Miller Puckette&#8217;s interactive computer music and multimedia software <strong>Pd</strong>. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data&#8217;s role in the Pd ecosystem and how it came about.</p>
<h2 id="whatispurrdata">What is Purr Data?</h2>
<p><strong>Purr Data</strong> is the latest (2.x) branch of Ivica Ico Bukvic&#8217;s Pd-l2ork. <strong>Pd-l2ork</strong> in turn is a fork of Hans-Christoph Steiner&#8217;s <strong>Pd-extended</strong>, which has been the longest-running (and arguably the most popular) variant of Miller Puckette&#8217;s Pd. <strong>Pd</strong> a.k.a. <strong>Pure Data</strong>, the common basis of all these variants, is Miller Puckette&#8217;s interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74&#8217;s well-known commercial <strong>Max</strong> program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical &#8220;patching&#8221; environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a &#8220;real&#8221; programming language.</p>
<p><strong><a href="https://git.purrdata.net/jwilkes/purr-data">Purr Data</a></strong> is the latest (2.x) branch of Ivica Ico Bukvic&#8217;s Pd-l2ork. <strong><a href="http://l2ork.music.vt.edu/main/make-your-own-l2ork/software/">Pd-l2ork</a></strong> in turn is a fork of Hans-Christoph Steiner&#8217;s <strong><a href="http://puredata.info/downloads/pd-extended">Pd-extended</a></strong>, which has been the longest-running (and arguably the most popular) variant of Miller Puckette&#8217;s Pd. <strong><a href="http://puredata.info/">Pd</a></strong> a.k.a. <strong>Pure Data</strong>, the common basis of all these variants, is Miller Puckette&#8217;s interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74&#8217;s well-known commercial <strong><a href="https://cycling74.com/">Max</a></strong> program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular applications in the realm of computer music and media art, most notably <a href="http://csound.github.io/">Csound</a> and <a href="http://supercollider.github.io/">SuperCollider</a>. Max and Pd&#8217;s special appeal is that you work in an intuitive graphical &#8220;patching&#8221; environment which allows you to put together advanced real-time signal processing applications without having to learn a &#8220;real&#8221; programming language.</p>
<p>Puckette&#8217;s version of the program is often jokingly referred to as <strong>&#8220;vanilla&#8221;</strong> Pd, because it comes without any extras and thus provides the purest taste of Pd, you might say. In keeping with this metaphor, the other Pd variants are often called its different <strong>flavors</strong>.</p>
<p>While vanilla Pd, being the reference implementation, remains critically important for the development of Pd&#8217;s real-time engine, its Tcl/Tk-based graphical user interface has never been very pretty or convenient. Consequently there have been several attempts by the community to improve Pd&#8217;s user interface in various ways. Pd-extended is the earliest and the longest-running of these, which also includes a fairly complete selection of 3rd party add-ons. However, its development has stopped in 2013 due to lack of contributions, and thus it receives no more bugfixes and updates of the real-time engine.</p>
<p>Ico Bukvic introduced <strong>Pd-l2ork</strong> in 2010 as a fork of Pd-extended to be used by the &#8220;Linux Laptop Orchestra&#8221; (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is required to run even <em>very</em> old patches created with ancient Pd versions.</p>
<p>Ico Bukvic introduced <strong>Pd-l2ork</strong> in 2010 as a fork of Pd-extended to be used by the &#8220;Linux Laptop Orchestra&#8221; (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, so that it is still able to run <em>very</em> old patches created with ancient Pd versions.</p>
<p>Despite the many and substantial improvements it offers, Pd-l2ork&#8217;s GUI is still based on Tcl/Tk. This is both good and bad. The major advantage is compatibility with vanilla Pd. On the other hand, Tcl/Tk looks and feels outdated in this day and age, even when going to some lengths with theming, as Pd-l2ork does. Tcl is a rather basic programming language, and its libraries have been falling behind, making it hard to integrate the latest advancements in GUI, multimedia and web technologies. But most importantly, Pd-l2ork&#8217;s adoption was seriously hampered by the fact that in order to implement some of the graphical improvements, it relies on some more or less Linux-specific Tcl/Tk extensions, which means that it wouldn&#8217;t run on Windows or the Mac without substantial effort.</p>
<p>Despite the many and substantial improvements it offers, Pd-l2ork&#8217;s GUI is still based on Tcl/Tk. This is both good and bad. The major advantage is compatibility with vanilla Pd. On the other hand, Tcl/Tk looks and feels outdated in this day and age, even when going to some lengths with theming, as Pd-l2ork does. Tcl is a rather basic programming language, and its libraries have been falling behind, making it hard to integrate the latest advancements in GUI, multimedia and web technologies. Also, Pd-l2ork&#8217;s adoption was hampered by the fact that it was essentially tied to Linux, and thus a cross-platform solution was needed.</p>
<p>In 2015 Jonathan Wilkes stepped in and started creating <strong>Purr Data</strong> to address these problems. In a nutshell, Purr Data is Pd-l2ork with the Tcl/Tk GUI part ripped out and replaced with modern web technology. To these ends, it uses a framework called <a href="https://nwjs.io/">nw.js</a> a.k.a. &#8220;node-webkit&#8221;, which is essentially a stand-alone web browser engine (<a href="http://www.chromium.org/">Chromium</a>) combined with a JavaScript runtime (<a href="http://nodejs.org/">Node.js</a>). Both these components are open-source, and while they were originally invented for developing server-side web applications, frameworks like nw.js combine them in a way so that they can be used for creating full-featured and portable desktop applications. Thus nw.js makes sure that Purr Data also runs on Mac and Windows systems, and it also paves the way to leverage standard web technologies such as JavaScript, HTML5 and SVG which have way better support than Tcl/Tk these days. Last but not least, JavaScript is a much more capable and widespread programming language than Tcl, which makes developing Purr Data&#8217;s graphical user interface a lot easier now that the initial GUI port is done.</p>
<p>In 2015 Jonathan Wilkes stepped in and started creating <strong>Purr Data</strong> to address these problems. In a nutshell, Purr Data is Pd-l2ork with the Tcl/Tk GUI part ripped out and replaced with modern web technology. To these ends, it uses an open-source framework called <a href="https://nwjs.io/">nw.js</a> a.k.a. &#8220;node-webkit&#8221;, which is essentially a stand-alone web browser engine (<a href="http://www.chromium.org/">Chromium</a>) combined with a JavaScript runtime (<a href="http://nodejs.org/">Node.js</a>). While the latter was originally invented for developing server-side web applications, frameworks like nw.js allow the two to be used in concert to create fully-fledged and portable desktop applications. Using nw.js ensures that Purr Data runs on Linux, Mac and Windows, looking the same on all supported platforms, and it paves the way to leverage standard web technologies such as JavaScript, HTML5, CSS3 and SVG.</p>
<p>So Purr Data&#8217;s GUI is written entirely in JavaScript. Patches are implemented as HTML5 SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. Purr Data also looks better and is easier on the eyes than Pd-l2ork, let alone vanilla Pd, especially on high-dpi displays (cf. Fig. 1).</p>
<p>Purr Data&#8217;s GUI is written entirely in JavaScript, which is much more advanced than Tcl, offering an abundance of libraries and support materials. This makes the further development of Purr Data&#8217;s graphical user interface a lot easier now that the initial GUI port is done. Patches are implemented as HTML5 SVG documents which offer better responsiveness and graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. Purr Data also looks better and is easier on the eyes than Pd-l2ork, let alone vanilla Pd, especially on high-dpi displays (cf. Fig. 1).</p>
<p><img src="purr-data.png" alt="Fig. 1: Purr Data running on Mac OSX." /><br/>
Fig. 1: Purr Data running on Mac OSX.</p>
<p><img src="purr-data.png" alt="Fig. 1: Purr Data running on macOS." /><br/>
Fig. 1: Purr Data running on macOS.</p>
<p>Purr Data&#8217;s nw.js GUI also has some disadvantages. Most notably, some of the included externals still rely on Tcl code, so their GUI features will not work in Purr Data until they get ported to the new GUI. Second, the size of the binary packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with <em>very</em> tight memory constraints. None of these should normally be a real show-stopper, however. Just give it a try and see whether it works for your use case and target platform.</p>
<p>Purr Data&#8217;s nw.js GUI also has some disadvantages. First, some of the included externals still rely on Tcl code, so their GUI features will not work in Purr Data until they get ported to the new GUI. Second, the size of the binary package is considerably larger than with Pd-l2ork or Pd-extended since it also includes the full nw.js binary distribution. (This is a valid concern with many of the so-called &#8220;portable desktop applications&#8221; being offered these days, but in the case of Purr Data it is mitigated by the fact that its Pd-l2ork base is not exactly a slim package either.) Third, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with <em>very</em> tight memory constraints. While none of these issues should normally be a real show-stopper on the supported platforms, it is worth keeping them in mind.</p>
<p>Purr Data is still comparatively young, but its basis is the tried and proven Pd-l2ork, the present release has been thoroughly tested and many bugs have been ironed out, so it is certainly ready for day-to-day use. It also offers some really compelling advancements over its predecessors. If you have been looking for a modern and actively-maintained successor of Pd-extended, this is it.</p>
<p>Finally, Purr Data is still comparatively young, but its basis is the tried and proven Pd-l2ork, the present release has been thoroughly tested and many bugs have been ironed out, so it is certainly ready for day-to-day use. It also offers some really compelling advancements over its predecessors. If you have been looking for a modern and actively-maintained successor of Pd-extended, this is it.</p>
<h2 id="thename">The Name?</h2>
......@@ -68,23 +68,23 @@ Fig. 1: Purr Data running on Mac OSX.</p>
<h2 id="wheretogetit">Where to Get It</h2>
<p>Jonathan Wilkes maintains the Purr Data sources in GitLab at <a href="https://git.purrdata.net/jwilkes/purr-data">https://git.purrdata.net/jwilkes/purr-data</a>. The latest packages for Linux (Debian, Raspbian, Ubuntu), OSX and Windows are available at <a href="https://git.purrdata.net/jwilkes/purr-data-binaries/tree/master">https://git.purrdata.net/jwilkes/purr-data-binaries/tree/master</a>.</p>
<p>Jonathan Wilkes maintains the Purr Data sources in GitLab at <a href="https://git.purrdata.net/jwilkes/purr-data">https://git.purrdata.net/jwilkes/purr-data</a>. The latest packages for Linux (Debian, Raspbian, Ubuntu), macOS and Windows are available in the <a href="https://git.purrdata.net/jwilkes/purr-data-binaries/tree/master">download area</a> on this site. The Linux packages are in Debian format (.deb files), the Windows package is distributed as a zip file which contains an installer executable (.exe file). Normally you can just run the .deb or .exe packages by double-clicking them in your file manager, and walk through the installation procedure. The Mac package is distributed as a disk image (.dmg file); double-clicking the disk image in Finder opens a new Finder window, in which you can drag the application to your Application folder. The Mac and Windows packages should be self-contained, while the .deb packages will pull in a lot of dependencies, which may require some fiddling. (If you&#8217;re running Ubuntu or one of its derivatives, and the .deb packages give you trouble, try using the JGU Ubuntu packages instead, see below.)</p>
<p>At JGU we also maintain a collection of Linux packages for Arch Linux (via the Arch User Repositories a.k.a. AUR) and Ubuntu 14.04/16.04 (via Launchpad). More information about these can be found at <a href="http://l2orkaur.bitbucket.org/">http://l2orkaur.bitbucket.org/</a> (Arch) and <a href="http://l2orkubuntu.bitbucket.org/">http://l2orkubuntu.bitbucket.org/</a> (Ubuntu). Besides Purr Data, these repositories also contain the &#8220;classic&#8221; Pd-l2ork (Ico Bukvic&#8217;s 1.0 version), as well as two additional programming extensions for Pd which enable you to run Faust and Pure externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.</p>
<p>At JGU we also maintain a collection of Linux packages for Arch Linux (via the <a href="https://aur.archlinux.org/">Arch User Repositories</a> a.k.a. AUR) and recent Ubuntu releases (via <a href="https://launchpad.net/~dr-graef">Launchpad</a>). More information and installation instructions can be found at <a href="https://l2orkaur.bitbucket.io/">https://l2orkaur.bitbucket.io/</a> (Arch) and <a href="https://l2orkubuntu.bitbucket.io/">https://l2orkubuntu.bitbucket.io/</a> (Ubuntu). Besides Purr Data, these repositories also contain the &#8220;classic&#8221; Pd-l2ork (Ico Bukvic&#8217;s 1.0 version), as well as two additional programming extensions for Pd which enable you to run <a href="http://faust.grame.fr/">Faust</a> and <a href="https://purelang.bitbucket.io/">Pure</a> externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.</p>
<p>Because of the large number of included externals, Purr Data&#8217;s build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn&#8217;t officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.</p>
<p>Of course, it is also possible to build Purr Data from source. However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn&#8217;t officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.</p>
<h2 id="gettingstarted">Getting Started</h2>
<p>Once you&#8217;ve installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run <code>pd-l2ork</code> from the command line, or look in your desktop environment&#8217;s program menu or launcher for the <code>Pd-L2Ork</code> entry and click on that. (If you installed Purr Data from one of the JGU packages, use the <code>purr-data</code> command or the <code>Purr-Data</code> desktop icon instead.)</p>
<p>On Mac OSX and Windows, double-click on the application icon (normally to be found in the application or program folder, depending on how you installed it). </p>
<p>On macOS and Windows, double-click on the application icon, normally to be found in the Application folder on macOS and on the desktop on Windows. (If you didn&#8217;t create a desktop icon during the Windows installation, look for <code>Purr-Data</code> in the start menu.) </p>
<p>You can also just double-click on a patch file to have it open in Purr Data. However, this will usually require a first-time setup to tell the file manager that the Pd file type should be opened using the Purr Data application.</p>
<p>You can also right-click on a patch (.pd) file, choose &#8220;Open With&#8221; and then select Pd-l2ork or Purr Data to open the patch in Purr Data. This may require a first-time setup to associate the .pd file type with the Purr Data program, however. Most desktop environments will also let you set Purr Data as the default application for .pd files, so that you can subsequently open patch files simply with a double-click. The details of this are system-specific; usually right-clicking the file and choosing <code>Properties</code> or some similar option (<code>Get Info</code> on macOS) will give you a dialog which allows you to change the file association.</p>
<p>In any case, Purr Data should then open its main &#8220;console&#8221; window which logs all messages from the program. If you double-clicked a patch file, it will be shown in a separate &#8220;canvas&#8221; window.</p>
<p>In any case, Purr Data should then launch its main &#8220;console&#8221; window which logs all messages from the program. If you opened a patch file, it will be shown in a separate &#8220;canvas&#8221; window.</p>
<p>Purr Data understands basically the same set of command line options as vanilla Pd or Pd-l2ork. On Linux, you can find out about these by running <code>pd-l2ork -help</code> (<code>purr-data -help</code> when using the JGU packages) from the command line. (Right now this isn&#8217;t easy to do on Mac and Windows, since you&#8217;ll have to locate the program executable in the application folder.) Some common options which can be placed into the startup flags are <code>-path</code> and <code>-lib</code>, see section &#8220;GUI and Startup Options&#8221; below.</p>
<p>Purr Data understands basically the same set of command line options as vanilla Pd or Pd-l2ork. On Linux, you can find out about these by running <code>pd-l2ork -help</code> (<code>purr-data -help</code> when using the JGU packages) from the command line. (This isn&#8217;t easy to do on Mac and Windows, since the program executable is stowed away somewhere in the application folder.) Some common options which can be placed into the startup flags are <code>-path</code> and <code>-lib</code>, see section &#8220;GUI and Startup Options&#8221; below.</p>
<h3 id="singleapplicationinstance">Single Application Instance</h3>
......@@ -149,15 +149,11 @@ Fig. 4: Help browser.</p>
<p>Note that in any case, you can always return to the home screen of the help browser by clicking that tiny &#8220;x&#8221; symbol in the search entry (or by just hitting Enter in the field if it is empty).</p>
<h2 id="tipsandtricks">Tips and Tricks</h2>
<p>We conclude this primer with a little grab bag of helpful tips and tricks. If your questions aren&#8217;t answered here, please post them to the DISIS <a href="http://disis.music.vt.edu/listinfo/l2ork-dev">Pd-l2ork mailing list</a>. Questions (and answers) which are of interest to all Purr Data users will likely be added to this section in the future. </p>
<h3 id="pd-l2orkandpurrdatagoodies">Pd-l2ork and Purr Data goodies</h3>
<h2 id="pd-l2orkandpurrdatagoodies">Pd-l2ork and Purr Data Goodies</h2>
<p>Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the <a href="http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf">PdCon 2016 paper</a> for details. The paper also has a detailed account on the history and motivation of the Pd-l2ork project.</p>
<p>Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the <a href="http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf">PdCon 2016 paper</a> for details. The paper also covers the history and motivation of the Pd-l2ork project.</p>
<p>Many of the new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren&#8217;t even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and the &#8220;graph on parent&#8221; areas using the mouse. An important new feature is Pd-l2ork&#8217;s <em>infinite undo</em> capability which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they&#8217;re under development. A helpful change also worth mentioning here is the improved <em>tidy up</em> option in the Edit menu, which first aligns objects and then spaces them equidistantly.</p>
<p>One of Pd-l2ork&#8217;s major advancements over vanilla Pd is its <em>infinite undo</em> capability, which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they&#8217;re under development. Many of the other new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren&#8217;t even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and &#8220;graph on parent&#8221; areas using the mouse. A helpful change also worth mentioning here is the improved <em>tidy up</em> option in the Edit menu, which first aligns objects and then spaces them equidistantly.</p>
<p>Another big time-saver is Pd-l2ork&#8217;s <em>intelligent patching</em> facility, which lets you select two or more objects in order to connect multiple outlets and inlets in one go. Intelligent patching offers a number of different modes, the most useful (or at least the easiest) of these are:</p>
......@@ -167,9 +163,13 @@ Fig. 4: Help browser.</p>
<li><p>Also, pressing the shift key while doing connections will let you do multiple connections from the same outlet in one go.</p></li>
</ul>
<p>It is worth practicing these so that you can amaze your vanilla-running friends with the speed at which you can construct rather complicated patches using these shortcuts. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little <a href="intelligent-patching.pd">intelligent-patching.pd</a> patch with this primer for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.</p>
<p>It is worth practicing these so that you can amaze your vanilla-running friends with the speed at which you can construct rather complicated patches using these shortcuts. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little <a href="intelligent-patching.pd">intelligent-patching.pd</a> patch with this document for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.</p>
<p>Other features will be more useful for advanced users, like the reflection capabilities (see the <code>pdinfo</code>, <code>canvasinfo</code>, <code>classinfo</code> and <code>objectinfo</code> help patches) and the new SVG elements for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the &#8220;Pd-L2Ork Data Structures&#8221; section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a &#8220;real&#8221; programming language.</p>
<h2 id="tipsandtricks">Tips and Tricks</h2>
<p>Other features will be more useful for advanced users, like the reflection capabilities (see the <code>pdinfo</code>, <code>canvasinfo</code>, <code>classinfo</code> and <code>objectinfo</code> help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the &#8220;Pd-L2Ork Data Structures&#8221; section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a &#8220;real&#8221; programming language.</p>
<p>We conclude this introduction with a little grab bag of helpful tips and tricks. If your questions aren&#8217;t answered here, please post them to the DISIS <a href="http://disis.music.vt.edu/listinfo/l2ork-dev">Pd-l2ork mailing list</a>.</p>
<h3 id="installclassicpd-l2orkalongsidepurrdata">Install classic Pd-l2ork alongside Purr Data</h3>
......@@ -209,7 +209,7 @@ Fig. 4: Help browser.</p>
<h3 id="purrdatahangsduringstartup">Purr Data hangs during startup</h3>
<p>As far as I can tell, this was only reported on Mac OS X so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message <code>incoming connection to GUI</code> in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it (&#8220;force quit&#8221;).</p>
<p>As far as I can tell, this was only reported on macOS so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message <code>incoming connection to GUI</code> in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it (&#8220;force quit&#8221;).</p>
<p>The exact causes are unknown right now, but it seems that this behavior may be caused by bad 3rd party externals causing the realtime engine to hang or crash during startup. The GUI then waits for the incoming connection from the engine which never gets established, which makes it hang in turn.</p>
......
......@@ -5,30 +5,30 @@ Computer Music Dept., Institute of Art History and Musicology
Johannes Gutenberg University (JGU) Mainz, Germany
February 2017
Purr Data a.k.a. Pd-l2ork 2.x is an improved version of Miller Puckette's Pd. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data's role in the Pd ecosystem and how it came about.
**Purr Data** a.k.a. **Pd-l2ork** 2.0 is an improved version of Miller Puckette's interactive computer music and multimedia software **Pd**. The purpose of this document is to provide new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started. It also includes some background information to explain Purr Data's role in the Pd ecosystem and how it came about.
## What is Purr Data?
**Purr Data** is the latest (2.x) branch of Ivica Ico Bukvic's Pd-l2ork. **Pd-l2ork** in turn is a fork of Hans-Christoph Steiner's **Pd-extended**, which has been the longest-running (and arguably the most popular) variant of Miller Puckette's Pd. **Pd** a.k.a. **Pure Data**, the common basis of all these variants, is Miller Puckette's interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74's well-known commercial **Max** program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular real-time applications in the realm of computer music and media art, most notably Csound and SuperCollider. However, what makes Max and Pd special is that you work in a graphical "patching" environment which allows you to put together complex signal processing applications in an intuitive way without having to learn a "real" programming language.
**[Purr Data](https://git.purrdata.net/jwilkes/purr-data)** is the latest (2.x) branch of Ivica Ico Bukvic's Pd-l2ork. **[Pd-l2ork](http://l2ork.music.vt.edu/main/make-your-own-l2ork/software/)** in turn is a fork of Hans-Christoph Steiner's **[Pd-extended](http://puredata.info/downloads/pd-extended)**, which has been the longest-running (and arguably the most popular) variant of Miller Puckette's Pd. **[Pd](http://puredata.info/)** a.k.a. **Pure Data**, the common basis of all these variants, is Miller Puckette's interactive and graphical computer music and multimedia environment. Pd is also the premier open-source alternative to Cycling74's well-known commercial **[Max](https://cycling74.com/)** program (whose original version was also developed by Miller Puckette when he was at IRCAM in the 1980s). There are a few other popular applications in the realm of computer music and media art, most notably [Csound](http://csound.github.io/) and [SuperCollider](http://supercollider.github.io/). Max and Pd's special appeal is that you work in an intuitive graphical "patching" environment which allows you to put together advanced real-time signal processing applications without having to learn a "real" programming language.
Puckette's version of the program is often jokingly referred to as **"vanilla"** Pd, because it comes without any extras and thus provides the purest taste of Pd, you might say. In keeping with this metaphor, the other Pd variants are often called its different **flavors**.
While vanilla Pd, being the reference implementation, remains critically important for the development of Pd's real-time engine, its Tcl/Tk-based graphical user interface has never been very pretty or convenient. Consequently there have been several attempts by the community to improve Pd's user interface in various ways. Pd-extended is the earliest and the longest-running of these, which also includes a fairly complete selection of 3rd party add-ons. However, its development has stopped in 2013 due to lack of contributions, and thus it receives no more bugfixes and updates of the real-time engine.
Ico Bukvic introduced **Pd-l2ork** in 2010 as a fork of Pd-extended to be used by the "Linux Laptop Orchestra" (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, since it is required to run even *very* old patches created with ancient Pd versions.
Ico Bukvic introduced **Pd-l2ork** in 2010 as a fork of Pd-extended to be used by the "Linux Laptop Orchestra" (L2Ork) he founded at the School of Performing Arts at Virginia Tech. Although the original motivation was to create an improved version of Pd-extended to be used by the L2Ork (hence the name) as well as in education, on Linux it quickly became a more up-to-date alternative to Pd-extended offering a fair number of additional bug fixes and GUI improvements. This is mainly due to its more nimble development model which allows bugfixes and improvements to be deployed quickly even if this may have an impact on backwards compatibility. Vanilla Pd, on the other hand, necessarily has a much firmer outlook on backwards compatibility, so that it is still able to run *very* old patches created with ancient Pd versions.
Despite the many and substantial improvements it offers, Pd-l2ork's GUI is still based on Tcl/Tk. This is both good and bad. The major advantage is compatibility with vanilla Pd. On the other hand, Tcl/Tk looks and feels outdated in this day and age, even when going to some lengths with theming, as Pd-l2ork does. Tcl is a rather basic programming language, and its libraries have been falling behind, making it hard to integrate the latest advancements in GUI, multimedia and web technologies. But most importantly, Pd-l2ork's adoption was seriously hampered by the fact that in order to implement some of the graphical improvements, it relies on some more or less Linux-specific Tcl/Tk extensions, which means that it wouldn't run on Windows or the Mac without substantial effort.
Despite the many and substantial improvements it offers, Pd-l2ork's GUI is still based on Tcl/Tk. This is both good and bad. The major advantage is compatibility with vanilla Pd. On the other hand, Tcl/Tk looks and feels outdated in this day and age, even when going to some lengths with theming, as Pd-l2ork does. Tcl is a rather basic programming language, and its libraries have been falling behind, making it hard to integrate the latest advancements in GUI, multimedia and web technologies. Also, Pd-l2ork's adoption was hampered by the fact that it was essentially tied to Linux, and thus a cross-platform solution was needed.
In 2015 Jonathan Wilkes stepped in and started creating **Purr Data** to address these problems. In a nutshell, Purr Data is Pd-l2ork with the Tcl/Tk GUI part ripped out and replaced with modern web technology. To these ends, it uses a framework called [nw.js](https://nwjs.io/) a.k.a. "node-webkit", which is essentially a stand-alone web browser engine ([Chromium](http://www.chromium.org/)) combined with a JavaScript runtime ([Node.js](http://nodejs.org/)). Both these components are open-source, and while they were originally invented for developing server-side web applications, frameworks like nw.js combine them in a way so that they can be used for creating full-featured and portable desktop applications. Thus nw.js makes sure that Purr Data also runs on Mac and Windows systems, and it also paves the way to leverage standard web technologies such as JavaScript, HTML5 and SVG which have way better support than Tcl/Tk these days. Last but not least, JavaScript is a much more capable and widespread programming language than Tcl, which makes developing Purr Data's graphical user interface a lot easier now that the initial GUI port is done.
In 2015 Jonathan Wilkes stepped in and started creating **Purr Data** to address these problems. In a nutshell, Purr Data is Pd-l2ork with the Tcl/Tk GUI part ripped out and replaced with modern web technology. To these ends, it uses an open-source framework called [nw.js](https://nwjs.io/) a.k.a. "node-webkit", which is essentially a stand-alone web browser engine ([Chromium](http://www.chromium.org/)) combined with a JavaScript runtime ([Node.js](http://nodejs.org/)). While the latter was originally invented for developing server-side web applications, frameworks like nw.js allow the two to be used in concert to create fully-fledged and portable desktop applications. Using nw.js ensures that Purr Data runs on Linux, Mac and Windows, looking the same on all supported platforms, and it paves the way to leverage standard web technologies such as JavaScript, HTML5, CSS3 and SVG.
So Purr Data's GUI is written entirely in JavaScript. Patches are implemented as HTML5 SVG documents which are generally much more responsive and offer better graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. Purr Data also looks better and is easier on the eyes than Pd-l2ork, let alone vanilla Pd, especially on high-dpi displays (cf. Fig. 1).
Purr Data's GUI is written entirely in JavaScript, which is much more advanced than Tcl, offering an abundance of libraries and support materials. This makes the further development of Purr Data's graphical user interface a lot easier now that the initial GUI port is done. Patches are implemented as HTML5 SVG documents which offer better responsiveness and graphical capabilities than Tk windows. They can also be themed using CSS and zoomed like any browser window, improving usability. These features alone make the switch to Purr Data worthwhile. Purr Data also looks better and is easier on the eyes than Pd-l2ork, let alone vanilla Pd, especially on high-dpi displays (cf. Fig. 1).
![Fig. 1: Purr Data running on Mac OSX.](purr-data.png)
Fig. 1: Purr Data running on Mac OSX.
![Fig. 1: Purr Data running on macOS.](purr-data.png)
Fig. 1: Purr Data running on macOS.
Purr Data's nw.js GUI also has some disadvantages. Most notably, some of the included externals still rely on Tcl code, so their GUI features will not work in Purr Data until they get ported to the new GUI. Second, the size of the binary packages is considerably larger than with Pd-l2ork or Pd-extended since, in order to make the packages self-contained, they also include the full nw.js binary distribution. Finally, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with *very* tight memory constraints. None of these should normally be a real show-stopper, however. Just give it a try and see whether it works for your use case and target platform.
Purr Data's nw.js GUI also has some disadvantages. First, some of the included externals still rely on Tcl code, so their GUI features will not work in Purr Data until they get ported to the new GUI. Second, the size of the binary package is considerably larger than with Pd-l2ork or Pd-extended since it also includes the full nw.js binary distribution. (This is a valid concern with many of the so-called "portable desktop applications" being offered these days, but in the case of Purr Data it is mitigated by the fact that its Pd-l2ork base is not exactly a slim package either.) Third, the browser engine has a much higher memory footprint than Tcl/Tk which might be an issue on embedded platforms with *very* tight memory constraints. While none of these issues should normally be a real show-stopper on the supported platforms, it is worth keeping them in mind.
Purr Data is still comparatively young, but its basis is the tried and proven Pd-l2ork, the present release has been thoroughly tested and many bugs have been ironed out, so it is certainly ready for day-to-day use. It also offers some really compelling advancements over its predecessors. If you have been looking for a modern and actively-maintained successor of Pd-extended, this is it.
Finally, Purr Data is still comparatively young, but its basis is the tried and proven Pd-l2ork, the present release has been thoroughly tested and many bugs have been ironed out, so it is certainly ready for day-to-day use. It also offers some really compelling advancements over its predecessors. If you have been looking for a modern and actively-maintained successor of Pd-extended, this is it.
## The Name?
......@@ -45,23 +45,23 @@ We also refer to Bukvic's original Pd-l2ork version as Pd-l2ork 1.0 or "classic"
## Where to Get It
Jonathan Wilkes maintains the Purr Data sources in GitLab at <https://git.purrdata.net/jwilkes/purr-data>. The latest packages for Linux (Debian, Raspbian, Ubuntu), OSX and Windows are available at <https://git.purrdata.net/jwilkes/purr-data-binaries/tree/master>.
Jonathan Wilkes maintains the Purr Data sources in GitLab at <https://git.purrdata.net/jwilkes/purr-data>. The latest packages for Linux (Debian, Raspbian, Ubuntu), macOS and Windows are available in the [download area](https://git.purrdata.net/jwilkes/purr-data-binaries/tree/master) on this site. The Linux packages are in Debian format (.deb files), the Windows package is distributed as a zip file which contains an installer executable (.exe file). Normally you can just run the .deb or .exe packages by double-clicking them in your file manager, and walk through the installation procedure. The Mac package is distributed as a disk image (.dmg file); double-clicking the disk image in Finder opens a new Finder window, in which you can drag the application to your Application folder. The Mac and Windows packages should be self-contained, while the .deb packages will pull in a lot of dependencies, which may require some fiddling. (If you're running Ubuntu or one of its derivatives, and the .deb packages give you trouble, try using the JGU Ubuntu packages instead, see below.)
At JGU we also maintain a collection of Linux packages for Arch Linux (via the Arch User Repositories a.k.a. AUR) and Ubuntu 14.04/16.04 (via Launchpad). More information about these can be found at <http://l2orkaur.bitbucket.org/> (Arch) and <http://l2orkubuntu.bitbucket.org/> (Ubuntu). Besides Purr Data, these repositories also contain the "classic" Pd-l2ork (Ico Bukvic's 1.0 version), as well as two additional programming extensions for Pd which enable you to run Faust and Pure externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.
At JGU we also maintain a collection of Linux packages for Arch Linux (via the [Arch User Repositories](https://aur.archlinux.org/) a.k.a. AUR) and recent Ubuntu releases (via [Launchpad](https://launchpad.net/~dr-graef)). More information and installation instructions can be found at <https://l2orkaur.bitbucket.io/> (Arch) and <https://l2orkubuntu.bitbucket.io/> (Ubuntu). Besides Purr Data, these repositories also contain the "classic" Pd-l2ork (Ico Bukvic's 1.0 version), as well as two additional programming extensions for Pd which enable you to run [Faust](http://faust.grame.fr/) and [Pure](https://purelang.bitbucket.io/) externals in Pd-l2ork and Purr Data. The JGU packages also offer the advantage that they let you install both classic Pd-l2ork and Purr Data on the same system.
Because of the large number of included externals, Purr Data's build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn't officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.
Of course, it is also possible to build Purr Data from source. However, because of the large number of included externals, the build process is rather involved, requires a lot of 3rd party dependencies, and takes quite a while even on modern high-end hardware. Therefore, unless your system isn't officially supported or you have specific requirements forcing you to compile from source, we recommend using the available binaries.
## Getting Started
Once you've installed Purr Data, you can launch it from the desktop environment as usual. On Linux, you can just run `pd-l2ork` from the command line, or look in your desktop environment's program menu or launcher for the `Pd-L2Ork` entry and click on that. (If you installed Purr Data from one of the JGU packages, use the `purr-data` command or the `Purr-Data` desktop icon instead.)
On Mac OSX and Windows, double-click on the application icon (normally to be found in the application or program folder, depending on how you installed it).
On macOS and Windows, double-click on the application icon, normally to be found in the Application folder on macOS and on the desktop on Windows. (If you didn't create a desktop icon during the Windows installation, look for `Purr-Data` in the start menu.)
You can also just double-click on a patch file to have it open in Purr Data. However, this will usually require a first-time setup to tell the file manager that the Pd file type should be opened using the Purr Data application.
You can also right-click on a patch (.pd) file, choose "Open With" and then select Pd-l2ork or Purr Data to open the patch in Purr Data. This may require a first-time setup to associate the .pd file type with the Purr Data program, however. Most desktop environments will also let you set Purr Data as the default application for .pd files, so that you can subsequently open patch files simply with a double-click. The details of this are system-specific; usually right-clicking the file and choosing `Properties` or some similar option (`Get Info` on macOS) will give you a dialog which allows you to change the file association.
In any case, Purr Data should then open its main "console" window which logs all messages from the program. If you double-clicked a patch file, it will be shown in a separate "canvas" window.
In any case, Purr Data should then launch its main "console" window which logs all messages from the program. If you opened a patch file, it will be shown in a separate "canvas" window.
Purr Data understands basically the same set of command line options as vanilla Pd or Pd-l2ork. On Linux, you can find out about these by running `pd-l2ork -help` (`purr-data -help` when using the JGU packages) from the command line. (Right now this isn't easy to do on Mac and Windows, since you'll have to locate the program executable in the application folder.) Some common options which can be placed into the startup flags are `-path` and `-lib`, see section "GUI and Startup Options" below.
Purr Data understands basically the same set of command line options as vanilla Pd or Pd-l2ork. On Linux, you can find out about these by running `pd-l2ork -help` (`purr-data -help` when using the JGU packages) from the command line. (This isn't easy to do on Mac and Windows, since the program executable is stowed away somewhere in the application folder.) Some common options which can be placed into the startup flags are `-path` and `-lib`, see section "GUI and Startup Options" below.
### Single Application Instance
......@@ -126,15 +126,11 @@ If you already know the name of a subdirectory with interesting help patches, yo
Note that in any case, you can always return to the home screen of the help browser by clicking that tiny "x" symbol in the search entry (or by just hitting Enter in the field if it is empty).
## Tips and Tricks
We conclude this primer with a little grab bag of helpful tips and tricks. If your questions aren't answered here, please post them to the DISIS [Pd-l2ork mailing list](http://disis.music.vt.edu/listinfo/l2ork-dev). Questions (and answers) which are of interest to all Purr Data users will likely be added to this section in the future.
### Pd-l2ork and Purr Data goodies
## Pd-l2ork and Purr Data Goodies
Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the [PdCon 2016 paper](http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf) for details. The paper also has a detailed account on the history and motivation of the Pd-l2ork project.
Compared to vanilla Pd, Pd-l2ork and Purr Data provide a comprehensive set of new and improved features, way too many to even just mention them all, so we refer the interested reader to the [PdCon 2016 paper](http://ico.bukvic.net/PDF/PdCon16_paper_84.pdf) for details. The paper also covers the history and motivation of the Pd-l2ork project.
Many of the new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren't even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and the "graph on parent" areas using the mouse. An important new feature is Pd-l2ork's *infinite undo* capability which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they're under development. A helpful change also worth mentioning here is the improved *tidy up* option in the Edit menu, which first aligns objects and then spaces them equidistantly.
One of Pd-l2ork's major advancements over vanilla Pd is its *infinite undo* capability, which makes it easy to revert accidental changes without having to worry about taking snapshots of patches while they're under development. Many of the other new features are simply GUI and usability improvements which, if done right, quickly become second nature to the user, so that they aren't even consciously noticed any more, such as the graphical improvements and the ability to resize the IEM GUI elements and "graph on parent" areas using the mouse. A helpful change also worth mentioning here is the improved *tidy up* option in the Edit menu, which first aligns objects and then spaces them equidistantly.
Another big time-saver is Pd-l2ork's *intelligent patching* facility, which lets you select two or more objects in order to connect multiple outlets and inlets in one go. Intelligent patching offers a number of different modes, the most useful (or at least the easiest) of these are:
......@@ -144,9 +140,13 @@ Another big time-saver is Pd-l2ork's *intelligent patching* facility, which lets
- Also, pressing the shift key while doing connections will let you do multiple connections from the same outlet in one go.
It is worth practicing these so that you can amaze your vanilla-running friends with the speed at which you can construct rather complicated patches using these shortcuts. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little [intelligent-patching.pd](intelligent-patching.pd) patch with this primer for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.
It is worth practicing these so that you can amaze your vanilla-running friends with the speed at which you can construct rather complicated patches using these shortcuts. Unfortunately, neither Pd-l2ork nor Purr Data has a help patch for this incredibly useful facility, so I have provided a little [intelligent-patching.pd](intelligent-patching.pd) patch with this document for your amusement. In the comments, the patch also includes detailed explanations of all the different intelligent patching modes for your perusal.
Other features will be more useful for advanced users, like the reflection capabilities (see the `pdinfo`, `canvasinfo`, `classinfo` and `objectinfo` help patches) and the new SVG elements for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the "Pd-L2Ork Data Structures" section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a "real" programming language.
## Tips and Tricks
Other features will be more useful for advanced users, like the reflection capabilities (see the `pdinfo`, `canvasinfo`, `classinfo` and `objectinfo` help patches) and the new SVG graphics for data structure visualizations. The latter have been considerably enhanced in Purr Data, see the "Pd-L2Ork Data Structures" section in the help browser. They also make it possible to create your own custom GUI elements in plain Pd, without having to learn a "real" programming language.
We conclude this introduction with a little grab bag of helpful tips and tricks. If your questions aren't answered here, please post them to the DISIS [Pd-l2ork mailing list](http://disis.music.vt.edu/listinfo/l2ork-dev).
### Install classic Pd-l2ork alongside Purr Data
......@@ -184,7 +184,7 @@ Sometimes options may seem to stick even if the startup flags field is in fact e
### Purr Data hangs during startup
As far as I can tell, this was only reported on Mac OS X so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message `incoming connection to GUI` in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it ("force quit").
As far as I can tell, this was only reported on macOS so far. The symptom is that the GUI launches, but then hangs during the startup sequence after printing the message `incoming connection to GUI` in the console window. The GUI then becomes totally unresponsive, eating up 100% cpu, and the only way to get rid of it is killing it ("force quit").
The exact causes are unknown right now, but it seems that this behavior may be caused by bad 3rd party externals causing the realtime engine to hang or crash during startup. The GUI then waits for the incoming connection from the engine which never gets established, which makes it hang in turn.
......
No preview for this file type
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment