+++ /dev/null
-
-======================================
-faust2pd: Pd Patch Generator for Faust
-======================================
-
-Version 2.5, October 20, 2011
-
-Albert Graef <Dr.Graef@t-online.de>
-
-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 <http://www.gnu.org/licenses/>.
-
-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.
projects / Faustine.git / blobdiff