X-Git-Url: https://scm.cri.ensmp.fr/git/Faustine.git/blobdiff_plain/c7f552fd8888da2f0d8cfb228fe0f28d3df3a12c..b4b6f2ea75b9f0f3ca918f5b84016610bf7a4d4f:/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README diff --git a/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README b/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README new file mode 100644 index 0000000..832df70 --- /dev/null +++ b/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README @@ -0,0 +1,440 @@ + +====================================== +faust2pd: Pd Patch Generator for Faust +====================================== + +Version 2.5, October 20, 2011 + +Albert Graef + +This package contains software which makes it easier to use Faust DSPs with Pd +and the Pure programming language. The main component is the faust2pd script +which creates GUI wrappers for Faust DSPs. The package also includes a bunch +of examples. The software is distributed under the GPL; see the COPYING file +for details. + +.. note:: This faust2pd version is written in Pure and was ported from an + earlier version written in Pure's predecessor Q. The version of the script + provided here should be 100% backward-compatible to those previous + versions, except for the following changes: + + - The (rarely used) -f (a.k.a. --fake-buttons) option was renamed to -b. + + - A new -f (a.k.a. --font-size) option was added to change the font size + of the GUI elements. + + - Most command line options can now also be specified using special + ``[pd:...]`` tags in the Faust source. + + Also note that you can now run the script on 64 bit systems (Q never worked + there). + +As of version 2.1, the faust2pd script is now compiled to a native executable +before installation. This makes the program start up much faster, which is a +big advantage because most xml files don't take long to be processed. + +.. _Pure: http://pure-lang.googlecode.com + +.. contents:: +.. sectnum:: + +Copying +======= + +Copyright (c) 2009-2011 by Albert Graef. + +faust2pd is free software: you can redistribute it and/or modify it under the +terms of the GNU General Public License as published by the Free Software +Foundation, either version 3 of the License, or (at your option) any later +version. + +faust2pd is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +A PARTICULAR PURPOSE. See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along with +this program. If not, see . + +Requirements +============ + +faust2pd is known to work on Linux, Mac OS X, and Windows, and there shouldn't +be any major roadblocks preventing it to work on other systems supported by +Pure. + +The faust2pd script is written in the Pure_ programming language and requires +Pure's XML module, so you need to install these to make it work. Install the +latest pure*.tar.gz and pure-xml*.tar.gz packages and you should be set. (Pure +0.47 or later is required.) Also make sure that the LLVM base package is +installed, as described in the Pure INSTALL file, some LLVM utilities are +needed to make Pure's batch compiler work. + +To run the seqdemo example, you'll also need the Pd Pure external +(pd-pure*.tar.gz), also available at the Pure_ website. + +To compile the examples, you'll need GNU C++ and make, Pd_ and, of course, +Faust_. Make sure you get a recent version of Faust; Faust releases >0.9.8 +include the puredata architecture necessary to create Pd externals from Faust +DSPs. + +.. _Pd: http://puredata.info +.. _Faust: http://faudiostream.sf.net + +Installation +============ + +Get the latest source from +http://pure-lang.googlecode.com/files/faust2pd-2.5.tar.gz. + +Run ``make`` and ``make install`` to compile and install the faust2pd program +on your system. You can set the installation prefix by running make as ``make +install prefix=/some/path``. Default installation prefix is /usr/local, +faust2pd is installed in the bin directory below that. + +Optionally, you can also run ``make install-pd`` to copy the supporting Pd +abstractions (faust-\*.pd) to your lib/pd/extra directory, so that you can use +the patches generated by faust2pd without copying these abstractions to your +working directory. The Makefile tries to guess the prefix of your Pd +installation, if it guesses wrong, you can specify the prefix explicitly by +running make as ``make install-pd pdprefix=/some/path``. + +The included faustxml.pure script provides access to Faust-generated dsp +descriptions in xml files to Pure scripts. This module is described in its own +appendix__ below. It may have uses beyond faust2pd, but isn't normally +installed. If you want to use this module, you can just copy it to your Pure +library directory. + +__ `Appendix: faustxml`_ + +Quickstart +========== + +Run ``make examples`` to compile the Faust examples included in this package +to corresponding Pd plugins. After that you should be able to run the patches +in the various subdirectories of the examples directory. Everything is set up +so that you can try the examples "in-place", without installing anything +except the required software as noted in Requirements_ above. You can also run +``make realclean`` before ``make`` to regenerate everything from scratch (this +requires faust2pd, so this will only work if you already installed the Pure +interpreter). + +Faust Pd plugins work in much the same way as the well-known plugin~ object +(which interfaces to LADSPA plugins), except that each Faust DSP is compiled +to its own Pd external. Under Linux, the basic compilation process is as +follows (taking the freeverb module from the Faust distribution as an +example): + +.. code-block:: sh + + # compile the Faust source to a C++ module using the "puredata" architecture + faust -a puredata.cpp freeverb.dsp -o freeverb.cpp + # compile the C++ module to a Pd plugin + g++ -shared -Dmydsp=freeverb freeverb.cpp -o freeverb~.pd_linux + +By these means, a Faust DSP named ``xyz`` with n audio inputs and m audio +outputs becomes a Pd object ``xyz~`` with n+1 inlets and m+1 outlets. The +leftmost inlet/outlet pair is for control messages only. This allows you to +inspect and change the controls the unit provides, as detailed below. The +remaining inlets and outlets are the audio inputs and outputs of the unit, +respectively. For instance, ``freeverb.dsp`` becomes the Pd object +``freeverb~`` which, in addition to the control inlet/outlet pair, has 2 audio +inputs and outputs. + +When creating a Faust object it is also possible to specify, as optional +creation parameters, an extra unit name (this is explained in the following +section) and a sample rate. If no sample rate is specified explicitly, it +defaults to the sample rate at which Pd is executing. (Usually it is not +necessary or even desirable to override the default choice, but this might +occasionally be useful for debugging purposes.) + +As already mentioned, the main ingredient of this package is a Pure script +named "faust2pd" which allows you to create Pd abstractions as "wrappers" +around Faust units. The wrappers generated by faust2pd can be used in Pd +patches just like any other Pd objects. They are much easier to operate than +the "naked" Faust plugins themselves, as they also provide "graph-on-parent" +GUI elements to inspect and change the control values. + +The process to compile a plugin and build a wrapper patch is very similar to +what we've seen above. You only have to add the -xml option when invoking the +Faust compiler and run faust2pd on the resulting XML file: + +.. code-block:: sh + + # compile the Faust source and generate the xml file + faust -a puredata.cpp -xml freeverb.dsp -o freeverb.cpp + # compile the C++ module to a Pd plugin + g++ -shared -Dmydsp=freeverb freeverb.cpp -o freeverb~.pd_linux + # generate the Pd patch from the xml file + faust2pd freeverb.dsp.xml + +Please see `Wrapping DSPs with faust2pd`_ below for further details. + +Note that, just as with other Pd externals and abstractions, the compiled +.pd_linux modules and wrapper patches must be put somewhere where Pd can find +them. To these ends you can either move the files into the directory with the +patches that use the plugin, or you can put them into the lib/pd/extra +directory or some other directory on Pd's library path for system-wide use. + +Also, faust2pd-generated wrappers use a number of supporting abstractions (the +faust-\*.pd files in the faust2pd sources), so you have to put these into the +directory of the main patch or install them under lib/pd/extra as well. (The +``make pd-install`` step does the latter, see Installation_ above.) + +Control Interface +================= + +The control inlet of a Faust plugin understands messages in one of the +following forms: + +- ``bang``, which reports all available controls of the unit on the control + outlet, in the form: ``type name val init min max step``, where ``type`` is + the type of the control as specified in the Faust source (``checkbox``, + ``nentry``, etc.), ``name`` its (fully qualified) name, ``val`` the current + value, and ``init``, ``min``, ``max``, ``step`` the initial value, minimum, + maximum and stepsize of the control, respectively. + +- ``foo 0.99``, which sets the control ``foo`` to the value 0.99, and outputs + nothing. + +- Just ``foo``, which outputs the (fully qualified) name and current value of + the ``foo`` control on the control outlet. + +Control names can be specified in their fully qualified form, like e.g. +``/gnu/bar/foo`` which indicates the control ``foo`` in the subgroup ``bar`` +of the topmost group ``gnu``, following the hierarchical group layout defined +in the Faust source. This lets you distinguish between different controls with +the same name which are located in different groups. To find out about all the +controls of a unit and their fully qualified names, you can bang the control +inlet of the unit as described above, and connect its control outlet to a +``print`` object, which will cause the descriptions of all controls to be +printed in Pd's main window. (The same information can also be used, e.g., to +initialize GUI elements with the proper values. Patches generated with +faust2pd rely on this.) + +You can also specify just a part of the control path (like ``bar/foo`` or just +``foo`` in the example above) which means that the message applies to *all* +controls which have the given pathname as the final portion of their fully +qualified name. Thus, if there is more than one ``foo`` control in different +groups of the Faust unit then sending the message ``foo`` to the control inlet +will report the fully qualified name and value for each of them. Likewise, +sending ``foo 0.99`` will set the value of all controls named ``foo`` at once. + +Concerning the naming of Faust controls in Pd you should also note the +following: + +- A unit name can be specified at object creation time, in which case the + given symbol is used as a prefix for all control names of the unit. E.g., + the control ``/gnu/bar/foo`` of an object ``baz~`` created with ``baz~ + baz1`` has the fully qualified name ``/baz1/gnu/bar/foo``. This lets you + distinguish different instances of an object such as, e.g., different voices + of a polyphonic synth unit. + +- Pd's input syntax for symbols is rather restrictive. Therefore group and + control names in the Faust source are mangled into a form which only + contains alphanumeric characters and hyphens, so that the control names are + always legal Pd symbols. For instance, a Faust control name like ``meter #1 + (dB)`` will become ``meter-1-dB`` which can be input directly as a symbol in + Pd without any problems. + +- "Anonymous" groups and controls (groups and controls which have empty labels + in the Faust source) are omitted from the path specification. E.g., if + ``foo`` is a control located in a main group with an empty name then the + fully qualified name of the control is just ``/foo`` rather than ``//foo``. + Likewise, an anonymous control in the group ``/foo/bar`` is named just + ``/foo/bar`` instead of ``/foo/bar/``. + +Last but not least, there is also a special control named ``active`` which is +generated automatically for your convenience. The default behaviour of this +control is as follows: + +- When ``active`` is nonzero (the default), the unit works as usual. + +- When ``active`` is zero, and the unit's number of audio inputs and outputs + match, then the audio input is simply passed through. + +- When ``active`` is zero, but the unit's number of audio inputs and outputs + do *not* match, then the unit generates silence. + +The ``active`` control frequently alleviates the need for special "bypass" or +"mute" controls in the Faust source. However, if the default behaviour of the +generated control is not appropriate you can also define your own custom +version of ``active`` explicitly in the Faust program; in this case the custom +version will override the default one. + +Examples +======== + +In the examples subdirectory you'll find a bunch of sample Faust DSPs and Pd +patches illustrating how Faust units are used in Pd. + +- The examples/basic/test.pd patch demonstrates the basics of operating "bare" + Faust plugins in Pd. You'll rarely have to do this when using the wrappers + generated with the faust2pd program, but it is a useful starting point to + take a look behind the scenes anyway. + +- The examples/faust directory contains all the examples from (an earlier + version of) the Faust distribution, along with corresponding Pd wrappers + generated with faust2pd. Have a look at examples/faust/faustdemo.pd to see + some of the DSPs in action. Note that not all examples from the Faust + distribution are working out of the box because of name clashes with Pd + builtins, so we renamed those. We also edited some of the .dsp sources + (e.g., turning buttons into checkboxes or sliders into nentries) where this + seemed necessary to make it easier to operate the Pd patches. + +- The examples/synth directory contains various plugins and patches showing + how to implement polyphonic synthesizers using Faust units. Take a look at + examples/synth/synth.pd for an example. If you have properly configured your + interfaces then you should be able to play the synthesizer via Pd's MIDI + input. + +- The examples/seqdemo/seqdemo.pd patch demonstrates how to operate a + multitimbral synth, built with Faust units, in an automatic fashion using a + pattern sequencer programmed in Pure. This example requires the Pure + interpreter as well as the pd-pure plugin available from + http://pure-lang.googlecode.com. + +Wrapping DSPs with faust2pd +=========================== + +The faust2pd script generates Pd patches from the dsp.xml files created by +Faust when run with the -xml option. Most of the sample patches were actually +created that way. After installation you can run the script as follows:: + + faust2pd [-hVbs] [-f size] [-o output-file] [-n #voices] + [-r max] [-X patterns] [-x width] [-y height] input-file + +The default output filename is ``input-file`` with new extension +``.pd``. Thus, ``faust2pd filename.dsp.xml`` creates a Pd patch named +``filename.pd`` from the Faust XML description in ``filename.dsp.xml``. + +The faust2pd program understands a number of options which affect the layout +of the GUI elements and the contents of the generated patch. Here is a brief +list of the available options: + +-h, --help display a short help message and exit +-V, --version display the version number and exit +-b, --fake-buttons replace buttons (bangs) with checkboxes (toggles) +-f, --font-size font size for GUI elements (10 by default) +-n, --nvoices create a synth patch with the given number of voices +-o, --output-file output file name (.pd file) +-r, --radio-sliders radio controls for sliders +-s, --slider-nums sliders with additional number control +-X, --exclude exclude controls matching the given glob patterns +-x, --width maximum width of the GUI area +-y, --height maximum height of the GUI area + +Just like the Faust plugin itself, the generated patch has a control +input/output as the leftmost inlet/outlet pair, and the remaining plugs are +signal inlets and outlets for each audio input/output of the Faust +unit. However, the control inlet/outlet pair works slightly different from +that of the Faust plugin. Instead of being used for control replies, the +control outlet of the patch simply passes through its control input (after +processing messages which are understood by the wrapped plugin). By these +means control messages can flow along with the audio signal through an entire +chain of Faust units. (You can find an example of this in +examples/faust/faustdemo.pd.) Moreover, when generating a polyphonic synth +patch using the -n option then there will actually be two control inlets, one +for note messages and one for ordinary control messages; this is illustrated +in the examples/synth/synth.pd example. + +The generated patch also includes the necessary GUI elements to see and change +all (active and passive) controls of the Faust unit. Faust control elements +are mapped to Pd GUI elements in an obvious fashion, following the horizontal +and vertical layout specified in the Faust source. The script also adds +special buttons for resetting all controls to their defaults and to operate +the special ``active`` control. + +This generally works very well, but you should be aware that the control GUIs +generated by faust2pd are somewhat hampered by the limited range of GUI +elements available in a vanilla Pd installation. As a remedy, faust2pd +provides various options to change the content of the generated wrapper and +work around these limitations. + +- There are no real button widgets as required by the Faust specification, + so bangs are used instead. There is a global delay time for switching the + control from 1 back to 0, which can be changed by sending a value in + milliseconds to the ``faust-delay`` receiver. If you need interactive + control over the switching time then it is better to use checkboxes instead, + or you can have faust2pd automatically substitute checkboxes for all buttons + in a patch by invoking it with the -f a.k.a. --fake-buttons option. + +- Sliders in Pd do not display their value in numeric form so it may be hard + to figure out what the current value is. Therefore faust2pd has an option -s + a.k.a. --slider-nums which causes it to add a number box to each slider + control. (This flag also applies to Faust's passive bargraph controls, as + these are implemented using sliders, see below.) + +- Pd's sliders also have no provision for specifying a stepsize, so they are + an awkward way to input integral values from a small range. OTOH, Faust + doesn't support the "radio" control elements which Pd provides for that + purpose. As a remedy, faust2pd allows you to specify the option -r max + (a.k.a. --radio-sliders=max) to indicate that sliders with integral values + from the range 0..max-1 are to be mapped to corresponding Pd radio controls. + +- Faust's bargraphs are emulated using sliders. Note that these are passive + controls which just display a value computed by the Faust unit. A different + background color is used for these widgets so that you can distinguish them + from the ordinary (active) slider controls. The values shown in passive + controls are sampled every 40 ms by default. You can change this value by + sending an appropriate message to the global ``faust-timer`` receiver. + +- Since Pd has no "tabbed" (notebook-like) GUI element, Faust's tgroups are + mapped to hgroups instead. It may be difficult to present large and + complicated control interfaces without tabbed dialogs, though. As a remedy, + you can control the amount of horizontal or vertical space available for the + GUI area with the -x and -y (a.k.a. --width and --height) options and + faust2pd will then try to break rows and columns in the layout to make + everything fit within that area. (This feature has only been tested with + simple layouts so far, so beware.) + +- You can also exclude certain controls from appearing in the GUI using the -X + option. This option takes a comma-separated list of shell glob patterns + indicating either just the names or the fully qualified paths of Faust + controls which are to be excluded from the GUI. For instance, the option + ``-X 'volume,meter*,faust/resonator?/*'`` will exclude all volume controls, + all controls whose names start with ``meter``, and all controls in groups + matching ``faust/resonator?``. (Note that the argument to -X has to be + quoted if it contains any wildcards such as ``*`` and ``?``, so that the + shell doesn't try to expand the patterns beforehand. Also note that only one + -X option is recognized, so you have to specify all controls to be excluded + as a single option.) + +- Faust group labels are not shown at all, since I haven't found an easy way + to draw some kind of labelled frame in Pd yet. + +Despite these limitations, faust2pd appears to work rather well, at least for +the kind of DSPs found in the Faust distribution. (Still, for more complicated +control surfaces and interfaces to be used on stage you'll probably have to +edit the generated GUI layouts by hand.) + +For convenience, all the content-related command line options mentioned above +can also be specified in the Faust source, as special tags in the label of the +toplevel group of the dsp. These take the form ``[pd:option]`` or +``[pd:option=value]`` where ``option`` is any of the (long) options understood +by faust2pd. For instance:: + + process = vgroup("mysynth [pd:nvoices=8] [pd:slider-nums]", ...); + +Source options carrying arguments, like ``nvoices`` in the above example, can +also be overridden with corresponding command line options. + +Conclusion +========== + +Creating Faust plugins for use with Pd has never been easier before, so I hope +that you'll soon have much joy trying your Faust programs in Pd. Add Pd-Pure +to this, and you can program all your specialized audio and control objects +using two modern-style functional languages which are much more fun than +C/C++. Of course there's an initial learning curve to be mastered, but IMHO it +is well worth the effort. The bottomline is that Pd+Faust+Pure really makes an +excellent combo which provides you with a powerful, programmable interactive +environment for creating advanced computer music and multimedia applications +with ease. + +Acknowledgements +---------------- + +Thanks are due to Yann Orlarey for his wonderful Faust, which makes developing +DSP algorithms so easy and fun. + +.. Appendix follows here.