Faust Syntax

Faust Program

A Faust program is essentially a list of statements. These statements can be metadata declarations (either global metadata or function metadata), imports, definitions, and documentation tags, with optional C++ style (//... and /*...*/) comments.

Here is a short Faust program that implements of a simple noise generator (called from the noises.lib Faust library). It exhibits various kind of statements : two global metadata declarations, an imports, a comment, and a definition. We will study later how documentation statements work:


declare name "Noise";
declare copyright "(c)GRAME 2018";

import("stdfaust.lib");

// noise level controlled by a slider
process = no.noise * hslider("gain",0,0,1, 0.1);

The keyword process is the equivalent of main in C/C++. Any Faust program, to be valid, must at least define process.

Statements

The statements of a Faust program are of four kinds:

All statements but documentation end with a semicolon ;.

Metadata

Metadata allow us to add elements which are not part of the language to Faust code. These can range to the name of a Faust program, its author, to potential compilation options or user interface element customizations.

There are three different types of metadata in Faust:

Note that some Global Metadata have standard names and can be used for specific tasks. Their role is described in the Standard Metadata section.

Global Metadata

All global metadata declaration in Faust start with declare, followed by a key and a string. For example:

declare name "Noise";

allows us to specify the name of a Faust program in its whole.

Unlike regular comments, metadata declarations will appear in the C++ code generated by the Faust compiler. A good practice is to start a Faust program with some standard declarations:

declare name "MyProgram";
declare author "MySelf";
declare copyright "MyCompany";
declare version "1.00";
declare license "BSD"; 

Function Metadata

Metadata can be associated to a specific function. In that case, declare is followed by the name of the function, a key, and a string. For example:

declare add author "John Doe"
add = +;

This is very useful when a library has several contributors and that functions potentially have different license terms, etc.

Standard Metadata

There exists a series of standard global metadata in Faust whose role role is described in the following table:

Metadata Role
declare options "[key0:value][key1:value]" This metadata can be used to specify various options associated to a Faust code such as the fact its polyphonic, if it should have OSC, MIDI support, etc. Specific keys usable with this metadata are described throughout this documentation.
declare interface "xxx" Specifies an interface replacing the standard Faust UI.

Imports

File imports allow us to import definitions from other source files.

For example import("maths.lib"); imports the definitions of the maths.lib library.

The most common file to be imported is the stdfaust.lib library which gives access to all the standard Faust libraries from a single point:


import("stdfaust.lib");
process = os.osc(440); // the "hello world" of computer music

Documentation Tags

Documentation statements are optional and typically used to control the generation of the mathematical documentation of a Faust program. This documentation system is detailed in the Mathematical Documentation chapter. In this section we essentially describe the documentation statements syntax.

A documentation statement starts with an opening <mdoc> tag and ends with a closing </mdoc> tag. Free text content, typically in Latex format, can be placed in between these two tags.

Moreover, optional sub-tags can be inserted in the text content itself to require the generation, at the insertion point, of mathematical equations, graphical block-diagrams, Faust source code listing and explanation notice.

The generation of the mathematical equations of a Faust expression can be requested by placing this expression between an opening <equation> and a closing </equation> tag. The expression is evaluated within the lexical context of the Faust program.

Similarly, the generation of the graphical block-diagram of a Faust expression can be requested by placing this expression between an opening <diagram> and a closing </diagram> tag. The expression is evaluated within the lexical context of the Faust program.

The <metadata> tags allow to reference Faust global metadatas, calling the corresponding keyword.

The <notice/> empty-element tag is used to generate the conventions used in the mathematical equations.

The <listing/> empty-element tag is used to generate the listing of the Faust program. Its three attributes mdoctags, dependencies, and distributed enable or disable respectively <mdoc> tags, other files dependencies and distribution of interleaved Faust code between <mdoc> sections.

Definitions

A definition associates an identifier with an expression. Definitions are essentially a convenient shortcut avoiding to type long expressions. During compilation, more precisely during the evaluation stage, identifiers are replaced by their definitions. It is therefore always equivalent to use an identifier or directly its definition. Please note that multiple definitions of a same identifier are not allowed, unless it is a pattern matching based definition.

Simple Definitions

The syntax of a simple definition is:

identifier = expression;

For example here is the definition of random, a simple pseudo-random number generator:

random = +(12345) ~ *(1103515245);

Function Definitions

Definitions with formal parameters correspond to functions definitions.

For example the definition of linear2db, a function that converts linear values to decibels, is:

linear2db(x) = 20*log10(x);

Please note that this notation is only a convenient alternative to the direct use of lambda-abstractions (also called anonymous functions). The following is an equivalent definition of linear2db using a lambda-abstraction:

linear2db = \(x).(20*log10(x));

Definitions With Pattern Matching

Moreover, formal parameters can also be full expressions representing patterns:

This powerful mechanism allows to algorithmically create and manipulate block diagrams expressions. Let's say that you want to describe a function to duplicate an expression several times in parallel:

duplicate(1,x) = x;
duplicate(n,x) = x, duplicate(n-1,x);

Note that this last definition is a convenient alternative to the more verbose:

duplicate = case { 
  (1,x) => x; 
  (n,x) => x, duplicate(n-1,x); 
};

A use case for duplicate could be to put 5 white noise generators in parallel:


import("stdfaust.lib");
duplicate(1,x) = x;
duplicate(n,x) = x, duplicate(n-1,x);
process = duplicate(5,no.noise);

Here is another example to count the number of elements of a list. Please note that we simulate lists using parallel composition: (1,2,3,5,7,11). The main limitation of this approach is that there is no empty list. Moreover lists of only one element are represented by this element:

count((x,xs)) = 1+count(xs);
count(x) = 1;

If we now write count(duplicate(10,666)), the expression will be evaluated as 10.

Note that the order of pattern matching rules matters. The more specific rules must precede the more general rules. When this order is not respected, as in:

count(x) = 1;
count((x,xs)) = 1+count(xs);

the first rule will always match and the second rule will never be called.

Expressions

Despite its textual syntax, Faust is conceptually a block-diagram language. Faust expressions represent DSP block-diagrams and are assembled from primitive ones using various composition operations. More traditional numerical expressions in infix notation are also possible. Additionally Faust provides time based expressions, like delays, expressions related to lexical environments, expressions to interface with foreign function and lambda expressions.

Diagram Expressions

Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions.

Diagram Composition Operations

Five binary composition operations are available to combine block-diagrams:

One can think of each of these composition operations as a particular way to connect two block diagrams.

To describe precisely how these connections are done, we have to introduce some notation. The number of inputs and outputs of a block-diagram are expressed as and . The inputs and outputs themselves are respectively expressed as: , , , and , , , etc.

For each composition operation between two block-diagrams and we will describe the connections that are created and the constraints on their relative numbers of inputs and outputs.

The priority and associativity of this five operations are:

Syntax Priority Association Description
expression ~ expression 4 left Recursive Composition
expression , expression 3 right Parallel Composition
expression : expression 2 right Sequential Composition
expression <: expression 1 right Split Composition
expression :> expression 1 right Merge Composition

Parallel Composition

The parallel composition (e.g., (A,B)) is probably the simplest one. It places the two block-diagrams one on top of the other, without connections. The inputs of the resulting block-diagram are the inputs of A and B. The outputs of the resulting block-diagram are the outputs of A and B.

Parallel composition is an associative operation: (A,(B,C)) and ((A,B),C) are equivalents. When no parenthesis are used (e.g., A,B,C,D), Faust uses right associativity and therefore builds internally the expression (A,(B,(C,D))). This organization is important to know when using pattern matching techniques on parallel compositions.

Example: Oscillators in Parallel

Parallel composition can be used to put 3 oscillators of different kinds and frequencies in parallel, which will result in a Faust program with 3 outputs:


import("stdfaust.lib");
process = os.osc(440),os.sawtooth(550),os.triangle(660);

Example: Stereo Effect

Parallel composition can be used to easily turn a mono effect into a stereo one which will result in a Faust program with 2 inputs and 2 outputs:


import("stdfaust.lib");
level = 1;
process = ve.autowah(level),ve.autowah(level);

Note that there's a better to write this last example using the par iteration:


import("stdfaust.lib");
level = 1;
process = par(i,2,ve.autowah(level));

Sequential Composition

The sequential composition (e.g., A:B) expects:

It connects each output of to the corresponding input of :

Sequential composition is an associative operation: (A:(B:C)) and ((A:B):C) are equivalents. When no parenthesis are used, like in A:B:C:D, Faust uses right associativity and therefore builds internally the expression (A:(B:(C:D))).

Example: Sine Oscillator

Since everything is considered as a signal generator in Faust, sequential composition can be simply used to pass an argument to a function:


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

Example: Effect Chain

Sequential composition can be used to create an audio effect chain. Here we're plugging a guitar distortion to an autowah:


import("stdfaust.lib");
drive = 0.6;
offset = 0;
autoWahLevel = 1;
process = ef.cubicnl(drive,offset) : ve.autowah(autoWahLevel);

Split Composition

The split composition (e.g., A<:B) operator is used to distribute the outputs of to the inputs of .

For the operation to be valid, the number of inputs of must be a multiple of the number of outputs of :

Each input of is connected to the output of :

Example: Duplicating the Output of an Oscillator

Split composition can be used to duplicate signals. For example, the output of the following sawtooth oscillator is duplicated 3 times in parallel.


import("stdfaust.lib");
process = os.sawtooth(440) <: _,_,_;

Note that this can be written in a more effective way by replacing _,_,_ with par(i,3,_) using the par iteration.

Example: Connecting a Mono Effect to a Stereo One

More generally, the split composition can be used to connect a block with a certain number of output to a block with a greater number of inputs:


import("stdfaust.lib");
drive = 0.6;
offset = 0;
process = ef.cubicnl(drive,offset) <: dm.zita_light;

Note that an arbitrary number of signals can be split, for example:


import("stdfaust.lib");
drive = 0.6;
offset = 0;
process = par(i,2,ef.cubicnl(drive,offset)) <: par(i,2,dm.zita_light);

Once again, the only rule with this is that in the expression A<:B the number of inputs of B has to be a multiple of the number of outputs of A.

Merge Composition

The merge composition (e.g., A:>B) is the dual of the split composition. The number of outputs of must be a multiple of the number of inputs of :

Each output of is connected to the input of :

The incoming signals of an input of are summed together.

Example: Summing Signals Together - Additive Synthesis

Merge composition can be used to sum an arbitrary number of signals together. Here's an example of a simple additive synthesizer (note that the result of the sum of the signals is divided by 3 to prevent clicking):


import("stdfaust.lib");
freq = hslider("freq",440,50,3000,0.01);
gain = hslider("gain",1,0,1,0.01);
gate = button("gate");
envelope = gain*gate : si.smoo;
process = os.osc(freq),os.osc(freq*2),os.osc(freq*3) :> /(3)*envelope;

While the resulting block diagram will look slightly different, this is mathematically equivalent to:


import("stdfaust.lib");
freq = hslider("freq",440,50,3000,0.01);
gain = hslider("gain",1,0,1,0.01);
gate = button("gate");
envelope = gain*gate : si.smoo;
process = (os.osc(freq) + os.osc(freq*2) + os.osc(freq*3))/(3)*envelope;

Example: Connecting a Stereo Effect to a Mono One

More generally, the merge composition can be used to connect a block with a certain number of output to a block with a smaller number of inputs:


import("stdfaust.lib");
drive = 0.6;
offset = 0;
process = dm.zita_light :> ef.cubicnl(drive,offset);

Note that an arbitrary number of signals can be split, for example:


import("stdfaust.lib");
drive = 0.6;
offset = 0;
process = par(i,2,dm.zita_light) :> par(i,2,ef.cubicnl(drive,offset));

Once again, the only rule with this is that in the expression A:>B the number of outputs of A has to be a multiple of the number of inputs of B.

Recursive Composition

The recursive composition (e.g., A~B) is used to create cycles in the block-diagram in order to express recursive computations. It is the most complex operation in terms of connections.

To be applicable, it requires that:

Each input of is connected to the corresponding output of via an implicit 1-sample delay :

and each output of is connected to the corresponding input of :

The inputs of the resulting block diagram are the remaining unconnected inputs of . The outputs are all the outputs of .

Example: Timer

Recursive composition can be used to implement a "timer" that will count each sample starting at time :


process = _~+(1);

The difference equation corresponding to this program is:

an its output signal will look like: .

Example: One Pole Filter

Recursive composition can be used to implement a one pole filter with one line of code and just a few characters:


a1 = 0.999; // the pole
process = +~*(a1);

The difference equation corresponding to this program is:

Note that the one sample delay of the filter is implicit here so it doesn't have to be declared.

Inputs and Outputs of an Expression

The number of inputs and outputs of a Faust expression can be known at compile time simply by using inputs(expression) and outputs(expression).

For example, the number of outputs of a sine wave oscillator can be known simply by writing the following program:


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

Note that Faust automatically simplified the expression by generating a program that just outputs 1.

This type of construction is useful to define high order functions and build algorithmically complex block-diagrams. Here is an example to automatically reverse the order of the outputs of an expression.

Xo(expr) = expr <: par(i,n,ba.selector(n-i-1,n)) 
with { 
  n = outputs(expr);
};

And the inputs of an expression :

Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr 
with { 
  n = inputs(expr); 
};

For example Xi(-) will reverse the order of the two inputs of the substraction:


import("stdfaust.lib");
Xi(expr) = si.bus(n) <: par(i,n,ba.selector(n-i-1,n)) : expr 
with { 
  n = inputs(expr); 
};
process = Xi(-);

Iterations

Iterations are analogous to for(...) loops in other languages and provide a convenient way to automate some complex block-diagram constructions.

The use and role of par, seq, sum, and prod are detailed in the following sections.

par Iteration

The par iteration can be used to duplicate an expression in parallel. Just like other types of iterations in Faust:

Example: Simple Additive Synthesizer


import("stdfaust.lib");
freq = hslider("freq",440,50,3000,0.01);
gain = hslider("gain",1,0,1,0.01);
gate = button("gate");
envelope = gain*gate : si.smoo;
nHarmonics = 4;
process = par(i,nHarmonics,os.osc(freq*(i+1))) :> /(nHarmonics)*envelope;

i is used here at each iteration to compute the value of the frequency of the current oscillator. Also, note that this example could be re-wrtitten using sum iteration (see example in the corresponding section).

seq Iteration

The seq iteration can be used to duplicate an expression in series. Just like other types of iterations in Faust:

Example: Peak Equalizer

The fi.peak_eq function of the Faust libraries implements a second order "peak equalizer" section (gain boost or cut near some frequency). When placed in series, it can be used to implement a full peak equalizer:


import("stdfaust.lib");
nBands = 8;
filterBank(N) = hgroup("Filter Bank",seq(i,N,oneBand(i)))
with {
    oneBand(j) = vgroup("[%j]Band %a",fi.peak_eq(l,f,b))
    with {
        a = j+1; // just so that band numbers don't start at 0
        l = vslider("[2]Level[unit:db]",0,-70,12,0.01) : si.smoo;
        f = nentry("[1]Freq",(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
        b = f/hslider("[0]Q[style:knob]",1,1,50,0.01) : si.smoo;
    };
};
process = filterBank(nBands);

Note that i is used here at each iteration to compute various elements and to format some labels. Having user interface elements with different names is a way to force their differentiation in the generated interface.

sum Iteration

The sum iteration can be used to duplicate an expression as a sum. Just like other types of iterations in Faust:

Example: Simple Additive Synthesizer

The following example is just a slightly different version from the one presented in the par iteration section. While their block diagrams look slightly different, the generated code is exactly the same.


import("stdfaust.lib");
freq = hslider("freq",440,50,3000,0.01);
gain = hslider("gain",1,0,1,0.01);
gate = button("gate");
envelope = gain*gate : si.smoo;
nHarmonics = 4;
process = sum(i,nHarmonics,os.osc(freq*(i+1)))/(nHarmonics)*envelope;

i is used here at each iteration to compute the value of the frequency of the current oscillator.

prod Iteration

The prod iteration can be used to duplicate an expression as a product. Just like other types of iterations in Faust:

Example: Amplitude Modulation Synthesizer

The following example implements an amplitude modulation synthesizer using an arbitrary number of oscillators thanks to the prod iteration:


import("stdfaust.lib");
freq = hslider("[0]freq",440,50,3000,0.01);
gain = hslider("[1]gain",1,0,1,0.01);
shift = hslider("[2]shift",0,0,1,0.01);
gate = button("[3]gate");
envelope = gain*gate : si.smoo;
nOscs = 4;
process = prod(i,nOscs,os.osc(freq*(i+1+shift)))*envelope;

i is used here at each iteration to compute the value of the frequency of the current oscillator. Note that the shift parameter can be used to tune the frequency drift between each oscillator.

Infix Notation and Other Syntax Extensions

Infix notation is commonly used in mathematics. It consists in placing the operand between the arguments as in

Besides its algebra-based core syntax, Faust provides some syntax extensions, in particular the familiar infix notation. For example if you want to multiply two numbers, say 2 and 3, you can write directly 2*3 instead of the equivalent core-syntax expression 2,3 : *.

The infix notation is not limited to numbers or numerical expressions. Arbitrary expressions A and B can be used, provided that A,B has exactly two outputs. For example _/2 is equivalent to _,2:/ which divides the incoming signal by 2.

Here are a few examples of equivalences:

Infix Syntax Core Syntax
2-3 2,3 : -
2*3 2,3 : *
_@7 _,7 : @
_/2 _,2 : /
A<B A,B : <

In case of doubts on the meaning of an infix expression, for example _*_, it is useful to translate it to its core syntax equivalent, here _,_:*, which is equivalent to *.

Infix Operators

Built-in primitives that can be used in infix notation are called infix operators and are listed below. Please note that a more detailed description of these operators is available section on primitives.

Prefix Notation

Beside infix notation, it is also possible to use prefix notation. The prefix notation is the usual mathematical notation for functions , but extended to infix operators.

It consists in first having the operator, for example /, followed by its arguments between parentheses: /(2,3):

Prefix Syntax Core Syntax
*(2,3) 2,3 : *
@(_,7) _,7 : @
/(_,2) _,2 : /
<(A,B) A,B : <

Partial Application

The partial application notation is a variant of the prefix notation in which not all arguments are given. For instance /(2) (divide by 2), ^(3) (rise to the cube), and @(512) (delay by 512 samples) are examples of partial applications where only one argument is given. The result of a partial application is a function that "waits" for the remaining arguments.

When doing partial application with an infix operator, it is important to note that the supplied argument is not the first argument, but always the second one:

Prefix Partial Application Syntax Core Syntax
+(C) _,C : *
-(C) _,C : -
<(C) _,C : <
/(C) _,C : /

For commutative operations that doesn't matter. But for non-commutative ones, it is more "natural" to fix the second argument. We use divide by 2 (/(2)) or rise to the cube (^(3)) more often than the other way around.

Please note that this rule only applies to infix operators, not to other primitives or functions. If you partially apply a regular function to a single argument, it will correspond to the first parameter.

Example: Gain Controller

The following example demonstrates the use of partial application in the context of a gain controller:


gain = hslider("gain",0.5,0,1,0.01);
process = *(gain);

' Time Expression

' is used to express a one sample delay. For example:


process = _';

will delay the incoming signal by one sample.

' time expressions can be chained, so the output signal of this program:


process = 1'';

will look like: .

The ' time expression is useful when designing filters, etc. and is equivalent to @(1) (see the @ Time Expression).

@ Time Expression

@ is used to express a delay with an arbitrary number of samples. For example:


process = @(10);

will delay the incoming signal by 10 samples.

A delay expressed with @ doesn't have to be fixed but it must be bounded and cannot be negative. Therefore, the values of a slider are perfectly acceptable:


process = @(hslider("delay",0,0,100,1));

@ only allows for the implementation of integer delay. Thus, various fractional delay algorithms are implemented in the Faust libraries.

Environment Expressions

Faust is a lexically scoped language. The meaning of a Faust expression is determined by its context of definition (its lexical environment) and not by its context of use.

To keep their original meaning, Faust expressions are bounded to their lexical environment in structures called closures. The following constructions allow to explicitly create and access such environments. Moreover they provide powerful means to reuse existing code and promote modular design.

with Expression

The with construction allows to specify a local environment: a private list of definition that will be used to evaluate the left hand expression.

In the following example :


pink = f : + ~ g 
with {
  f(x) = 0.04957526213389*x - 0.06305581334498*x' + 0.01483220320740*x'';
  g(x) = 1.80116083982126*x - 0.80257737639225*x';
};
process = pink;

the definitions of f(x) and g(x) are local to f : + ~ g.

Please note that with is left associative and has the lowest priority:

letrec Expression

The letrec construction is somehow similar to with, but for difference equations instead of regular definitions. It allows us to easily express groups of mutually recursive signals, for example:

as E letrec { 'x = y+10; 'y = x-1; }

The syntax is defined by the following rules:

Note the special notation 'x = y + 10 instead of x = y' + 10. It makes syntactically impossible to write non-sensical equations like x=x+1.

Here is a more involved example. Let say we want to define an envelope generator with an attack and a release time (as a number of samples), and a gate signal. A possible definition could be:


import("stdfaust.lib");
ar(a,r,g) = v
letrec {
  'n = (n+1) * (g<=g');
  'v = max(0, v + (n<a)/a - (n>=a)/r) * (g<=g');
};
gate = button("gate");
process = os.osc(440)*ar(1000,1000,gate);

With the following semantics for and :

environment Expression

The environment construction allows to create an explicit environment. It is like a `with', but without the left hand expression. It is a convenient way to group together related definitions, to isolate groups of definitions and to create a name space hierarchy.

In the following example an environment construction is used to group together some constant definitions :

constant = environment {
  pi = 3.14159;
  e = 2,718;
  ...
};

The . construction allows to access the definitions of an environment (see next section).

Access Expression

Definitions inside an environment can be accessed using the . construction.

For example constant.pi refers to the definition of pi in the constant environment defined above.

Note that environments don't have to be named. We could have written directly:

environment{pi = 3.14159; e = 2,718;....}.pi

library Expression

The library construct allows to create an environment by reading the definitions from a file.

For example library("filters.lib") represents the environment obtained by reading the file filters.lib. It works like import("filters.lib") but all the read definitions are stored in a new separate lexical environment. Individual definitions can be accessed as described in the previous paragraph. For example library("filters.lib").lowpass denotes the function lowpass as defined in the file filters.lib.

To avoid name conflicts when importing libraries it is recommended to prefer library to import. So instead of :

import("filters.lib");
  ...
  ...lowpass....
  ...
};

the following will ensure an absence of conflicts :

fl = library("filters.lib");
  ...
...fl.lowpass....
    ...
};

In practice, that's how the stdfaust.liblibrary works.

component Expression

The component construction allows us to reuse a full Faust program (e.g., a .dsp file) as a simple expression.

For example component("freeverb.dsp") denotes the signal processor defined in file freeverb.dsp.

Components can be used within expressions like in:

...component("karplus32.dsp") : component("freeverb.dsp")... 

Please note that component("freeverb.dsp") is equivalent to library("freeverb.dsp").process.

component works well in tandem with explicit substitution (see next section).

Explicit Substitution

Explicit substitution can be used to customize a component or any expression with a lexical environment by replacing some of its internal definitions, without having to modify it.

For example we can create a customized version of component("freeverb.dsp"), with a different definition of foo(x), by writing:

...component("freeverb.dsp")[foo(x) = ...;]...
};

Foreign Expressions

Reference to external C functions, variables and constants can be introduced using the foreign function mechanism.

ffunction

An external C function is declared by indicating its name and signature as well as the required include file. The file maths.lib of the Faust distribution contains several foreign function definitions, for example the inverse hyperbolic sine function asinh:

asinh = ffunction(float asinh (float), <math.h>, "");

Foreign functions with input parameters are considered pure math functions. They are therefore considered free of side effects and called only when their parameters change (that is at the rate of the fastest parameter).

Exceptions are functions with no input parameters. A typical example is the C rand() function. In this case, the compiler generates code to call the function at sample rate.

Signature

The signature part (float asinh (float) in the example presented in the previous section) describes the prototype of the C function: return type, function name, and list of parameter types. Because the name of the foreign function can possibly depend on the floating point precision in use (float, double and quad), it is possible to give a different function name or each floating point precision using a signature with up to three function names.

For example in the declaration:

asinh = ffunction(float asinhf|asinh|asinhl (float), <math.h>, "");

the signature float asinhf|asinh|asinhl (float) indicates to use the function name asinhf in single precision, asinh in double precision and asinhl in long double (quad) precision.

Types

Only numerical functions involving simple int and float parameters are allowed currently in Faust. No vectors, tables or data structures can be passed as parameters or returned.

Variables and Constants

External variables and constants can also be declared with a similar syntax. In the same maths.lib file, the definition of the sampling rate constant SR and the definition of the block-size variable BS can be found:

SR = min(192000.0,max(1.0,fconstant(int fSamplingFreq, <math.h>)));
BS = fvariable(int count, <math.h>);

Foreign constants are not supposed to vary. Therefore expressions involving only foreign constants are only computed once, during the initialization period.

Variable are considered to vary at block speed. This means that expressions depending of external variables are computed every block.

File Include

In declaring foreign functions one has also to specify the include file. It allows the Faust compiler to add the corresponding #include in the generated code.

Library File

In declaring foreign functions one can possibly specify the library where the actual code is located. It allows the Faust compiler to (possibly) automatically link the library. Note that this feature is only used with the LLVM backend in 'libfaust' dynamic library model.

Applications and Abstractions

Abstractions and applications are fundamental programming constructions directly inspired by Lambda-Calculus. These constructions provide powerful ways to describe and transform block-diagrams algorithmically.

Abstractions

Abstractions correspond to functions definitions and allow to generalize a block-diagram by making variable some of its parts.

Let's say we want to transform a stereo reverb, dm.zita_light for instance, into a mono effect. The following expression can be written (see the sections on Split Composition and Merge Composition):

_ <: dm.zita_light :> _ 

The incoming mono signal is split to feed the two input channels of the reverb, while the two output channels of the reverb are mixed together to produce the resulting mono output.

Imagine now that we are interested in transforming other stereo effects. We could generalize this principle by making zita_light a variable:

\(zita_light).(_ <: zita_light :> _)

The resulting abstraction can then be applied to transform other effects. Note that if zita_light is a perfectly valid variable name, a more neutral name would probably be easier to read like:

\(fx).(_ <: fx :> _)

A name can be given to the abstraction and in turn use it on dm.zita_light:


import("stdfaust.lib");
mono = \(fx).(_ <: fx :> _);
process = mono(dm.zita_light);

Or even use a more traditional, but equivalent, notation:

mono(fx) = _ <: fx :> _;

Applications

Applications correspond to function calls and allow to replace the variable parts of an abstraction with the specified arguments.

For example, the abstraction described in the previous section can be used to transform a stereo reverb:

mono(dm.zita_light)

The compiler will start by replacing mono by its definition:

\(fx).(_ <: fx :> _)(dm.zita_light)

Replacing the variable part with the argument is called beta-reduction in Lambda-Calculus

Whenever the Faust compiler find an application of an abstraction it replaces the variable part with the argument. The resulting expression is as expected:

(_ <: dm.zita_light :> _)

Pattern Matching

Pattern matching rules provide an effective way to analyze and transform block-diagrams algorithmically.

For example case{ (x:y) => y:x; (x) => x; } contains two rules. The first one will match a sequential expression and invert the two part. The second one will match all remaining expressions and leave it untouched. Therefore the application:

case{(x:y) => y:x; (x) => x;}(reverb : harmonizer)

will produce:

harmonizer : freeverb

Please note that patterns are evaluated before the pattern matching operation. Therefore only variables that appear free in the pattern are binding variables during pattern matching.

Primitives

The primitive signal processing operations represent the built-in functionalities of Faust, that is the atomic operations on signals provided by the language. All these primitives denote signal processors, in other words, functions transforming input signals into output signals.

Numbers

Faust considers two types of numbers: integers and floats. Integers are implemented as 32-bits integers, and floats are implemented either with a simple, double, or extended precision depending of the compiler options. Floats are available in decimal or scientific notation.

Like any other Faust expression, numbers are signal processors. For example the number 0.95 is a signal processor of type that transforms an empty tuple of signals into a 1-tuple of signals such that .

waveform Primitive

The waveform primitive was designed to facilitate the use of rdtable (read table). It allows us to specify a fixed periodic signal as a list of samples.

waveform has two outputs:

For example waveform{0,1,2,3} produces two outputs: the constant signal 4 and the periodic signal .

In the following example:


import("stdfaust.lib");
triangleWave = waveform{0,0.5,1,0.5,0,-0.5,-1,-.5};
triangleOsc(f) = triangleWave,int(os.phasor(8,f)) : rdtable;
f = hslider("freq",440,50,2000,0.01);
process = triangleOsc(f);

waveform is used to define a triangle waveform (in its most primitive form), which is then used with a rdtable controlled by a phaser to implement a triangle wave oscillator. Note that the quality of this oscillator is very low because of the low resolution of the triangle waveform.

soundfile Primitive

The soundfile("label[url:{'path1';'path2';'path3'}]", n) primitive allows for the access a list of externally defined sound resources, described as the list of their filename, or complete paths. The soundfile("label[url:path]", n) simplified syntax allows to use a single file. A soundfile has:

If more outputs than the actual number of channels in the sound file are used, the audio channels will be automatically duplicated up to the wanted number of outputs (so for instance, if a stereo file is used with four output channels, the same group of two channels will be duplicated).

If the soundfile cannot be loaded for whatever reason, a default sound with one channel, a length of 1024 frames and null outputs (with samples of value 0) will be used. Note also that soundfiles are entirely loaded in memory by the architecture file, so that the read index signal can access any sample.

A minimal example to play a stereo soundfile until it's end can be written with:

process = 0,_~+(1):soundfile("son[url:{'foo.wav'}]",2):!,!,_,_;

The 0 first parameter selects the first sound in the soundfile list (which only contains one file in this example), then uses an incrementing read index signal to play the soundfile, cuts the unneeded sound length in frames and sample rate ouputs, and keeps the two actual sound outputs. Having the sound length in frames first output allows to implement sound looping, or any kind of more sophisticated read index signal. Having the sound sample rate second output allows to possibly adapt or change the reading speed.

Specialized architecture files are responsible to load the actual soundfile. The SoundUI C++ class located in the faust/gui/SoundUI.h file in the Faust repository implements the void addSoundfile(label, path, sf_zone) method, which loads the actual soundfiles using the libsndfile library, or possibly specific audio file loading code (in the case of the JUCE framework for instance), and set up the sf_zone sound memory pointers. If label is used without any url metadata, it will be considered as the soundfile pathname. Note that the complete sounfile content is preloaded in memory at initialisation time when the compiled program starts.

Note that a special architecture file can well decide to access and use sound resources created by another means (that is, not directly loaded from a sound file). For instance a mapping between labels and sound resources defined in memory could be used, with some additional code in charge of actually setting up all sound memory pointers when void addSoundfile(label, path, sf_zone) is called by the buidUserInterface mechanism.

C-Equivalent Primitives

Most Faust primitives are analogous to their C counterpart but adapted to signal processing. For example + is a function of type that transforms a pair of signals into a 1-tuple of signals such that . + can be used to very simply implement a mixer:


process = +;

Note that this is equivalent to (see Identity Function):


process = _+_;

The function - has type and transforms a pair of signals into a 1-tuple of signals such that .

Be aware that the unary - only exists in a limited form. It can be used with numbers: -0.5 and variables: -myvar, but not with expressions surrounded by parenthesis, because in this case it represents a partial application. For instance, -(a*b) is a partial application. It is syntactic sugar for _,(a*b) : -. If you want to negate a complex term in parenthesis, you'll have to use 0 - (a*b) instead.

Integer Number

Integer numbers are of type in Faust and can be described mathematically as .

Example: DC Offset of 1


process = 1;

Floating Point Number

Floating point numbers are of type in Faust and can be described as .

Example: DC Offset of 0.5


process = 0.5;

Identity Function

The identity function is expressed in Faust with the _ primitive.

Example: a Signal Passing Through

In the following example, the _ primitive is used to connect the single audio input of a Faust program to its output:


process = _;

Cut Primitive

The cut primitive is expressed in Faust with !. It can be used to "stop"/terminate a signal.

Example: Stopping a Signal

In the following example, the ! primitive is used to stop one of two parallel signals:


process = 1,2 : !,_;

int Primitive

The int primitive can be used to force the cast of a signal to int. It is of type and can be described mathematically as . This primitive is useful when declaringindices to read in a table, etc.

Example: Simple Cast


process = 1.5 : int;

float Primitive

The float primitive can be used to force the cast of a signal to float.

Example: Simple Cast


process = 1.5 : float;

Add Primitive

The + primitive can be used to add two signals together.

Example: Simple Mixer


process = +;

Subtract Primitive

The - primitive can be used to subtract two signals.

Example: Subtracting Two Input Signals


process = -;

Multiply Primitive

The * primitive can be used to multiply two signals.

Example: Multiplying a Signal by 0.5


process = *(0.5);

Divide Primitive

The / primitive can be used to divide two signals.

Example: Dividing a Signal by 2


process = /(2);

Power Primitive

The ^ primitive can be used to raise to the power of N a signal.

Example: Power of Two of a Signal


process = ^(2);

Modulo Primitive

The % primitive can be used to take the modulo of a signal.

Example: Phaser

The following example uses a counter and the % primitive to implement a basic phaser:


process = _~+(1) : -(1) : %(10);

will output a signal: (0,1,2,3,4,5,6,7,8,9,0,1,2,3,4).

AND Primitive

Logical AND can be expressed in Faust with the & primitive.

OR Primitive

Logical OR can be expressed in Faust with the | primitive.

Example

The following example will output 1 if the incoming signal is smaller than 0.5 or greater than 0.7 and 0 otherwise. Note that the result of this operation could be multiplied to another signal to create a condition.


process = _ <: <(0.5) | >(0.7);

XOR Primitive

Logical XOR can be expressed in Faust with the xor primitive.

Example


process = _ <: <(0.5) xor >(0.7);

Left Shift Primitive

Left shift can be expressed in Faust with the << primitive.

Example


process = 1 << 2;

Right Shift Primitive

Right shift can be expressed in Faust with the >> primitive.

Example


process = 1 >> 2;

Smaller Than Primitive

The smaller than comparison can be expressed in Faust with the < primitive.

Example

The following code will output 1 if the input signal is smaller than 0.5 and 0 otherwise.


process = <(0.5);

Smaller or Equal Than Primitive

The smaller or equal than comparison can be expressed in Faust with the <= primitive.

Example

The following code will output 1 if the input signal is smaller or equal than 0.5 and 0 otherwise.


process = <=(0.5);

Greater Than Primitive

The greater than comparison can be expressed in Faust with the > primitive.

Example

The following code will output 1 if the input signal is greater than 0.5 and 0 otherwise.


process = >(0.5);

Greater or Equal Than Primitive

The greater or equal than comparison can be expressed in Faust with the >= primitive.

Example

The following code will output 1 if the input signal is greater or equal than 0.5 and 0 otherwise.


process = >=(0.5);

Equal to Primitive

The equal to comparison can be expressed in Faust with the == primitive.

Example


process = 0 == 1;

Different Than Primitive

The different than comparison can be expressed in Faust with the != primitive.

Example


process = 0 != 1;

math.h-Equivalent Primitives

Most of the C math.h functions are also built-in as primitives (the others are defined as external functions in file math.lib).

acos Primitive

Arc cosine can be expressed as acos in Faust.

Example


process = 0.1 : acos;

asin Primitive

Arc sine can be expressed as asin in Faust.

Example


process = 0.1 : asin;

atan Primitive

Arc tangent can be expressed as atan in Faust.

Example


process = 0.1 : atan;

atan2 Primitive

The arc tangent of 2 signals can be expressed as atan2 in Faust.

Example


process = 0.1,-0.1 : atan2;

cos Primitive

Cosine can be expressed as cos in Faust.

Example


process = 0.1 : cos;

sin Primitive

Sine can be expressed as sin in Faust.

Example


process = 0.1 : sin;

tan Primitive

Tangent can be expressed as tan in Faust.

Example


process = 0.1 : tan;

exp Primitive

Base-e exponential can be expressed as exp in Faust.

Example


process = 0.1 : exp;

log Primitive

Base-e logarithm can be expressed as log in Faust.

Example


process = 0.1 : log;

log10 Primitive

Base-10 logarithm can be expressed as log10 in Faust.

Example


process = 0.1 : log10;

pow Primitive

Power can be expressed as pow in Faust.

Example


process = 2,4 : pow;

sqrt Primitive

Square root can be expressed as sqrt in Faust.

Example


process = 4 : sqrt;

abs Primitive

Absolute value can be expressed as abs in Faust.

Example


process = -0.5 : abs;

min Primitive

Minimum can be expressed as min in Faust.

Example


process = -0.5,0.2 : min;

max Primitive

Maximum can be expressed as max in Faust.

Example


process = -0.5,0.2 : max;

fmod Primitive

Float modulo can be expressed as fmod in Faust.

Example


process = 5.3,2 : fmod;

remainder Primitive

Float remainder can be expressed as remainder in Faust.

Example


process = 5.3,2 : remainder;

floor Primitive

Largest int can be expressed as floor in Faust.

Example


process = 3.6 : floor;

ceil Primitive

Smallest int can be expressed as ceil in Faust.

Example


process = 3.6 : ceil;

rint Primitive

Closest int can be expressed as rint in Faust.

Example


process = 3.6 : rint;

Delay Primitives and Modifiers

Faust hosts various modifiers and primitives to define one sample or integer delay of arbitrary length. They are presented in this section.

mem Primitive

A 1 sample delay can be expressed as mem in Faust.

Example


process = mem;

Note that this is equivalent to process = _' (see ' Modifier) and process = @(1) (see @ Primitive)

' Modifier

' can be used to apply a 1 sample delay to a signal in Faust. It can be seen as syntactic sugar to the mem primitive. ' is very convenient when implementing filters and can help significantly decrease the size of the Faust code.

Example


process = _';

@ Primitive

An integer delay of N samples can be expressed as @(N) in Faust. Note that N can be dynamic but that its range must be bounded. This can be done by using a UI primitive (see example below) allowing for the definition of a range such as hslider, vslider, or nentry.

Note that floating point delay is also available in Faust by the mean of various fractional delay implementations available in the Faust standard libraries.

Usage

_ : @(N) : _

Where:

Example: Static N Samples Delay


N = 10;
process = @(N);

Example: Dynamic N Samples Delay


N = hslider("N",10,1,10,1);
process = @(N);

Table Primitives

rdtable Primitive

The rdtable primitive can be used to read through a read-only (pre-defined at initialisation time) table. The table can either be implemented by using the waveform primitive (as shown in the first example) or using a function controlled by a timer (such as ba.time) as demonstrated in the second example. The idea is that the table is created during the initialization step and before audio computation begins.

Usage

rdtable(n,s,r) : _

Where:

Example: Basic Triangle Wave Oscillator Using the waveform Primitive

In this example, a basic (and dirty) triangle wave-table is defined using the waveform. It is then used with the rdtable primitive and a phasor to implement a triangle wave oscillator:


import("stdfaust.lib");
triangleWave = waveform{0,0.5,1,0.5,0,-0.5,-1,-.5};
triangleOsc(f) = triangleWave,int(os.phasor(8,f)) : rdtable;
f = hslider("freq",440,50,2000,0.01);
process = triangleOsc(f);

Example: Basic Triangle Wave Oscillator Using the sin Primitive and a Timer

In this example, a sine table is implemented using the sin primitive and a timer (ba.time). The timer calls the sin function during the initialization step of the Faust program. It is then used with rdtable to implement a sine wave oscillator.


import("stdfaust.lib");
tableSize = 1 << 16;
sineWave(tablesize) = float(ba.time)*(2.0*ma.PI)/float(tablesize) : sin;
triangleOsc(f) = tableSize,sineWave(tableSize),int(os.phasor(tableSize,f)) : rdtable;
f = hslider("freq",440,50,2000,0.01);
process = triangleOsc(f);

rwtable Primitive

The rwtable primitive can be used to implement a read/write table. It takes an audio input that can be written in the table using a write index (i.e., w below) and read using a read index (i.e., r below).

Usage

_ : rwtable(n,s,w,_,r) : _

Where:

Note that the fourth argument of rwtable corresponds to the input of the table.

Example: Simple Looper

In this example, an input signal is written in the table when record is true (equal to 1). The read index is constantly updated to loop through the table. The table size is set to 48000, which corresponds to one second if the sampling rate is 48000 KHz.


import("stdfaust.lib");
tableSize = 48000;
recIndex = (+(1) : %(tableSize)) ~ *(record);
readIndex = readSpeed/float(ma.SR) : (+ : ma.decimal) ~ _ : *(float(tableSize)) : int;
readSpeed = hslider("[0]Read Speed",1,0.001,10,0.01);
record = button("[1]Record") : int;
looper = rwtable(tableSize,0.0,recIndex,_,readIndex);
process = looper;

Selector Primitives

Selector primitives can be used to create conditions in Faust and to implement switches to choose between several signals.

select2 Primitive

The select2 primitive is a "two-way selector". It has three input signals: , , and one output signal . At each instant the value of the selector signal is used to dynamically route samples from the other two inputs and to the output .

Note

Please note that select2 is not the equivalent of a traditional if-then-else construction. Like every Faust primitive, it has a strict semantics. All input signals are always computed, even when they are not selected. Therefore you can't use select2 to avoid computing something.

The semantics of select2 is as follows:

Usage

_,_ : select2(s) : _

Where:

Example: Signal Selector

The following example allows the user to choose between a sine and a sawtooth wave oscillator.


import("stdfaust.lib");
s = nentry("Selector",0,0,1,1) : int;
sig = os.osc(440),os.sawtooth(440) : select2(s);
process = sig;

Note that select2 could be easily implemented from scratch in Faust:


import("stdfaust.lib");
s = nentry("Selector",0,0,1,1);
mySelect2(s) = *(s==0),*(s==1) :> _;
sig = os.osc(440),os.sawtooth(440) : mySelect2(s);
process = sig;

While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.

select3 Primitive

The select3 primitive is a "three-ways selector". It has four input signals: , , , and one output signal . At each instant the value of the selector signal is used to dynamically route samples from the other three inputs , and to the output .

Usage

_,_,_ : select3(s) : _

Where:

Example: Signal Selector

The following example allows the user to choose between a sine, a sawtooth and a triangle wave oscillator.


import("stdfaust.lib");
s = nentry("Selector",0,0,1,1);
sig = os.osc(440),os.sawtooth(440),os.triangle(440) : select3(s);
process = sig;

Note that select3 could be easily implemented from scratch in Faust using Boolean primitives:


import("stdfaust.lib");
s = nentry("Selector",0,0,2,1) : int;
mySelect3(s) = *(s==0),*(s==1),*(s==2) :> _;
sig = os.osc(440),os.sawtooth(440),os.triangle(440) : mySelect3(s);
process = sig;

While the behavior of this last solution is identical to the first one, the generated code will be a bit different and potentially less efficient.

User Interface Primitives and Configuration

Faust user interface widgets/primitives allow for an abstract description of a user interface from within the Faust code. This description is independent from any GUI toolkits/frameworks and is purely abstract. Widgets can be discrete (e.g., button, checkbox, etc.), continuous (e.g., hslider, vslider, nentry), and organizational (e.g., vgroup, hgroup).

Discrete and continuous elements are signal generators. For example, a button produces a signal which is 1 when the button is pressed and 0 otherwise:

These signals can be freely combined with other audio signals. In fact, the following code is perfectly valid and will generate sound:


process = button("DC");

Each primitive implements a specific UI element, but their appearance can also be completely modified using metadata (a little bit like HTML and CSS in the web). Therefore, hslider, vslider, and nentry) can for example be turned into a knob, a dropdown menu, etc. This concept is further developed in the section on UI metadata.

Continuous UI elements (i.e., hslider, vslider, and nentry) must all declare a range for the parameter they're controlling. In some cases, this range is used during compilation to allocate memory and will impact the generated code. For example, in the case of:


process = @(hslider("N",1,1,10,1));

a buffer of 10 samples will be allocated for the delay implemented with the @ primitive while 20 samples will be allocated in the following example:


process = @(hslider("N",1,1,20,1));

button Primitive

The button primitive implements a button.

Usage

button("label") : _

Where:

Example: Trigger


import("stdfaust.lib");
process = no.noise*button("gate");

checkbox Primitive

The checkbox primitive implements a checkbox/toggle.

Usage

checkbox("label") : _

Where:

Example: Trigger


import("stdfaust.lib");
process = no.noise*checkbox("gate");

hslider Primitive

The hslider primitive implements a horizontal slider.

Usage

hslider("label",init,min,max,step) : _

Where:

Example: Gain Control


gain = hslider("gain",0,0,1,0.01);
process = *(gain);

vslider Primitive

The vslider primitive implements a vertical slider.

Usage

vslider("label",init,min,max,step) : _

Where:

Example


gain = vslider("gain",0,0,1,0.01);
process = *(gain);

nentry Primitive

The nentry primitive implements a "numerical entry".

Usage

nentry("label",init,min,max,step) : _

Where:

Example


gain = nentry("gain",0,0,1,0.01);
process = *(gain);

hgroup Primitive

The hgroup primitive implements a horizontal group. A group contains other UI elements that can also be groups. hgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code.

Usage

hgroup("label",x)

Where:

Example

In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group.


import("stdfaust.lib");
freq = vslider("freq",440,50,1000,0.1);
gain = vslider("gain",0,0,1,0.01);
process = hgroup("Oscillator",os.sawtooth(freq)*gain);

Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.


import("stdfaust.lib");
oscGroup(x) = hgroup("Oscillator",x);
freq = oscGroup(vslider("freq",440,50,1000,0.1));
gain = oscGroup(vslider("gain",0,0,1,0.01));
process = os.sawtooth(freq)*gain;

vgroup Primitive

The vgroup primitive implements a vertical group. A group contains other UI elements that can also be groups. vgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code.

Usage

vgroup("label",x)

Where:

Example

In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group.


import("stdfaust.lib");
freq = hslider("freq",440,50,1000,0.1);
gain = hslider("gain",0,0,1,0.01);
process = vgroup("Oscillator",os.sawtooth(freq)*gain);

Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.


import("stdfaust.lib");
oscGroup(x) = vgroup("Oscillator",x);
freq = oscGroup(hslider("freq",440,50,1000,0.1));
gain = oscGroup(hslider("gain",0,0,1,0.01));
process = os.sawtooth(freq)*gain;

tgroup Primitive

The tgroup primitive implements a "tab group." Tab groups can be used to group UI elements in tabs in the interface. A group contains other UI elements that can also be groups. tgroup is not a signal processor per se and is just a way to label/delimitate part of a Faust code.

Usage

tgroup("label",x)

Where:

Example

In the following example, the 2 UI elements controlling an oscillator are encapsulated in a group.


import("stdfaust.lib");
freq = hslider("freq",440,50,1000,0.1);
gain = hslider("gain",0,0,1,0.01);
process = tgroup("Oscillator",os.sawtooth(freq)*gain);

Note that the Oscillator group can be placed in a function in case we'd like to add elements to it multiple times.


import("stdfaust.lib");
oscGroup(x) = tgroup("Oscillator",x);
freq = oscGroup(hslider("freq",440,50,1000,0.1));
gain = oscGroup(hslider("gain",0,0,1,0.01));
process = os.sawtooth(freq)*gain;

vbargraph Primitive

The vbargraph primitive implements a vertical bar-graph (typically a meter displaying the level of a signal).

Usage

vbargraph takes an input signal and outputs it while making it available to the UI.

_ : vbargraph("label",min,max) : _

Where:

Example: Simple VU Meter

A simple VU meter can be implemented using the vbargraph primitive:


import("stdfaust.lib");
process = _ <: attach(_,abs : ba.linear2db : vbargraph("Level",-60,0));

Note the use of the attach primitive here that forces the compilation of the vbargraph without using its output signal (see section on the attach primitive).

hbargraph Primitive

The hbargraph primitive implements a horizontal bar-graph (typically a meter displaying the level of a signal).

Usage

hbargraph takes an input signal and outputs it while making it available to the UI.

_ : hbargraph("label",min,max) : _

Where:

Example: Simple VU Meter

A simple VU meter can be implemented using the hbargraph primitive:


import("stdfaust.lib");
process = _ <: attach(_,abs : ba.linear2db : hbargraph("Level",-60,0));

Note the use of the attach primitive here that forces the compilation of the hbargraph without using its output signal (see section on the attach primitive).

attach Primitive

The attach primitive takes two input signals and produces one output signal which is a copy of the first input. The role of attach is to force its second input signal to be compiled with the first one. From a mathematical standpoint attach(x,y) is equivalent to 1*x+0*y, which is in turn equivalent to x, but it tells the compiler not to optimize-out y.

To illustrate this role, let's say that we want to develop a mixer application with a vumeter for each input signals. Such vumeters can be easily coded in Faust using an envelope detector connected to a bargraph. The problem is that the signal of the envelope generators has no role in the output signals. Using attach(x,vumeter(x)) one can tell the compiler that when x is compiled vumeter(x) should also be compiled.

The examples in the hbargraph Primitive and the vbargraph Primitive illustrate well the use of attach.

Variable Parts of a Label

Labels can contain variable parts. These are indicated with the sign % followed by the name of a variable. During compilation each label is processed in order to replace the variable parts by the value of the variable. For example:


process = par(i,8,hslider("Voice %i", 0.9, 0, 1, 0.01));

creates 8 sliders in parallel with different names while par(i,8,hslider("Voice", 0.9, 0, 1, 0.01)) would have created only one slider and duplicated its output 8 times.

The variable part can have an optional format digit. For example "Voice %2i" would indicate to use two digit when inserting the value of i in the string.

An escape mechanism is provided. If the sign % is followed by itself, it will be included in the resulting string. For example "feedback (%%)" will result in "feedback (%)".

Labels as Pathnames

Thanks to horizontal, vertical, and tabs groups, user interfaces have a hierarchical structure analog to a hierarchical file system. Each widget has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label.

In the following example :

hgroup("Foo",
    ...
    vgroup("Faa", 
        ...
        hslider("volume",...)
        ...
    )
    ...
)

the volume slider has pathname /h:Foo/v:Faa/volume.

In order to give more flexibility to the design of user interfaces, it is possible to explicitly specify the absolute or relative pathname of a widget directly in its label.

Elements of a path are separated using /. Group types are defined with the following identifiers:

Group Type Group Identifier
hgroup h:
vgroup v:
tgroup t:

Hence, the example presented in the section on the hgroup primitive can be rewritten as:


import("stdfaust.lib");
freq = vslider("h:Oscillator/freq",440,50,1000,0.1);
gain = vslider("h:Oscillator/gain",0,0,1,0.01);
process = os.sawtooth(freq)*gain;

which will be reflected in C++ as:

virtual void buildUserInterface(UI* ui_interface) {
  ui_interface->openHorizontalBox("Oscillator");
  ui_interface->addVerticalSlider("freq", &fVslider1, 440.0f, 50.0f, 1000.0f, 0.100000001f);
  ui_interface->addVerticalSlider("gain", &fVslider0, 0.0f, 0.0f, 1.0f, 0.00999999978f);
  ui_interface->closeBox();
}

Note that path names are inherent to the use of tools gravitating around Faust such as OSC control or faust2api. In the case of faust2api, since no user interface is actually generated, UI elements just become a way to declare parameters of a Faust object. Therefore, there's no distinction between nentry, hslider, vslider, etc.

Smoothing

Despite the fact that the signal generated by user interface elements can be used in Faust with any other signals, UI elements run at a slower rate than the audio rate. This might be a source of clicking if the value of the corresponding parameter is modified while the program is running. This behavior is also amplified by the low resolution of signals generated by UI elements (as opposed to actual audio signals). For example, changing the value of the freq or gain parameters of the following code will likely create clicks (in the case of gain) or abrupt jumps (in the case of freq) in the signal:


import("stdfaust.lib");
freq = hslider("freq",440,50,1000,0.1);
gain = hslider("gain",0,0,1,0.01);
process = os.osc(freq)*gain;

This problem can be easily solved in Faust by using the si.smoo function which implements an exponential smoothing by a unit-dc-gain one-pole lowpass with a pole at 0.999 (si.smoo is just sugar for si.smooth(0.999)). Therefore, the previous example can be rewritten as:


import("stdfaust.lib");
freq = hslider("freq",440,50,1000,0.1) : si.smoo;
gain = hslider("gain",0,0,1,0.01) : si.smoo;
process = os.osc(freq)*gain;

Beware that each si.smoo that you place in your code will add some extra computation so they should be used precociously.

UI elements provide a convenient entry point to the DSP process in the code generated by the Faust compiler (e.g., C++, etc.). For example, the Faust program:

import("stdfaust.lib");
freq = hslider("freq",440,50,1000,0.1);
process = os.osc(freq);

will have the corresponding buildUserInterface method in C++:

virtual void buildUserInterface(UI* ui_interface) {
  ui_interface->openVerticalBox("osc");
  ui_interface->addHorizontalSlider("freq", &fHslider0, 440.0f, 50.0f, 1000.0f, 0.100001f);
  ui_interface->closeBox();
}

The second argument of the addHorizontalSlider method is a pointer to the variable containing the current value of the freq parameter. The value of this pointer can be updated at any point to change the frequency of the corresponding oscillator.

UI Label Metadata

Widget labels can contain metadata enclosed in square brackets. These metadata associate a key with a value and are used to provide additional information to the architecture file. They are typically used to improve the look and feel of the user interface, configure OSC and accelerometer control/mapping, etc. Since the format of the value associated to a key is relatively open, metadata constitute a flexible way for programmers to add features to the language.

The Faust code:

process = *(hslider("foo[key1: val 1][key2: val 2]",0,0,1,0.1));

will produce the corresponding C++ code:

class mydsp : public dsp {
  ...
  virtual void buildUserInterface(UI* ui_interface) {
    ui_interface->openVerticalBox("tst");
    ui_interface->declare(&fHslider0, "key1", "val 1");
    ui_interface->declare(&fHslider0, "key2", "val 2");
    ui_interface->addHorizontalSlider("foo", &fHslider0, 0.0f, 0.0f, 1.0f, 0.100000001f);
    ui_interface->closeBox();
  }
  ...
};

All metadata are removed from the label by the compiler and transformed in calls to the UI::declare() method. All these UI::declare() calls will always take place before the UI::AddSomething() call that creates the User Interface element. This allows the UI::AddSomething() method to make full use of the available metadata.

Metadata are architecture-specific: it is up to the architecture file to decide what to do with it. While some metadata will work with most architectures (e.g., accelerometer and OSC configuration, etc.), others might be more specific. Some of them are presented in the following sections.

Ordering UI Elements

The order of UI declarations in a Faust code doesn't necessarily reflect the actual order of the UI elements in the corresponding interface. Therefore, UI elements can be ordered by placing a metadata before the declaration of the name of the UI element in the label. For example, in the following declaration:

gain = vslider("h:Oscillator/[1]gain",0,0,1,0.01);
freq = vslider("h:Oscillator/[0]freq",440,50,1000,0.1);

the freq parameter will be placed before gain despite the fact that gain is declared first.

This system can be used to order groups as well. Ordering will be carried out on elements at the same level. For example:


import("stdfaust.lib");
freqS = vslider("h:Oscillators/h:[0]Sawtooth/[0]freq",440,50,1000,0.1);
gainS = vslider("h:Oscillators/h:[0]Sawtooth/[1]gain",0,0,1,0.01);
freqT = vslider("h:Oscillators/h:[1]Triangle/[0]freq",440,50,1000,0.1);
gainT = vslider("h:Oscillators/h:[1]Triangle/[1]gain",0,0,1,0.01);
process = os.sawtooth(freqS)*gainS + os.triangle(freqT)*gainT;

Note that this could also be written as:


import("stdfaust.lib");
freqS = vslider("[0]freq",440,50,1000,0.1);
gainS = vslider("[1]gain",0,0,1,0.01);
freqT = vslider("[0]freq",440,50,1000,0.1);
gainT = vslider("[1]gain",0,0,1,0.01);
process = hgroup("Oscillators",
  hgroup("[0]Sawtooth",os.sawtooth(freqS)*gainS) + 
  hgroup("[1]Triangle",os.triangle(freqT)*gainT)
);

Global UI Metadata

Note that global user interfaces completely replacing the one defined using the standard Faust UI primitives may be declared using global metadata. This is the case of the SmartKeyboard interface for example.

In the following subsections, the standard Faust UI metadata are documented. Other types of metadata (e.g., accelerometers, OSC, etc.) are documented in the sections related to these topics.

[style:knob] Metadata

The [style:knob] metadata turns any continuous UI element (i.e., hslider, vslider, nentry) into a knob.

Example


import("stdfaust.lib");
freq = vslider("freq[style:knob]",440,50,1000,0.1);
process = os.sawtooth(freq);

[style:menu] Metadata

The [style:menu] metadata turns any continuous UI element (i.e., hslider, vslider, nentry) into a drop-down menu.

Usage

[style:menu{'Name0':value0;'Name1':value1}]

Where:

Example: Selector


import("stdfaust.lib");
s = vslider("Signal[style:menu{'Noise':0;'Sawtooth':1}]",0,0,1,1);
process = select2(s,no.noise,os.sawtooth(440));

[style:radio] Metadata

The [style:radio] metadata turns a hslider or a vslider into a radio-button-menu. The orientation of the menu is determined by the type of UI element (i.e., hslider for horizontal and vslider for vertical).

Usage

[style:radio{'Name0':value0;'Name1':value1}]

Where:

Example: Selector


import("stdfaust.lib");
s = vslider("Signal[style:radio{'Noise':0;'Sawtooth':1}]",0,0,1,1);
process = select2(s,no.noise,os.sawtooth(440));

[style:led] Metadata

The [style:led] metadata turns a vbargraph or a hbargraph into a blinking LED (with varying intensity).

Example: Level Display


import("stdfaust.lib");
process = _ <: attach(_,abs : ba.linear2db : vbargraph("Level[style:led]",-60,0));

[style:numerical] Metadata

The [style:numerical] metadata turns a vbargraph or a hbargraph into a numerical zone (thus the bargraph itself is no more displayed).

Example: Level Display


import("stdfaust.lib");
process = _ <: attach(_,abs : ba.linear2db : vbargraph("Level[style:numerical]",-60,0));

[unit:dB] Metadata

The [style:dB] metadata changes the unit of a vbargraph or a hbargraph to dB. This impacts its overall appearance by applying a rainbow color scheme, etc.

Example: Level Display


import("stdfaust.lib");
process = _ <: attach(_,abs : ba.linear2db : vbargraph("Level[style:dB]",-60,0));

[unit:xx] Metadata

The [unit:xx] metadata allows us to specify the unit of a UI element. The unit will be displayed right next to the current value of the parameter in the interface.

Usage

[unit:xx]

Where:

Example


import("stdfaust.lib");
freq = vslider("freq[unit:Hz]",440,50,1000,0.1);
process = os.sawtooth(freq);

[scale:xx] Metadata

The [scale:xx] metadata allows for the specification of a scale (different than the default linear one) to the parameter in the UI. [scale:log] can be used to change to scale to logarithmic and [scale:exp] to exponential.

[tooltip:xx] Metadata

The [tooltip:xx] metadata allows for the specification of a "tooltip" when the mouse hover a parameter in the interface. This is very convenient when implementing complex interfaces.

Usage

[tooltip:xx]

Where:

Example


import("stdfaust.lib");
freq = vslider("freq[tooltip:The frequency of the oscillator]",440,50,1000,0.1);
process = os.sawtooth(freq);

[hidden:xx] Metadata

The [hidden:xx] metadata can be used to hide a parameter in the interface. This is convenient when controlling a parameter with a motion sensor or OSC messages and we don't want it to be visible in the interface. This feature is commonly used when making apps for Android and iOS using faust2android or faust2ios.

Compatibility

Sensors Control Metadatas

Sensors control metadata can be used to map the built-in sensors of mobile devices to some of the parameters of a Faust program.

Compatibility

These metadatas are compatible with the following Faust targets and no additional step is required for them to be taken into account when the corresponding app is generated:

Sensors control metadatas have five parameters and follow the following syntax:

[acc: a b c d e] // for accelerometer
[gyr: a b c d e] // for gyroscope

They can be used in a Faust UI parameter declaration:

parameter = nentry("UIparamName[acc: a b c d e]",def,min,max,step);

with:

This allows for the implementation of complex linear and non-linear mappings that are summarized in this figure:

For example, controlling the gain of a synthesizer using the X axis of the accelerometer can be easily done simply by writing something like:

g = nentry("gain[acc: 0 0 -10 0 10]",0.5,0,1,0.01);

With this configuration, g = 0 when the device is standing vertically on its right side, g = 0.5 when the device is standing horizontally with screen facing up, and g = 1 when the device is standing vertically on its left side.

Finally, in this slightly more complex mapping, g = 0 when the device is tilted on its right side and the value of g increases towards 1 when the device is tilted on its left side:

g = nentry("gain[acc: 0 0 0 0 10]",0,0,1,0.01);

Complex nonlinear mappings can be implemented using this system.