New directory tree, with preprocessor/ inside interpretor/.
[Faustine.git] / interpretor / preprocessor / faust-0.9.47mr3 / tools / faust2pd / README
1
2 ======================================
3 faust2pd: Pd Patch Generator for Faust
4 ======================================
5
6 Version 2.5, October 20, 2011
7
8 Albert Graef <Dr.Graef@t-online.de>
9
10 This package contains software which makes it easier to use Faust DSPs with Pd
11 and the Pure programming language. The main component is the faust2pd script
12 which creates GUI wrappers for Faust DSPs. The package also includes a bunch
13 of examples. The software is distributed under the GPL; see the COPYING file
14 for details.
15
16 .. note:: This faust2pd version is written in Pure and was ported from an
17 earlier version written in Pure's predecessor Q. The version of the script
18 provided here should be 100% backward-compatible to those previous
19 versions, except for the following changes:
20
21 - The (rarely used) -f (a.k.a. --fake-buttons) option was renamed to -b.
22
23 - A new -f (a.k.a. --font-size) option was added to change the font size
24 of the GUI elements.
25
26 - Most command line options can now also be specified using special
27 ``[pd:...]`` tags in the Faust source.
28
29 Also note that you can now run the script on 64 bit systems (Q never worked
30 there).
31
32 As of version 2.1, the faust2pd script is now compiled to a native executable
33 before installation. This makes the program start up much faster, which is a
34 big advantage because most xml files don't take long to be processed.
35
36 .. _Pure: http://pure-lang.googlecode.com
37
38 .. contents::
39 .. sectnum::
40
41 Copying
42 =======
43
44 Copyright (c) 2009-2011 by Albert Graef.
45
46 faust2pd is free software: you can redistribute it and/or modify it under the
47 terms of the GNU General Public License as published by the Free Software
48 Foundation, either version 3 of the License, or (at your option) any later
49 version.
50
51 faust2pd is distributed in the hope that it will be useful, but WITHOUT ANY
52 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
53 A PARTICULAR PURPOSE. See the GNU General Public License for more details.
54
55 You should have received a copy of the GNU General Public License along with
56 this program. If not, see <http://www.gnu.org/licenses/>.
57
58 Requirements
59 ============
60
61 faust2pd is known to work on Linux, Mac OS X, and Windows, and there shouldn't
62 be any major roadblocks preventing it to work on other systems supported by
63 Pure.
64
65 The faust2pd script is written in the Pure_ programming language and requires
66 Pure's XML module, so you need to install these to make it work. Install the
67 latest pure*.tar.gz and pure-xml*.tar.gz packages and you should be set. (Pure
68 0.47 or later is required.) Also make sure that the LLVM base package is
69 installed, as described in the Pure INSTALL file, some LLVM utilities are
70 needed to make Pure's batch compiler work.
71
72 To run the seqdemo example, you'll also need the Pd Pure external
73 (pd-pure*.tar.gz), also available at the Pure_ website.
74
75 To compile the examples, you'll need GNU C++ and make, Pd_ and, of course,
76 Faust_. Make sure you get a recent version of Faust; Faust releases >0.9.8
77 include the puredata architecture necessary to create Pd externals from Faust
78 DSPs.
79
80 .. _Pd: http://puredata.info
81 .. _Faust: http://faudiostream.sf.net
82
83 Installation
84 ============
85
86 Get the latest source from
87 http://pure-lang.googlecode.com/files/faust2pd-2.5.tar.gz.
88
89 Run ``make`` and ``make install`` to compile and install the faust2pd program
90 on your system. You can set the installation prefix by running make as ``make
91 install prefix=/some/path``. Default installation prefix is /usr/local,
92 faust2pd is installed in the bin directory below that.
93
94 Optionally, you can also run ``make install-pd`` to copy the supporting Pd
95 abstractions (faust-\*.pd) to your lib/pd/extra directory, so that you can use
96 the patches generated by faust2pd without copying these abstractions to your
97 working directory. The Makefile tries to guess the prefix of your Pd
98 installation, if it guesses wrong, you can specify the prefix explicitly by
99 running make as ``make install-pd pdprefix=/some/path``.
100
101 The included faustxml.pure script provides access to Faust-generated dsp
102 descriptions in xml files to Pure scripts. This module is described in its own
103 appendix__ below. It may have uses beyond faust2pd, but isn't normally
104 installed. If you want to use this module, you can just copy it to your Pure
105 library directory.
106
107 __ `Appendix: faustxml`_
108
109 Quickstart
110 ==========
111
112 Run ``make examples`` to compile the Faust examples included in this package
113 to corresponding Pd plugins. After that you should be able to run the patches
114 in the various subdirectories of the examples directory. Everything is set up
115 so that you can try the examples "in-place", without installing anything
116 except the required software as noted in Requirements_ above. You can also run
117 ``make realclean`` before ``make`` to regenerate everything from scratch (this
118 requires faust2pd, so this will only work if you already installed the Pure
119 interpreter).
120
121 Faust Pd plugins work in much the same way as the well-known plugin~ object
122 (which interfaces to LADSPA plugins), except that each Faust DSP is compiled
123 to its own Pd external. Under Linux, the basic compilation process is as
124 follows (taking the freeverb module from the Faust distribution as an
125 example):
126
127 .. code-block:: sh
128
129 # compile the Faust source to a C++ module using the "puredata" architecture
130 faust -a puredata.cpp freeverb.dsp -o freeverb.cpp
131 # compile the C++ module to a Pd plugin
132 g++ -shared -Dmydsp=freeverb freeverb.cpp -o freeverb~.pd_linux
133
134 By these means, a Faust DSP named ``xyz`` with n audio inputs and m audio
135 outputs becomes a Pd object ``xyz~`` with n+1 inlets and m+1 outlets. The
136 leftmost inlet/outlet pair is for control messages only. This allows you to
137 inspect and change the controls the unit provides, as detailed below. The
138 remaining inlets and outlets are the audio inputs and outputs of the unit,
139 respectively. For instance, ``freeverb.dsp`` becomes the Pd object
140 ``freeverb~`` which, in addition to the control inlet/outlet pair, has 2 audio
141 inputs and outputs.
142
143 When creating a Faust object it is also possible to specify, as optional
144 creation parameters, an extra unit name (this is explained in the following
145 section) and a sample rate. If no sample rate is specified explicitly, it
146 defaults to the sample rate at which Pd is executing. (Usually it is not
147 necessary or even desirable to override the default choice, but this might
148 occasionally be useful for debugging purposes.)
149
150 As already mentioned, the main ingredient of this package is a Pure script
151 named "faust2pd" which allows you to create Pd abstractions as "wrappers"
152 around Faust units. The wrappers generated by faust2pd can be used in Pd
153 patches just like any other Pd objects. They are much easier to operate than
154 the "naked" Faust plugins themselves, as they also provide "graph-on-parent"
155 GUI elements to inspect and change the control values.
156
157 The process to compile a plugin and build a wrapper patch is very similar to
158 what we've seen above. You only have to add the -xml option when invoking the
159 Faust compiler and run faust2pd on the resulting XML file:
160
161 .. code-block:: sh
162
163 # compile the Faust source and generate the xml file
164 faust -a puredata.cpp -xml freeverb.dsp -o freeverb.cpp
165 # compile the C++ module to a Pd plugin
166 g++ -shared -Dmydsp=freeverb freeverb.cpp -o freeverb~.pd_linux
167 # generate the Pd patch from the xml file
168 faust2pd freeverb.dsp.xml
169
170 Please see `Wrapping DSPs with faust2pd`_ below for further details.
171
172 Note that, just as with other Pd externals and abstractions, the compiled
173 .pd_linux modules and wrapper patches must be put somewhere where Pd can find
174 them. To these ends you can either move the files into the directory with the
175 patches that use the plugin, or you can put them into the lib/pd/extra
176 directory or some other directory on Pd's library path for system-wide use.
177
178 Also, faust2pd-generated wrappers use a number of supporting abstractions (the
179 faust-\*.pd files in the faust2pd sources), so you have to put these into the
180 directory of the main patch or install them under lib/pd/extra as well. (The
181 ``make pd-install`` step does the latter, see Installation_ above.)
182
183 Control Interface
184 =================
185
186 The control inlet of a Faust plugin understands messages in one of the
187 following forms:
188
189 - ``bang``, which reports all available controls of the unit on the control
190 outlet, in the form: ``type name val init min max step``, where ``type`` is
191 the type of the control as specified in the Faust source (``checkbox``,
192 ``nentry``, etc.), ``name`` its (fully qualified) name, ``val`` the current
193 value, and ``init``, ``min``, ``max``, ``step`` the initial value, minimum,
194 maximum and stepsize of the control, respectively.
195
196 - ``foo 0.99``, which sets the control ``foo`` to the value 0.99, and outputs
197 nothing.
198
199 - Just ``foo``, which outputs the (fully qualified) name and current value of
200 the ``foo`` control on the control outlet.
201
202 Control names can be specified in their fully qualified form, like e.g.
203 ``/gnu/bar/foo`` which indicates the control ``foo`` in the subgroup ``bar``
204 of the topmost group ``gnu``, following the hierarchical group layout defined
205 in the Faust source. This lets you distinguish between different controls with
206 the same name which are located in different groups. To find out about all the
207 controls of a unit and their fully qualified names, you can bang the control
208 inlet of the unit as described above, and connect its control outlet to a
209 ``print`` object, which will cause the descriptions of all controls to be
210 printed in Pd's main window. (The same information can also be used, e.g., to
211 initialize GUI elements with the proper values. Patches generated with
212 faust2pd rely on this.)
213
214 You can also specify just a part of the control path (like ``bar/foo`` or just
215 ``foo`` in the example above) which means that the message applies to *all*
216 controls which have the given pathname as the final portion of their fully
217 qualified name. Thus, if there is more than one ``foo`` control in different
218 groups of the Faust unit then sending the message ``foo`` to the control inlet
219 will report the fully qualified name and value for each of them. Likewise,
220 sending ``foo 0.99`` will set the value of all controls named ``foo`` at once.
221
222 Concerning the naming of Faust controls in Pd you should also note the
223 following:
224
225 - A unit name can be specified at object creation time, in which case the
226 given symbol is used as a prefix for all control names of the unit. E.g.,
227 the control ``/gnu/bar/foo`` of an object ``baz~`` created with ``baz~
228 baz1`` has the fully qualified name ``/baz1/gnu/bar/foo``. This lets you
229 distinguish different instances of an object such as, e.g., different voices
230 of a polyphonic synth unit.
231
232 - Pd's input syntax for symbols is rather restrictive. Therefore group and
233 control names in the Faust source are mangled into a form which only
234 contains alphanumeric characters and hyphens, so that the control names are
235 always legal Pd symbols. For instance, a Faust control name like ``meter #1
236 (dB)`` will become ``meter-1-dB`` which can be input directly as a symbol in
237 Pd without any problems.
238
239 - "Anonymous" groups and controls (groups and controls which have empty labels
240 in the Faust source) are omitted from the path specification. E.g., if
241 ``foo`` is a control located in a main group with an empty name then the
242 fully qualified name of the control is just ``/foo`` rather than ``//foo``.
243 Likewise, an anonymous control in the group ``/foo/bar`` is named just
244 ``/foo/bar`` instead of ``/foo/bar/``.
245
246 Last but not least, there is also a special control named ``active`` which is
247 generated automatically for your convenience. The default behaviour of this
248 control is as follows:
249
250 - When ``active`` is nonzero (the default), the unit works as usual.
251
252 - When ``active`` is zero, and the unit's number of audio inputs and outputs
253 match, then the audio input is simply passed through.
254
255 - When ``active`` is zero, but the unit's number of audio inputs and outputs
256 do *not* match, then the unit generates silence.
257
258 The ``active`` control frequently alleviates the need for special "bypass" or
259 "mute" controls in the Faust source. However, if the default behaviour of the
260 generated control is not appropriate you can also define your own custom
261 version of ``active`` explicitly in the Faust program; in this case the custom
262 version will override the default one.
263
264 Examples
265 ========
266
267 In the examples subdirectory you'll find a bunch of sample Faust DSPs and Pd
268 patches illustrating how Faust units are used in Pd.
269
270 - The examples/basic/test.pd patch demonstrates the basics of operating "bare"
271 Faust plugins in Pd. You'll rarely have to do this when using the wrappers
272 generated with the faust2pd program, but it is a useful starting point to
273 take a look behind the scenes anyway.
274
275 - The examples/faust directory contains all the examples from (an earlier
276 version of) the Faust distribution, along with corresponding Pd wrappers
277 generated with faust2pd. Have a look at examples/faust/faustdemo.pd to see
278 some of the DSPs in action. Note that not all examples from the Faust
279 distribution are working out of the box because of name clashes with Pd
280 builtins, so we renamed those. We also edited some of the .dsp sources
281 (e.g., turning buttons into checkboxes or sliders into nentries) where this
282 seemed necessary to make it easier to operate the Pd patches.
283
284 - The examples/synth directory contains various plugins and patches showing
285 how to implement polyphonic synthesizers using Faust units. Take a look at
286 examples/synth/synth.pd for an example. If you have properly configured your
287 interfaces then you should be able to play the synthesizer via Pd's MIDI
288 input.
289
290 - The examples/seqdemo/seqdemo.pd patch demonstrates how to operate a
291 multitimbral synth, built with Faust units, in an automatic fashion using a
292 pattern sequencer programmed in Pure. This example requires the Pure
293 interpreter as well as the pd-pure plugin available from
294 http://pure-lang.googlecode.com.
295
296 Wrapping DSPs with faust2pd
297 ===========================
298
299 The faust2pd script generates Pd patches from the dsp.xml files created by
300 Faust when run with the -xml option. Most of the sample patches were actually
301 created that way. After installation you can run the script as follows::
302
303 faust2pd [-hVbs] [-f size] [-o output-file] [-n #voices]
304 [-r max] [-X patterns] [-x width] [-y height] input-file
305
306 The default output filename is ``input-file`` with new extension
307 ``.pd``. Thus, ``faust2pd filename.dsp.xml`` creates a Pd patch named
308 ``filename.pd`` from the Faust XML description in ``filename.dsp.xml``.
309
310 The faust2pd program understands a number of options which affect the layout
311 of the GUI elements and the contents of the generated patch. Here is a brief
312 list of the available options:
313
314 -h, --help display a short help message and exit
315 -V, --version display the version number and exit
316 -b, --fake-buttons replace buttons (bangs) with checkboxes (toggles)
317 -f, --font-size font size for GUI elements (10 by default)
318 -n, --nvoices create a synth patch with the given number of voices
319 -o, --output-file output file name (.pd file)
320 -r, --radio-sliders radio controls for sliders
321 -s, --slider-nums sliders with additional number control
322 -X, --exclude exclude controls matching the given glob patterns
323 -x, --width maximum width of the GUI area
324 -y, --height maximum height of the GUI area
325
326 Just like the Faust plugin itself, the generated patch has a control
327 input/output as the leftmost inlet/outlet pair, and the remaining plugs are
328 signal inlets and outlets for each audio input/output of the Faust
329 unit. However, the control inlet/outlet pair works slightly different from
330 that of the Faust plugin. Instead of being used for control replies, the
331 control outlet of the patch simply passes through its control input (after
332 processing messages which are understood by the wrapped plugin). By these
333 means control messages can flow along with the audio signal through an entire
334 chain of Faust units. (You can find an example of this in
335 examples/faust/faustdemo.pd.) Moreover, when generating a polyphonic synth
336 patch using the -n option then there will actually be two control inlets, one
337 for note messages and one for ordinary control messages; this is illustrated
338 in the examples/synth/synth.pd example.
339
340 The generated patch also includes the necessary GUI elements to see and change
341 all (active and passive) controls of the Faust unit. Faust control elements
342 are mapped to Pd GUI elements in an obvious fashion, following the horizontal
343 and vertical layout specified in the Faust source. The script also adds
344 special buttons for resetting all controls to their defaults and to operate
345 the special ``active`` control.
346
347 This generally works very well, but you should be aware that the control GUIs
348 generated by faust2pd are somewhat hampered by the limited range of GUI
349 elements available in a vanilla Pd installation. As a remedy, faust2pd
350 provides various options to change the content of the generated wrapper and
351 work around these limitations.
352
353 - There are no real button widgets as required by the Faust specification,
354 so bangs are used instead. There is a global delay time for switching the
355 control from 1 back to 0, which can be changed by sending a value in
356 milliseconds to the ``faust-delay`` receiver. If you need interactive
357 control over the switching time then it is better to use checkboxes instead,
358 or you can have faust2pd automatically substitute checkboxes for all buttons
359 in a patch by invoking it with the -f a.k.a. --fake-buttons option.
360
361 - Sliders in Pd do not display their value in numeric form so it may be hard
362 to figure out what the current value is. Therefore faust2pd has an option -s
363 a.k.a. --slider-nums which causes it to add a number box to each slider
364 control. (This flag also applies to Faust's passive bargraph controls, as
365 these are implemented using sliders, see below.)
366
367 - Pd's sliders also have no provision for specifying a stepsize, so they are
368 an awkward way to input integral values from a small range. OTOH, Faust
369 doesn't support the "radio" control elements which Pd provides for that
370 purpose. As a remedy, faust2pd allows you to specify the option -r max
371 (a.k.a. --radio-sliders=max) to indicate that sliders with integral values
372 from the range 0..max-1 are to be mapped to corresponding Pd radio controls.
373
374 - Faust's bargraphs are emulated using sliders. Note that these are passive
375 controls which just display a value computed by the Faust unit. A different
376 background color is used for these widgets so that you can distinguish them
377 from the ordinary (active) slider controls. The values shown in passive
378 controls are sampled every 40 ms by default. You can change this value by
379 sending an appropriate message to the global ``faust-timer`` receiver.
380
381 - Since Pd has no "tabbed" (notebook-like) GUI element, Faust's tgroups are
382 mapped to hgroups instead. It may be difficult to present large and
383 complicated control interfaces without tabbed dialogs, though. As a remedy,
384 you can control the amount of horizontal or vertical space available for the
385 GUI area with the -x and -y (a.k.a. --width and --height) options and
386 faust2pd will then try to break rows and columns in the layout to make
387 everything fit within that area. (This feature has only been tested with
388 simple layouts so far, so beware.)
389
390 - You can also exclude certain controls from appearing in the GUI using the -X
391 option. This option takes a comma-separated list of shell glob patterns
392 indicating either just the names or the fully qualified paths of Faust
393 controls which are to be excluded from the GUI. For instance, the option
394 ``-X 'volume,meter*,faust/resonator?/*'`` will exclude all volume controls,
395 all controls whose names start with ``meter``, and all controls in groups
396 matching ``faust/resonator?``. (Note that the argument to -X has to be
397 quoted if it contains any wildcards such as ``*`` and ``?``, so that the
398 shell doesn't try to expand the patterns beforehand. Also note that only one
399 -X option is recognized, so you have to specify all controls to be excluded
400 as a single option.)
401
402 - Faust group labels are not shown at all, since I haven't found an easy way
403 to draw some kind of labelled frame in Pd yet.
404
405 Despite these limitations, faust2pd appears to work rather well, at least for
406 the kind of DSPs found in the Faust distribution. (Still, for more complicated
407 control surfaces and interfaces to be used on stage you'll probably have to
408 edit the generated GUI layouts by hand.)
409
410 For convenience, all the content-related command line options mentioned above
411 can also be specified in the Faust source, as special tags in the label of the
412 toplevel group of the dsp. These take the form ``[pd:option]`` or
413 ``[pd:option=value]`` where ``option`` is any of the (long) options understood
414 by faust2pd. For instance::
415
416 process = vgroup("mysynth [pd:nvoices=8] [pd:slider-nums]", ...);
417
418 Source options carrying arguments, like ``nvoices`` in the above example, can
419 also be overridden with corresponding command line options.
420
421 Conclusion
422 ==========
423
424 Creating Faust plugins for use with Pd has never been easier before, so I hope
425 that you'll soon have much joy trying your Faust programs in Pd. Add Pd-Pure
426 to this, and you can program all your specialized audio and control objects
427 using two modern-style functional languages which are much more fun than
428 C/C++. Of course there's an initial learning curve to be mastered, but IMHO it
429 is well worth the effort. The bottomline is that Pd+Faust+Pure really makes an
430 excellent combo which provides you with a powerful, programmable interactive
431 environment for creating advanced computer music and multimedia applications
432 with ease.
433
434 Acknowledgements
435 ----------------
436
437 Thanks are due to Yann Orlarey for his wonderful Faust, which makes developing
438 DSP algorithms so easy and fun.
439
440 .. Appendix follows here.