A Quick Introduction to Pd-Lua
Albert Gräf <aggraef@gmail.com>
Computer Music Dept., Institute of Art History and Musicology
Johannes Gutenberg University (JGU) Mainz, Germany
August 2024
This document is licensed under CC BY-SA 4.0. Other formats: Markdown source, PDF
Permanent link: https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html
Why Pd-Lua?
Pd's facilities for data structures, iteration, and recursion are somewhat limited, thus sooner or later you'll probably run into a problem that can't be easily solved by a Pd abstraction any more. At this point you'll have to consider writing an external object (or just external, for short) in a "real" programming language instead. Pd externals are usually programmed using C, the same programming language that Pd itself is written in. But novices may find C difficult to learn, and the arcana of Pd's C interface may also be hard to master.
Enter Pd-Lua, the Pd programmer's secret weapon, which lets you develop your externals in the Lua scripting language. Pd-Lua was originally written by Claude Heiland-Allen and has since been maintained by a number of other people in the Pd community. Lua, from PUC Rio, is open-source (under the MIT license), mature, very popular, and supported by a large developer community. It is a small programming language, but very capable, and is generally considered to be relatively easy to learn. For programming Pd externals, you'll also need to learn a few bits and pieces which let you interface your Lua functions to Pd, as explained in this tutorial, but programming externals in Lua is still quite easy and a lot of fun.
Using Pd-Lua, you can program your own externals ranging from little helper objects to full-blown sequencers and algorithmic composition tools. Pd-Lua is primarily aimed at control objects at this time (for doing dsp, you might consider using Faust instead), but thanks to contributions by Timothy Schoen, the most recent version also provides support for signal processing and even graphics. It also gives you access to Pd arrays and tables, as well as a number of other useful facilities such as clocks and receivers, which we'll explain in some detail. Pd-Lua also ships with a large collection of instructive examples which you'll find helpful when exploring its possibilities.
Note that we can't possibly cover Pd or the Lua language themselves here, so you'll have to refer to other online resources to learn about those. In particular, check out the Lua website, which has extensive documentation available, and maybe have a look at Derek Banas' video tutorial for a quick overview of Lua. For Pd, we recommend the Pd FLOSS Manual at https://flossmanuals.net/ to get started.
Installation
Pd-Lua works inside any reasonably modern Pd flavor. This encompasses vanilla Pd, of course, but also Purr Data which includes an up-to-date version of Pd-Lua for Lua 5.4 and has it enabled by default, so you should be ready to go immediately; no need to install anything else. The same is true for plugdata (version 0.6.3 or later), a Pd flavor which can also run as a plug-in inside a DAW.
With vanilla Pd, you can install the pdlua package from Deken. There's also an official Debian package, maintained by IOhannes Zmölnig. You can also compile Pd-Lua from source, using the author's Github repository. Compilation instructions are in the README, and you'll also find some Mac and Windows binaries there. In either case, after installing Pd-Lua you also have to add pdlua to Pd's startup libraries.
If all is well, you should see a message like the following in the Pd console (note that for vanilla Pd you'll have to switch the log level to 2 or more to see that message):
xxxxxxxxxxpdlua 0.12.4 (GPL) 2008 Claude Heiland-Allen, 2014 Martin Peach et al.pdlua: compiled for pd-0.55 on Aug 24 2024 00:51:01Using lua version 5.4
This will also tell you the Lua version that Pd-Lua is using, so that you can install a matching version of the stand-alone Lua interpreter if needed. Lua should be readily available from your package repositories on Linux, and for Mac and Windows you can find binaries on the Lua website. In the following we generally assume that you're using Lua 5.3 or later (using Lua versions older than 5.3 is not recommended).
If all is not well and you do not see that message, then most likely Pd-Lua refused to load because the Lua library is missing. This shouldn't happen if you installed Pd-Lua from a binary package, but if it does then you may have to manually install the right version of the Lua library to make Pd-Lua work. Make sure that you install the package with the Lua library in it; on Debian, Ubuntu and their derivatives this will be something like liblua5.4-0.
A basic example
With that out of the way, let's have a look at the most essential parts of a Lua external. To make an external, say foo, loadable by Pd-Lua, you need to put it into a Lua script, which is simply a text file with the right name (which must be the same as the object name, foo in this case) and extension (which needs to be .pd_lua), so the file name will be foo.pd_lua in this example.
Any implementation of an object must always include:
a call to the
pd.Class:new():registermethod which registers the object class with Pd (this should always be the first line of the script, other than comments)a definition of the
initializemethod for your object class
Here is a prototypical example (this is the contents of the foo.pd_lua file):
xxxxxxxxxxlocal foo = pd.Class:new():register("foo")
+A Quick Introduction to Pd-Lua
Albert Gräf <aggraef@gmail.com>
Computer Music Dept., Institute of Art History and Musicology
Johannes Gutenberg University (JGU) Mainz, Germany
August 2024
This document is licensed under CC BY-SA 4.0. Other formats: Markdown source, PDF
Permanent link: https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html
Why Pd-Lua?
Pd's facilities for data structures, iteration, and recursion are somewhat limited, thus sooner or later you'll probably run into a problem that can't be easily solved by a Pd abstraction any more. At this point you'll have to consider writing an external object (or just external, for short) in a "real" programming language instead. Pd externals are usually programmed using C, the same programming language that Pd itself is written in. But novices may find C difficult to learn, and the arcana of Pd's C interface may also be hard to master.
Enter Pd-Lua, the Pd programmer's secret weapon, which lets you develop your externals in the Lua scripting language. Pd-Lua was originally written by Claude Heiland-Allen and has since been maintained by a number of other people in the Pd community. Lua, from PUC Rio, is open-source (under the MIT license), mature, very popular, and supported by a large developer community. It is a small programming language, but very capable, and is generally considered to be relatively easy to learn. For programming Pd externals, you'll also need to learn a few bits and pieces which let you interface your Lua functions to Pd, as explained in this tutorial, but programming externals in Lua is still quite easy and a lot of fun. Using Pd-Lua, you can program your own externals ranging from little helper objects to full-blown synthesizers, sequencers, and algorithmic composition tools. It gives you access to Pd arrays and tables, as well as a number of other useful facilities such as clocks and receivers, which we'll explain in some detail. Pd-Lua also ships with a large collection of instructive examples which you'll find helpful when exploring its possibilities.
Pd-Lua was originally designed for control processing, so we used to recommend Faust for doing dsp instead. We still do, but Faust isn't for everyone; being a purely functional language, Faust follows a paradigm which most programmers aren't very familiar with. Fortunately, thanks to the work of Timothy Schoen, the most recent Pd-Lua versions now also provide support for signal processing and even graphics. So it is now possible to create pretty much any kind of Pd object in Lua, including dsp objects. (However, Faust will almost certainly execute dsp code much more efficiently than Pd-Lua, as it generates highly optimized native code for just this purpose.)
Note that we can't possibly cover Pd or the Lua language themselves here, so you'll have to refer to other online resources to learn about those. In particular, check out the Lua website, which has extensive documentation available, and maybe have a look at Derek Banas' video tutorial for a quick overview of Lua. For Pd, we recommend the Pd FLOSS Manual at https://flossmanuals.net/ to get started.
Installation
Pd-Lua works inside any reasonably modern Pd flavor. This encompasses vanilla Pd, of course, but also Purr Data which includes an up-to-date version of Pd-Lua for Lua 5.4 and has it enabled by default, so you should be ready to go immediately; no need to install anything else. The same is true for plugdata (version 0.6.3 or later), a Pd flavor which can also run as a plug-in inside a DAW.
With vanilla Pd, you can install the pdlua package from Deken. There's also an official Debian package, maintained by IOhannes Zmölnig. You can also compile Pd-Lua from source, using the author's Github repository. Compilation instructions are in the README, and you'll also find some Mac and Windows binaries there. In either case, after installing Pd-Lua you also have to add pdlua to Pd's startup libraries.
If all is well, you should see a message like the following in the Pd console (note that for vanilla Pd you'll have to switch the log level to 2 or more to see that message):
pdlua 0.12.4 (GPL) 2008 Claude Heiland-Allen, 2014 Martin Peach et al.pdlua: compiled for pd-0.55 on Aug 24 2024 00:51:01Using lua version 5.4
This will also tell you the Lua version that Pd-Lua is using, so that you can install a matching version of the stand-alone Lua interpreter if needed. Lua should be readily available from your package repositories on Linux, and for Mac and Windows you can find binaries on the Lua website. In the following we generally assume that you're using Lua 5.3 or later (using Lua versions older than 5.3 is not recommended).
If all is not well and you do not see that message, then most likely Pd-Lua refused to load because the Lua library is missing. This shouldn't happen if you installed Pd-Lua from a binary package, but if it does then you may have to manually install the right version of the Lua library to make Pd-Lua work. Make sure that you install the package with the Lua library in it; on Debian, Ubuntu and their derivatives this will be something like liblua5.4-0.
A basic example
With that out of the way, let's have a look at the most essential parts of a Lua external. To make an external, say foo, loadable by Pd-Lua, you need to put it into a Lua script, which is simply a text file with the right name (which must be the same as the object name, foo in this case) and extension (which needs to be .pd_lua), so the file name will be foo.pd_lua in this example.
Any implementation of an object must always include:
a call to the pd.Class:new():register method which registers the object class with Pd (this should always be the first line of the script, other than comments)
a definition of the initialize method for your object class
Here is a prototypical example (this is the contents of the foo.pd_lua file):
xlocal foo = pd.Class:new():register("foo")
function foo:initialize(sel, atoms) return trueend
Note that in the first line we called pd.Class:new():register with the name of the object class as a string, which must be the same as the basename of the script, otherwise Pd's loader will get very confused, create the wrong object class, print a (rather cryptic) error message, and won't be able to create the object.
We also assigned the created class (which is represented as a Lua table) to a variable foo (which we made local to the script file here, as explained below). We need that variable as a qualifier for the methods of the object class, including initialize. You can actually name that variable whatever you want, as long as you use that name consistently throughout the script. This can be useful at times, if the actual class name you chose, as it is known to Pd and set with pd.Class:new():register (as well as being the basename of your .pd_lua script), is a jumble of special characters such as fo:o#?!, which isn't a valid Lua identifier.
Next comes the initialize method, which is implemented as a Lua function, prefixing the method name with the name of the class variable we created above and a colon, i.e., foo:initialize. (This colon syntax is used for all functions that represent methods, which receive the called object as an implicit self parameter; please check the section on function definitions in the Lua manual for details.) As a bare minimum, as is shown here, this method must return true, otherwise the loader will assume that the object creation has failed, and will complain that it couldn't create the object with an error message.
We mention in passing here that Pd-Lua also provides a parameter-less postinitialize method which can be used to execute code after the object has been created, but before the object starts processing messages. We'll see an example of this method later.
NOTE: Pd-Lua runs all Lua objects in the same instance of the Lua interpreter. Therefore, as a general guideline, we want to keep the global name space tidy and clean. That's why we made foo a local variable, which means that its scope is confined to this single script. Note that this isn't needed for the member variables and methods, as these are securely stowed away inside the object and not accessible from the outside anyway, if the class variable is local. But the same caveat applies to all variables and functions in the script file that might be needed to implement the object, so normally you want to mark these as local, too (or turn them into member variables and methods, if that seems more appropriate).
We mention in passing that global variables and functions may also have their uses if you need to share a certain amount of global state between different Lua objects. But even then it's usually safer to have the objects communicate with each other behind the scenes using receivers, which we'll explain later.
To actually use the object class we just created, Pd needs be able to find our foo.pd_lua file. We'll discuss different approaches in the following section, but the easiest way to achieve this is to just drop foo.pd_lua into the directory that your patch is in (say, pd-lua in your home directory). Now we can just create our first foo object (hit Ctrl+1, then type the object name foo), and we should see something like this:
Hooray, it works! :)) Well, this object doesn't do anything right now, so let's equip it with a single inlet/outlet pair. This is what the initialize method is for, so we have to edit that method accordingly.
NB: If you closed the editor already and don't remember where the file is, you can just right-click the object and choose Open, which will open the .pd_lua file in your favorite text editor, as configured in your desktop and/or shell environment.
xxxxxxxxxxlocal foo = pd.Class:new():register("foo")
function foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 return trueend
Note that, as we already mentioned, the self variable here is an implicit parameter of any Lua method, which refers to the object itself. Every Pd-Lua object has two member variables inlets and outlets which let us specify the number of inlets and outlets our object should have. This needs to be done when the object is initialized; afterwards, the number of inlets and outlets is set in stone and can't be changed any more.
Next, we have to make sure that Pd picks up our edited class definition. Since the Pd-Lua loader will never reload the .pd_lua file for any given object class during a Pd session, we will have to save the patch, quit Pd, relaunch it and reopen the patch:
So there, we got our single inlet/outlet pair now. To do anything with these, we finally have to add some message handlers to our object. Say, for instance, we want to handle a bang message by incrementing a counter and outputting its current value to the outlet. We first have to initialize the counter value in the initialize method. As we want each foo object to have its own local counter value, we create the counter as a member variable:
xxxxxxxxxxfunction foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 self.counter = 0 return trueend
It's not necessary to declare the self.counter variable in any way, just give it an initial value and be done with it. Finally, we have to add a method for the bang message, which looks as follows:
xxxxxxxxxxfunction foo:in_1_bang() self.counter = self.counter + 1 self:outlet(1, "float", {self.counter})end
We'll dive into the naming conventions for message handlers later, but note that in_1 specifies the first (and only) inlet and bang the kind of message we expect. In the body of the method we increment the self.counter value and output its new value on the first (and only) outlet. This is done by the predefined self:outlet method which takes three arguments: the outlet number, the (Pd) data type to output, and the output value itself. (In general, it's possible to have multiple values there, e.g., when outputting a list value. Therefore the output value is always specified as a Lua table, hence the curly braces around the float output value.)
Throwing everything together, our Lua external now looks as follows:
xxxxxxxxxxlocal foo = pd.Class:new():register("foo")
function foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 self.counter = 0 return trueend
-function foo:in_1_bang() self.counter = self.counter + 1 self:outlet(1, "float", {self.counter})end
So let's relaunch Pd, reload the patch again, and add some GUI elements to test it out:
Note that this is still a very basic example. While the example is complete and fully functional, we have barely scratched the surface here. Pd-Lua also allows you to process an object's creation arguments (employing the atoms parameter of the initialize method, which we didn't use above), log messages and errors in the Pd console, create handlers for different types of input messages, output data to different outlets, work with Pd arrays, clocks, and receivers, and even do some live coding. We will dive into each of these topics in the following sections.
Where your Lua files go
As already mentioned, the externals (.pd_lua files) themselves can go either into the directory of the patch using the external, or into any other directory on Pd's search path (on Linux, this generally includes, ~/.pd-externals, or ~/.pd-l2ork-externals when running pd-l2ork or purr-data).
The Lua loader temporarily sets up Lua's package.path so that it includes the directory with the external, so you can put any Lua modules (.lua files) required by the external into that directory.
If you need/want to use Lua libraries from other locations (which aren't on the standard Lua package.path), then you'll have to set up the LUA_PATH environment variable accordingly. When using LuaRocks, Lua's most popular package manager, it usually takes care of this for you when set up properly. Otherwise you can set LUA_PATH manually in your system startup files, such as ~/.bashrc or ~/.xprofile on Linux. E.g.:
xxxxxxxxxxexport LUA_PATH=~/lua/'?.lua;;'
Note that ? is a placeholder for the module name, the semicolon ; can be used to separate different locations, and a double semicolon ;; adds Lua's standard search path (make sure that you quote those special characters so that the shell doesn't try to interpret them). You should always include the double semicolon somewhere, otherwise the Lua interpreter won't be able to find its standard library modules any more. Also note that you may want to place the ;; in front of the path instead, if the standard locations are to be searched before your custom ones.
Creation arguments
Besides the implicit self argument, the initialize method has two additional parameters:
sel, the selector argument, is a string which contains the Pd name of the object class. You probably won't need this, unless you want to use it for error reporting, or if you have a generic setup function for several related object classes. We won't go into this here.
atoms is a Lua table which contains all the arguments (Pd "atoms", i.e., numbers or strings) an object was created with. #atoms gives you the number of creation arguments (which may be zero if none were specified), atoms[1] is the first argument, atoms[2] the second, and so on. As usual in Lua, if the index i runs past the last argument, atoms[i] returns nil.
For instance, let's say that we want to equip our foo object with an optional creation argument, a number, to set the initial counter value. This can be done as follows:
xxxxxxxxxxfunction foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 if type(atoms[1]) == "number" then self.counter = atoms[1] else self.counter = 0 end return trueend
Here we check that the first creation argument is a number. In that case we use it to initialize the counter member variable, otherwise a default value of 0 is set. Note that if there is no creation argument, atoms[1] will be nil which is of type "nil", in which case the zero default value will be used.
Note that currently our bang handler outputs the value after incrementing it, which seems a bit awkward now that we can actually specify the counter's start value. Let's rework that method so that it spits out the current value before incrementing it:
xxxxxxxxxxfunction foo:in_1_bang() self:outlet(1, "float", {self.counter}) self.counter = self.counter + 1end
Note that it's perfectly fine to invoke self:outlet at any point in the method.
While we're at it, we might as well add an optional second creation argument to specify the step value of the counter. Try doing that on your own, before peeking at the solution below!
Got it? Good. Here is our final script:
xxxxxxxxxxlocal foo = pd.Class:new():register("foo")
+function foo:in_1_bang() self.counter = self.counter + 1 self:outlet(1, "float", {self.counter})end
So let's relaunch Pd, reload the patch again, and add some GUI elements to test it out:
Note that this is still a very basic example. While the example is complete and fully functional, we have barely scratched the surface here. Pd-Lua also allows you to process an object's creation arguments (employing the atoms parameter of the initialize method, which we didn't use above), log messages and errors in the Pd console, create handlers for different types of input messages, output data to different outlets, work with Pd arrays, clocks, and receivers, and even do some live coding. We will dive into each of these topics in the following sections.
Where your Lua files go
As already mentioned, the externals (.pd_lua files) themselves can go either into the directory of the patch using the external, or into any other directory on Pd's search path (on Linux, this generally includes, ~/.pd-externals, or ~/.pd-l2ork-externals when running pd-l2ork or purr-data).
The Lua loader temporarily sets up Lua's package.path so that it includes the directory with the external, so you can put any Lua modules (.lua files) required by the external into that directory.
NOTE: As of Pd-Lua 0.12.5, the same is true for the pdlua external directory, where you can put any Lua modules that should be readily available to all your Pd-Lua objects. One example of this is Pd-Lua's own pdx.lua live-coding module which we'll discuss later, but it can also be used for general Lua utility modules that you want to use. There are a lot of incredibly useful Lua libraries out there, such as kikito 's inspect or lunarmodules' penlight, although you might prefer to install these using LuaRocks, Lua's most popular package manager.
If you need/want to use Lua libraries from other locations which aren't on the standard Lua package.path, then you'll have to set up the LUA_PATH environment variable accordingly. LuaRocks usually takes care of this for you when set up properly. Otherwise you can set LUA_PATH manually in your system startup files, such as ~/.bashrc or ~/.xprofile on Linux. E.g.:
x
export LUA_PATH=~/lua/'?.lua;;'
Note that ? is a placeholder for the module name, the semicolon ; can be used to separate different locations, and a double semicolon ;; adds Lua's standard search path (make sure that you quote those special characters so that the shell doesn't try to interpret them). You should always include the double semicolon somewhere, otherwise the Lua interpreter won't be able to find its standard library modules any more. Also note that you may want to place the ;; in front of the path instead, if the standard locations are to be searched before your custom ones.
Creation arguments
Besides the implicit self argument, the initialize method has two additional parameters:
sel, the selector argument, is a string which contains the Pd name of the object class. You probably won't need this, unless you want to use it for error reporting, or if you have a generic setup function for several related object classes. We won't go into this here.
atoms is a Lua table which contains all the arguments (Pd "atoms", i.e., numbers or strings) an object was created with. #atoms gives you the number of creation arguments (which may be zero if none were specified), atoms[1] is the first argument, atoms[2] the second, and so on. As usual in Lua, if the index i runs past the last argument, atoms[i] returns nil.
For instance, let's say that we want to equip our foo object with an optional creation argument, a number, to set the initial counter value. This can be done as follows:
xxxxxxxxxxfunction foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 if type(atoms[1]) == "number" then self.counter = atoms[1] else self.counter = 0 end return trueend
Here we check that the first creation argument is a number. In that case we use it to initialize the counter member variable, otherwise a default value of 0 is set. Note that if there is no creation argument, atoms[1] will be nil which is of type "nil", in which case the zero default value will be used.
Note that currently our bang handler outputs the value after incrementing it, which seems a bit awkward now that we can actually specify the counter's start value. Let's rework that method so that it spits out the current value before incrementing it:
xxxxxxxxxxfunction foo:in_1_bang() self:outlet(1, "float", {self.counter}) self.counter = self.counter + 1end
Note that it's perfectly fine to invoke self:outlet at any point in the method.
While we're at it, we might as well add an optional second creation argument to specify the step value of the counter. Try doing that on your own, before peeking at the solution below!
Got it? Good. Here is our final script:
xxxxxxxxxxlocal foo = pd.Class:new():register("foo")
function foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 if type(atoms[1]) == "number" then self.counter = atoms[1] else self.counter = 0 end if type(atoms[2]) == "number" then self.step = atoms[2] else self.step = 1 end return trueend
function foo:in_1_bang() self:outlet(1, "float", {self.counter}) self.counter = self.counter + self.stepend
That was easy enough. If you've been following along, you also know by now how to reload the patch and add a few bits to test the new features. For instance:
Log messages and errors
As soon as your objects get more complicated, you'll probably want to add some messages indicating to the user (or yourself) what's going on inside the object's methods. To these ends, Pd-Lua provides the following two facilities which let you output text messages to the Pd console:
pd.post(msg) outputs the string msg to the console on a separate line. You can also post multi-line messages by embedding newline (\n) characters in the msg string. This is also frequently used for debugging purposes, e.g., to print out incoming messages or intermediate values that your code calculates.
self:error(msg) reports an error message, given as a string msg, to the console. These messages are printed in red, to make them stand out, and you can use the "Find Last Error" menu option to locate the object which reported the error. (In Purr Data it's also possible to just click on the "error" link in the console to locate the object.) Note that self:error simply prints the message in a way that ties in with "Find Last Error". It doesn't abort the method that executes it, or have any other grave consequences. Thus you can also use it for debugging purposes, like pd.post, if you need to trace the message back to the object it came from.
For instance, let's use these facilities to have our foo object post the initial counter value in the initialize method, as well as report an error if any of the given creation arguments is of the wrong type. Here is the suitably modified initialize method:
xxxxxxxxxxfunction foo:initialize(sel, atoms) self.inlets = 1 self.outlets = 1 self.counter = 0 self.step = 1 if type(atoms[1]) == "number" then self.counter = atoms[1] elseif type(atoms[1]) ~= "nil" then self:error(string.format("foo: #1: %s is of the wrong type %s", tostring(atoms[1]), type(atoms[1]))) end if type(atoms[2]) == "number" then self.step = atoms[2] elseif type(atoms[2]) ~= "nil" then self:error(string.format("foo: #2: %s is of the wrong type %s", tostring(atoms[2]), type(atoms[2]))) end pd.post(string.format("foo: initialized counter: %g, step size: %g", self.counter, self.step)) return trueend
And here's how the console log looks like after loading our test patch, and creating an erroneous foo bad object:
Note that the foo bad object was still created with the appropriate defaults after the error message, so the initialize method ran through to the end alright. If you want the object creation to fail after printing the error message, you only have to add a return false statement in the elseif branch, after the call to self:error. Try it! (Of course, you won't be able to locate the object using the printed error message in this case, since the object wasn't actually created. But "Find Last Error" will still work, since Pd itself will also print a "couldn't create" error message.)
Here's another fun exercise: Let's have foo print a welcome message when it first gets invoked. This can be done by adding a variable init to the foo class itself, which is shared between different object instances, as follows:
xxxxxxxxxxfoo.init = false
You should put this after the definition of foo (i.e., after the line with the pd.Class:new() call), but before any code that uses this variable. Note that we could also just have used an ordinary local variable at script level instead, but this illustrates how you create static class members in Lua.
You still have to add the code which outputs the welcome message. An obvious place for this is somewhere in initialize, but here we use the postinitialize method for illustration purposes:
xxxxxxxxxxfunction foo:postinitialize() if not foo.init then pd.post("Welcome to foo! Copyright (c) by Foo software.") foo.init = true endend
This will print the message just once, right after the first foo object is created. There's another finalize method which can be used to perform any kind of cleanup when an object gets destroyed. For instance, let's rework our example so that it keeps track of the actual number of foo objects, and prints an additional message when the last foo object is deleted. To these ends, we turn foo.init into a counter which keeps track of the number of foo objects:
xxxxxxxxxxfoo.init = 0
function foo:postinitialize() if foo.init == 0 then pd.post("Welcome to foo! Copyright (c) by Foo software.") end foo.init = foo.init + 1end
@@ -772,7 +772,7 @@
local x1, y1 = x/width-0.5, y/height-0.5 -- calculate the normalized phase, shifted by 0.5, since we want zero to be -- the center up position local phase = math.atan(y1, x1)/math.pi + 0.5 -- renormalize if we get an angle > 1, to account for the phase shift if phase > 1 then phase = phase - 2 end
self.phase = phase
local tip_x, tip_y = self:tip();
- if tip_x ~= self.tip_x or tip_y ~= self.tip_y then self.tip_x = tip_x self.tip_y = tip_y self:in_1_bang() self:repaint() endend
And here's the same patch again, which now lets us drag the hand to change the phase value:
More dial action: clocks and speedometers
Now that our dial object is basically finished, let's do something interesting with it. The most obvious thing is to just turn it into a clock (albeit one with just a seconds dial) counting off the seconds. For that we just need to add a metro object which increments the phase angle and sends the value to the dial each second:
In the patch, we store the current phase angle in the phase variable, so that it can be updated easily using the expr object by just assigning to the variable. Note that we also update the variable whenever the dial outputs a new value, so you can also drag around the hand to determine its starting phase.
Here's another little example, rather useless but fun, simulating a speedometer which just randomly moves the needle left and right:
I'm sure you can imagine many more creative uses for this simple but surprisingly versatile little GUI object, which we did in just a few lines of fairly simple Lua code. Have fun with it! An extended version of this object, which covers some more features of the graphics API that we didn't discuss here to keep things simple, can be found as dial.pd and dial.pd_lua in the tutorial examples:
The extended example adds messages for resizing the object and setting colors, and also shows how to save and restore object state in the creation arguments using the set_args() method mentioned at the beginning of this section. The accompanying patch covers all the examples we discussed here, and adds a third example showing how to utilize our dial object as a dB meter.
Live coding
I've been telling you all along that in order to make Pd-Lua pick up changes you made to your .pd_lua files, you have to relaunch Pd and reload your patches. Well, in this section we are going to discuss Pd-Lua's live coding features, which let you modify your sources and have Pd-Lua reload them on the fly, without ever exiting the Pd environment. This rapid incremental style of development is one of the hallmark features of dynamic programming environments like Pd and Lua. Musicians also like to employ it to modify their algorithmic composition programs live on stage, which is where the term "live coding" comes from. You'll probably be using live coding a lot while developing your Pd-Lua externals, but I've kept this topic for the final section of this guide, because it requires a good understanding of Pd-Lua's basic features. So without any further ado, let's dive right into it now.
First, we need to describe the predefined Pd-Lua object classes pdlua and pdluax, so that you know what's readily available. We'll also discuss how to add a reload message to your existing object definitions. This is quite easy to do by directly employing Pd-Lua's dofile method, which is also what both pdlua and pdluax use internally. These methods all work with older Pd-Lua versions, but they require a lot of manual fiddling with the Lua source and are are thus arduous and error-prone. That's why we also provide the special pdx.lua module which automatizes the entire process and is much less work than all the other approaches (basically, you just add two lines to your script and be done with it). Hence this is the method we recommend for all modern Pd-Lua versions. We describe it last so that you can also gather a good understanding of the "legacy" live coding methods on offer. But if you want something that just works with minimal effort, feel free to skip ahead to the pdx.lua section below which should be readable without any prior knowledge of the other approaches.
pdlua
The pdlua object accepts a single kind of message of the form load filename on its single inlet, which causes the given Lua file to be loaded and executed. Since pdlua has no outlets, its uses are rather limited. However, it does enable you to load global Lua definitions and execute an arbitrary number of statements, e.g., to post some text to the console or transmit messages to Pd receivers using the corresponding Pd-Lua functions. For instance, here's a little Lua script loadtest.lua which simply increments a global counter variable (first initializing it to zero if the variable doesn't exist yet) and posts its current value in the console:
xxxxxxxxxxcounter = counter and counter + 1 or 0pd.post(string.format("loadtest: counter = %d", counter))
To run this Lua code in Pd, you just need to connect the message load loadtest.lua to pdlua's inlet (note that you really need to specify the full filename here, there's no default suffix):
Now, each time you click on the load loadtest.lua message, the file is reloaded and executed, resulting in some output in the console, e.g.:
xxxxxxxxxxloadtest: counter = 0loadtest: counter = 1
Also, you can edit the script between invocations and the new code will be loaded and used immediately. E.g., if you change counter + 1 to counter - 1, you'll get:
xxxxxxxxxxloadtest: counter = 0loadtest: counter = -1
That's about all there is to say about pdlua; it's a very simple object.
pdluax
pdluax is a bit more elaborate and allows you to create real Pd-Lua objects with an arbitrary number of inlets, outlets, and methods. To these ends, it takes a single creation argument, the basename of a .pd_luax file. This file is a Lua script returning a function to be executed in pdluax's own initialize method, which contains all the usual definitions, including the object's method definitions, in its body. This function receives the object's self as well as all the extra arguments pdluax was invoked with, and should return true if creation of the object succeeded.
For instance, here's a simplified version of our foo counter object, rewritten as a .pd_luax file, to be named foo.pd_luax:
xxxxxxxxxxreturn function (self, sel, atoms) self.inlets = 1 self.outlets = 1 self.counter = type(atoms[1]) == "number" and atoms[1] or 0 self.step = type(atoms[2]) == "number" and atoms[2] or 1 function self:in_1_bang() self:outlet(1, "float", {self.counter}) self.counter = self.counter + self.step end return trueend
Note the colon syntax self:in_1_bang(). This adds the bang method directly to the self object rather than its class, which is pdluax. (We obviously don't want to modify the class itself, which may be used to create any number of different kinds of objects, each with their own collection of methods.) Also note that the outer function is "anonymous" (nameless) here; you can name it, but there's usually no need to do that, because this function will be executed just once, when the corresponding pdluax object is created. Another interesting point to mention here is that this approach of including all the object's method definitions in its initialization method works with regular .pd_lua objects, too; try it!
In the patch, we invoke a .pd_luax object by specifying the basename of its script file as pdluax's first argument, adding any additional creation arguments that the object itself might need:
These pdluax foo objects work just the same as their regular foo counterparts, but there's an important difference: The code in foo.pd_luax is loaded every time you create a new pdluax foo object. Thus you can easily modify that file and just add a new pdluax foo object to have it run the latest version of your code. For instance, in foo.pd_luax take the line that reads:
xxxxxxxxxx self.counter = self.counter + self.step
Now change that + operator to -:
xxxxxxxxxx self.counter = self.counter - self.step
Don't forget to save your edits, then go back to the patch and recreate the pdluax foo object on the left. The quickest way to do that is to just delete the object, then use Pd's "Undo" operation, Ctrl+Z. Et voilà: the new object now decrements the counter rather than incrementing it. Also note that the other object on the right still runs the old code which increments the counter; thus you will have to give that object the same treatment if you want to update it, too.
While pdluax was considered Pd-Lua's main workhorse for live coding, it has its quirks. Most notably, the syntax is different from regular object definitions, so you have to change the code if you want to turn it into a .pd_lua file. Also, having to recreate an object to reload the script file is quite disruptive (it resets the internal state of the object), and may leave objects in an inconsistent state (different objects may use various different versions of the same script file). Sometimes this may be what you want, but it makes pdluax somewhat difficult to use. It's not really tailored for interactive development, but it shines if you need a specialized tool for changing your objects on a whim in a live situation.
Fortunately, if you're not content with Pd-Lua's built-in facilities for live coding, it's easy to roll your own using the internal dofile method, which is discussed in the next subsection.
dofile and dofilex
So let's discuss how to use dofile in a direct fashion. Actually, we're going to use its companion dofilex here, which works the same as dofile, but loads Lua code relative to the "externdir" of the class (the directory of the .pd_lua file) rather than the directory of the Pd canvas with the pdlua object, which is what dofile does. Normally, you don't have to worry about these intricacies, but they will matter if Lua class names are specified using relative pathnames, such as ../foo or bar/baz. Since we're reloading class definitions here, it's better to use dofilex so that our code doesn't break if we later change the directory structure.
The method we sketch out below is really simple and doesn't have any of the drawbacks of the pdluax object, but you still have to add a small amount of boilerplate code to your existing object definition. Here is how dofilex is invoked:
self:dofilex(scriptname): This loads the given Lua script, like Lua's loadfile, but also performs a search on Pd's path to locate the file, and finally executes the file if it was loaded successfully. Note that self must be a valid Pd-Lua object, which is used solely to determine the externdir of the object's class, so that the script will be found if it is located there.
The return values of dofilex are those of the Lua script, along with the path under which the script was found. If the script itself returns no value, then only the path will be returned. (We don't use any of this information in what follows, but it may be useful in more elaborate schemes. For instance, pdluax uses the returned function to initialize the object, and the path in setting up the object's actual script name.)
Of course, dofilex needs the name of the script file to be loaded. We could hardcode this as a string literal, but it's easier to just ask the object itself for this information. Each Pd-Lua object has a number of private member variables, among them _name (which is the name under which the object class was registered) and _scriptname (which is the name of the corresponding script file, usually this is just _name with the .pd_lua extension tacked onto it). The latter is what we need. Pd-Lua also offers a whoami() method for this purpose, but that method just returns _scriptname if it is set, or _name otherwise. Regular Pd-Lua objects always have _scriptname set, so it will do for our purposes.
Finally, we need to decide how to invoke dofilex in our object. The easiest way to do this is to just add a message handler (i.e., an inlet method) to the object. For instance, say that the object is named foo which is defined in the foo.pd_lua script. Then all you have to do is add something like the following definition to the script:
xxxxxxxxxxfunction foo:in_1_reload() self:dofilex(self._scriptname)end
As we already discussed, this code uses the object's internal _scriptname variable, and so is completely generic. You can just copy this over to any .pd_lua file, if you replace the foo prefix with whatever the name of your actual class variable is. With that definition added, you can now just send the object a reload message whenever you want to have its script file reloaded.
NOTE: This works because the pd.Class:new():register("foo") call of the object only registers a new class if that object class doesn't exist yet; otherwise it just returns the existing class.
By reloading the script file, all of the object's method definitions will be overwritten, not only for the object receiving the reload message, but for all objects of the same class, so it's sufficient to send the message to any (rather than every) object of the class. Also, existing object state (as embodied by the internal member variables of each object) will be preserved.
In general all this works pretty well, but there are some caveats, too. Note that if you delete one of the object's methods, or change its name, the old method will still hang around in the runtime class definition until you relaunch Pd. That's because reloading the script does not erase any old method definitions, it merely replaces existing and adds new ones.
Finally, keep in mind that reloading the script file does not re-execute the initialize method. This method is only invoked when an object is instantiated. Thus, in particular, reloading the file won't change the number of inlets and outlets of an existing object. Newly created objects will pick up the changes in initialize, though, and have the proper number of inlets and outlets if those member variables were changed.
Let's give this a try, using luatab.pd_lua from the "Using arrays and tables" section as an example. In fact, that's a perfect showcase for live coding, since we want to be able to change the definition of the waveform function f in luatab:in_1_float on the fly. Just add the following code to the end of luatab.pd_lua:
xxxxxxxxxxfunction luatab:in_1_reload() self:dofilex(self._scriptname)end
Now launch the luatab.pd patch and connect a reload message to the luatab wave object, like so:
Next change the wavetable function to whatever you want, e.g.:
xxxxxxxxxx local function f(x) return math.sin(2*math.pi*freq*x)+1/3*math.sin(2*math.pi*3*freq*x) end
Return to the patch, click the reload message, and finally reenter the frequency value, so that the waveform gets updated:
pdx.lua
The method sketched out in the preceding subsection works well enough for simple patches. However, having to manually wire up the reload message to one object of each class that you're editing is still quite cumbersome. In a big patch, which is being changed all the time, this quickly becomes unwieldy. Wouldn't it be nice if we could equip each object with a special receiver, so that we can just click a message somewhere in the patch to reload a given class, or even all Pd-Lua objects at once? And maybe even do that remotely from the editor, using the pdsend program?
Well, all this is in fact possible, but the implementation is a bit too involved to fully present it here. So we have provided this in a separate pdx.lua module, which you can find in the sources accompanying this tutorial. Setting up an object for this kind of remote control is easy, though. First, you need to import the pdx module into your script, using Lua's require:
xxxxxxxxxxlocal pdx = require 'pdx'
Then just call pdx.reload(self) somewhere in the initialize method. This will set up the whole receiver/dofilex machinery in a fully automatic manner. Finally, add a message like this to your patch, which goes to the special pdluax receiver (note that this is completely unrelated to the pdluax object discussed previously, it just incidentally uses the same name):
xxxxxxxxxx; pdluax reload
When clicked, this just reloads all Pd-Lua objects in the patch, provided they have been set up with pdx.reload. You can also specify the class to be reloaded (the receiver matches this against each object's class name):
xxxxxxxxxx; pdluax reload foo
Or maybe name several classes, like so:
xxxxxxxxxx; pdluax reload foo, reload bar
You get the idea. Getting set up for remote control via pdsend isn't much harder. E.g., let's say that we use UDP port 4711 on localhost for communicating with Pd, then you just need to connect netreceive 4711 1 to the ; pdluax reload message in a suitable way, e.g.:
You can then use pdsend 4711 localhost udp to transmit the reload message to Pd when needed. You probably don't want to run those commands yourself, but a decent code editor will let you bind a keyboard command which does this for you. Myself, I'm a die-hard Emacs fan, so I've included a little elisp module pd-remote.el which shows how to do this. Once you've added this to your .emacs, you can just type Ctrl+C Ctrl+K in Emacs to make Pd reload your Lua script after saving it. It doesn't get much easier than that.
Moreover, for your convenience I've also added a little abstraction named pd-remote.pd which takes care of the netreceive and messaging bits and will look much tidier in your patches. Using the abstraction is easy: Insert pd-remote into the patch you're working on, and connect a pdluax reload message (without the ; prefix) to the inlet of the abstraction. Now you can just click on that message to reload your script files. In fact any of the variations of reload messages discussed above will work, if you remove the ; prefix, and the abstraction will also respond to such messages on port 4711 by default (the port number can be changed in the abstraction if needed).
NOTE: As of Pd-Lua 0.12.5, using pdx.lua has become much easier, since pdx.lua, pd-remote.el, and pd-remote.pd get installed in your pdlua external directory, and this directory now also gets searched for Lua imports. Thus require 'pdx' will just work in all your Pd-Lua scripts without any further ado. To make Pd find the pd-remote.pd abstraction, you'll still have to copy it to your project directory. Or you can add the pdlua directory to your Pd library path. (Depending on how Pd-Lua was installed, you may want to do that anyway so that the pdlua directory shows up in Pd's help browser.)
The pd-remote.el file can be installed in your Emacs site-lisp directory if needed. Please also check the pd-remote repository on GitHub for the latest pd-remote version and further details. This also includes a pointer to a Visual Studio Code extension written by Baris Altun which can be used as a replacement for pd-remote.el if you're not familiar with Emacs, or just prefer to use VS Code as an editor.
So here's the full source code of our reworked luatab example (now with the in_1_reload handler removed and the pdx.reload call added to the initialize method):
xlocal luatab = pd.Class:new():register("luatab")
+ if tip_x ~= self.tip_x or tip_y ~= self.tip_y then self.tip_x = tip_x self.tip_y = tip_y self:in_1_bang() self:repaint() endend
And here's the same patch again, which now lets us drag the hand to change the phase value:
More dial action: clocks and speedometers
Now that our dial object is basically finished, let's do something interesting with it. The most obvious thing is to just turn it into a clock (albeit one with just a seconds hand) counting off the seconds. For that we just need to add a metro object which increments the phase angle and sends the value to the dial each second:
In the patch, we store the current phase angle in the phase variable, so that it can be updated easily using the expr object by just assigning to the variable. Note that we also update the variable whenever the dial outputs a new value, so you can also drag around the hand to determine its starting phase.
Here's another little example, rather useless but fun, simulating a speedometer which just randomly moves the needle left and right:
I'm sure you can imagine many more creative uses for this simple but surprisingly versatile little GUI object, which we did in just a few lines of fairly simple Lua code. Have fun with it! An extended version of this object, which covers some more features of the graphics API that we didn't discuss here to keep things simple, can be found as dial.pd and dial.pd_lua in the tutorial examples:
The extended example adds messages for resizing the object and setting colors, and also shows how to save and restore object state in the creation arguments using the set_args() method mentioned at the beginning of this section. The accompanying patch covers all the examples we discussed here, and adds a third example showing how to utilize our dial object as a dB meter.
Live coding
I've been telling you all along that in order to make Pd-Lua pick up changes you made to your .pd_lua files, you have to relaunch Pd and reload your patches. Well, in this section we are going to discuss Pd-Lua's live coding features, which let you modify your sources and have Pd-Lua reload them on the fly, without ever exiting the Pd environment. This rapid incremental style of development is one of the hallmark features of dynamic programming environments like Pd and Lua. Musicians also like to employ it to modify their algorithmic composition programs live on stage, which is where the term "live coding" comes from. You'll probably be using live coding a lot while developing your Pd-Lua externals, but I've kept this topic for the final section of this guide, because it requires a good understanding of Pd-Lua's basic features. So without any further ado, let's dive right into it now.
First, we need to describe the predefined Pd-Lua object classes pdlua and pdluax, so that you know what's readily available. We'll also discuss how to add a reload message to your existing object definitions. This is quite easy to do by directly employing Pd-Lua's dofile method, which is also what both pdlua and pdluax use internally. These methods all work with older Pd-Lua versions, but they require a lot of manual fiddling with the Lua source and are are thus arduous and error-prone. That's why we also provide the special pdx.lua module which automatizes the entire process and is much less work than all the other approaches (basically, you just add two lines to your script and be done with it). Hence this is the method we recommend for all modern Pd-Lua versions. We describe it last so that you can also gather a good understanding of the "legacy" live coding methods on offer. But if you want something that just works with minimal effort, feel free to skip ahead to the pdx.lua section below which should be readable without any prior knowledge of the other approaches.
pdlua
The pdlua object accepts a single kind of message of the form load filename on its single inlet, which causes the given Lua file to be loaded and executed. Since pdlua has no outlets, its uses are rather limited. However, it does enable you to load global Lua definitions and execute an arbitrary number of statements, e.g., to post some text to the console or transmit messages to Pd receivers using the corresponding Pd-Lua functions. For instance, here's a little Lua script loadtest.lua which simply increments a global counter variable (first initializing it to zero if the variable doesn't exist yet) and posts its current value in the console:
xxxxxxxxxxcounter = counter and counter + 1 or 0pd.post(string.format("loadtest: counter = %d", counter))
To run this Lua code in Pd, you just need to connect the message load loadtest.lua to pdlua's inlet (note that you really need to specify the full filename here, there's no default suffix):
Now, each time you click on the load loadtest.lua message, the file is reloaded and executed, resulting in some output in the console, e.g.:
xxxxxxxxxxloadtest: counter = 0loadtest: counter = 1
Also, you can edit the script between invocations and the new code will be loaded and used immediately. E.g., if you change counter + 1 to counter - 1, you'll get:
xxxxxxxxxxloadtest: counter = 0loadtest: counter = -1
That's about all there is to say about pdlua; it's a very simple object.
pdluax
pdluax is a bit more elaborate and allows you to create real Pd-Lua objects with an arbitrary number of inlets, outlets, and methods. To these ends, it takes a single creation argument, the basename of a .pd_luax file. This file is a Lua script returning a function to be executed in pdluax's own initialize method, which contains all the usual definitions, including the object's method definitions, in its body. This function receives the object's self as well as all the extra arguments pdluax was invoked with, and should return true if creation of the object succeeded.
For instance, here's a simplified version of our foo counter object, rewritten as a .pd_luax file, to be named foo.pd_luax:
xxxxxxxxxxreturn function (self, sel, atoms) self.inlets = 1 self.outlets = 1 self.counter = type(atoms[1]) == "number" and atoms[1] or 0 self.step = type(atoms[2]) == "number" and atoms[2] or 1 function self:in_1_bang() self:outlet(1, "float", {self.counter}) self.counter = self.counter + self.step end return trueend
Note the colon syntax self:in_1_bang(). This adds the bang method directly to the self object rather than its class, which is pdluax. (We obviously don't want to modify the class itself, which may be used to create any number of different kinds of objects, each with their own collection of methods.) Also note that the outer function is "anonymous" (nameless) here; you can name it, but there's usually no need to do that, because this function will be executed just once, when the corresponding pdluax object is created. Another interesting point to mention here is that this approach of including all the object's method definitions in its initialization method works with regular .pd_lua objects, too; try it!
In the patch, we invoke a .pd_luax object by specifying the basename of its script file as pdluax's first argument, adding any additional creation arguments that the object itself might need:
These pdluax foo objects work just the same as their regular foo counterparts, but there's an important difference: The code in foo.pd_luax is loaded every time you create a new pdluax foo object. Thus you can easily modify that file and just add a new pdluax foo object to have it run the latest version of your code. For instance, in foo.pd_luax take the line that reads:
xxxxxxxxxx self.counter = self.counter + self.step
Now change that + operator to -:
xxxxxxxxxx self.counter = self.counter - self.step
Don't forget to save your edits, then go back to the patch and recreate the pdluax foo object on the left. The quickest way to do that is to just delete the object, then use Pd's "Undo" operation, Ctrl+Z. Et voilà: the new object now decrements the counter rather than incrementing it. Also note that the other object on the right still runs the old code which increments the counter; thus you will have to give that object the same treatment if you want to update it, too.
While pdluax was considered Pd-Lua's main workhorse for live coding, it has its quirks. Most notably, the syntax is different from regular object definitions, so you have to change the code if you want to turn it into a .pd_lua file. Also, having to recreate an object to reload the script file is quite disruptive (it resets the internal state of the object), and may leave objects in an inconsistent state (different objects may use various different versions of the same script file). Sometimes this may be what you want, but it makes pdluax somewhat difficult to use. It's not really tailored for interactive development, but it shines if you need a specialized tool for changing your objects on a whim in a live situation.
Fortunately, if you're not content with Pd-Lua's built-in facilities for live coding, it's easy to roll your own using the internal dofile method, which is discussed in the next subsection.
dofile and dofilex
So let's discuss how to use dofile in a direct fashion. Actually, we're going to use its companion dofilex here, which works the same as dofile, but loads Lua code relative to the "externdir" of the class (the directory of the .pd_lua file) rather than the directory of the Pd canvas with the pdlua object, which is what dofile does. Normally, you don't have to worry about these intricacies, but they will matter if Lua class names are specified using relative pathnames, such as ../foo or bar/baz. Since we're reloading class definitions here, it's better to use dofilex so that our code doesn't break if we later change the directory structure.
The method we sketch out below is really simple and doesn't have any of the drawbacks of the pdluax object, but you still have to add a small amount of boilerplate code to your existing object definition. Here is how dofilex is invoked:
self:dofilex(scriptname): This loads the given Lua script, like Lua's loadfile, but also performs a search on Pd's path to locate the file, and finally executes the file if it was loaded successfully. Note that self must be a valid Pd-Lua object, which is used solely to determine the externdir of the object's class, so that the script will be found if it is located there.
The return values of dofilex are those of the Lua script, along with the path under which the script was found. If the script itself returns no value, then only the path will be returned. (We don't use any of this information in what follows, but it may be useful in more elaborate schemes. For instance, pdluax uses the returned function to initialize the object, and the path in setting up the object's actual script name.)
Of course, dofilex needs the name of the script file to be loaded. We could hardcode this as a string literal, but it's easier to just ask the object itself for this information. Each Pd-Lua object has a number of private member variables, among them _name (which is the name under which the object class was registered) and _scriptname (which is the name of the corresponding script file, usually this is just _name with the .pd_lua extension tacked onto it). The latter is what we need. Pd-Lua also offers a whoami() method for this purpose, but that method just returns _scriptname if it is set, or _name otherwise. Regular Pd-Lua objects always have _scriptname set, so it will do for our purposes.
Finally, we need to decide how to invoke dofilex in our object. The easiest way to do this is to just add a message handler (i.e., an inlet method) to the object. For instance, say that the object is named foo which is defined in the foo.pd_lua script. Then all you have to do is add something like the following definition to the script:
xxxxxxxxxxfunction foo:in_1_reload() self:dofilex(self._scriptname)end
As we already discussed, this code uses the object's internal _scriptname variable, and so is completely generic. You can just copy this over to any .pd_lua file, if you replace the foo prefix with whatever the name of your actual class variable is. With that definition added, you can now just send the object a reload message whenever you want to have its script file reloaded.
NOTE: This works because the pd.Class:new():register("foo") call of the object only registers a new class if that object class doesn't exist yet; otherwise it just returns the existing class.
By reloading the script file, all of the object's method definitions will be overwritten, not only for the object receiving the reload message, but for all objects of the same class, so it's sufficient to send the message to any (rather than every) object of the class. Also, existing object state (as embodied by the internal member variables of each object) will be preserved.
In general all this works pretty well, but there are some caveats, too. Note that if you delete one of the object's methods, or change its name, the old method will still hang around in the runtime class definition until you relaunch Pd. That's because reloading the script does not erase any old method definitions, it merely replaces existing and adds new ones.
Finally, keep in mind that reloading the script file does not re-execute the initialize method. This method is only invoked when an object is instantiated. Thus, in particular, reloading the file won't change the number of inlets and outlets of an existing object. Newly created objects will pick up the changes in initialize, though, and have the proper number of inlets and outlets if those member variables were changed.
Let's give this a try, using luatab.pd_lua from the "Using arrays and tables" section as an example. In fact, that's a perfect showcase for live coding, since we want to be able to change the definition of the waveform function f in luatab:in_1_float on the fly. Just add the following code to the end of luatab.pd_lua:
xxxxxxxxxxfunction luatab:in_1_reload() self:dofilex(self._scriptname)end
Now launch the luatab.pd patch and connect a reload message to the luatab wave object, like so:
Next change the wavetable function to whatever you want, e.g.:
xxxxxxxxxx local function f(x) return math.sin(2*math.pi*freq*x)+1/3*math.sin(2*math.pi*3*freq*x) end
Return to the patch, click the reload message, and finally reenter the frequency value, so that the waveform gets updated:
pdx.lua
The method sketched out in the preceding subsection works well enough for simple patches. However, having to manually wire up the reload message to one object of each class that you're editing is still quite cumbersome. In a big patch, which is being changed all the time, this quickly becomes unwieldy. Wouldn't it be nice if we could equip each object with a special receiver, so that we can just click a message somewhere in the patch to reload a given class, or even all Pd-Lua objects at once? And maybe even do that remotely from the editor, using the pdsend program?
Well, all this is in fact possible, but the implementation is a bit too involved to fully present it here. So we have provided this in a separate pdx.lua module, which you can find in the sources accompanying this tutorial. Setting up an object for this kind of remote control is easy, though. First, you need to import the pdx module into your script, using Lua's require:
xxxxxxxxxxlocal pdx = require 'pdx'
Then just call pdx.reload(self) somewhere in the initialize method. This will set up the whole receiver/dofilex machinery in a fully automatic manner. Finally, add a message like this to your patch, which goes to the special pdluax receiver (note that this is completely unrelated to the pdluax object discussed previously, it just incidentally uses the same name):
xxxxxxxxxx; pdluax reload
When clicked, this just reloads all Pd-Lua objects in the patch, provided they have been set up with pdx.reload. You can also specify the class to be reloaded (the receiver matches this against each object's class name):
xxxxxxxxxx; pdluax reload foo
Or maybe name several classes, like so:
xxxxxxxxxx; pdluax reload foo, reload bar
You get the idea. Getting set up for remote control via pdsend isn't much harder. E.g., let's say that we use UDP port 4711 on localhost for communicating with Pd, then you just need to connect netreceive 4711 1 to the ; pdluax reload message in a suitable way, e.g.:
You can then use pdsend 4711 localhost udp to transmit the reload message to Pd when needed. You probably don't want to run those commands yourself, but a decent code editor will let you bind a keyboard command which does this for you. Myself, I'm a die-hard Emacs fan, so I've included a little elisp module pd-remote.el which shows how to do this. Once you've added this to your .emacs, you can just type Ctrl+C Ctrl+K in Emacs to make Pd reload your Lua script after saving it. It doesn't get much easier than that.
Moreover, for your convenience I've also added a little abstraction named pd-remote.pd which takes care of the netreceive and messaging bits and will look much tidier in your patches. Using the abstraction is easy: Insert pd-remote into the patch you're working on, and connect a pdluax reload message (without the ; prefix) to the inlet of the abstraction. Now you can just click on that message to reload your script files. In fact any of the variations of reload messages discussed above will work, if you remove the ; prefix, and the abstraction will also respond to such messages on port 4711 by default (the port number can be changed in the abstraction if needed).
NOTE: As of Pd-Lua 0.12.5, using pdx.lua has become much easier, since pdx.lua, pd-remote.el, and pd-remote.pd get installed in your pdlua external directory, and this directory now also gets searched for Lua imports. Thus require 'pdx' will just work in all your Pd-Lua scripts without any further ado. To make Pd find the pd-remote.pd abstraction, you'll still have to copy it to your project directory. Or you can add the pdlua directory to your Pd library path. (Depending on how Pd-Lua was installed, you may want to do that anyway so that the pdlua directory shows up in Pd's help browser.)
The pd-remote.el file can be installed in your Emacs site-lisp directory if needed. Please also check the pd-remote repository on GitHub for the latest pd-remote version and further details. This also includes a pointer to a Visual Studio Code extension written by Baris Altun which can be used as a replacement for pd-remote.el if you're not familiar with Emacs, or just prefer to use VS Code as an editor.
So here's the full source code of our reworked luatab example (now with the in_1_reload handler removed and the pdx.reload call added to the initialize method):
xxxxxxxxxxlocal luatab = pd.Class:new():register("luatab")
-- our own pdlua extension, needed for the reload functionalitylocal pdx = require 'pdx'
function luatab:initialize(sel, atoms) -- single inlet for the frequency, bang goes to the single outlet when we -- finished generating a new waveform self.inlets = 1 self.outlets = 1 -- enable the reload callback pdx.reload(self) -- the name of the array/table should be in the 1st creation argument if type(atoms[1]) == "string" then self.tabname = atoms[1] return true else self:error(string.format("luatab: expected array name, got %s", tostring(atoms[1]))) return false endend
function luatab:in_1_float(freq) if type(freq) == "number" then -- the waveform we want to compute, adjust this as needed local function f(x) return math.sin(2*math.pi*freq*(x+1))/(x+1) end -- get the Pd array and its length local t = pd.Table:new():sync(self.tabname) if t == nil then self:error(string.format("luatab: array or table %s not found", self.tabname)) return end local l = t:length() -- Pd array indices are zero-based for i = 0, l-1 do -- normalize arguments to the 0-1 range t:set(i, f(i/l)) end -- this is needed to update the graph display t:redraw() -- output a bang to indicate that we've generated a new waveform self:outlet(1, "bang", {}) else self:error(string.format("luatab: expected frequency, got %s", tostring(freq))) endend
And here's a little gif showing the above patch in action. You may want to watch this in Typora or your favorite web browser to make the animation work.
So there you have it: four different ways to live-code with Pd-Lua. Choose whatever best fits your purpose and is the most convenient for you.
Conclusion
Congratulations! If you made it this far, you should have learned more than enough to start using Pd-Lua successfully for your own projects. You should also be able to read and understand the many examples in the Pd-Lua distribution, which illustrate all the various features in much more detail than we could muster in this introduction. You can find these in the examples folder, both in the Pd-Lua sources and the pdlua folder of your Pd installation.
The examples accompanying this tutorial (including the pdx.lua, pdlua-remote.el and pdlua-remote.pd files mentioned at the end of the previous section) are also available for your perusal in the examples subdirectory of the folder where you found this document.
Finally, I'd like to thank Claude Heiland-Allen for creating such an amazing tool, it makes programming Pd externals really easy and fun. Kudos also to Roberto Ierusalimschy for Lua, which for me is one of the best-designed, easiest to learn, and most capable multi-paradigm scripting languages there are today, while also being fast, simple, and light-weight.
diff --git a/tutorial/pd-lua-intro.md b/tutorial/pd-lua-intro.md
index 9baaadc..a81dba6 100644
--- a/tutorial/pd-lua-intro.md
+++ b/tutorial/pd-lua-intro.md
@@ -13,9 +13,9 @@ Permanent link:
Pd's facilities for data structures, iteration, and recursion are somewhat limited, thus sooner or later you'll probably run into a problem that can't be easily solved by a Pd abstraction any more. At this point you'll have to consider writing an external object (or just *external*, for short) in a "real" programming language instead. Pd externals are usually programmed using C, the same programming language that Pd itself is written in. But novices may find C difficult to learn, and the arcana of Pd's C interface may also be hard to master.
-Enter Pd-Lua, the Pd programmer's secret weapon, which lets you develop your externals in the [Lua](https://www.lua.org/) scripting language. Pd-Lua was originally written by Claude Heiland-Allen and has since been maintained by a number of other people in the Pd community. Lua, from [PUC Rio](http://www.puc-rio.br/), is open-source (under the MIT license), mature, very popular, and supported by a large developer community. It is a small programming language, but very capable, and is generally considered to be relatively easy to learn. For programming Pd externals, you'll also need to learn a few bits and pieces which let you interface your Lua functions to Pd, as explained in this tutorial, but programming externals in Lua is still quite easy and a lot of fun.
+Enter Pd-Lua, the Pd programmer's secret weapon, which lets you develop your externals in the [Lua](https://www.lua.org/) scripting language. Pd-Lua was originally written by Claude Heiland-Allen and has since been maintained by a number of other people in the Pd community. Lua, from [PUC Rio](http://www.puc-rio.br/), is open-source (under the MIT license), mature, very popular, and supported by a large developer community. It is a small programming language, but very capable, and is generally considered to be relatively easy to learn. For programming Pd externals, you'll also need to learn a few bits and pieces which let you interface your Lua functions to Pd, as explained in this tutorial, but programming externals in Lua is still quite easy and a lot of fun. Using Pd-Lua, you can program your own externals ranging from little helper objects to full-blown synthesizers, sequencers, and algorithmic composition tools. It gives you access to Pd arrays and tables, as well as a number of other useful facilities such as clocks and receivers, which we'll explain in some detail. Pd-Lua also ships with a large collection of instructive examples which you'll find helpful when exploring its possibilities.
-Using Pd-Lua, you can program your own externals ranging from little helper objects to full-blown sequencers and algorithmic composition tools. Pd-Lua is primarily aimed at control objects at this time (for doing dsp, you might consider using [Faust](https://faust.grame.fr/) instead), but thanks to contributions by Timothy Schoen, the most recent version also provides support for signal processing and even graphics. It also gives you access to Pd arrays and tables, as well as a number of other useful facilities such as clocks and receivers, which we'll explain in some detail. Pd-Lua also ships with a large collection of instructive examples which you'll find helpful when exploring its possibilities.
+Pd-Lua was originally designed for control processing, so we used to recommend [Faust](https://faust.grame.fr/) for doing dsp instead. We still do, but Faust isn't for everyone; being a purely functional language, Faust follows a paradigm which most programmers aren't very familiar with. Fortunately, thanks to the work of Timothy Schoen, the most recent Pd-Lua versions now also provide support for signal processing and even graphics. So it is now possible to create pretty much any kind of Pd object in Lua, including dsp objects. (However, Faust will almost certainly execute dsp code much more efficiently than Pd-Lua, as it generates highly optimized native code for just this purpose.)
Note that we can't possibly cover Pd or the Lua language themselves here, so you'll have to refer to other online resources to learn about those. In particular, check out the Lua website, which has extensive [documentation](https://www.lua.org/docs.html) available, and maybe have a look at Derek Banas' [video tutorial](https://www.youtube.com/watch?v=iMacxZQMPXs) for a quick overview of Lua. For Pd, we recommend the Pd FLOSS Manual at https://flossmanuals.net/ to get started.
@@ -149,7 +149,13 @@ As already mentioned, the externals (.pd_lua files) themselves can go either int
The Lua loader temporarily sets up Lua's `package.path` so that it includes the directory with the external, so you can put any Lua modules (.lua files) required by the external into that directory.
-If you need/want to use Lua libraries from other locations (which aren't on the standard Lua `package.path`), then you'll have to set up the `LUA_PATH` environment variable accordingly. When using [LuaRocks](https://luarocks.org/), Lua's most popular package manager, it usually takes care of this for you when set up properly. Otherwise you can set `LUA_PATH` manually in your system startup files, such as ~/.bashrc or ~/.xprofile on Linux. E.g.:
+---
+
+**NOTE:** As of Pd-Lua 0.12.5, the same is true for the pdlua external directory, where you can put any Lua modules that should be readily available to all your Pd-Lua objects. One example of this is Pd-Lua's own [pdx.lua](#pdx.lua) live-coding module which we'll discuss later, but it can also be used for general Lua utility modules that you want to use. There are a lot of incredibly useful Lua libraries out there, such as [kikito 's inspect](https://github.com/kikito/inspect.lua) or [lunarmodules' penlight](https://github.com/lunarmodules/Penlight), although you might prefer to install these using [LuaRocks](https://luarocks.org/), Lua's most popular package manager.
+
+---
+
+If you need/want to use Lua libraries from other locations which aren't on the standard Lua `package.path`, then you'll have to set up the `LUA_PATH` environment variable accordingly. LuaRocks usually takes care of this for you when set up properly. Otherwise you can set `LUA_PATH` manually in your system startup files, such as ~/.bashrc or ~/.xprofile on Linux. E.g.:
~~~shell
export LUA_PATH=~/lua/'?.lua;;'
@@ -1175,7 +1181,7 @@ And here's the same patch again, which now lets us drag the hand to change the p
#### More dial action: clocks and speedometers
-Now that our dial object is basically finished, let's do something interesting with it. The most obvious thing is to just turn it into a clock (albeit one with just a seconds dial) counting off the seconds. For that we just need to add a metro object which increments the phase angle and sends the value to the dial each second:
+Now that our dial object is basically finished, let's do something interesting with it. The most obvious thing is to just turn it into a clock (albeit one with just a seconds hand) counting off the seconds. For that we just need to add a metro object which increments the phase angle and sends the value to the dial each second:
