Purr-Data-Intro.html 57.5 KB
Newer Older
Albert Gräf's avatar
Albert Gräf committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!DOCTYPE html>  
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <title>Purr-Data-Intro</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <style id="mkstylesheet">
/*! normalize.css v3.0.3 | MIT License | github.com/necolas/normalize.css */html{font-family:sans-serif;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;text-size-adjust:100%}body{margin:0}article,aside,details,figcaption,figure,footer,header,hgroup,main,menu,nav,section,summary{display:block}audio,canvas,progress,video{display:inline-block;vertical-align:baseline}audio:not([controls]){display:none;height:0}[hidden],template{display:none}a{background-color:transparent}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:bold}dfn{font-style:italic}h1{font-size:2em;margin:0.67em 0}mark{background:#ff0;color:#000}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-0.5em}sub{bottom:-0.25em}img{border:0}svg:not(:root){overflow:hidden}figure{margin:1em 40px}hr{box-sizing:content-box;height:0}pre{overflow:auto}code,kbd,pre,samp{font-family:monospace, monospace;font-size:1em}button,input,optgroup,select,textarea{color:inherit;font:inherit;margin:0}button{overflow:visible}button,select{text-transform:none}button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}button[disabled],html input[disabled]{cursor:default}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}input{line-height:normal}input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}input[type="number"]::-webkit-inner-spin-button,input[type="number"]::-webkit-outer-spin-button{height:auto}input[type="search"]{-webkit-appearance:textfield;box-sizing:content-box}input[type="search"]::-webkit-search-cancel-button,input[type="search"]::-webkit-search-decoration{-webkit-appearance:none}fieldset{border:1px solid #c0c0c0;margin:0 2px;padding:0.35em 0.625em 0.75em}legend{border:0;padding:0}textarea{overflow:auto}optgroup{font-weight:bold}table{border-collapse:collapse;border-spacing:0}td,th{padding:0}*{box-sizing:border-box}input,select,textarea,button{font:13px/1.4 Helvetica,arial,nimbussansl,liberationsans,freesans,clean,sans-serif,"Segoe UI Emoji","Segoe UI Symbol"}body{font:13px/1.4 Helvetica, arial, nimbussansl, liberationsans, freesans, clean, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol";color:#333;background-color:#fff}a{color:#4078c0;text-decoration:none}a:hover,a:active{text-decoration:underline}hr,.rule{height:0;margin:15px 0;overflow:hidden;background:transparent;border:0;border-bottom:1px solid #ddd}hr:before,.rule:before{display:table;content:""}hr:after,.rule:after{display:table;clear:both;content:""}h1,h2,h3,h4,h5,h6{margin-top:15px;margin-bottom:15px;line-height:1.1}h1{font-size:30px}h2{font-size:21px}h3{font-size:16px}h4{font-size:14px}h5{font-size:12px}h6{font-size:11px}small{font-size:90%}blockquote{margin:0}ul,ol{padding:0;margin-top:0;margin-bottom:0}ol ol,ul ol{list-style-type:lower-roman}ul ul ol,ul ol ol,ol ul ol,ol ol ol{list-style-type:lower-alpha}dd{margin-left:0}tt,code{font-family:Consolas, "Liberation Mono", Menlo, Courier, monospace;font-size:12px}pre{margin-top:0;margin-bottom:0;font:12px Consolas,"Liberation Mono",Menlo,Courier,monospace}html,body{color:black}#wrapper{font:16px helvetica,arial,freesans,clean,sans-serif;-webkit-font-smoothing:antialiased;line-height:1.6;padding:3px;background:#fff;border-radius:3px;-moz-border-radius:3px;-webkit-border-radius:3px;border:solid 1px #dddddd !important;color:#333}p{margin:1em 0}a{color:#4183c4;text-decoration:none}#wrapper{background-color:#fff;padding:30px;margin:15px;font-size:16px;line-height:1.6}#wrapper>*:first-child{margin-top:0 !important}#wrapper>*:last-child{margin-bottom:0 !important}@media screen{#wrapper{border:solid 1px #ddd}}h1,h2,h3,h4,h5,h6{position:relative;margin-top:1em;margin-bottom:16px;font-weight:700;line-height:1.4;color:#333}h1{padding-bottom:.3em;font-size:2.25em;line-height:1.2;border-bottom:1px solid #eee}h2{padding-bottom:0.3em;font-size:1.75em;line-height:1.225;border-bottom:1px solid #eee}h3{font-size:1.5em;line-height:1.43}h4{font-size:1.25em}h5{font-size:1em}h6{color:#777;font-size:1em}p,blockquote,ul,ol,dl,table,pre{margin-top:0;margin-bottom:16px}hr{height:4px;padding:0;margin:16px 0;background-color:#e7e7e7;border:0 none}ul,ol{padding-left:2em}ul.no-list,ol.no-list{padding:0;list-style-type:none}ul ul,ul ol{margin-top:0;margin-bottom:0}ol ol,ol ul{margin-top:0;margin-bottom:0}li>p{margin-top:16px}dl{padding:0}dl dt{padding:0;margin-top:16px;font-size:1em;font-style:italic;font-weight:700}dl dd{padding:0 16px;margin-bottom:16px}blockquote{padding:0 15px;margin-left:0;color:#777;border-left:4px solid #ddd}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}table{display:block;width:100%;overflow:auto}table th{font-weight:700;padding:6px 13px;border:1px solid #ddd}table td{padding:6px 13px;border:1px solid #ddd}table tr{background-color:#fff;border-top:1px solid #ccc}table tr:nth-child(2n){background-color:#f8f8f8}img{max-width:100%;-moz-box-sizing:border-box;box-sizing:border-box}span.frame{display:block;overflow:hidden}span.frame>span{display:block;float:left;width:auto;padding:7px;margin:13px 0 0;overflow:hidden;border:1px solid #ddd}span.frame span img{display:block;float:left}span.frame span span{display:block;padding:5px 0 0;clear:both;color:#333}span.align-center{display:block;overflow:hidden;clear:both}span.align-center>span{display:block;margin:13px auto 0;overflow:hidden;text-align:center}span.align-center span img{margin:0 auto;text-align:center}span.align-right{display:block;overflow:hidden;clear:both}span.align-right>span{display:block;margin:13px 0 0;overflow:hidden;text-align:right}span.align-right span img{margin:0;text-align:right}span.float-left{display:block;float:left;margin-right:13px;overflow:hidden}span.float-left span{margin:13px 0 0}span.float-right{display:block;float:right;margin-left:13px;overflow:hidden}span.float-right>span{display:block;margin:13px auto 0;overflow:hidden;text-align:right}code,tt{padding:0;padding-top:.2em;padding-bottom:.2em;margin:0;font-size:85%;background-color:rgba(0,0,0,0.04);border-radius:3px}code:before,code:after{letter-spacing:-.2em;content:"\00a0"}tt:before,tt:after{letter-spacing:-.2em;content:"\00a0"}code br,tt br{display:none}del code{text-decoration:inherit;vertical-align:text-top}pre>code{padding:0;margin:0;font-size:100%;white-space:pre;background:transparent;border:0}.highlight{margin-bottom:16px}.highlight pre{padding:16px;margin-bottom:0;overflow:auto;font-size:85%;line-height:1.45;background-color:#f7f7f7;border-radius:3px}pre{padding:16px;margin-bottom:16px;overflow:auto;font-size:85%;line-height:1.45;background-color:#f7f7f7;border-radius:3px;word-wrap:normal}pre code,pre tt{display:inline;max-width:initial;padding:0;margin:0;overflow:initial;line-height:inherit;word-wrap:normal;background-color:transparent;border:0}pre code:before,pre code:after{content:normal}pre tt:before,pre tt:after{content:normal}.poetry pre{font-family:Georgia, Garamond, serif !important;font-style:italic;font-size:110% !important;line-height:1.6em;display:block;margin-left:1em}.poetry pre code{font-family:Georgia, Garamond, serif !important;word-break:break-all;word-break:break-word;-webkit-hyphens:auto;-moz-hyphens:auto;hyphens:auto;white-space:pre-wrap}sup,sub,a.footnote{font-size:1.4ex;height:0;line-height:1;vertical-align:super;position:relative}sub{vertical-align:sub;top:-1px}@media print{body{background:#fff}img,table,figure{page-break-inside:avoid}#wrapper{background:#fff;border:none !important;font-size:12px}pre code{overflow:visible}}@media screen{body.inverted{color:#eee !important;border-color:#555;box-shadow:none}.inverted #wrapper,.inverted hr,.inverted p,.inverted td,.inverted li,.inverted h1,.inverted h2,.inverted h3,.inverted h4,.inverted h5,.inverted h6,.inverted th,.inverted .math,.inverted caption,.inverted dd,.inverted dt,.inverted blockquote{color:#eee !important;border-color:#555;box-shadow:none}.inverted td,.inverted th{background:#333}.inverted pre,.inverted code,.inverted tt{background:#eeeeee !important;color:#111}.inverted h2{border-color:#555555}.inverted hr{border-color:#777;border-width:1px !important}::selection{background:rgba(157,193,200,0.5)}h1::selection{background-color:rgba(45,156,208,0.3)}h2::selection{background-color:rgba(90,182,224,0.3)}h3::selection,h4::selection,h5::selection,h6::selection,li::selection,ol::selection{background-color:rgba(133,201,232,0.3)}code::selection{background-color:rgba(0,0,0,0.7);color:#eeeeee}code span::selection{background-color:rgba(0,0,0,0.7) !important;color:#eeeeee !important}a::selection{background-color:rgba(255,230,102,0.2)}.inverted a::selection{background-color:rgba(255,230,102,0.6)}td::selection,th::selection,caption::selection{background-color:rgba(180,237,95,0.5)}.inverted{background:#0b2531;background:#252a2a}.inverted #wrapper{background:#252a2a}.inverted a{color:#acd1d5}}.highlight{background:#fff}.highlight .c{color:#998;font-style:italic}.highlight .err{color:#a61717;background-color:#e3d2d2}.highlight .k,.highlight .o{font-weight:700}.highlight .cm{color:#998;font-style:italic}.highlight .cp{color:#999;font-weight:700}.highlight .c1{color:#998;font-style:italic}.highlight .cs{color:#999;font-weight:700;font-style:italic}.highlight .gd{color:#000;background-color:#fdd}.highlight .gd .x{color:#000;background-color:#faa}.highlight .ge{font-style:italic}.highlight .gr{color:#a00}.highlight .gh{color:#999}.highlight .gi{color:#000;background-color:#dfd}.highlight .gi .x{color:#000;background-color:#afa}.highlight .go{color:#888}.highlight .gp{color:#555}.highlight .gs{font-weight:700}.highlight .gu{color:purple;font-weight:700}.highlight .gt{color:#a00}.highlight .kc,.highlight .kd,.highlight .kn,.highlight .kp,.highlight .kr{font-weight:700}.highlight .kt{color:#458;font-weight:700}.highlight .m{color:#099}.highlight .s{color:#d14}.highlight .n{color:#333}.highlight .na{color:teal}.highlight .nb{color:#0086b3}.highlight .nc{color:#458;font-weight:700}.highlight .no{color:teal}.highlight .ni{color:purple}.highlight .ne,.highlight .nf{color:#900;font-weight:700}.highlight .nn{color:#555}.highlight .nt{color:navy}.highlight .nv{color:teal}.highlight .ow{font-weight:700}.highlight .w{color:#bbb}.highlight .mf,.highlight .mh,.highlight .mi,.highlight .mo{color:#099}.highlight .sb,.highlight .sc,.highlight .sd,.highlight .s2,.highlight .se,.highlight .sh,.highlight .si,.highlight .sx{color:#d14}.highlight .sr{color:#009926}.highlight .s1{color:#d14}.highlight .ss{color:#990073}.highlight .bp{color:#999}.highlight .vc,.highlight .vg,.highlight .vi{color:teal}.highlight .il{color:#099}.highlight .gc{color:#999;background-color:#EAF2F5}.type-csharp .highlight .k,.type-csharp .highlight .kt{color:blue}.type-csharp .highlight .nf{color:#000;font-weight:400}.type-csharp .highlight .nc{color:#2b91af}.type-csharp .highlight .nn{color:#000}.type-csharp .highlight .s,.type-csharp .highlight .sc{color:#a31515}.type-csharp .highlight .k,.type-csharp .highlight .kt{color:#00F}.type-csharp .highlight .nf{color:#000;font-weight:normal}.type-csharp .highlight .nc{color:#2B91AF}.type-csharp .highlight .nn{color:#000}.type-csharp .highlight .s,.type-csharp .highlight .sc{color:#A31515}body.dark #wrapper{background:transparent !important;box-shadow:none !important}
#mkreplaced-toc{list-style-position:inside;padding:0;margin:0 0 0 1rem;list-style-type:none}#mkreplaced-toc li::before{content:''}#mkreplaced-toc li{font-size:1rem;line-height:1.25;font-weight:normal}#mkreplaced-toc li ul{font-size:1.3rem;font-weight:300;padding:.5rem 0;margin:0 0 0 1rem}#mkreplaced-toc li.missing{list-style-type:none !important}#mkreplaced-toc.max-1 ul,#mkreplaced-toc.max1 ul{display:none}#mkreplaced-toc.max-2 ul ul,#mkreplaced-toc.max2 ul ul{display:none}#mkreplaced-toc.max-3 ul ul ul,#mkreplaced-toc.max3 ul ul ul{display:none}#mkreplaced-toc.max-4 ul ul ul ul,#mkreplaced-toc.max4 ul ul ul ul{display:none}#mkreplaced-toc.max-5 ul ul ul ul ul,#mkreplaced-toc.max5 ul ul ul ul ul{display:none}.rtl{direction:rtl;text-align:right}@media print{body{background:white;line-height:1.4}html,body,#wrapper{max-width:100%;width:100%;-webkit-text-size-adjust:none;-webkit-perspective:none !important;box-sizing:border-box;width:auto;border:0;margin:0;padding:0;float:none;-moz-box-shadow:none !important;-webkit-box-shadow:none !important;box-shadow:none !important}mark{background:transparent !important}h1,h2,h3,h4,h5,h6{page-break-after:avoid}p,h2,h3{orphans:3;widows:3}section{page-break-before:avoid}pre>code{white-space:pre;word-break:break-word}#generated-toc,#firstdiff,#toc-title,#mkdocumentprogress,#mkincludechart,#mkprogressbar1,#mkprogressbar2,.mkscrollmeter,#alllinks,.popup{display:none !important}.suppressprintlinks a{color:inherit !important;text-decoration:none !important;border-bottom:none !important;cursor:default !important}.hrefafterlinktext #wrapper a:link:after,.hrefafterlinktext #wrapper a:visited:after{content:" (" attr(href) ") ";font-size:90%;opacity:0.9}.nocodebreak pre{page-break-inside:avoid}img,table,figure{page-break-inside:avoid}.breakfootnotes .footnotes{page-break-before:always}.breakfootnotes .footnotes hr{display:none}#mktoctitle{display:block}#print-title{display:block;border-bottom:solid 1px #666}#wrapper pre{white-space:pre;white-space:pre-wrap;word-wrap:break-word}#wrapper #generated-toc-clone,#wrapper #mkreplaced-toc{display:block}.task-list .task-list-item{list-style-type:none !important}.task-list .gh-complete.task-list-item .task-list-item-checkbox:before{content:'\2713';background:#838387}.task-list .task-list-item-checkbox{-webkit-appearance:none;position:relative}.task-list .task-list-item-checkbox:before{content:' ';border:solid 1px #aaa;width:1em;height:1em;display:block;border-radius:2px;left:-20px;top:-.75em;color:white;font-weight:bold;line-height:1;text-align:center;position:absolute}}
#wrapper #generated-toc-clone,#wrapper #mkreplaced-toc,#wrapper #generated-toc-clone ul,#wrapper #mkreplaced-toc ul{list-style-position:inside}#wrapper #generated-toc-clone li.missing,#wrapper #mkreplaced-toc li.missing{list-style-type: none!important}#wrapper #generated-toc-clone,#wrapper #mkreplaced-toc{list-style-type: upper-roman}#wrapper #generated-toc-clone>li>ul,#wrapper #mkreplaced-toc>li>ul {list-style-type: decimal}#wrapper #generated-toc-clone>li>ul>li>ul,#wrapper #mkreplaced-toc>li>ul>li>ul{list-style-type: decimal-leading-zero}#wrapper #generated-toc-clone>li>ul>li>ul>li>ul,#wrapper #mkreplaced-toc>li>ul>li>ul>li>ul{list-style-type: lower-greek}#wrapper #generated-toc-clone>li>ul>li>ul>li>ul>li>ul,#wrapper #mkreplaced-toc>li>ul>li>ul>li>ul>li>ul{list-style-type: disc}#wrapper #generated-toc-clone>li>ul>li>ul>li>ul>li>ul>li>ul,#wrapper #mkreplaced-toc>li>ul>li>ul>li>ul>li>ul>li>ul{list-style-type: square}#wrapper #generated-toc-clone,#wrapper #mkreplaced-toc{list-style-position:outside!important;margin-left:2rem;}
</style>

<style id="mkprintstyles">@media print{
html,body,#wrapper{font-size:10pt!important}
}
</style>


</head>
Albert Gräf's avatar
Albert Gräf committed
21
<body class="normal">
Albert Gräf's avatar
Albert Gräf committed
22
23
24
25
26
27
28
29
  <div id="wrapper">
      <h1 id="meetthecat:aquickintroductiontopurrdata">Meet the Cat: A Quick Introduction to Purr Data</h1>

<p>Albert Gräf <a href="mailto:aggraef@gmail.com">aggraef@gmail.com</a><br/>
Computer Music Dept., Institute of Art History and Musicology<br/>
Johannes Gutenberg University (JGU) Mainz, Germany<br/>
February 2017</p>

30
31
32
<p>This document is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>.
Other formats: <a href="Purr-Data-Intro.md">Markdown</a> source, <a href="Purr-Data-Intro.pdf">PDF</a><br/>
Permanent link: <a href="https://agraef.github.io/purr-data-intro/">https://agraef.github.io/purr-data-intro/</a></p>
33
34

<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>. This document provides new or prospective Purr Data users with a gentle introduction to the program and some helpful information to get started.</p>
Albert Gräf's avatar
Albert Gräf committed
35
36
37

<h2 id="whatispurrdata">What is Purr Data?</h2>

Albert Gräf's avatar
Albert Gräf committed
38
<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>
Albert Gräf's avatar
Albert Gräf committed
39

Albert Gräf's avatar
Albert Gräf committed
40
<p>Puckette&#8217;s version of the program is sometimes 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 <strong>flavors</strong>.</p>
Albert Gräf's avatar
Albert Gräf committed
41

Albert Gräf's avatar
Albert Gräf committed
42
<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>
Albert Gräf's avatar
Albert Gräf committed
43

Albert Gräf's avatar
Albert Gräf committed
44
<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>
Albert Gräf's avatar
Albert Gräf committed
45

Albert Gräf's avatar
Albert Gräf committed
46
<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>
Albert Gräf's avatar
Albert Gräf committed
47

48
<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 <a href="https://en.wikipedia.org/wiki/JavaScript">JavaScript</a>, <a href="https://www.w3.org/TR/html5/">HTML5</a>, <a href="https://www.w3.org/Style/CSS/">CSS3</a> and <a href="https://www.w3.org/TR/SVG/">SVG</a>.</p>
Albert Gräf's avatar
Albert Gräf committed
49

50
<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. 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>
Albert Gräf's avatar
Albert Gräf committed
51

Albert Gräf's avatar
Albert Gräf committed
52
53
<p><img src="purr-data.png" alt="Fig. 1: Purr Data running on macOS." /><br/>
Fig. 1: Purr Data running on macOS.</p>
Albert Gräf's avatar
Albert Gräf committed
54

Albert Gräf's avatar
Albert Gräf committed
55
<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>
Albert Gräf's avatar
Albert Gräf committed
56

Albert Gräf's avatar
Albert Gräf committed
57
<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>
Albert Gräf's avatar
Albert Gräf committed
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

<h2 id="thename">The Name?</h2>

<p>Purr Data is the official nickname of the Pd-l2ork 2.x branch. To quote chief developer Jonathan Wilkes from his initial announcement on the <a href="http://forum.pdpatchrepo.info/topic/9956/gui-port-of-pd-l2ork-alpha-0-release">Pd forum</a>:</p>

<p><img src="purr.png" align="right"/></p>

<blockquote>
<p>I&#8217;ve nicknamed it &#8220;Purr Data&#8221;, because cats.</p>
</blockquote>

<p>Quite obviously the name is a play on &#8220;Pure Data&#8221; on which &#8220;Purr Data&#8221; is ultimately based. It also raises positive connotations of soothing purring sounds, and makes for a nice logo.</p>

<p>We also refer to Bukvic&#8217;s original Pd-l2ork version as Pd-l2ork 1.0 or &#8220;classic&#8221; Pd-l2ork. Note that Purr Data still clearly shows its Pd-l2ork heritage. It shares a lot of code with Pd-l2ork (essentially all the non-GUI parts), and the executable, library directory etc. are all still named pd-l2ork as well.</p>

<h2 id="wheretogetit">Where to Get It</h2>

Albert Gräf's avatar
Albert Gräf committed
75
<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>
Albert Gräf's avatar
Albert Gräf committed
76

Albert Gräf's avatar
Albert Gräf committed
77
<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>
Albert Gräf's avatar
Albert Gräf committed
78

Albert Gräf's avatar
Albert Gräf committed
79
<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>
Albert Gräf's avatar
Albert Gräf committed
80
81
82

<h2 id="gettingstarted">Getting Started</h2>

Albert Gräf's avatar
Albert Gräf committed
83
<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>
Albert Gräf's avatar
Albert Gräf committed
84

Albert Gräf's avatar
Albert Gräf committed
85
<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>
Albert Gräf's avatar
Albert Gräf committed
86

Albert Gräf's avatar
Albert Gräf committed
87
<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>
Albert Gräf's avatar
Albert Gräf committed
88

Albert Gräf's avatar
Albert Gräf committed
89
<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>
Albert Gräf's avatar
Albert Gräf committed
90

Albert Gräf's avatar
Albert Gräf committed
91
<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>
Albert Gräf's avatar
Albert Gräf committed
92
93
94

<h3 id="singleapplicationinstance">Single Application Instance</h3>

Albert Gräf's avatar
Albert Gräf committed
95
96
97
<p>Unlike vanilla Pd, Purr Data always runs as a <em>single application instance</em>. If you load additional patch files (by invoking the <code>pd-l2ork</code> executable or by clicking patch files in the file manager), they will be opened as new canvas windows in that single unique instance. This prevents the kind of confusion which often arises with vanilla Pd if you accidentally open different patches in different instances of the application. Pd requires that patches are loaded in the same program instance if they are to communicate via Pd&#8217;s built-in messaging system (send/receive), or if you&#8217;d like to copy/paste subpatches between them using the internal clipboard. Purr Data makes sure that this is always the case.</p>

<p>Please note that this also means that Purr Data&#8217;s real-time processing is all done in a single process right now. In the future, it will become possible to run different patches on different instances of the real-time engine in order to take advantage of the multi-processing capabilities on modern multi-core systems, but this hasn&#8217;t been implemented yet.</p>
Albert Gräf's avatar
Albert Gräf committed
98
99
100
101
102
103
104
105
106
107
108
109

<h2 id="configuration">Configuration</h2>

<p>When you launch Purr Data for the first time, most likely you will have to configure some things, such as the audio and MIDI devices that you want to use. Like Pd-l2ork, Purr Data provides a central &#8220;Preferences&#8221; dialog which lets you do this in a convenient way.</p>

<h3 id="audioandmididevices">Audio and MIDI Devices</h3>

<p>The following screenshot (Fig. 2) shows how the &#8220;Audio&#8221; and &#8220;MIDI&#8221; tabs in this dialog look like on the Mac. For most purposes it should be sufficient to just select the audio and MIDI inputs and outputs that you want to use from the corresponding dropdown lists. Pressing the <code>Apply</code> button applies the settings <em>without</em> closing the dialog or saving the options permanently. If you want to make your changes permanent, you must use the <code>Ok</code> button instead. This also closes the dialog.</p>

<p><img src="prefs-audio+midi.png" alt="Fig. 2: Audio and MIDI setup." /><br/>
Fig. 2: Audio and MIDI setup.</p>

Albert Gräf's avatar
Albert Gräf committed
110
111
<p>You can redo this procedure at any time if needed. Note that it is usually possible to select multiple input and output devices, but this depends on the platform and the selected audio/MIDI back-end or &#8220;API&#8221;. Also note that on Linux (using the ALSA API), the MIDI tab will only allow you to set the number of ALSA MIDI input/output ports to be created; you then still have to use a MIDI patchbay program such as <a href="https://qjackctl.sourceforge.io/">qjackctl</a> to connect these ports to the hardware devices as needed.</p>

Albert Gräf's avatar
Albert Gräf committed
112
113
114
115
<p>One pitfall of the Pd engine is that it does not rescan the devices if you connect new external audio or MIDI gear while Purr Data is already running. Thus you need to relaunch the program to make the new devices show up in the preferences. In the case of MIDI, it is easy to work around this limitation by employing virtual MIDI devices, which ALSA MIDI does by default. On the Mac you&#8217;d use the <a href="https://sites.google.com/site/mfalab/mac-stuff/how-to-use-the-iac-driver">IAC</a> devices, on Windows a MIDI loopback driver such as <a href="http://www.tobias-erichsen.de/software/loopmidi.html">loopMIDI</a> for that purpose. You then wire these up to the MIDI hardware using a separate patchbay program. A similar approach is possible with audio loopback software such as <a href="http://www.jackaudio.org/">Jack</a>.</p>

<h3 id="guiandstartupoptions">GUI and Startup Options</h3>

Albert Gräf's avatar
Albert Gräf committed
116
<p>The GUI theme can be selected on the &#8220;GUI&#8221; tab (see Fig. 3, left). The changes will be applied immediately. Purr Data provides various different GUI themes out of the box. Note that the GUI themes are in fact just CSS files in Purr Data&#8217;s library directory, so if you&#8217;re familiar with HTML5 and CSS then you can easily change them or create your own. Another useful option on the GUI tab is &#8220;save/load zoom level with patch&#8221;. Purr Data can zoom any patch window to 16 different levels, and this option, when enabled, allows you to store the current zoom level when a patch is saved, and then later restore the zoom level when the patch gets reloaded.</p>
Albert Gräf's avatar
Albert Gräf committed
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

<p><img src="prefs-gui+startup.png" alt="Fig. 3: GUI and Startup options." /><br/>
Fig. 3: GUI and Startup options.</p>

<p>The final tab in the preferences dialog is the &#8220;Startup&#8221; tab (Fig. 3, right), which lets you edit the lists of library paths and startup libraries, as well as the additional options the program is to be invoked with. By default, Purr Data loads most bundled external libraries at startup and adds the corresponding directories to its library search path. If you don&#8217;t need all of these, you can remove individual search paths and/or libraries using the &#8220;Search Paths&#8221; and &#8220;Libraries&#8221; lists on the Startup tab. Just click on a search path or library and click the <code>Delete</code> button. It is also possible to select an item and add your own search paths and external libraries with the <code>New</code> button, or change an existing entry with the <code>Edit</code> button.</p>

<p>At the bottom of the Startup tab there is a &#8220;Startup Flags&#8221; field which lets you specify which additional options the program should be invoked with. This is commonly used to add options like <code>-legacy</code> (which enforces bug compatibility with vanilla Pd) as well as the <code>-path</code> and <code>-lib</code> options which provide an alternative way to add search paths and external libraries. For instance, to add JGU&#8217;s Pure and Faust extensions to the startup libraries, the Startup Flags field may contain something like the following: <code>-lib pure -lib faust/pdfaust</code></p>

<p>Any desired startup options can be set that way, i.e., anything that Pd usually accepts on the command line. However, note that the startup flags require that you relaunch Purr Data for the options to take effect (the same is true if you change the list of startup libraries). Also, while setting paths and libraries via the startup flags is often convenient, there are some downsides to having these options in two different places, see &#8220;Sticky preferences&#8221; in the &#8220;Tips and Tricks&#8221; section below.</p>

<p>As with the other configuration options, remember to press the <code>Ok</code> button in order to have your changes recorded in permanent storage. This will also close the dialog.</p>

<p>Finally, note that if your configuration gets seriously messed up, there are ways to reset Purr Data to its default configuration, see &#8220;Resetting the preferences&#8221; in the &#8220;Tips and Tricks&#8221; section.</p>

<h2 id="gettinghelp">Getting Help</h2>

<p>The best way for new users to learn how to use Purr Data, and Pd in general, is its excellent integrated help system. This is really one of the hallmark features of the Pd program, no matter which flavor you use. Purr Data&#8217;s help system offers hundreds of help patches covering many different areas, and these help patches are not just documentation, they are <em>real</em> Pd patches which you can run to try them out, and then copy and paste relevant parts to your own patches.</p>

<p>It is worth noting here that Purr Data, like Pd-l2ork, continues to build on the Pd-extended documentation efforts. This includes over 200 new and updated help files, including the cyclone library documentation. All of the new help files provide supporting meta info contained within the META subpatch (which is needed, in particular, to enable keyword searches), following the standards set by the Pd documentation project (PDDP). This is an ongoing effort, however, and so not all help patches have been converted yet.</p>

<p>While the sheer amount of help patches can be overwhelming at first, there are some sections in the documentation which are organized as tutorials, so that you can work through them step by step. This includes all the help patches that go along with Miller Puckette&#8217;s comprehensive book <a href="http://msp.ucsd.edu/techniques.htm">&#8220;Theory and Techniques of Electronic Music&#8221;</a>, which are still the best way to get to grips with Pd. If you are new to Pd, we recommend that you work at least through the sections &#8220;Control Tutorials&#8221; and &#8220;Audio Tutorials&#8221;, and <em>really</em> try to understand what&#8217;s going on in these patches. With a complex software like Pd, it&#8217;s all too easy to fall victim to &#8220;cargo cult&#8221; habits if you just blindly copy parts of other people&#8217;s patches. You should resist that temptation, at least until you have a solid foundation under your belt, and those two sections will provide you with that.</p>

<p>Purr Data&#8217;s central point of entry to the help system is its <em>Help Browser</em>, discussed below. In addition, as with other Pd flavors, it is also possible to open the help patch for an object by just right-clicking on that object in a patch and choosing the &#8220;Help&#8221; menu item. </p>

<h3 id="thehelpbrowser">The Help Browser</h3>

<p>Using the Help / Help Browser menu option (shortcut: ctrl + B, or cmd + B on the Mac) fires up Purr Data&#8217;s help browser, which looks deceptively simple (see Fig. 4) and is actually quite easy to use, but offers a lot of functionality under the hood. You can search for object names or keywords by typing them in the search entry field at the top of the browser, or you can browse the available documentation sections in the browser&#8217;s <em>home screen</em>, which is what gets shown initially below the search entry, by just clicking on one of the section titles.</p>

<p><img src="browser.png" alt="Fig. 4: Help browser." /><br/>
Fig. 4: Help browser.</p>

Albert Gräf's avatar
Albert Gräf committed
148
149
<p>On the right in Fig. 4 you can see how the display changes after you entered a search term like &#8220;audio devices&#8221; and hit Enter. All related help patches will be shown in the list (with short descriptions of the help patches if available). You can then click on one of the help patches to open it in a canvas window. Clicking on the &#8220;x&#8221; symbol in the search entry returns you to the home screen.</p>

Albert Gräf's avatar
Albert Gräf committed
150
151
152
153
154
155
<p>Note that to keep things simple and not to overwhelm novice users with too much information, the search function only covers the &#8220;official&#8221; documentation (the doc/ hierarchy). To explore all the other help patches which are available in the extra/ hierarchy (which contains all the 3rd party abstractions and externals), you must employ the little folder icon to the right of the search entry. This will open a file browser (initially on the doc/ folder) which can then be used to browse <em>all</em> the available help patches. When looking for help patches in the extra/ hierarchy, which is a sibling of doc/, simply point the file browser to that directory and click on one of its subdirectories containing the various abstractions and externals. Double-clicking on a help patch will open the patch in its own window, and then also show the corresponding directory in the help browser, so that additional help patches from the same folder can be accessed without any further ado.</p>

<p>If you already know the name of a subdirectory with interesting help patches, you can also just type its name in the search entry (including the doc/ or extra/ prefix) to have the corresponding folder displayed in the help browser. For instance, typing &#8220;extra/mrpeach&#8221; and Enter provides a quick way to access the help patches for the mrpeach externals.</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>

Albert Gräf's avatar
Albert Gräf committed
156
<h2 id="pd-l2orkandpurrdatagoodies">Pd-l2ork and Purr Data Goodies</h2>
Albert Gräf's avatar
Albert Gräf committed
157

Albert Gräf's avatar
Albert Gräf committed
158
<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>
Albert Gräf's avatar
Albert Gräf committed
159

Albert Gräf's avatar
Albert Gräf committed
160
<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>
Albert Gräf's avatar
Albert Gräf committed
161
162
163
164
165
166
167
168
169

<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>

<ul>
<li><p>If you select <em>exactly</em> two objects A and B, say, and then connect one of the outlets from A to one of the inlets of B, then starting from the initial outlet-inlet pair the remaining outlets of A will be connected to the corresponding inlets of B.</p></li>
<li><p>If you select two (or more) objects B and C, say, and then connect an outlet of a third, unselected object A to an inlet of B, then the corresponding connection from A to C will be done automatically. Conversely, you can also connect an outlet of B to an inlet of A to have the corresponding C-A connection completed for you.</p></li>
<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>

Albert Gräf's avatar
Albert Gräf committed
170
171
172
173
174
<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>
Albert Gräf's avatar
Albert Gräf committed
175

Albert Gräf's avatar
Albert Gräf committed
176
<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>
Albert Gräf's avatar
Albert Gräf committed
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

<h3 id="installclassicpd-l2orkalongsidepurrdata">Install classic Pd-l2ork alongside Purr Data</h3>

<p>On Linux there are some situations where you may want to run <em>both</em> classic Pd-l2ork and Purr Data on the same system. This may be useful, e.g., if you need some feature of Pd-l2ork like its K12 mode which hasn&#8217;t been ported to Purr Data yet. In order to do this, you need one of the JGU packages of Purr Data (see &#8220;Where to Get It&#8221; above). These will install into a separate directory (normally <code>/opt/purr-data</code>) so that the pathnames of the binaries and libraries in the package do not clash with those from a classic Pd-l2ork installation under <code>/usr</code>. The desktop icons will be named differently as well, and a symbolic link named <code>purr-data</code> will be created in the <code>/usr/bin</code> directory. The link points to <code>/opt/purr-data/bin/pd-l2ork</code> and lets you run Purr Data from the command line without having to specify the full path to the executable. Last but not least, the JGU packages have also been patched up so that they use a separate <code>.purr-data</code> configuration directory in your home directory instead of Pd-l2ork&#8217;s <code>.pd-l2ork</code> folder, so that the two programs can happily coexist.</p>

<h3 id="installingexternals">Installing externals</h3>

<p>Purr Data already bundles many if not most of the 3rd party externals commonly used by Pd users. To add even more, there are some special directories into which you can install the externals so that Purr Data finds them. This is basically the same as with Pd-extended, but the directories are named differently so that you can keep the Purr Data externals separate from the vanilla/extended ones if needed. There&#8217;s always one location for system-wide and another one for personal installation. The precise locations and names of these directories depend on your platform:</p>

<ul>
<li>Linux: <code>/usr/lib/pd-l2ork-externals</code> for system-wide, <code>~/pd-l2ork-externals</code> for personal installation</li>
<li>Mac: <code>/Library/Pd-l2ork</code> for system-wide, <code>~/Library/Pd-l2ork</code> for personal installation</li>
<li>Windows: <code>%ProgramFiles%\Common Files\Pd-l2ork</code> for system-wide, <code>%UserProfile%\Application Data\Pd-l2ork</code> for personal installation</li>
</ul>

<p>For singleton externals it will usually be enough if you just copy them into one of these folders and then relaunch Purr Data. External libraries containing a collection of different externals, on the other hand, will typically require that you also load the library at startup, using the available startup configuration options in the preferences (see &#8220;GUI and Startup Options&#8221; above). </p>

<h3 id="resettingthepreferences">Resetting the preferences</h3>

<p>It happens to the best of us that we mess up our Pd configuration so badly that it is beyond repair. In such a case you probably want to go back to Purr Data&#8217;s default setup and start from a clean slate again. Unfortunately, Purr Data&#8217;s preferences dialog does not provide a button for this (yet), but there are ways to accomplish this. They depend on the particular platform, however.</p>

<ul>
<li><p>On Linux, do <code>rm -rf ~/.pd-l2ork</code> in the terminal (<code>rm -rf ~/.purr-data</code> when using the JGU packages).</p></li>
<li><p>On the Mac, do <code>rm ~/Library/Preferences/org.puredata.pd-l2ork.plist</code> in the terminal.</p></li>
<li><p>On Windows, launch the <code>regedit</code> program and look for the registry key <code>HKEY_CURRENT_USER\Software\Purr-Data</code> or <code>HKEY_LOCAL_MACHINE\Software\Purr-Data</code>. Delete that key and all its subkeys.</p></li>
</ul>

<p>Then just relaunch Purr Data. Your preferences should now be in pristine state again, and all the default search paths and startup libraries will be restored. Of course, you will then have to reconfigure your audio and MIDI devices as needed.</p>

Albert Gräf's avatar
Albert Gräf committed
206
207
208
209
210
211
212
213
<h3 id="stickypreferences">&#8220;Sticky&#8221; preferences</h3>

<p>One pitfall with Purr Data&#8217;s preferences system (which it shares with its predecessors) is that some options in the startup flags may override other changes done manually in the preferences dialog, and will then appear to &#8220;stick&#8221; when you relaunch Purr Data. E.g., if a library gets loaded via the <code>-lib</code> option in the startup flags, it will <em>also</em> show up in the list of libraries next time you run Purr Data. But if you just remove it there, and not also in the startup flags, then the library will <em>still</em> be loaded next time you run Purr Data. The same caveat applies if you have some options setting up aspects of the audio and MIDI configuration in the startup flags and then reconfigure your devices in the Audio and MIDI tabs of the dialog. Thus, if Purr Data appears to stick to a certain audio or MIDI setup even though you&#8217;re certain that you set (and saved) a new configuration, check the startup flags, they&#8217;re almost certainly to blame. (Another possible culprit are the Linux desktop files, see below.) </p>

<p>This irritating behavior is due to how Pd handles the startup flags, especially flags which may override some behavior in other configuration options. The easiest way to get rid of all these mishaps is to remove the relevant options in the startup flags (when in doubt, just delete them all so that the startup flags field is completely empty) and save your options by clicking <code>Ok</code> in the preferences dialog.</p>

<p>Sometimes options may seem to stick even if the startup flags field is in fact empty, so that the preferences dialog appears to be partially dysfunctional. This is almost certainly due to some stray startup options in the application&#8217;s desktop files, most likely on Linux (Pd-l2ork&#8217;s original desktop files, which Purr Data inherited in the Linux version, seem to be the main culprit here). Remove the offending options in the desktop icons that you use to launch Purr Data, then this will go away. (Again, when in doubt, just remove <em>all</em> of the extra options in the desktop file, so that just the program name remains; none of these options are essential for Purr Data&#8217;s proper operation.)</p>

Albert Gräf's avatar
Albert Gräf committed
214
215
<h3 id="purrdatahangsduringstartup">Purr Data hangs during startup</h3>

Albert Gräf's avatar
Albert Gräf committed
216
<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>
Albert Gräf's avatar
Albert Gräf committed
217
218
219
220
221
222
223
224
225
226

<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>

<p>As it&#8217;s impossible to launch the GUI and remove the offending external in the preferences dialog in this rather unfortunate situation, the only known solution to this problem is to reset the configuration (see &#8220;Resetting the preferences&#8221; above), after which Purr Data hopefully launches without any hitches again. If you&#8217;re feeling adventurous, you may then start adding your local externals one by one until the GUI hangs again, at which point you will have identified the culprit, so that you can remove it from your system.</p>

<h3 id="purrdatastartsupveryslowly">Purr Data starts up very slowly</h3>

<p>Again, this seems to be a Mac-specific issue. Older (pre&#8211;2.0) Mac versions of Purr Data had the defect that old search paths and startup libraries from previous installations would keep piling up in the configuration until eventually Purr Data&#8217;s startup would become <em>very</em> slow. This has been fixed in the 2.0 version (and startup time on the Mac has generally been improved as well), but if you&#8217;re still using an old configuration from the pre&#8211;2.0 days, then you might still see remnants of this issue even in the 2.0 version.</p>

<p>One thing you can try in this case is to launch the preferences dialog, press <code>Ok</code> and then quit and relaunch Purr Data. If that doesn&#8217;t help, reset the configuration as explained under &#8220;Resetting the preferences&#8221; above. (If that doesn&#8217;t help either, then you probably have a different issue which you should report on Purr Data&#8217;s <a href="https://git.purrdata.net/jwilkes/purr-data/issues">issue tracker</a>.)</p>
Albert Gräf's avatar
Albert Gräf committed
227
228
229
230
231
232
233

<h3 id="legacytclcommandsinexternals">Legacy Tcl commands in externals</h3>

<p>Every so often you may run into warnings about &#8220;legacy Tcl commands&#8221; in Purr Data&#8217;s console window which typically look like this:</p>
<pre><code class="(null)">legacy tcl command at 201 of ../shared/hammer/file.c: hammereditor_close .86439b0 0</code></pre>

<p>In most cases these should be harmless, but they may indicate a missing piece of GUI functionality due to Tcl code which has not been ported to Purr Data&#8217;s new nw.js GUI yet. In any case, feel free to report such messages at Purr Data&#8217;s <a href="https://git.purrdata.net/jwilkes/purr-data/issues">issue tracker</a>, so that hopefully someone from the development team can look into them. A proper bug report should at least include the message itself and the Pd object it relates to. If some special steps are needed to reproduce the message, you should report these as well. Also, please do make sure <em>first</em> that the specific message you&#8217;re seeing has not been reported in the issue tracker already.</p>
Albert Gräf's avatar
Albert Gräf committed
234
235
236
237
238
239
240
241
242
<!-- ##END MARKED WRAPPER## -->
    </div>



<script>(function(factory){if(typeof define==="function"&&define.amd){define("bidi_helpers",[],factory)}else{window.bidi_helpers=factory()}})(function(){var module={};module.Dir={RTL:-1,UNKNOWN:0,LTR:1};module.Format={LRE:"\u202A",RLE:"\u202B",PDF:"\u202C",LRM:"\u200E",RLM:"\u200F"};module.ltrChars_="A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02B8\u0300-\u0590\u0800-\u1FFF\u2C00-\uFB1C\uFE00-\uFE6F\uFEFD-\uFFFF";module.rtlChars_="\u0591-\u07FF\uFB1D-\uFDFF\uFE70-\uFEFC";module.ltrDirCheckRe_=new RegExp("^[^"+module.rtlChars_+"]*["+module.ltrChars_+"]");module.ltrCharReg_=new RegExp("["+module.ltrChars_+"]");module.hasAnyLtr=function(text){return module.ltrCharReg_.test(text)};module.rtlDirCheckRe_=new RegExp("^[^"+module.ltrChars_+"]*["+module.rtlChars_+"]");module.rtlRe=module.rtlDirCheckRe_;module.isRtlText=function(text){return module.rtlDirCheckRe_.test(text)};module.isLtrText=function(text){return module.ltrDirCheckRe_.test(text)};module.isRequiredLtrRe_=/^http:\/\/.*/;module.hasNumeralsRe_=/\d/;module.estimateDirection=function(text,detectionThreshold){var rtlCount=0;var totalCount=0;var hasWeaklyLtr=false;var tokens=text.split(/\s+/);for(var i=0;i<tokens.length;i++){var token=tokens[i];if(module.isRtlText(token)){rtlCount++;totalCount++}else{if(module.isRequiredLtrRe_.test(token)){hasWeaklyLtr=true}else{if(module.hasAnyLtr(token)){totalCount++}else{if(module.hasNumeralsRe_.test(token)){hasWeaklyLtr=true}}}}}return totalCount==0?(hasWeaklyLtr?module.Dir.LTR:module.Dir.UNKNOWN):(rtlCount/totalCount>detectionThreshold?module.Dir.RTL:module.Dir.LTR)};return module});(function(factory){if(typeof define==="function"&&define.amd){define("bidiweb",["bidi_helpers"],factory)}else{window.bidiweb=factory(bidi_helpers)}})(function(bidi_helpers){var module={};var IProcessor={makeRtl:function(element){},makeLtr:function(element){}};var css_processor=function(classes){return{makeRtl:function(element){element.classList.add(classes.rtl)},makeLtr:function(element){element.classList.add(classes.ltr)}}};var style_processor=function(falign){return{makeRtl:function(element){element.style.direction="rtl";if(falign){element.style.textAlign="right"}},makeLtr:function(element){element.style.direction="ltr";if(falign){element.style.textAlign="left"}}}};module.processors={css:css_processor,style:style_processor};var nodeListMock=function(node){var list=[node];list.item=function(i){return list[i]};return list};module.process=function(query,processor){var elements;if(query instanceof NodeList){elements=query}else{if(query instanceof Node){elements=nodeListMock(query)}else{elements=document.querySelectorAll(query)}}module.process_elements(elements,processor);return elements};module.process_elements=function(elements,processor){for(var index=0;index<elements.length;index++){var element=elements.item(index);var text=element.textContent||element.value||element.placeholder||"";var dir=bidi_helpers.estimateDirection(text,0.4);if(dir==bidi_helpers.Dir.RTL){processor.makeRtl(element)}else{if(dir==bidi_helpers.Dir.LTR){processor.makeLtr(element)}}}};module.process_css=function(query,classes){var proc=module.processors.css(classes);return module.process(query,proc)};module.process_style=function(query,falign){var proc=module.processors.style(falign);return module.process(query,proc)};module.style=function(query){return module.process_style(query,true)};module.css=function(query){return module.process_css(query,{rtl:"rtl",ltr:"ltr"})};module.htmlToElement=function(html){var container=document.createElement("div");container.innerHTML=html;return container};module.html_css=function(html){var container=module.htmlToElement(html);var nodes=container.querySelectorAll("*");module.css(nodes);return container.innerHTML};module.html_style=function(html){var container=module.htmlToElement(html);var nodes=container.querySelectorAll("*");module.style(nodes);return container.innerHTML};return module});</script>

</body>
</html>