faust-common 0.9.95~repack1-2 / usr / share / faust / basic.lib

//################################## basic.lib ###########################################
// A library of basic elements for Faust organized in 5 sections: 
//
// * Conversion Tools
// * Counters and Time/Tempo Tools
// * Array Processing/Pattern Matching
// * Selectors (Conditions)
// * Other Tools (Misc)
//
// It should be used using the `ba` environment:
//
// ```
// ba = library("basic.lib");
// process = ba.functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `ba`
// environment:
//
// ```
// import("stdfaust.lib");
// process = ba.functionCall;
// ```
//########################################################################################

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2003-2016 GRAME, Centre National de Creation Musicale
----------------------------------------------------------------------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the GNU C Library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

EXCEPTION TO THE LGPL LICENSE : As a special exception, you may create a
larger FAUST program which directly or indirectly imports this library
file and still distribute the compiled code generated by the FAUST
compiler, or a modified version of this compiled code, under your own
copyright and license. This EXCEPTION TO THE LGPL LICENSE explicitly
grants you the right to freely choose the license for the resulting
compiled code. In particular the resulting compiled code has no obligation
to be LGPL or GPL. For example you are free to choose a commercial or
closed source license or any other license if you decide so.
************************************************************************
************************************************************************/

ma = library("math.lib");
ro = library("route.lib");

declare name "Faust Basic Element Library";
declare version "0.0";

//=============================Conversion Tools===========================================
//========================================================================================


//-------`samp2sec`----------
// Converts a number of samples to a duration in seconds.
// `samp2sec` is a standard Faust function.
// 
// #### Usage
//
// ```
// samp2sec(n) : _
// ```
//
// Where:
//
// * `n`: number of samples
//----------------------------
samp2sec = /(ma.SR);


//-------`sec2samp`----------
// Converts a duration in seconds to a number of samples.
// `samp2sec` is a standard Faust function.
//
// #### Usage
//
// ```
// sec2samp(d) : _
// ```
//
// Where:
//
// * `d`: duration in seconds
//----------------------------
sec2samp = *(ma.SR);


//-------`db2linear`----------
// Converts a loudness in dB to a linear gain (0-1).
// `db2linear` is a standard Faust function.
//
// #### Usage
//
// ```
// db2linear(l) : _
// ```
//
// Where:
//
// * `l`: loudness in dB
//-----------------------------
db2linear(n) = pow(10, n/20.0);


//-------`linear2db`----------
// Converts a linear gain (0-1) to a loudness in dB.
// `linear2db` is a standard Faust function.
//
// #### Usage
//
// ```
// linear2db(g) : _
// ```
//
// Where:
//
// * `g`: a linear gain
//-----------------------------
linear2db(n) = 20*log10(n);


//----------`lin2LogGain`------------------
// Converts a linear gain (0-1) to a log gain (0-1).
//
// #### Usage
//
// ```
// _ : lin2LogGain : _
// ```
//---------------------------------------------
lin2LogGain = _ <: _*_;


//----------`log2LinGain`------------------
// Converts a log gain (0-1) to a linear gain (0-1).
//
// #### Usage
//
// ```
// _ : log2LinGain : _
// ```
//---------------------------------------------
log2LinGain = sqrt;

//-------`tau2pole`----------
// Returns a real pole giving exponential decay.
// Note that t60 (time to decay 60 dB) is ~6.91 time constants.
// `tau2pole` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : smooth(tau2pole(tau)) : _
// ```
//
// Where:
//
// * `tau`: time-constant in seconds
//-----------------------------
// TODO: author JOS, revised by RM
tau2pole(tau) = exp(-1.0/(tau*ma.SR));


//-------`pole2tau`----------
// Returns the time-constant, in seconds, corresponding to the given real, 
// positive pole in (0,1).
// `pole2tau` is a standard Faust function.
//
// #### Usage
//
// ```
// pole2tau(pole) : _
// ```
//
// Where:
//
// * `pole`: the pole
//-----------------------------
// TODO: author JOS, revised by RM
pole2tau(pole) = -1.0/(log(pole)*ma.SR);


//-------`midikey2hz`----------
// Converts a MIDI key number to a frequency in Hz (MIDI key 69 = A440).
// `midikey2hz` is a standard Faust function.
//
// #### Usage
//
// ```
// midikey2hz(mk) : _
// ```
//
// Where:
//
// * `mk`: the MIDI key number
//-----------------------------
midikey2hz(mk)  = 440.0*pow(2.0, (mk-69.0)/12);


//-------`pianokey2hz`----------
// Converts a piano key number to a frequency in Hz (piano key 49 = A440).
//
// #### Usage
//
// ```
// pianokey2hz(pk) : _
// ```
//
// Where:
//
// * `pk`: the piano key number
//-----------------------------
pianokey2hz(pk) = 440.0*pow(2.0, (pk-49.0)/12);


//-------`hz2pianokey`----------
// Converts a frequency in Hz to a piano key number (piano key 49 = A440).
//
// #### Usage
//
// ```
// hz2pianokey(f) : _
// ```
//
// Where:
//
// * `f`: frequency in Hz
//-----------------------------
hz2pianokey(f)  = 12*ma.log2(f/440.0) + 49.0;


//==============================Counters and Time/Tempo Tools=============================
//========================================================================================

//----------------------------`countdown`------------------------------
// Starts counting down from n included to 0. While trig is 1 the output is n.
// The countdown starts with the transition of trig from 1 to 0. At the end
// of the countdown the output value will remain at 0 until the next trig.
// `countdown` is a standard Faust function.
//
// #### Usage
//
// ```
// countdown(n,trig) : _
// ```
//
// Where:
//
// * `count`: the starting point of the countdown
// * `trig`: the trigger signal (1: start at `n`; 0: decrease until 0)
//-----------------------------------------------------------------------------
countdown(count, trig)	= \(c).(if(trig>0, count, max(0, c-1))) ~_;


//----------------------------`countup`--------------------------------
// Starts counting up from 0 to n included. While trig is 1 the output is 0.
// The countup starts with the transition of trig from 1 to 0. At the end
// of the countup the output value will remain at n until the next trig.
// `countup` is a standard Faust function.
//
// #### Usage
//
// ```
// countup(n,trig) : _
// ```
//
// Where:
//
// * `count`: the starting point of the countup
// * `trig`: the trigger signal (1: start at 0; 0: increase until `n`)
//-----------------------------------------------------------------------------
countup(count, trig)	= \(c).(if(trig>0, 0, min(count, c+1))) ~_;


//--------------------`sweep`--------------------------
// Counts from 0 to `period` samples repeatedly, while `run` is 1.
// Outsputs zero while `run` is 0.
//
// #### Usage
//
// ```
// sweep(period,run) : _
// ```
//-----------------------------------------------------------------
// TODO: author Jonatan Liljedahl, revised by RM
sweep = %(int(*:max(1)))~+(1);


//-------`time`----------
// A simple timer that counts every samples from the beginning of the process.
// `time` is a standard Faust function.
//
// #### Usage
//
// ```
// time : _
// ```
//------------------------
time = (+(1)~_ ) - 1; 


//-------`tempo`----------
// Converts a tempo in BPM into a number of samples.
//
// #### Usage
//
// ```
// tempo(t) : _
// ```
//
// Where:
//
// * `t`: tempo in BPM
//------------------------
tempo(t) = (60*ma.SR)/t;


//-------`period`----------
// Basic sawtooth wave of period `p`.
//
// #### Usage
//
// ```
// period(p) : _
// ```
//
// Where:
//
// * `p`: period as a number of samples
//------------------------
// NOTE: may be this should go in oscillator.lib
period(p) = %(int(p))~+(1);


//-------`pulse`----------
// Pulses (10000) generated at period `p`.
//
// #### Usage
//
// ```
// pulse(p) : _
// ```
//
// Where:
//
// * `p`: period as a number of samples
//------------------------
// NOTE: may be this should go in oscillator.lib 
pulse(p) = period(p)==0;


//-------`pulsen`----------
// Pulses (11110000) of length `n` generated at period `p`.
//
// #### Usage
//
// ```
// pulsen(n,p) : _
// ```
//
// Where:
//
// * `n`: the length of the pulse as a number of samples
// * `p`: period as a number of samples
//------------------------
// NOTE: may be this should go in oscillator.lib
pulsen(n,p) = period(p)<n;


//-------`beat`----------
// Pulses at tempo `t`.
// `beat` is a standard Faust function.
//
// #### Usage
//
// ```
// beat(t) : _
// ```
//
// Where:
//
// * `t`: tempo in BPM
//------------------------
beat(t) = pulse(tempo(t));


//----------------------------`pulse_countup`-----------------------------------
// Starts counting up pulses. While trig is 1 the output is
// counting up, while trig is 0 the counter is reset to 0.
//
// #### Usage
//
// ```
// _ : pulse_countup(trig) : _
// ```
//
// Where:
//
// * `trig`: the trigger signal (1: start at next pulse; 0: reset to 0)
//------------------------------------------------------------------------------
//TODO: author "Vince"
pulse_countup(t) =  + ~ _ * t ;


//----------------------------`pulse_countdown`---------------------------------
// Starts counting down pulses. While trig is 1 the output is
// counting down, while trig is 0 the counter is reset to 0.
//
// #### Usage
//
// ```
// _ : pulse_countdown(trig) : _
// ```
//
// Where:
//
// * `trig`: the trigger signal (1: start at next pulse; 0: reset to 0)
//------------------------------------------------------------------------------
//TODO: author "Vince"
pulse_countdown(t) =  - ~ _ * t ;


//----------------------------`pulse_countup_loop`------------------------------
// Starts counting up pulses from 0 to n included. While trig is 1 the output is
// counting up, while trig is 0 the counter is reset to 0. At the end
// of the countup (n) the output value will be reset to 0.
//
// #### Usage
//
// ```
// _ : pulse_countup_loop(n,trig) : _
// ```
//
// Where:
//
// * `n`: the highest number of the countup (included) before reset to 0.
// * `trig`: the trigger signal (1: start at next pulse; 0: reset to 0)
//------------------------------------------------------------------------------
//TODO: author "Vince"
pulse_countup_loop(n, t) =  + ~ cond(n)*t
  with {
    cond(n) =  _ <: _ * (_ <= n) ;
  };


//----------------------------`pulse_countdown_loop`----------------------------
// Starts counting down pulses from 0 to n included. While trig is 1 the output
// is counting down, while trig is 0 the counter is reset to 0. At the end
// of the countdown (n) the output value will be reset to 0.
//
// #### Usage
//
// ```
// _ : pulse_coundown_loop(n,trig) : _
// ```
//
// Where:
//
// * `n`: the highest number of the countup (included) before reset to 0.
// * `trig`: the trigger signal (1: start at next pulse; 0: reset to 0)
//------------------------------------------------------------------------------
//TODO: author "Vince:
pulse_countdown_loop(n, t) =  - ~ cond(n)*t
  with {
    cond(n) =  _ <: _ * (_ >= n) ;
  };



//===============================Array Processing/Pattern Matching========================
//========================================================================================

//---------------------------------`count`---------------------------------
// Count the number of elements of list l.
// `count` is a standard Faust function.
//
// #### Usage
//
// ```
// count(l)
// count ((10,20,30,40)) -> 4
// ```
//
// Where:
//
// * `l`: list of elements
//-----------------------------------------------------------------------------
count ((xs, xxs)) = 1 + count(xxs);
count (xx) = 1;


//-------------------------------`take`-----------------------------------
// Take an element from a list.
// `take` is a standard Faust function.
//
// #### Usage
// 
// ```
// take(e,l)
// take(3,(10,20,30,40)) -> 30
// ```
//
// Where:
//
// * `p`: position (starting at 1)
// * `l`: list of elements
//-----------------------------------------------------------------------------
take (1, (xs, xxs)) 	= xs;
take (1, xs) 			= xs;
take (nn, (xs, xxs)) 	= take (nn-1, xxs);


//----------------------------`subseq`--------------------------------
// Extract a part of a list.
//
// #### Usage
//
// ```
// subseq(l, p, n)
// subseq((10,20,30,40,50,60), 1, 3) -> (20,30,40)
// subseq((10,20,30,40,50,60), 4, 1) -> 50
// ```
//
// Where:
//
// * `l`: list
// * `p`: start point (0: begin of list)
// * `n`: number of elements
//
// #### Note:
//
// Faust doesn't have proper lists. Lists are simulated with parallel
// compositions and there is no empty list
//-----------------------------------------------------------------------------
subseq((head, tail), 0, 1)      = head;
subseq((head, tail), 0, n)      = head, subseq(tail, 0, n-1);
subseq((head, tail), p, n)      = subseq(tail, p-1, n);
subseq(head, 0, n)              = head;


//============================Selectors (Conditions)======================================
//========================================================================================

//-----------------------------`if`-----------------------------------
// if-then-else implemented with a select2.
//
// #### Usage
//
// *   `if(c, t, e) : _`
//
// Where:
//
// * `c`: condition
// * `t`: signal selected while c is true
// * `e`: signal selected while c is false
//-----------------------------------------------------------------------------
if(cond,thn,els) = select2(cond,els,thn);
// TODO: perhaps it would make more sense to have an if(a,b) and an ifelse(a,b,c)?

//-----------------------------`selector`---------------------------------
// Selects the ith input among n at compile time.
//
// #### Usage
//
// ```
// selector(i,n)
// _,_,_,_ : selector(2,4) : _  // selects the 3rd input among 4
// ```
//
// Where:
//
// * `i`: input to select (`int`, numbered from 0, known at compile time)
// * `n`: number of inputs (`int`, known at compile time, `n > i`)
//
//-----------------------------------------------------------------------------
selector(i,n) = par(j, n, S(i, j))    with { S(i,i) = _; S(i,j) = !; };


//-----------------------------`selectn`---------------------------------
// Selects the ith input among N at run time.
//
// #### Usage
//
// ```
// selectn(N,i)
// _,_,_,_ : selectn(4,2) : _  // selects the 3rd input among 4
// ```
//
// Where:
//
// * `N`: number of inputs (int, known at compile time, N > 0)
// * `i`: input to select (int, numbered from 0)
//
// #### Example test program
//
// ```
// N=64; 
// process = par(n,N, (par(i,N,i) : selectn(N,n)));
// ```
//-----------------------------------------------------------------------------
selectn(N,i) = S(N,0)
    with {
       S(1,offset) = _;
       S(n,offset) = S(left, offset), S(right, offset+left) : select2(i >= offset+left)
            with {
                right = int(n/2);
                left  = n-right;
            };
    };


//--------------------`select2stereo`--------------------
// Select between 2 stereo signals.
//
// #### Usage
//
// ```
// _,_,_,_ : select2stereo(bpc) : _,_,_,_
// ```
//
// Where:
// 
// * `bpc`: the selector switch (0/1)
//------------------------------------------------------------
// TODO: author JOS, revised by RM    
select2stereo(bpc) = ro.cross2 : select2(bpc), select2(bpc) : _,_;


//=====================================Other==============================================
//========================================================================================

//----------------------------`latch`--------------------------------
// Latch input on positive-going transition of "clock" ("sample-and-hold").
//
// #### Usage
//
// ```
// _ : latch(clocksig) : _
// ```
// 
// Where:
//
// * `clocksig`: hold trigger (0 for hold, 1 for bypass)
//------------------------------------------------------------
// TODO: author JOS, revised by RM
// TODO: not sure how this function works: doesn't seem to work the way
// it described which is why sAndH was implemented below.
latch(c,x) = x * s : + ~ *(1-s) with { s = ((c'<=0)&(c>0)); };


//--------------------------`sAndH`-------------------------------
// Sample And Hold.
// `sAndH` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : sAndH(t) : _
// ``` 
//
// Where:
//
// * `t`: hold trigger (0 for hold, 1 for bypass)
//----------------------------------------------------------------
// TODO: author RM
sAndH(t) = *(t) : +~*(1-t);


//------------------`peakhold`---------------------------
// Outputs current max value above zero. 
//
// #### Usage
//
// ```
// _ : peakhold(mode) : _;
// ```
//
// Where:
//
// `mode` means: 0 - Pass through. A single sample 0 trigger will work as a reset.
//    1 - Track and hold max value.
//----------------------------------------------------------------
// TODO: author Jonatan Liljedahl, revised by RM
peakhold = (*,_:max) ~ _;


//------------------`peakholder`---------------------------
// Tracks abs peak and holds peak for 'holdtime' samples.
//
// #### Usage 
//
// ```
// _ : peakholder(holdtime) : _;
// ```
//----------------------------------------------------------------
// TODO: author Jonatan Liljedahl
peakholder(holdtime) = peakhold2 ~ reset : (!,_) with {
    reset = ba.sweep(holdtime) > 0;
    // first out is gate that is 1 while holding last peak
    peakhold2 = _,abs <: peakhold,!,_ <: >=,_,!;
};


//--------------------------`impulsify`---------------------------
// Turns the signal from a button into an impulse (1,0,0,... when
// button turns on).
// `impulsify` is a standard Faust function.
//
// #### Usage
//
// ```
// button("gate") : impulsify ;
// ```
//----------------------------------------------------------------
impulsify = _ <: _,mem : - : >(0);


//-----------------------`automat`------------------------------
// Record and replay to the values the input signal in a loop.
//
// #### Usage
// 
// ```
// hslider(...) : automat(bps, size, init) : _
// ```
//-----------------------------------------------------------------------
automat(bps, size, init, input) = rwtable(size+1, init, windex, input, rindex)
with {
	clock 	= beat(bps);
	rindex 	= int(clock) : (+ : %(size)) ~ _;		// each clock read the next entry of the table
	windex 	= if (timeToRenew, rindex, size);		// we ignore input unless it is time to renew
	timeToRenew 	= int(clock) & (inputHasMoved | (input <= init));	
	inputHasMoved 	= abs(input-input') : countfrom(int(clock)') : >(0);
	countfrom(reset) = (+ : if(reset, 0, _)) ~ _;
};


//-----------------`bpf`-------------------
// bpf is an environment (a group of related definitions) that can be used to 
// create break-point functions. It contains three functions : 
//
// * `start(x,y)` to start a break-point function
// * `end(x,y)` to end a break-point function
// * `point(x,y)` to add intermediate points to a break-point function
//
// A minimal break-point function must contain at least a start and an end point :
//
// ```
// f = bpf.start(x0,y0) : bpf.end(x1,y1);
// ```
//
// A more involved break-point function can contains any number of intermediate 
// points:
//
// ```
// f = bpf.start(x0,y0) : bpf.point(x1,y1) : bpf.point(x2,y2) : bpf.end(x3,y3);
// ```
//
// In any case the `x_{i}` must be in increasing order (for all `i`, `x_{i} < x_{i+1}`).
// For example the following definition :
//
// ```
// f = bpf.start(x0,y0) : ... : bpf.point(xi,yi) : ... : bpf.end(xn,yn);
// ```
//
// implements a break-point function f such that :
//
// * `f(x) = y_{0}` when `x < x_{0}`
// * `f(x) = y_{n}` when `x > x_{n}`
// * `f(x) = y_{i} + (y_{i+1}-y_{i})*(x-x_{i})/(x_{i+1}-x_{i})` when `x_{i} <= x` 
// and `x < x_{i+1}`
//
// `bpf` is a standard Faust function.
//--------------------------------------------------------
bpf = environment 
{
  // Start a break-point function
  start(x0,y0) = \(x).(x0,y0,x,y0);
  // Add a break-point
  point(x1,y1) = \(x0,y0,x,y).(x1, y1, x , if (x < x0, y, if (x < x1, y0 + (x-x0)*(y1-y0)/(x1-x0), y1)));
  // End a break-point function
  end  (x1,y1) = \(x0,y0,x,y).(if (x < x0, y, if (x < x1, y0 + (x-x0)*(y1-y0)/(x1-x0), y1)));
};


//-------------------`bypass1`-------------------------
// Takes a mono input signal, route it to `e` and bypass it if `bpc = 1`.
// `bypass1` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : bypass1(bpc,e) : _
// ```
//
// Where:
//
// * `bpc`: bypass switch (0/1)
// * `e`: a mono effect
//------------------------------------------------------------
// TODO: author JOS, revised by RM
bypass1(bpc,e) = _ <: select2(bpc,(inswitch:e),_)
                 with {inswitch = select2(bpc,_,0);};

//-------------------`bypass2`-------------------------
// Takes a stereo input signal, route it to `e` and bypass it if `bpc = 1`.
// `bypass2` is a standard Faust function.
//
// #### Usage
//
// ```
// _,_ : bypass2(bpc,e) : _,_
// ```
//
// Where:
//
// * `bpc`: bypass switch (0/1)
// * `e`: a stereo effect
//------------------------------------------------------------
// TODO: author JOS, revised by RM 
bypass2(bpc,e) = _,_ <: ((inswitch:e),_,_) : select2stereo(bpc) with {
  inswitch = _,_ : (select2(bpc,_,0), select2(bpc,_,0)) : _,_;
};


//----------------------------`toggle`------------------------------------------
// Triggered by the change of 0 to 1, it toggles the output value
// between 0 and 1.
//
// #### Usage
//
// ```
// _ : toggle : _
// ```
// #### Examples
//
// ```
// button("toggle") : toggle : vbargraph("output", 0, 1)
// (an.amp_follower(0.1) > 0.01) : toggle : vbargraph("output", 0, 1) // takes audio input
// ```
//
//------------------------------------------------------------------------------
// TODO: author "Vince"
toggle = trig : loop
  with {
    trig(x) = (x-x') == 1;
    loop = (_ != _) ~ _ ;
  } ;


//----------------------------`on_and_off`------------------------------------------
// The first channel set the output to 1, the second channel to 0.
//
// #### Usage
//
// ```
// _ , _ : on_and_off : _
// ```
//
// #### Example
//
// ```
// button("on"), button("off") : on_and_off : vbargraph("output", 0, 1)
// ```
//
//------------------------------------------------------------------------------
// TODO: author "Vince"
on_and_off(a, b) = (a : trig) : loop(b)
with {
  trig(x) = (x-x') == 1;
  loop(b) = + ~ (_ >= 1) * ((b : trig) == 0) ;
};


//-----------------------------`selectoutn`---------------------------------
// Route input to the output among N at run time.
//
// #### Usage
//
// ```
// _ : selectoutn(n, s) : _,_,...n
// ```
//
// Where:
//
// * `n`: number of outputs (int, known at compile time, N > 0)
// * `s`: output number to route to (int, numbered from 0) (i.e. slider)
//
// #### Example
//
// ```
// process = 1 : selectoutn(3, sel) : par(i,3,bar) ;
// sel = hslider("volume",0,0,2,1) : int;
// bar = vbargraph("v.bargraph", 0, 1);
// ```
//--------------------------------------------------------------------------
// TODO: author "Vince"
selectoutn(n, s) = _ <: par(i,n, _* (s==i) ) ;

//////////////////////////////////Deprecated Functions////////////////////////////////////
// This section implements functions that used to be in music.lib but that are now
// considered as "deprecated".
//////////////////////////////////////////////////////////////////////////////////////////

millisec	= ma.SR/1000.0;

time1s 	= hslider("time", 0, 0,  1000, 0.1)*millisec;
time2s 	= hslider("time", 0, 0,  2000, 0.1)*millisec;
time5s 	= hslider("time", 0, 0,  5000, 0.1)*millisec;
time10s = hslider("time", 0, 0, 10000, 0.1)*millisec;
time21s = hslider("time", 0, 0, 21000, 0.1)*millisec;
time43s = hslider("time", 0, 0, 43000, 0.1)*millisec;