X-Git-Url: https://scm.cri.ensmp.fr/git/Faustine.git/blobdiff_plain/1059e1cc0c2ecfa237406949aa26155b6a5b9154:/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README..66f23d4fabf89ad09adbd4dfc15ac6b5b2b7da83:/interpreter/preprocessor/faust-0.9.47mr3/tools/faust2pd/static/gitweb.js diff --git a/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README b/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README deleted file mode 100644 index 832df70..0000000 --- a/interpretor/preprocessor/faust-0.9.47mr3/tools/faust2pd/README +++ /dev/null @@ -1,440 +0,0 @@ - -====================================== -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.