Version 0.18, October 31, 2018
Albert Graef <aggraef@gmail.com>
pd-faust is a dynamic environment for running Faust dsps in Pd. It is based on the author’s faust2pd script, but offers many small improvements and some major additional features:
Copyright (c) 2011-2018 by Albert Graef
pd-faust is distributed under the GNU LGPL v3+. Please see the included COPYING and COPYING.LESSER files for details.
This package also includes the faust-stk instruments which are distributed under an MIT-style license, please check the examples/dsp/README-STK file and the dsp files for authorship information and licensing details pertaining to these. The original faust-stk sources can be found in the Faust distribution, cf. http://faust.grame.fr/.
You’ll need Faust and Pd, obviously. Faust versions >= 0.9.46 and 2.0.a3 and Pd version >= 0.43.1 have been tested and are known to work. Note that the examples still use the “old” a.k.a. “legacy” Faust library modules, so they should work out of the box with both “old” Faust versions (up to 0.9.85) and later ones featuring the “new” Faust library (anything after 0.9.85, including current git sources).
The pd-faust objects are written in the Pure programming language, so you’ll also need an installation of the Pure interpreter (0.51 or later), along with the following packages (minimum required versions are given in parentheses): pd-pure (0.26), pure-faust (0.8), pure-midi (0.5) and pure-stldict (0.3).
Finally, gcc and GNU make (or compatible) are required to compile the helper dsps and the example instruments; please check the Makefile for details.
For a basic installation run make, then sudo make install. This will install the pd-faust objects in your lib/pd/extra/faust folder as a Pd object library which can be loaded with Pd’s -lib option. To complete the installation, you still have to make sure that the library is loaded automatically at startup. This is done most conveniently by adding faust/pdfaust to your preloaded library modules in Pd’s Preferences/Startup dialog.
Note
The faust/pdfaust module must come after the pure entry which loads pd-pure, otherwise you’ll get an error message. In any case the pd-pure loader will be required to run these objects, so it should be configured accordingly; please check the pd-pure documentation for details.
The make command also compiles the Faust dsps included in the distribution, so that the provided examples will be ready to run afterwards well (see Examples below).
The Makefile tries to guess the installation prefix under which Pd is installed. If it guesses wrong, you can tell it the right prefix with make prefix=/some/path. Or you can specify the exact path of the lib/pd directory with make pdlibdir=/some/path; by default the Makefile assumes $(prefix)/lib/pd.
It is also possible to specify an alternative flavour of Pd when building and installing the module, by adding a definition like PD=pd-extended to the make command line. This is known to work with pd-extended and pd-l2ork, two popular alternative Pd distributions available on the web, as well as purr-data (the new cross-platform version of pd-l2ork).
Some further build options are described in the Makefile. In particular, it is possible to compile the Faust dsps to LLVM bitcode which can be loaded directly by the Pure interpreter. This requires a recent Faust version (2.0 and later) and an LLVM-capable C/C++ compiler such as clang (please check the Compiling Faust DSPs section below for details). If you have the required tools then you can build the bitcode modules by running make bitcode after make. If you run make install afterwards, the bitcode modules will be installed along with the “normal” Faust plugins. In addition, a second object library called pdfaust2 will be built and installed, which can be used as a drop-in replacement for pdfaust and lets you run the bitcode modules. (Note that in the present implementation it is not possible to load both pdfaust and pdfaust2 in Pd, you’ll have to pick one or the other.)
Working with pd-faust basically involves adding a bunch of faust~ objects to a Pd patch along with the corresponding GUI subpatches, and wiring up the Faust units in some variation of a synth-effects chain which typically takes input from Pd’s MIDI interface (notein, ctlin, etc.) and outputs the signals produced by the Faust units to Pd’s audio interface (dac~).
For convenience, pd-faust also includes a few helper objects and abstractions to handle MIDI input and playback as well as OSC controller automation. For simple uses, the included midi-input and midi-output abstractions provide a way to encode and decode MIDI messages in the author’s SMMF format used by faust~ objects. For applications requiring more elaborate MIDI and OSC support, the midiseq and oscseq objects and a corresponding midiosc abstraction can be used to handle MIDI input and playback as well as OSC controller automation. This is described in more detail under MIDI and OSC Sequencing below.
pd-faust interprets MIDI, OSC and Faust dsp filenames relative to the hosting Pd patch by default. It will also search the midi, osc and dsp subfolders, if they exist, for the corresponding types of files. Failing that, it finally searches the directories on the Pd library path (including their midi, osc and dsp subfolders). To disable this search, just use absolute pathnames (or pathnames relative to the . or .. directory) instead.
Like pd-pure, pd-faust remaps Pd’s menu-open command so that it lets you edit the Faust source of a faust~ object by right-clicking on the object and choosing Open from the context menu. (This requires that the .dsp source file of the Faust module is available in the same directory as the binary module.) There’s also special support for the Emacs editor which lets you quickly compile Faust programs and reload Faust dsps in Pd, see Remote Control for details.
To run a Faust module (.dsp file) inside Pd using the faust~ object, the Faust dsp must be compiled to a form which can be loaded in Pure (not Pd!), so the pure.cpp architecture (included in the Faust distribution) is used to compile the dsp to a shared library object. It is of course possible to do this manually using the faust and gcc compilers, but for convenience there’s a GNU Makefile in the examples/dsp subdirectory which provides all the build rules necessary to do this. This Makefile is self-contained, so you can just drop it into any directory with Faust dsp sources and run make there to compile the modules to a format which is ready to be loaded with pd-faust.
Another possibility is to use the faust2pure script included in recent Faust versions and also in the examples subdirectory of the pure-faust package, see the pure-faust documentation for details. E.g., to compile a Faust dsp organ.dsp to a module loadable with pd-faust, simply use the following command:
faust2pure organ.dsp
This will leave a shared library module organ.so (organ.dylib on macOS, organ.dll on Windows) in the current directory which can then be loaded with pd-faust, by just inserting an object like faust~ organ in your patch. Note that to make this work, pd-faust must be able to locate the object. To these ends, you should create the patch in the same directory that also contains the .dsp and .so files of the Faust dsp. (As mentioned earlier, it is also possible to put the .dsp and .so files into the dsp subdirectory of the directory containing the patch, or just put them somewhere on Pd’s library path.)
If you’re running a recent version of Faust, you can also compile to an LLVM bitcode file instead; pd-pure can load these directly using Pure’s built-in Faust bitcode loader. As already mentioned, this requires Faust 2.0 or later and that you build and install the alternative pdfaust2 library as described under Installation above. The main advantage of using bitcode modules is that compiling these is often much faster. The main disadvantage is that you’ll need a special C compiler capable of producing LLVM bitcode (i.e., clang).
The process of compiling Faust dsps to bitcode modules is pretty much the same as above, only that you have to run make bitcode with the provided Makefile, or use the faust2pure script with the -bitcode option, e.g.:
faust2pure -bitcode organ.dsp
This creates the organ.bc module which can be loaded by the pdfaust2 library, pretty much like pdfaust loads shared object modules. Otherwise there won’t be much of a noticeable difference (gcc may produce better code in some cases, clang in others, which may result in some Faust dsps running with better performance as shared library modules, others in bitcode). Note, however, that in the current implementation pdfaust and pdfaust2 can not be loaded at the same time in Pd, therefore you’ll have to decide beforehand which of the two available interfaces you want to use.
Starting with version 0.10, pd-faust offers the faust~ external which provides a uniform way to create both audio effects and synth (instrument) units, and also supplies reasonable defaults for most arguments. (While the underlying fdsp~ and fsynth~ objects of older pd-faust versions are still provided for backward compatibility, they are deprecated and shouldn’t be invoked directly any more.)
The faust~ object is invoked as follows:
faust~ dspname [instname] [channel] [numvoices]
The creation arguments in square brackets are optional. Please note that since the faust~ object is written in Pure, the creation arguments should be specified in Pure syntax. In particular, both dspname or instname may either be Pure identifiers or double-quoted strings (the former will automatically be translated to the latter). Similarly, the channel and numvoices arguments must be integer constants in Pure syntax, which is pretty much like Pd syntax but also allows the integer to be specified in hexadecimal, octal or binary.
The meaning of these arguments is as follows:
Note that if only a single number follows the dspname or instname argument then it is always interpreted as a channel number; thus, if you want to denote the numvoices value in the creation arguments then you’ll have to specify both channel and numvoices, in that order.
Unless specified explicitly, the number of voices of an instrument is determined using the value of the nvoices meta key declared in the dsp source. Thus, to turn a Faust dsp into a synth with 8 voices you can use a declaration like the following anywhere in the Faust program:
declare nvoices "8";
The format of this declaration is the same as for the faust-lv2 and faust-vst plugin architectures.
If the nvoices declaration isn’t present, the dsp is considered to be an effect unit by default. All default choices can be overridden by explicitly specifying the corresponding creation argument. In particular, you can specify the number of synth voices (overriding the nvoices key in the dsp source), or use a numvoices value of zero to force a synth to be loaded as an ordinary effect unit. Also, if there are multiple instances of the same dsp in a patch then you can (and should) explicitly specify different instance names using the instname argument, and the default channel value of zero (denoting omni input) can be overridden as needed if the unit should only listen on a specific MIDI channel.
A faust~ object with zero voices requires a Faust dsp which can work as an effect unit, processing audio input and producing audio output. The unit can have as many audio input and output channels as you like (including zero).
A faust~ object with a non-zero number of voices works in a similar fashion, but requires a Faust dsp which can work as a (monophonic) synthesizer. This typically means that the unit has zero audio inputs and a nonzero number of audio outputs, although it is possible to have synths processing any number of audio input channels as well. (You can even have synths producing zero audio outputs, but this is generally not very useful.)
In the synth case, pd-faust also assumes that the Faust unit provides three so-called “voice controls” which indicate which note to play:
pd-faust doesn’t care at which path inside the Faust dsp these controls are located, but they must all be there, and the basenames of the controls must be unique throughout the entire dsp. Otherwise the synth will not work as expected.
Like faust2pd, pd-faust implements the necessary logic to drive the given number of voices of a faust~ instrument object. That is, it will actually create a separate instance of the Faust dsp for each voice and handle polyphony by allocating voices from this pool in a round-robin fashion, performing the usual voice stealing if the number of simultaneous notes to play exceeds the number of voices. Also note that a faust~ instrument operated in omni mode (channel = 0) automatically filters out messages on channel 10 which is reserved for percussion in the General MIDI standard.
A faust~ object always responds to the following messages:
The object also responds to MIDI controller messages of the form ctl val num chan and, in the case of instruments, note-related messages of the form note num vel chan (note on/off) and bend val chan (pitch bend). It also provides the necessary logic to map controller and note-related messages to the corresponding control changes in the Faust unit.
In addition, pd-faust 0.13 and later offer support for the MIDI Tuning Standard (MTS), so that instruments can be retuned using the corresponding sysex messages for octave-based tunings. To these ends, the faust~ object accepts messages of the form sysex b1 b2 ... where b1, b2, ... are the individual data bytes of the message. A description of the MIDI Tuning Standard is beyond the scope of this manual. However, there are some tools which let you construct such messages from various input formats, such as the author’s sclsyx program. You can then either include the tuning messages in a MIDI file or transmit them directly to Pd’s MIDI input. There’s also a version of sclsyx.pure included in the author’s pd-smmf package, which can be run as a Pd external to output tunings in the format understood by the faust~ object.
Each faust~ object also subscribes to the following three global receivers which enable you to send various kinds of messages to all faust~ objects in a patch:
Finally, faust~ objects also send a message of the form create instance or destroy instance to the global faust-notify receiver whenever they are created and destroyed, respectively. The argument indicates the instance name of the object being created or destroyed. This receiver isn’t used by pd-faust itself in any way, but applications may receive this symbol if they need to be notified about changes in the collection of loaded Faust units.
For each faust~ object, the Pd patch may contain an (initially empty) “one-off” graph-on-parent subpatch with the same name as the instance name of the Faust unit:
pd instname
You shouldn’t insert anything into this subpatch, its contents (a bunch of Pd GUI elements corresponding to the control elements of the Faust unit) will be generated automatically by pd-faust when the corresponding faust~ object is created, and whenever the unit gets reloaded at runtime.
As with faust2pd, the default appearance of the GUI can be adjusted in various ways; see Tweaking the GUI Layout below for details.
The relative order in which you insert a faust~ object and its GUI subpatch into the main patch matters. Normally, the GUI subpatch should be inserted first, so that it will be updated automatically when its associated Faust unit is first created, and also when the main patch is saved and then reloaded later.
However, in some situations it may be preferable to insert the GUI subpatch after its associated Faust unit. If you do this, the GUI will not be updated automatically when the main patch is loaded, so you’ll have to reload the dsp manually (sending it a reload message) to force an update of the GUI subpatch. This is useful, in particular, if you’d like to edit the GUI patch manually after it has been generated.
In some cases it may even be desirable to completely “lock down” the GUI subpatch. This can be done by simply renaming the GUI subpatch after it has been generated. When Pd saves the main patch, it saves the current status of the GUI subpatches along with it, so that the renamed subpatch will remain static and will never be updated, even if its associated Faust unit gets reloaded. This generally makes sense only if the control interface of the Faust unit isn’t changed after locking down its GUI patch. To “unlock” a GUI subpatch, you just rename it back to its original name. (In this case you might also want to reinsert the corresponding Faust unit afterwards, if you want to have the GUI generated automatically without an explicit reload again.)
The examples folder contains a few example patches which illustrate how this all works. Having compiled and installed pd-faust as described above, you can run these directly from the examples directory in the sources, e.g.: pd test.pd. (You can also run the examples without actually installing pd-faust if you invoke Pd from the main pd-faust source directory, e.g., as follows: pd -lib lib/pdfaust examples/test.pd.) The same collection of examples is also copied to $prefix/lib/pd/extra/faust when running make install (where $prefix denotes the prefix under which Pd is installed, usually /usr or /usr/local) so that you can also run them from there.
Here are some of the examples that are currently available:
For your convenience, related MIDI and OSC files as well as the Faust sources of the instruments and effects are contained in corresponding subdirectories (midi, osc, dsp) of the examples directory. A slightly modified version of the faust-stk instruments from the Faust distribution is also included, please check the examples/dsp/README-STK file for more information about these. The MIDI files are all in standard MIDI file format. (Some of these come from the faust-stk distribution, others can be found on the web.) The OSC files used by pd-faust for controller automation are plain ASCII files suitable for hand-editing if you know what you are doing; the format should be fairly self-explanatory.
The generated Pd GUI elements for the Faust dsps are pretty much the same as with faust2pd (which see). The only obvious change is the addition of a “record” button (gray toggle in the upper right corner) which enables recording of OSC automation data. This requires the use of the midiosc abstraction which serves as a little sequencer applet that enables you to control MIDI playback and OSC recording. The usage of this abstraction should be fairly obvious, but you can also find a brief description under MIDI and OSC Sequencing below.
Note that the midiosc abstraction, even though most of the distributed examples include it, is by no means required unless you really need the MIDI playback and OSC automation features it provides. In most simple use cases, you just insert faust~ objects (along with their corresponding GUI subpatches if needed/wanted) into your patch, wire them up as needed and be done with it. If you also need MIDI input (controller and note data), the midi-input abstraction provides a simpler way to encode incoming MIDI messages from Pd’s MIDI inputs in the SMMF format understood by faust~ objects. Simply connect the outlet of midi-input to the leftmost inlet of any faust~ instrument or effect unit that you want to play or control through MIDI, make sure that the instrument (or last effect unit in the chain) is connected to Pd’s audio output a.k.a. dac~, and you should be set. MIDI output via the midiout receiver (cf. External MIDI and OSC Controllers) can be handled in a similar way using the midi-output abstraction (see simple.pd for an example).
Note
If you use the midiosc abstraction in your own patches, you should copy it to the directory containing your patch and other required files, so that MIDI and OSC files are properly located. Alternatively, you can also set up Pd’s search path as described at the beginning of the Usage section.
The first creation argument of midiosc is the name of the MIDI file, either as a Pure identifier (in this case the .mid filename extension is supplied automatically) or as a double-quoted string. Similarly, the second argument specifies the name of the OSC file. Both arguments are optional; if the second argument is omitted, it defaults to the name of the MIDI file with new extension .osc. You can also omit both arguments if neither MIDI file playback nor saving recorded OSC data is required. Or you can leave the first parameter empty (specify "" or 0 instead) to only set an OSC filename, if you don’t need MIDI playback. The latter is useful, in particular, if you use midiosc with an external MIDI sequencer (see below).
The abstraction has a single control outlet through which it feeds the generated MIDI and other messages to the connected faust~ objects. Live MIDI input is also accepted and forwarded to the control outlet, after being translated to the format understood by faust~ objects. In addition, midiosc can also be controlled through an external MIDI sequencer connected to Pd’s MIDI input. To these ends, MIDI Machine Control (MMC) can be used to start and stop OSC playback and recording with the transport controls of the external sequencer program. To make this work, the external sequencer must be configured as an MMC master.
At the bottom of the abstraction there is a little progress bar along with a time display which indicates the current song position. If playback is stopped, you can also use these to change the current position for playback, recording and a number of other operations as described below. Note that if you drive midiosc from an external MIDI sequencer instead, then it is a good idea to load the same MIDI file in midiosc anyway, so that it knows about the length of the MIDI sequence. This will make the progress bar display the proper position in the file.
Here is a brief rundown of the available controls:
Please note that midiosc is merely a prototypical implementation which should cover most common uses. It can also be used as a starting point for your own abstractions if you need more elaborate input/output interfacing than what midiosc provides.
For instrument units, the faust~ object has built-in (and hard-wired) support for MIDI notes, pitch bend and MIDI controller 123 (all notes off). Other controller data received from external MIDI and OSC devices is interpreted according to the controller mappings defined in the Faust source (this is explained below), by updating the corresponding GUI elements and the control variables of the Faust dsp. (This only works with active Faust controls, i.e., dsp controls which are to be manipulated from the host environment, not the dsp’s passive a.k.a. “bargraph” controls which return control values computed by the dsp.)
A faust~ object can also be put in write mode by feeding a message of the form write 1 into its control inlet (the write 0 message disables write mode again). For convenience, the write toggle in the midiosc abstraction allows you to do this simultaneously for all Faust units connected to midiosc‘s control outlet.
When an object is in write mode, it also outputs MIDI and OSC controller data in response to both automation data and the manual operation of the Pd GUI elements, again according to the controller mappings defined in the Faust source, so that it can drive an external device, e.g., in order to provide feedback to motorized MIDI or multitouch OSC controllers. This works with both active and passive Faust controls.
Note
For better or worse, the output is not emitted directly on the object’s control outlet, but instead goes to special midiout and oscout receivers provided by the midiosc abstraction which then takes care of outputting the data. Thus, if you’re not using midiosc, you will have to provide these receivers yourself if you want to process the generated MIDI and/or OSC data in some way (the included simple.pd example shows how to do this for MIDI data).
To configure MIDI controller assignments, the labels of the Faust control elements have to be marked up with the special midi attribute in the Faust source. For instance, a pan control (MIDI controller 10) may be implemented in the Faust source as follows:
pan = hslider("pan [midi:ctrl 10]", 0, -1, 1, 0.01);
pd-faust will then provide the necessary logic to handle MIDI input from controller 10 by changing the pan control in the Faust unit accordingly, mapping the controller values 0..127 to the range and step size given in the Faust source. Moreover, in write mode corresponding MIDI controller data will be generated and sent to the midiout receiver as discussed above, on the MIDI channel specified in the creation arguments of the Faust unit (0 meaning “omni”, i.e., output on all MIDI channels).
The same functionality is also available for external OSC devices, employing explicit OSC controller assignments in the Faust source by means of the osc attribute. E.g., the following enables input and output of OSC messages for the OSC /pan address:
pan = hslider("pan [osc:/pan]", 0, -1, 1, 0.01);
Note
In contrast to some other architectures included in the Faust distribution, at present pd-faust only allows literal OSC addresses (no glob-style patterns), and there is no way to specify an OSC value range (so the value ranges of the controls of an external OSC device must match the ranges of the corresponding controls in the Faust program).
To actually connect with external OSC devices, you will also need some OSC input and output facilities. Older versions of vanilla Pd didn’t offer these, and the built-in OSC facilities of the latest Pd versions still have some limitations, so pd-pure relies on 3rd party externals for that. We recommend Martin Peach’s OSC externals which are included in Hans-Christoph Steiner’s Pd-extended distribution and derivatives such as Pd-l2ork and Purr-Data.
pd-faust includes a version of the midiosc abstraction named midiosc-mrpeach which can be used as a drop-in replacement for midiosc and implements OSC input and output using Martin Peach’s objects. You most likely have to edit this abstraction to make it work for your local network setup; at least you’ll probably have to change the network addresses in the abstraction so that it works with the OSC device or application that you use.
Another useful abstraction is the oscbrowser object available in the author’s separate pd-mdnsbrowser package. It lets you discover and publish Zeroconf (Avahi/Bonjour) services in the local network, so that your Pd patches can establish OSC connections in an automatic fashion.
As already mentioned, pd-faust provides the same global GUI layout options as faust2pd. Please check the faust2pd documentation for details. There are a few minor changes in the meaning of some of the options, though, which we consider notable improvements after some experience working with faust2pd. Here is a brief rundown of the available options, as they are implemented in pd-faust:
In pd-faust there is no way to specify the above options on the command line, so you’ll have to put them as pd attributes on the main group of your Faust program, as described in the faust2pd documentation. For instance:
process = vgroup("[pd:no-slider-nums][pd:font-size=12]", ...);
In addition, the following options can be used to change the appearance of individual control items. If present, these options override the corresponding defaults. Each option can also be prefixed with “no-” to negate the option value. (Thus, e.g., no-hidden makes items visible which would otherwise, by means of the global exclude option, be removed from the GUI.)
Again, these options are specified with the pd attribute in the label of the corresponding Faust control. For instance, the following Faust code hides the controls in the aux group, removes the number entry from the pan control, and renders the preset item as a Pd radio control:
aux = vgroup("aux [pd:hidden]", aux_part);
pan = hslider("pan [pd:no-slider-num]", 0, -1, 1, 0.01);
preset = nentry("preset [pd:radio-slider]", 0, 0, 7, 1);
Also included in the sources is a helper abstraction faust-remote.pd and an accompanying elisp package faust-remote.el. These work pretty much like pure-remote.pd and pure-remote.el in the pd-pure distribution, but are tailored for the remote control of Faust dsps in a Pd patch. In particular, they enable you to quickly compile Faust sources (C-C C-K command) and reload the compiled dsps in Pd (C-C C-X) from Emacs. Clicking the bang control in the faust-remote.pd abstraction also reloads all Faust dsps.
The faust-remote.el package was designed to be used with Juan Romero’s Emacs Faust mode; please see etc/faust-remote.el in the pd-faust source for usage instructions. Note that at present faust-remote.el isn’t installed automatically. You can do this manually by just copying the file to your Emacs site-lisp directory or any other location on the Emacs load-path. E.g., on Linux and other Unix-like systems:
sudo cp etc/faust-remote.el /usr/share/emacs/site-lisp/
To enable the package, put the following line into your .emacs configuration file (this also auto-loads Faust mode):
(require 'faust-remote)
Some parts of this software might still be experimental, under construction and/or bug-ridden. Bug reports, patches and suggestions are welcome.
In particular, please note the following known limitations in the current implementation:
Also, please check the TODO file included in the distribution for other issues which we are already aware of and which will hopefully be addressed in future pd-faust versions.