Persistence

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 "2.6.2. persistence of data":

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.

Still, in a musician's practice some kind of persistence turns out to be an important feature, that many Pd beginners do miss. And as soon as a patch starts to use lots of graphical control objects, users will - and should - play around with different settings until they find some combination they like. But unless a way to save this combination for later use is found, all this is temporary and gone, as soon as the patch is closed.

There are several approaches to add persistence. Max/MSP has the preset-object, Pd provides the similar state-object which saves the current state of (some) GUI objects inside a patch. Both objects also support changing between several different states.

But both also have at least two problems: They only save the state of GUI objects, which might not be everything that a user wants to save. And they don't handle abstractions very well, which are crucial when creating modularized patches.

Another approach is to (ab)use some of the Pd objects that can persist itself to a file, especially textfile, qlist and table, which works better, but isn't standardized.

A rather new candidate for state saving is Thomas Grill's pool external. Basically it offers something, that is standard in many programming languages: a data structure that stores key-value-pairs. This structure also is known as hash, dictionary or map. With pool 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 pool MYPOOL in one patch will contain the same data as a pool MYPOOL in another patch. Changes to one pool will change the data in the other as well. This allows us to use pool MYPOOLs inside of abstractions, and still access the pool from modules outside the abstractions, for example for saving the pool to disk.

A pool object is central to the persistence in RRADical patches, but it is hidden behind an abstracted "API", if one could name it that. I'll come back to how this is done below.

Communication

Besides persistence 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, which might be possible, if he did write the whole patch himself and kept track of the send-names used. But this gets harder to impossible, if he uses prefabricated modules, which might use their own senders, maybe hidden deep inside of the module.

So it is crucial, that senders in RRADical abstractions use local names only with as few exceptions as possible. This is achieved by prepending the RRADical senders with the string "$0-". So instead of a sender named send volume, instead one called send $0-volume is used. $0 makes those sends local inside their own patch borders by being replaced with a number unique to that patch. Using $0 that way is a pretty standard idiom in the Pd world.

Still we will want to control a lot of parameters and do so not only through the GUI elements Pd offers, but probably also through other ways, for example through hardware Midi controllers, through some kind of score on disk, through satellite navigation receivers or whatever.

This creates a fundamental conflict:

We want borders

We want to separate our abstraction so they don't conflict with each other.

We want border crossings

We want to have a way to reach their many internals and control them from the outside.

The RRADical approach solves both requirements in that it enforces a strict border around abstractions but drills a single hole in it: the OSC inlet. This idea is the result of a discussion on the Pd mailing list and goes back to suggestions by Eric Skogen and Ben Bogart. Every RRADical patch has (to have) a rightmost inlet that accepts messages formatted according to the OSC protocol. OSC stands for Open Sound Control and is a network transparent system to control (audio) applications remotely and is developed at CNMAT in Berkley by Matt Wright mainly.

The nice thing about OSC is that it can control many parameters over a single communication path (like a network conneciton using a definite port). For this OSC uses a URL-like scheme to address parameters organized in a tree. An example would be this message:

/synth/fm/volume 85

It sends the message "85" to the "volume" control of a "fm" module below a "synth" module. OSC allows many parameters constructs like:

/synth/fm/basenote              52
/synth/virtualanalog/basenote   40
/synth/*/playchords             m7b5 M6 7b9

This might set the base note of two synths, fm and virtualanalog and send a chord progression to be played by both -- indicated by the wildcard * -- afterwards.

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 OSC-inlet. The OSC-inlet is strongly recommended to be the rightmost inlet of an abstraction. At least all of my RRADical patches do it this way.

Memento in Pd

I developed a set of abstractions, of patches for Pd, that follow this design pattern. Memento for Pd includes a caretaker and an originator abstraction, plus a third one called commun which is responsible for the internal communication. commun basically is just a thin extension of originator and should be considered part of it. There is another patch, the careGUI which I personally use instead of the caretaker directly, because it has a simple GUI included.

Here's how it looks:

The careGUI 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 careGUI sends a bang message to be used as you like.

Internally caretaker has a named pool object using the global pool called "RRADICAL". The same pool RRADICAL also is used inside the originator object. This abstraction handles all access to this pool. A user should not read or write the contents of pool RRADICAL directly. The originator patch also handles the border crossing through OSC messages by its rightmost inlet. The patch accepts two mandatory arguments: The first on is the name under which this patch is to be stored inside the pool data. Each originator SomeName secondarg 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 "/patch" , you can also access it via OSC through the rightmost inlet of originator under the tree "/patch"

The second argument practically always will be $0. It is used to talk to those commun 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 originator then only can talk to communs inside the same patch and will not disturb other commun objects in other abstractions.

The commun 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 commun /vol $0.

commun has one inlet and one outlet. What comes in through the inlet is send to originator who stores it inside its Memento under the key, that is specified by the commun's first arg. Actually originator. The outlet of a commun will spit out the current value stored under its key inside the Memento, when originator tells it to do so. So communs 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:

In this patch, every change to the slider will be reflected inside the Memento. The little print button in careGUI can be used to print the contents to the console from which Pd was started. Setting the slider will result in something like this:

/mypatch 0 , /volume , 38

Here a comma separates key and value pairs. "mypatch" is the top-level directory. This contains a 0, which is the default subdirectory, after that comes the key "/volume", whose value is 38. Let's add another slider for pan-values:

Moving the /pan slider will let careGUI print out:

/mypatch 0 , /volume , 38
/mypatch 0 , /pan , 92

The originator can save several substates or presets by sending a substate #number message to its first inlet. Let's do just this and move the sliders again as seen in the next picture:

Now careGUI prints:

/mypatch 0 , /volume , 38
/mypatch 0 , /pan , 92
/mypatch 1 , /volume , 116
/mypatch 1 , /pan , 27

You see, the substate 0 is unaffected, the new state can have different values. Exchanging the substate message with a setsub message will autoload the selected state and "set" the sliders to the stored values immediately.

OSC in Memento

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 /mypatch/volume #number and /mypatch/pan #number as shown in the next stage:

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 OSC-outlet of originator can be used, which is the rightmost outlet of the abstraction. It will print out every change to the current state. Connecting a print OSC debug object to it, we get to see what's coming out of the OSC-outlet when we move a slider:

OSC: /mypatch/pan 92
OSC: /mypatch/pan 91
OSC: /mypatch/pan 90
OSC: /mypatch/pan 89