aboutsummaryrefslogtreecommitdiff
path: root/doc/rradicalpd.html
diff options
context:
space:
mode:
authorFrank Barknecht <fbar@users.sourceforge.net>2004-04-23 16:26:21 +0000
committerFrank Barknecht <fbar@users.sourceforge.net>2004-04-23 16:26:21 +0000
commit28e7d308d91556ec078f708b6c4ac855ac340fcc (patch)
treeb406f3f4e426f3bb03acce88bb5027babd9b4a6b /doc/rradicalpd.html
parent35994ca3a4ef6a136a16cac63b4f68540d0434e1 (diff)
This commit was generated by cvs2svn to compensate for changes in r1632,
which included commits to RCS files with non-trunk default branches. svn path=/trunk/abstractions/rradical/; revision=1633
Diffstat (limited to 'doc/rradicalpd.html')
-rw-r--r--doc/rradicalpd.html335
1 files changed, 335 insertions, 0 deletions
diff --git a/doc/rradicalpd.html b/doc/rradicalpd.html
new file mode 100644
index 0000000..04d6a42
--- /dev/null
+++ b/doc/rradicalpd.html
@@ -0,0 +1,335 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.3.1: http://docutils.sourceforge.net/" />
+<title>RRADical Pd</title>
+<meta name="author" content="Frank Barknecht &lt;fbar&#64;footils.org&gt;" />
+<link rel="stylesheet" href="default.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="rradical-pd">
+<h1 class="title">RRADical Pd</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td>Frank Barknecht &lt;fbar&#64;footils.org&gt;</td></tr>
+</tbody>
+</table>
+<div class="abstract topic">
+<p class="topic-title">Abstract</p>
+<p>The goal of RRADical Pd is to create a collection of patches, that make
+Pd easier and faster to use for people who are more used to commercial
+software like Reason(tm) or Reaktor(tm). RRAD as an acronym stands for
+&quot;Reusable and Rapid Audio Development&quot; or &quot;Reusable and Rapid
+Application Development&quot;, if it includes non-audio patches, with Pd. It
+is spelled RRAD, but pronounced Rradical. ;)</p>
+</div>
+<div class="section" id="what-it-takes-to-be-a-rradical">
+<h1><a name="what-it-takes-to-be-a-rradical">What it takes to be a RRADical</a></h1>
+<p>RRAD as an acronym stands for &quot;Reusable and Rapid Audio Development&quot; or
+&quot;Reusable and Rapid Application Development&quot;, if it includes non-audio
+patches, with Pd. It is spelled RRAD, but pronounced Rradical. ;)</p>
+<p>The goal of RRADical Pd is to create a collection of patches, that make Pd
+easier and faster to use for people who are more used to software like Reason(tm)
+or Reaktor(tm). For that I would like to create patches, that solve real-world
+problems on a higher level of abstraction than the standard Pd objects do.
+Where suitable these high level abstractions should have a GUIs
+built in.</p>
+<p>So for example instead of a basic <tt class="literal"><span class="pre">lop~</span></tt> low pass filter something more
+complete like a recreation of the Sherman filter bank could be included in
+that collection. My older sseq and angriff patches followed this idea in
+general, but there are much more patches needed. Like this:</p>
+<ul class="simple">
+<li>a sample player (adapt Gyre?)</li>
+<li>Various OSC/LFO with preset waveforms</li>
+<li>drum machine</li>
+<li>guitar simulator</li>
+<li>grain sample player</li>
+<li>more sequencers</li>
+<li>basically a lot of things like these things in Reason</li>
+</ul>
+<p>Not that I want to make Pd be Reason, no way. But pre-fabricated high-level
+abstractions may not only make Pd easier to use for beginners, they also
+can spare lot of tedious, repeating patching work.</p>
+</div>
+<div class="section" id="problems-and-solutions">
+<h1><a name="problems-and-solutions">Problems and Solutions</a></h1>
+<p>To building above system several problems are to be solved. Two key areas
+already targetted are:</p>
+<dl>
+<dt><strong>Persistence</strong></dt>
+<dd>How to save the current state of a patch? How to save more than one
+state (state sequencing)?</dd>
+<dt><strong>Communication</strong></dt>
+<dd>The various modules are building blocks for a larger application. How
+should they talk to each other. (In Reason this is done by patching the
+back or modules with horrible looking cables. We must do better.)</dd>
+</dl>
+<p>It turned out, that both tasks are possible to solve in a consistent way
+using a unique abstraction. But first lets look a bit deeper at the
+problems at hand.</p>
+<div class="section" id="persistence">
+<h2><a name="persistence">Persistence</a></h2>
+<p>Pd offers no direct way to store the current state of a patch. Here's what
+Pd author Miller S. Puckette writes about this in the Pd manual in section
+&quot;2.6.2. persistence of data&quot;:</p>
+<blockquote>
+Among the design principles of Pd is that patches should be printable,
+in the sense that the appearance of a patch should fully determine its
+functionality. For this reason, if messages received by an object
+change its action, since the changes aren't reflected in the object's
+appearance, they are not saved as part of the file which specifies the
+patch and will be forgotten when the patch is reloaded.</blockquote>
+<p>(I'll show an example of a float object changing &quot;state&quot; by a message in
+its right inlet here.)</p>
+<p>Still, in a musician's practice some kind of persistence turns out to be an
+important feature, that many Pd beginners do miss. So there are several
+approaches to add it. Max/MSP has the <tt class="literal"><span class="pre">preset</span></tt>-object, Pd has the
+<tt class="literal"><span class="pre">state</span></tt>-object which saves the current state of (some) GUI objects inside
+a patch. Both also support changing between several different states.</p>
+<p>Both have at least two problems: They save only the state of GUI objects,
+which might not be all that a user wants to save. And they don't handle
+abstractions very well, which are crucial when creating modularized
+patches.</p>
+<p>Another approach is to (ab)use some of the Pd objects that can persist
+itself to a file, especially <tt class="literal"><span class="pre">textfile</span></tt>, <tt class="literal"><span class="pre">qlist</span></tt> and <tt class="literal"><span class="pre">table</span></tt>, which
+works better, but isn't standardized.</p>
+<p>A rather new candidate for state saving is Thomas Grill's <tt class="literal"><span class="pre">pool</span></tt>
+external. Basically it offers something, that is standard in many
+programming languages: a data structure that stores key-value-pairs. This
+also is known as hash, dictonary or map. With <tt class="literal"><span class="pre">pool</span></tt> those pairs also can
+be stored in hierarchies and they can be saved to or loaded from disk. The
+last but maybe most important feature for us is, that several pools can be
+shared by giving them the same name. A <tt class="literal"><span class="pre">pool</span> <span class="pre">MYPOOL</span></tt> in one patch will
+contain the same data as a <tt class="literal"><span class="pre">pool</span> <span class="pre">MYPOOL</span></tt> in another patch. Changes to one
+pool will change the data in the other as well.</p>
+<p>A <tt class="literal"><span class="pre">pool</span></tt> object is central to the persistence in RRADical patches, but it
+is hidden behind an abstracted &quot;API&quot;, if one could name it that. I'll
+come back to haw this is done late.</p>
+</div>
+<div class="section" id="communication">
+<h2><a name="communication">Communication</a></h2>
+<p>Besides persistance it also is important to create a common path through
+which the RRADical modules will talk to each other. Generally the modules
+will have to use, what Pd offers them, and that is either a direct
+connection through patch cords or the indirect use of the send/receive
+mechanism in Pd. Patch cords are fine, but tend to clutter the interface.
+Sends and receives on the other hand will have to make sure, that no name
+clashes occur. A name clash is, when one target receives messages not
+intended for it. A patch author has to remember all used send-names, but
+this gets harder, if he uses prefabricated modules, which might use their
+own senders.</p>
+<p>So it is crucial, that senders in RRADical abstractions use local senders
+only with as few exceptions as possible. This is achieved by prepending the
+RRADical senders with the string &quot;$0-&quot;. So you'd not use <tt class="literal"><span class="pre">send</span> <span class="pre">volume</span></tt>,
+but instead use <tt class="literal"><span class="pre">send</span> <span class="pre">$0-volume</span></tt>. $0 makes those sends local inside their
+own patch borders. This might be a bit difficult to understand to the
+casual Pd user, but is a pretty standard idiom in the Pd world.</p>
+<p>Still we will want to control a lot of parameters and do so not only
+through the GUI Pd offers, but probably also through other ways, for
+example through Midi controllers, through some kind of score on disk,
+through satellite navigation receivers or whatever.</p>
+<p>This creates a fundamental conflict:</p>
+<dl>
+<dt><strong>We want borders</strong> </dt>
+<dd>We want to separate our abstraction so they don't conflict with each
+other.</dd>
+<dt><strong>We want border crossings</strong></dt>
+<dd>We want to have a way to reach their many internals and control them
+from the outside.</dd>
+</dl>
+<p>The RRADical approach adheres to this in that it enforces a strict border
+but drills a single hole in it: the <strong>OSC inlet</strong>. This idea is the result
+of a discussion on the Pd mailing list and goes back to suggestions by
+<a class="reference" href="http://www.audionerd.com">Eric Skogen</a> and <a class="reference" href="http://www.ekran.org/ben/">Ben Bogart</a>. Every RRADical patch has (to have) a
+rightmost inlet that accepts messages formatted according to the OSC
+protocol. OSC stands for <a class="reference" href="http://www.cnmat.berkeley.edu/OpenSoundControl/">Open Sound Control</a> and is a network transparent
+system to control audio applications remotely developed at CNMAT in Berkley.</p>
+<p>The nice thing about OSC is that it can control many parameters over a
+single communication path. This is so, because OSC uses a URL-like scheme
+to address parameters. An example would be this message:</p>
+<pre class="literal-block">
+/synth/fm/volume 85
+</pre>
+<p>It sends the message &quot;85&quot; to the &quot;volume&quot; control of a &quot;fm&quot; module below a
+&quot;synth&quot; module. OSC allows many parameters constructs like:</p>
+<pre class="literal-block">
+/synth/fm/basenote 52
+/synth/virtualanalog/basenote 40
+/synth/*/playchords m7b5 M6 7b9
+</pre>
+<p>This might set the base note of two synths, <cite>fm</cite> and <cite>virtualanalog</cite> and
+send a chord progression to be played by both -- indicated by the wildcard
+<cite>*</cite> -- afterwards.</p>
+<p>The OSC-inlet of every RRADical patch is intended as the border crossing:
+Everything the author of a certain patch intends to be controlled from the
+outside can be controlled by OSC messages to the rightmost inlet.</p>
+</div>
+</div>
+<div class="section" id="trying-to-remember-it-all-memento">
+<h1><a name="trying-to-remember-it-all-memento">Trying to remember it all: Memento</a></h1>
+<p>To realize the functionality requirements developed so far I resorted to a
+so called <cite>Memento</cite>. <cite>&quot;Memento&quot;</cite> is a very cool movie by director
+Christopher Nolan where - quoting IMDB:</p>
+<blockquote>
+A man, suffering from short-term memory loss, uses notes and tattoos to
+hunt down his wife's killer.</blockquote>
+<p>If you haven't already done so: Watch this movie! It's much better than
+Matrix 2 and 3 and also stars Carrie-Anne &quot;Trinity&quot; Moss.</p>
+<p>Here's a scene from &quot;Memento&quot;:</p>
+<p><img alt="memento.png" src="memento.png" /></p>
+<p>We see the film's main character Leonard who has a similar problem as Pd: he
+cannot remember things. To deal with his persistence problem, his inability
+to save data to his internal harddisk he resorts to taking a lot of photos.
+These pictures act as what is called a Memento: a recording of the current
+state of things.</p>
+<p>In software development Mementos are quite common as well. The computer
+science literature describes them in great detail. To make the best use of
+a Memento science recommends an approach where certain tasks are in the
+responsibility of certain independent players.</p>
+<p>The Memento itself, as we have seen, is the photo, i.e. some kind of state
+record. A module called the &quot;Originator&quot; is responsible for creating this
+state and managing changes in it. In the movie, Leonard is the Originator,
+he is the one taking photos of the world he is soon to forget.</p>
+<p>The actual persistence, that could be the saving of a state to harddisk,
+but could just as well be an upload to a webserver or a CVS check-in, is
+done by someone called the &quot;Caretaker&quot; in the literature. A Caretaker could
+be a safe, where Leonard puts his photos, or could be a person, to whom
+Leonard gives his photos. In the movie Leonard also makes &quot;hard saves&quot; by
+tattooing himself with notes he took. In that case, he is not only the
+Originator of the notes, but also the Caretaker in one single person. The
+Caretaker only has to take care, that those photos, the Mementos, are in a
+safe place and noone fiddles around with them. Btw: In the movie some
+interesting problems with Caretakers, who don't always act responsible,
+occur.</p>
+<div class="section" id="memento-in-pd">
+<h2><a name="memento-in-pd">Memento in Pd</a></h2>
+<p>I developed a set of abstractions, of patches for Pd, that follow this
+design pattern. Memento for Pd includes a <tt class="literal"><span class="pre">caretaker</span></tt> and an
+<tt class="literal"><span class="pre">originator</span></tt> abstraction, plus a third one called <tt class="literal"><span class="pre">commun</span></tt> which is
+responsible for the <strong>internal</strong> communication. <tt class="literal"><span class="pre">commun</span></tt> basically is
+just a thin extension of <tt class="literal"><span class="pre">originator</span></tt> and should be considered part of
+it. There is another patch, the <tt class="literal"><span class="pre">careGUI</span></tt> which I personally use instead
+of the <tt class="literal"><span class="pre">caretaker</span></tt> directly, because it has a simple GUI included.</p>
+<p>Here's how it looks:</p>
+<p><img alt="caregui.png" src="caregui.png" /></p>
+<p>The <tt class="literal"><span class="pre">careGUI</span></tt> is very simple: select a FILE-name to save to, then
+clicking SAVE you can save the current state, with RESTORE you can restore
+a state previously saved. After restore, the outlet of <tt class="literal"><span class="pre">careGUI</span></tt> sends a
+<tt class="literal"><span class="pre">bang</span></tt> message to be used as you like.</p>
+<p>Internally <tt class="literal"><span class="pre">caretaker</span></tt> has a named <tt class="literal"><span class="pre">pool</span></tt> object using the global pool
+called &quot;RRADICAL&quot;. The same <tt class="literal"><span class="pre">pool</span> <span class="pre">RRADICAL</span></tt> also is used inside the
+<tt class="literal"><span class="pre">originator</span></tt> object. This abstraction handles all access to this pool. A
+user should not read or write the contents of <tt class="literal"><span class="pre">pool</span> <span class="pre">RRADICAL</span></tt> directly.
+The <tt class="literal"><span class="pre">originator</span></tt> patch also handles the border crossing through OSC
+messages by it's rightmost inlet. The patch accepts two mandatory
+arguments: The first on is the name under which this patch is to be stored
+inside the <tt class="literal"><span class="pre">pool</span></tt> data. Each <tt class="literal"><span class="pre">originator</span> <span class="pre">SomeName</span> <span class="pre">secondarg</span></tt> stores
+it's data in a virtual subdirectory inside the RRADICAL-pool called like
+its first argument - SomeName in the example. If the SomeName starts with a
+slash like &quot;/patch&quot; , you can also accesse it via OSC through the rightmost inlet of
+<tt class="literal"><span class="pre">originator</span></tt> under the tree &quot;/patch&quot;</p>
+<p>The second argument practically always will be $0. It is used to talk to
+those <tt class="literal"><span class="pre">commun</span></tt> objects which share the same second argument. As $0 is a
+value local and unique to a patch (or to an abstraction to be correct) each
+<tt class="literal"><span class="pre">originator</span></tt> then only can talk to <tt class="literal"><span class="pre">commun</span></tt>s inside the same patch and
+will not disturb other <tt class="literal"><span class="pre">commun</span></tt> objects in other abstractions.</p>
+<p>The <tt class="literal"><span class="pre">commun</span></tt> objects finally are where the contents of a state are read
+and set. They, too, accept two arguments, the second of which was
+discussed before and will most of the time just be $0. The first argument
+will be the key under which some value will be saved. You should use a slash
+as first character here as well to allow OSC control. So an example for a
+usage would be <tt class="literal"><span class="pre">commun</span> <span class="pre">/vol</span> <span class="pre">$0</span></tt>.</p>
+<p><tt class="literal"><span class="pre">commun</span></tt> has one inlet and one outlet. What comes in through the inlet is
+send to <tt class="literal"><span class="pre">originator</span></tt> who stores it inside its Memento under the key, that
+is specified by the <tt class="literal"><span class="pre">commun</span></tt>'s first arg. Actually <tt class="literal"><span class="pre">originator</span></tt>. The
+outlet of a <tt class="literal"><span class="pre">commun</span></tt> will spit out the current value stored under its key
+inside the Memento, when <tt class="literal"><span class="pre">originator</span></tt> tells it to do so. So <tt class="literal"><span class="pre">commun</span></tt>s
+are intended to be cross-connected to some thing that can change. And
+example would be a slider which can be connected as seen in the next
+picture:</p>
+<p><img alt="communslider.png" src="communslider.png" /></p>
+<p>In this patch, every change to the slider will be reflected inside the
+Memento. The little print button in <tt class="literal"><span class="pre">careGUI</span></tt> can be used to print the
+contents to the console from which Pd was started. Setting the slider will
+result in something like this:</p>
+<pre class="literal-block">
+/mypatch 0 , /volume , 38
+</pre>
+<p>Here a comma separates key and value pairs. &quot;mypatch&quot; is the toplevel
+directory. This contains a 0, which is the default subdirectory, after that
+comes the key &quot;/volume&quot;, whose value is 38. Let's add another slider for
+pan-values:</p>
+<p><img alt="moresliders.png" src="moresliders.png" /></p>
+<p>Moving the /pan slider will let careGUI print out:</p>
+<pre class="literal-block">
+/mypatch 0 , /volume , 38
+/mypatch 0 , /pan , 92
+</pre>
+<p>The <tt class="literal"><span class="pre">originator</span></tt> can save several substates or presets by sending a
+<tt class="literal"><span class="pre">substate</span> <span class="pre">#number</span></tt> message to its first inlet. Let's do just this and
+move the sliders again as seen in the next picture:</p>
+<p><img alt="substates.png" src="substates.png" /></p>
+<p>Now careGUI prints:</p>
+<pre class="literal-block">
+/mypatch 0 , /volume , 38
+/mypatch 0 , /pan , 92
+/mypatch 1 , /volume , 116
+/mypatch 1 , /pan , 27
+</pre>
+<p>You see, the substate 0 is unaffected, the new state can have different
+values. Exchanging the <tt class="literal"><span class="pre">substate</span></tt> message with a <tt class="literal"><span class="pre">setsub</span></tt> message will
+autoload the selected state and &quot;set&quot; the sliders to the stored values
+immediatly.</p>
+</div>
+<div class="section" id="osc-in-memento">
+<h2><a name="osc-in-memento">OSC in Memento</a></h2>
+<p>The whole system now already is prepared to be used over OSC. You probably
+already guess, how the message looks like. Any takers? Thank you, you're
+right, the messages are built as <tt class="literal"><span class="pre">/mypatch/volume</span> <span class="pre">#number</span></tt> and
+<tt class="literal"><span class="pre">/mypatch/pan</span> <span class="pre">#number</span></tt> as shown in the next stage:</p>
+<p><img alt="osccontrol.png" src="osccontrol.png" /></p>
+<p>Sometimes it is useful to also get OSC messages out of a patch, for example
+to control other OSC software through Pd. For this the <strong>OSC-outlet</strong> of
+<tt class="literal"><span class="pre">originator</span></tt> can be used, which is the rightmost outlet of the
+abstraction. It will print out every change to the current state.
+Connecting a <tt class="literal"><span class="pre">print</span> <span class="pre">OSC</span></tt> debug object to it, we get to see what's coming
+out of the OSC-outlet when we move a slider:</p>
+<pre class="literal-block">
+OSC: /mypatch/pan 92
+OSC: /mypatch/pan 91
+OSC: /mypatch/pan 90
+OSC: /mypatch/pan 89
+</pre>
+</div>
+</div>
+<div class="section" id="putting-it-all-to-rradical-use">
+<h1><a name="putting-it-all-to-rradical-use">Putting it all to RRADical use</a></h1>
+<p>Now that the foundation for a general preset and communication system are
+set, it is possible to build real patches with it that have two main
+characteristics:</p>
+<dl>
+<dt><strong>Rapidity</strong></dt>
+<dd>Ready-to-use highlevel abstraction can save a lot of time when building
+larger patches. Clear communication paths will let you think faster and
+more about the really important things.</dd>
+<dt><strong>Reusability</strong></dt>
+<dd>Don't reinvent the wheel all the time. Reuse patches like instruments
+for more than one piece by just exchanging the Caretaker-file used.</dd>
+</dl>
+<p>I already developed a growing number of patches that follow the RRADical
+paradigm, among these are a complex pattern sequencer, some synths and
+effects and more. The RRADical collection comes with a template file,
+called <tt class="literal"><span class="pre">rrad.tpl</span></tt> that makes deploying new RRADical patches easier and
+lets developers concentrate on the algorighm instead of bookeeping. Some
+utils (footils?) help with creating the sometimes needed many
+<tt class="literal"><span class="pre">commun</span></tt>-objects. Several usecases show example applications of the
+provided abstractions.</p>
+</div>
+</div>
+</body>
+</html>