Skip to content
The Faust libraries
OpenSCAD Shell
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Moving Eric Tarr's filters to veffects.lib Aug 30, 2019
dx7presets Rework dx72faust to use more flexible C++ iostreams. May 31, 2017
licenses Testing new local metadata system in oscillators.lib May 15, 2018
modalmodels Adding new modal models to physmodels.lib and fixing some bugs in mes… Apr 27, 2017
old Fix typos Mar 30, 2019
README.md Add interpolators.lib in documentation. Sep 8, 2019
all.lib Add reducemaps.lib in standard libraries. Aug 8, 2019
analyzers.lib Add soundfiles library in README and generateDoc, cleanup. Jul 27, 2019
basics.lib Correct 'ar' envelope, simplify 'impulsify'. Sep 26, 2019
compressors.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
delays.lib Add soundfiles library in README and generateDoc, cleanup. Jul 27, 2019
demos.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
double.lib Fix decrease_modulo in double.lib and documentation. Aug 6, 2019
dx7.lib Typos. Oct 31, 2018
envelopes.lib Correct table use in tubes.lib. Oct 4, 2019
filters.lib Correct documentation in interpolators.lib, typo in reducemaps.lib, c… Sep 8, 2019
float.lib Fix decrease_modulo in double.lib and documentation. Aug 6, 2019
generateDoc Add interpolators.lib in documentation. Sep 8, 2019
hoa.lib Correct documentation in interpolators.lib, typo in reducemaps.lib, c… Sep 8, 2019
install [NEW] script to install the Faust libraries Apr 8, 2019
instruments.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
interpolators.lib Correct waveform interpolator examples, cleanup. Sep 14, 2019
maths.lib Correct waveform interpolator examples, cleanup. Sep 14, 2019
maxmsp.lib Typo in maxmsp.lib. Sep 20, 2019
mi.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
misceffects.lib Simplifying the echo function Apr 26, 2019
noises.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
oscillators.lib Correct documentation in interpolators.lib, typo in reducemaps.lib, c… Sep 8, 2019
phaflangers.lib Adding libraries prefixes in doc Sep 22, 2017
physmodels.lib Add semi2ratio/ratio2semi functions in basics.lib. Rework pitchwheel … Sep 9, 2019
reducemaps.lib Correct documentation in interpolators.lib, typo in reducemaps.lib, c… Sep 8, 2019
reverbs.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
routes.lib [NEW] most of the definitions of routes.lib rewritten using the new (… Apr 8, 2019
runtime.lib Correct some function parameter order in soundfiles.lib, documentation. Aug 2, 2019
sf.lib add nextpow2 to maths.lib Apr 15, 2019
signals.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
soundfiles.lib Correct 'selectoutn' example code, improve 'selectmulti', cleanup. Sep 13, 2019
spats.lib Adding libraries prefixes in doc Sep 22, 2017
stdfaust.lib Add reducemaps.lib in standard libraries. Aug 8, 2019
synths.lib Rework soundfiles.lib, cleanup. Jul 28, 2019
tonestacks.lib Correct ba.selectmulti to handle circuits with inputs. Sep 8, 2019
tubes.lib Correct table use in tubes.lib. Oct 4, 2019
vaeffects.lib Correct documentation in interpolators.lib, typo in reducemaps.lib, c… Sep 8, 2019

README.md

Faust Libraries

NOTE: this documentation was automatically generated using pandoc.

This page provides information on how to use the Faust libraries.

The /libraries folder contains the different Faust libraries. If you wish to add your own functions to this library collection, you can refer to the "Contributing" section providing a set of coding conventions.

WARNING: These libraries replace the "old" Faust libraries. They are still being beta tested so you might encounter bugs while using them. If your codes still use the "old" Faust libraries, you might want to try to use Bart Brouns' script that automatically makes an old Faust code compatible with the new libraries: https://github.com/magnetophon/faustCompressors/blob/master/newlib.sh. If you find a bug, please report it at rmichon_at_ccrma_dot_stanford_dot_edu. Thanks ;)!

Using the Faust Libraries

The easiest and most standard way to use the Faust libraries is to import stdfaust.lib in your Faust code:

import("stdfaust.lib");

This will give you access to all the Faust libraries through a series of environments:

  • sf: all.lib
  • an: analyzers.lib
  • ba: basics.lib
  • co: compressors.lib
  • de: delays.lib
  • dm: demos.lib
  • dx: dx7.lib
  • en: envelopes.lib
  • fi: filters.lib
  • ho: hoa.lib
  • it: interpolators.lib
  • ma: maths.lib
  • ef: misceffects.lib
  • os: oscillators.lib
  • no: noises.lib
  • pf: phaflangers.lib
  • pm: physmodels.lib
  • rm: reducemaps.lib
  • re: reverbs.lib
  • ro: routes.lib
  • si: signals.lib
  • so: soundfiles.lib
  • sp: spats.lib
  • sy: synths.lib
  • ve: vaeffects.lib

Environments can then be used as follows in your Faust code:

import("stdfaust.lib");
process = os.osc(440);

In this case, we're calling the osc function from oscillators.lib.

You can also access all the functions of all the libraries directly using the sf environment:

import("stdfaust.lib");
process = sf.osc(440);

Alternatively, environments can be created by hand:

os = library("oscillators.lib");
process = os.osc(440);

Finally, libraries can be simply imported in the Faust code (not recommended):

import("oscillators.lib");
process = osc(440);

Contributing

If you wish to add a function to any of these libraries or if you plan to add a new library, make sure that you follow the following conventions:

New Functions

  • All functions must be preceded by a markdown documentation header respecting the following format (open the source code of any of the libraries for an example):
//-----------------functionName--------------------
// Description
//
// #### Usage
//
// ```
// Usage Example
// ```
//
// Where:
//
// * argument1: argument 1 description
//-------------------------------------------------
  • Every time a new function is added, the documentation should be updated simply by running make doclib.
  • The environment system (e.g. os.osc) should be used when calling a function declared in another library (see the section on Using the Faust Libraries).
  • Try to reuse exisiting functions as much as possible.
  • If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.

New Libraries

  • Any new "standard" library should be declared in stdfaust.lib with its own environment (2 letters - see stdfaust.lib).
  • Any new "standard" library must be added to generateDoc.
  • Functions must be organized by sections.
  • Any new library should at least declare a name and a version.
  • The comment based markdown documentation of each library must respect the following format (open the source code of any of the libraries for an example):
//############### libraryName ##################
// Description
//
// * Section Name 1
// * Section Name 2
// * ...
//
// It should be used using the `[...]` environment:
//
// ```
// [...] = library("libraryName");
// process = [...].functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `[...]`
// environment:
//
// ```
// import("stdfaust.lib");
// process = [...].functionCall;
// ```
//##############################################

//================= Section Name ===============
// Description
//==============================================
  • If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.

General Organization

Only the libraries that are considered to be "standard" are documented:

  • analyzers.lib
  • basics.lib
  • compressors.lib
  • delays.lib
  • demos.lib
  • dx7.lib
  • envelopes.lib
  • filters.lib
  • hoa.lib
  • interpolators.lib
  • maths.lib
  • misceffects.lib
  • oscillators.lib
  • noises.lib
  • phaflangers.lib
  • physmodels.lib
  • reducemaps.lib
  • reverbs.lib
  • routes.lib
  • signals.lib
  • soundfiles.lib
  • spats.lib
  • synths.lib
  • tonestacks.lib (not documented but example in /examples/misc)
  • tubes.lib (not documented but example in /examples/misc)
  • vaeffects.lib

Other deprecated libraries such as music.lib, etc. are present but are not documented to not confuse new users.

The doumentation of each library can be found in /documentation/library.html or in /documentation/library.pdf.

The /examples directory contains all the examples from the /examples folder of the Faust distribution as well as new ones. Most of them were updated to reflect the coding conventions described in the next section. Examples are organized by types in different folders. The /old folder contains examples that are fully deprecated, probably because they were integrated to the libraries and fully rewritten (see freeverb.dsp for example). Examples using deprecated libraries were integrated to the general tree but a warning comment was added at their beginning to point readers to the right library and function.

Coding Conventions

In order to have a uniformized library system, we established the following conventions (that hopefully will be followed by others when making modifications to them :-) ).

Documentation

  • All the functions that we want to be "public" are documented.
  • We used the faust2md "standards" for each library: //### for main title (library name - equivalent to # in markdown), //=== for section declarations (equivalent to ## in markdown) and //--- for function declarations (equivalent to #### in markdown - see basics.lib for an example).
  • Sections in function documentation should be declared as #### markdown title.
  • Each function documentation provides a "Usage" section (see basics.lib).

Library Import

To prevent cross-references between libraries we generalized the use of the library("") system for function calls in all the libraries. This means that everytime a function declared in another library is called, the environment corresponding to this library needs to be called too. To make things easier, a stdfaust.lib library was created and is imported by all the libraries:

an = library("analyzers.lib");
ba = library("basics.lib");
co = library("compressors.lib");
de = library("delays.lib");
dm = library("demos.lib");
dx = library("dx7.lib");
en = library("envelopes.lib");
fi = library("filters.lib");
ho = library("hoa.lib");
it = library("interpolators.lib");
ma = library("maths.lib");
ef = library("misceffects.lib");
os = library("oscillators.lib");
no = library("noises.lib");
pf = library("phaflangers.lib");
pm = library("physmodels.lib");
rm = library("reducemaps.lib");
re = library("reverbs.lib");
ro = library("routes.lib");
sp = library("spats.lib");
si = library("signals.lib");
so = library("soundfiles.lib");
sy = library("synths.lib");
ve = library("vaeffects.lib");

For example, if we wanted to use the smooth function which is now declared in signals.lib, we would do the following:

import("stdfaust.lib");

process = si.smooth(0.999);

This standard is only used within the libraries: nothing prevents coders to still import signals.lib directly and call smooth without ro., etc.

"Demo" Functions

"Demo" functions are placed in demos.lib and have a built-in user interface (UI). Their name ends with the _demo suffix. Each of these function have a .dsp file associated to them in the /examples folder.

Any function containing UI elements should be placed in this library and respect these standards.

"Standard" Functions

"Standard" functions are here to simplify the life of new (or not so new) Faust coders. They are declared in /libraries/doc/standardFunctions.md and allow to point programmers to preferred functions to carry out a specific task. For example, there are many different types of lowpass filters declared in filters.lib and only one of them is considered to be standard, etc.

Copyright / License

Now that Faust libraries are less author specific, each function will normally have its own copyright-and-license line in the library source (the .lib file, such as analyzers.lib). If not, see if the function is defined within a section of the .lib file stating the license in source-code comments. If not, then the copyright and license given at the beginning of the .lib file may be assumed, when present. If not, run git blame on the .lib file and ask the person who last edited the function!

Note that it is presently possible for a library function released under one license to utilize another library function having some different license. There is presently no indication of this situation in the Faust compiler output, but such notice is planned. For now, library contributors should strive to use only library functions having compatible licenses, and concerned end-users must manually determine the union of licenses applicable to the library functions they are using.

[//]: # Yann says: "I agree, we need to have metadata local to a single definition or a group of definition. This will allow the compiler to be more selective when including metadata in the generated code."

You can’t perform that action at this time.