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

//################################## misceffect.lib ##########################################
// This library contains a collection of audio effects.
//
// It should be used using the `ef` environment:
//
// ```
// ef = library("misceffect.lib");
// process = ef.functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `ef`
// environment:
//
// ```
// import("stdfaust.lib");
// process = ef.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");
ba = library("basic.lib");
de = library("delay.lib");
si = library("signal.lib");
an = library("analyzer.lib");
fi = library("filter.lib");


declare name "Faust Math Library";
declare version "2.0"; // TODO to check

//======================================Dynamic===========================================
//========================================================================================

//---------------------`cubicnl`-----------------------
// Cubic nonlinearity distortion.
// `cubicnl` is a standard Faust library.
//
// #### Usage:
//
// ```
// _ : cubicnl(drive,offset) : _
// _ : cubicnl_nodc(drive,offset) : _
// ```
//
// Where:
//
// * `drive`: distortion amount, between 0 and 1
// * `offset`: constant added before nonlinearity to give even harmonics. Note: offset 
// 	can introduce a nonzero mean - feed cubicnl output to dcblocker to remove this.
//
// #### References:
//
// * <https://ccrma.stanford.edu/~jos/pasp/Cubic_Soft_Clipper.html>
// * <https://ccrma.stanford.edu/~jos/pasp/Nonlinear_Distortion.html>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
cubicnl(drive,offset) = *(pregain) : +(offset) : clip(-1,1) : cubic
with {
    pregain = pow(10.0,2*drive);
    clip(lo,hi) = min(hi) : max(lo);
    cubic(x) = x - x*x*x/3;
    postgain = max(1.0,1.0/pregain);
};

cubicnl_nodc(drive,offset) = cubicnl(drive,offset) : fi.dcblocker;


//-----------------`gate_mono`-------------------
// Mono signal gate.
// `gate_mono` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : gate_mono(thresh,att,hold,rel) : _
// ```
//
// Where:
//
// * `thresh`: dB level threshold above which gate opens (e.g., -60 dB)
// * `att`: attack time = time constant (sec) for gate to open (e.g., 0.0001 s = 0.1 ms)
// * `hold`: hold time = time (sec) gate stays open after signal level < thresh (e.g., 0.1 s)
// * `rel`: release time = time constant (sec) for gate to close (e.g., 0.020 s = 20 ms)
//
// #### References
//
// * <http://en.wikipedia.org/wiki/Noise_gate>
// * <http://www.soundonsound.com/sos/apr01/articles/advanced.asp>
// * <http://en.wikipedia.org/wiki/Gating_(sound_engineering)>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
gate_mono(thresh,att,hold,rel,x) = x * gate_gain_mono(thresh,att,hold,rel,x);


//-----------------`gate_stereo`-------------------
// Stereo signal gates.
// `gate_stereo` is a standard Faust function.
//
// #### Usage
//
// ```
//  _,_ : gate_stereo(thresh,att,hold,rel) : _,_
// ```
//
// Where:
//
// * `thresh`: dB level threshold above which gate opens (e.g., -60 dB)
// * `att`: attack time = time constant (sec) for gate to open (e.g., 0.0001 s = 0.1 ms)
// * `hold`: hold time = time (sec) gate stays open after signal level < thresh (e.g., 0.1 s)
// * `rel`: release time = time constant (sec) for gate to close (e.g., 0.020 s = 20 ms)
//
// #### References
//
// * <http://en.wikipedia.org/wiki/Noise_gate>
// * <http://www.soundonsound.com/sos/apr01/articles/advanced.asp>
// * <http://en.wikipedia.org/wiki/Gating_(sound_engineering)>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
gate_stereo(thresh,att,hold,rel,x,y) = ggm*x, ggm*y with {
  ggm = gate_gain_mono(thresh,att,hold,rel,abs(x)+abs(y));
};

gate_gain_mono(thresh,att,hold,rel,x) = x : extendedrawgate : an.amp_follower_ar(att,rel) with {
  extendedrawgate(x) = max(float(rawgatesig(x)),holdsig(x));
  rawgatesig(x) = inlevel(x) > ba.db2linear(thresh);
  minrate = min(att,rel);
  inlevel = an.amp_follower_ar(minrate,minrate);
  holdcounter(x) = (max(holdreset(x) * holdsamps,_) ~-(1));
  holdsig(x) = holdcounter(x) > 0;
  holdreset(x) = rawgatesig(x) < rawgatesig(x)'; // reset hold when raw gate falls
  holdsamps = int(hold*ma.SR);
};


//=====================================Filtering==========================================
//========================================================================================

//-------------------------`speakerbp`-------------------------------
// Dirt-simple speaker simulator (overall bandpass eq with observed
// roll-offs above and below the passband).
//
// Low-frequency speaker model = +12 dB/octave slope breaking to
// flat near f1. Implemented using two dc blockers in series.
//
// High-frequency model = -24 dB/octave slope implemented using a
// fourth-order Butterworth lowpass.
//
// Example based on measured Celestion G12 (12" speaker):
//
// `speakerbp` is a standard Faust function
//
// #### Usage
// 
// ```
// speakerbp(f1,f2)
// _ : speakerbp(130,5000) : _
// ```
//------------------------------------------------------------
// TODO: author JOS, revised by RM
// TODO: perhaps this should be moved to pm.lib
speakerbp(f1,f2) = fi.dcblockerat(f1) : fi.dcblockerat(f1) : fi.lowpass(4,f2);


//------------`piano_dispersion_filter`---------------
// Piano dispersion allpass filter in closed form.
//
// #### Usage
//
// ```
// piano_dispersion_filter(M,B,f0)
// _ : piano_dispersion_filter(1,B,f0) : +(totalDelay),_ : fdelay(maxDelay) : _
// ```
//
// Where:
//
// * `M`: number of first-order allpass sections (compile-time only)
//  	Keep below 20. 8 is typical for medium-sized piano strings.
// * `B`: string inharmonicity coefficient (0.0001 is typical)
// * `f0`: fundamental frequency in Hz
//
// #### Outputs
//
// * MINUS the estimated delay at `f0` of allpass chain in samples,
//     provided in negative form to facilitate subtraction
//     from delay-line length.
// * Output signal from allpass chain

// #### Reference
//
// * "Dispersion Modeling in Waveguide Piano Synthesis Using Tunable 
// Allpass Filters", by Jukka Rauhala and Vesa Valimaki, DAFX-2006, pp. 71-76
// * <http://www.dafx.ca/proceedings/papers/p_071.pdf> (An erratum in Eq. (7) 
// 		is corrected in Dr. Rauhala's encompassing dissertation (and below).)
// * <http://www.acoustics.hut.fi/research/asp/piano/>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
// TODO: perhaps this should be moved to pm.lib?
piano_dispersion_filter(M,B,f0) = -Df0*M,seq(i,M,fi.tf1(a1,1,a1))
with {
 a1 = (1-D)/(1+D); // By Eq. 3, have D >= 0, hence a1 >= 0 also
 D = exp(Cd - Ikey(f0)*kd);
 trt = pow(2.0,1.0/12.0); // 12th root of 2
 logb(b,x) = log(x) / log(b); // log-base-b of x
 Ikey(f0) = logb(trt,f0*trt/27.5);
 Bc = max(B,0.000001);
 kd = exp(k1*log(Bc)*log(Bc) + k2*log(Bc)+k3);
 Cd = exp((m1*log(M)+m2)*log(Bc)+m3*log(M)+m4);
 k1 = -0.00179;
 k2 = -0.0233;
 k3 = -2.93;
 m1 = 0.0126;
 m2 = 0.0606;
 m3 = -0.00825;
 m4 = 1.97;
 wT = 2*ma.PI*f0/ma.SR;
 polydel(a) = atan(sin(wT)/(a+cos(wT)))/wT;
 Df0 = polydel(a1) - polydel(1.0/a1);
};


//-------------------------`stereo_width`---------------------------
// Stereo Width effect using the Blumlein Shuffler technique.
// `stereo_width` is a standard Faust function.
//
// #### Usage
//
// ```
// _,_ : stereo_width(w) : _,_
// ```
//
// Where:
//
// * `w`: stereo width between 0 and 1
//
// At `w=0`, the output signal is mono ((left+right)/2 in both channels).
// At `w=1`, there is no effect (original stereo image).
// Thus, w between 0 and 1 varies stereo width from 0 to "original".
//
// #### Reference
//
// * "Applications of Blumlein Shuffling to Stereo Microphone Techniques"
// Michael A. Gerzon, JAES vol. 42, no. 6, June 1994
//------------------------------------------------------------
// TODO: author JOS, revised by RM
stereo_width(w) = shuffle : *(mgain),*(sgain) : shuffle
with {
     shuffle =  _,_ <: +,-; // normally scaled by 1/sqrt(2) for orthonormality,
     mgain = 1-w/2;  // but we pick up the needed normalization here.
     sgain = w/2;
};


//========================================Time Based======================================
//========================================================================================

//----------`echo`----------
// A simple echo effect.
//
// `echo` is a standard Faust function
//
// #### Usage
//
// ```
// _ : echo(maxDuration,duration,feedback) : _
// ```
//
// Where:
//
// * `maxDuration`: the max echo duration in seconds
// * `duration`: the echo duration in seconds
// * `feedback`: the feedback coefficient
//----------------------------------------------------
// TODO: author RM
// TODO: needs to be checked
echo(maxDuration,duration,feedback) = +~(de.fdelay1(N,n)*feedback)
with{
	N = maxDuration : ba.sec2samp : ma.np2; // compute the next power of 2 of maxDuration
	n = duration : ba.sec2samp;
};

// TODO demo function for echo

//=======================================Pitch Shifting===================================
//========================================================================================

//--------------`transpose`----------------
// A simple pitch shifter based on 2 delay lines.
// `transpose` is a standard Faust function.
// 
// #### Usage
//
// ```
// _ : transpose(w, x, s) : _
// ```
//
// Where:
//
// * `w`: the window length (samples)
// * `x`: crossfade duration duration (samples)
// * `s`: shift (semitones)
//-----------------------------------------
transpose(w, x, s, sig) = de.fdelay(maxDelay,d,sig)*ma.fmin(d/x,1) + 
	de.fdelay(maxDelay,d+w,sig)*(1-ma.fmin(d/x,1))
with {
	maxDelay = 65536;
	i = 1 - pow(2, s/12);
	d = i : (+ : +(w) : fmod(_,w)) ~ _;
};


//===========================================Meshes=======================================
//========================================================================================


// TODO: the following should be in pm.lib when it will be operational
//----------------------------------`mesh_square`------------------------------
// Square Rectangular Digital Waveguide Mesh.
//
// #### Usage
//
// ```
// bus(4*N) : mesh_square(N) : bus(4*N);
// ```
//
// Where:
//
// * `N`: number of nodes along each edge - a power of two (1,2,4,8,...)
//
// #### Reference
//
// <https://ccrma.stanford.edu/~jos/pasp/Digital_Waveguide_Mesh.html>
//
// #### Signal Order In and Out
//
// The mesh is constructed recursively using 2x2 embeddings.  Thus,
// the top level of `mesh_square(M)` is a block 2x2 mesh, where each
// block is a `mesh(M/2)`.  Let these blocks be numbered 1,2,3,4 in the
// geometry NW,NE,SW,SE, i.e., as
//         1 2
//         3 4
// Each block has four vector inputs and four vector outputs, where the
// length of each vector is `M/2`.  Label the input vectors as Ni,Ei,Wi,Si,
// i.e., as the inputs from the North, East South, and West,
// and similarly for the outputs.  Then, for example, the upper
// left input block of M/2 signals is labeled 1Ni.  Most of the
// connections are internal, such as 1Eo -> 2Wi.  The `8*(M/2)` input
// signals are grouped in the order
//        1Ni 2Ni
//        3Si 4Si
//        1Wi 3Wi
//        2Ei 4Ei
// and the output signals are
//        1No 1Wo
//        2No 2Eo
//        3So 3Wo
//        4So 4Eo
// or
//
// In: 1No 1Wo 2No 2Eo 3So 3Wo 4So 4Eo
//
// Out: 1Ni 2Ni 3Si 4Si 1Wi 3Wi 2Ei 4Ei
//
// Thus, the inputs are grouped by direction N,S,W,E, while the
// outputs are grouped by block number 1,2,3,4, which can also be
// interpreted as directions NW, NE, SW, SE.  A simple program
// illustrating these orderings is `process = mesh_square(2);`.
//
// #### Example
//
// Reflectively terminated mesh impulsed at one corner:
//
// ```
// mesh_square_test(N,x) = mesh_square(N)~(busi(4*N,x)) // input to corner
// with { busi(N,x) = bus(N) : par(i,N,*(-1)) : par(i,N-1,_), +(x); };
// process = 1-1' : mesh_square_test(4); // all modes excited forever
// ```
//
// In this simple example, the mesh edges are connected as follows:
//
// 1No -> 1Ni, 1Wo -> 2Ni, 2No -> 3Si, 2Eo -> 4Si,
//
// 3So -> 1Wi, 3Wo -> 3Wi, 4So -> 2Ei, 4Eo -> 4Ei
//
// A routing matrix can be used to obtain other connection geometries.
//------------------------------------------------------------
// TODO: author JOS, revised by RM
// four-port scattering junction:
mesh_square(1) =
          si.bus(4) <: par(i,4,*(-1)), (si.bus(4) :> (*(.5)) <: si.bus(4)) :> si.bus(4);

// rectangular NxN square waveguide mesh:
mesh_square(N) = si.bus(4*N) : (route_inputs(N/2) : par(i,4,mesh_square(N/2)))
          ~(prune_feedback(N/2))
          : prune_outputs(N/2) : route_outputs(N/2) : si.bus(4*N)
with {
  // select block i of N, block size = M:
  s(i,N,M) = par(j, M*N, Sv(i, j))
     with { Sv(i,i) = si.bus(N); Sv(i,j) = si.block(N); };

  // prune mesh outputs down to the signals which make it out:
  prune_outputs(N)
    = si.bus(16*N) :
      si.block(N), si.bus(N),   si.block(N), si.bus(N),
      si.block(N), si.bus(N),   si.bus(N),   si.block(N),
      si.bus(N),   si.block(N), si.block(N), si.bus(N),
      si.bus(N),   si.block(N), si.bus(N),   si.block(N)
      : si.bus(8*N);

  // collect mesh outputs into standard order (N,W,E,S):
  route_outputs(N)
    = si.bus(8*N)
      <: s(4,N,8),s(5,N,8), s(0,N,8),s(2,N,8),
         s(3,N,8),s(7,N,8), s(1,N,8),s(6,N,8)
      : si.bus(8*N);

  // collect signals used as feedback:
  prune_feedback(N) = si.bus(16*N) :
      si.bus(N),   si.block(N), si.bus(N),   si.block(N),
      si.bus(N),   si.block(N), si.block(N), si.bus(N),
      si.block(N), si.bus(N),   si.bus(N),   si.block(N),
      si.block(N), si.bus(N),   si.block(N), si.bus(N) :
      si.bus(8*N);

  // route mesh inputs (feedback, external inputs):
  route_inputs(N) = si.bus(8*N), si.bus(8*N)
  <:s(8,N,16),s(4,N,16), s(12,N,16),s(3,N,16),
    s(9,N,16),s(6,N,16), s(1,N,16),s(14,N,16),
    s(0,N,16),s(10,N,16), s(13,N,16),s(7,N,16),
    s(2,N,16),s(11,N,16), s(5,N,16),s(15,N,16)
    : si.bus(16*N);
};


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

echo1s  = vgroup("echo  1000", +~(de.delay(65536,   int(hslider("millisecond", 0, 0,	1000, 0.10)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));
echo2s  = vgroup("echo  2000", +~(de.delay(131072,  int(hslider("millisecond", 0, 0,	2000, 0.25)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));
echo5s  = vgroup("echo  5000", +~(de.delay(262144,  int(hslider("millisecond", 0, 0,	5000, 0.50)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));
echo10s = vgroup("echo 10000", +~(de.delay(524288,  int(hslider("millisecond", 0, 0,  10000, 1.00)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));
echo21s = vgroup("echo 21000", +~(de.delay(1048576, int(hslider("millisecond", 0, 0,  21000, 1.00)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));
echo43s = vgroup("echo 43000", +~(de.delay(2097152, int(hslider("millisecond", 0, 0,  43000, 1.00)*ba.millisec)-1) * (hslider("feedback", 0, 0,  100, 0.1)/100.0)));