misceffects.lib

//################################## misceffects.lib ##########################################
// This library contains a collection of audio effects. Its official prefix is `ef`.
//########################################################################################

/************************************************************************
************************************************************************
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("maths.lib");
ba = library("basics.lib");
de = library("delays.lib");
si = library("signals.lib");
an = library("analyzers.lib");
fi = library("filters.lib");
ef = library("misceffects.lib"); // for compatible copy/paste out of this file

declare name "Misc Effects Library";
declare version "2.0"; // TODO to check

//########################################################################################
/************************************************************************
FAUST library file, jos section

Except where noted otherwise, The Faust functions below in this
section are Copyright (C) 2003-2019 by Julius O. Smith III <jos@ccrma.stanford.edu>
([jos](http://ccrma.stanford.edu/~jos/)), and released under the
(MIT-style) [STK-4.3](#stk-4.3-license) license.

MarkDown comments in this section are Copyright 2016-2019 by Romain
Michon and Julius O. Smith III, and are released under the
[CCA4I](https://creativecommons.org/licenses/by/4.0/) license (TODO: if/when Romain agrees!)

************************************************************************/

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

//---------------------`(ef.)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>
//------------------------------------------------------------
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;


//-----------------`(ef.)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)>
//------------------------------------------------------------
gate_mono(thresh,att,hold,rel,x) = x * gate_gain_mono(thresh,att,hold,rel,x);


//-----------------`(ef.)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)>
//------------------------------------------------------------
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==========================================
//========================================================================================

//-------------------------`(ef.)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: perhaps this should be moved to physmodels.lib
// [JOS: I don't think so because it's merely a bandpass filter tuned to speaker bandwidth]
speakerbp(f1,f2) = fi.dcblockerat(f1) : fi.dcblockerat(f1) : fi.lowpass(4,f2);


//------------`(ef.)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://lib.tkk.fi/Diss/2007/isbn9789512290666/article2.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: perhaps this should be moved to physmodels.lib?
// [JOS: I vote yes when there is a piano model in physmodels.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);
};

//-------------------------`(ef.)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
//------------------------------------------------------------
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;
};

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


// TODO: the following should be in physmodels.lib when it will be operational
// [JOS: I think a new "Meshes" section would fit well after Modal Percussions.]
//----------------------------------`(ef.)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.
//------------------------------------------------------------
// 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);
};

//--------------------`(ef.)reverseEchoN(nChans,delay)`-------------------
// Reverse echo effect
//
// #### Usage
//
// ```
// _ : ef.reverseEchoN(N,delay) : si.bus(N)
// ```
//
// Where:
//
// *     `N`: Number of output channels desired (1 or more)
// * `delay`: echo delay (integer power of 2)
//
// #### Demo
//
// ```
// _ : dm.reverseEchoN(N) : _,_
// ```
//
// #### Description
//
// The effect uses N instances of reverseDelayRamped at different phases.
//
//------------------------------------------------------------
reverseEchoN(N,delMax) = _<: par(i,N,ef.reverseDelayRamped(delMax,i/N));

//-------------------`(ef.)reverseDelayRamped(delay,phase)`------------------
// Reverse delay with amplitude ramp
//
// #### Usage
//
// ```
// _ : ef.reverseDelayRamped(delay,phase) : _
// ```
//
// Where:
//
// * `delay`: echo delay (integer power of 2)
// * `phase`: float between 0 and 1 giving ramp delay phase*delay
//
// #### Demo
//
// ```
// _ : dm.reverseEchoN(N) : _,_
// ```
//
//------------------------------------------------------------
reverseDelayRamped(delMax,phs) = rampGain * de.delay(delMax,del) with {
  rampGain = 4 * (del/delMax) * (1 - del/delMax); // suppress click when delay-line wraps around
  delOffset = int(floor(0.5 + delMax * max(0,min(0.999999,phs)))); // starting point in delay line
  startPulse = (1-1') * delOffset;
  del = int(startPulse : +  ~ +(2)) & (delMax-1);
};

//-------------------`(ef.)uniformPanToStereo(nChans)`------------------
// Pan nChans channels to the stereo field, spread uniformly left to right
//
// #### Usage
//
// ```
// si.bus(N) : ef.uniformPanToStereo(N) : _,_
// ```
//
// Where:
//
// * `N`: Number of input channels to pan down to stereo
//
// #### Demo
//
// ```
// _ : dm.reverseEchoN(N) : _,_
// ```
//
//------------------------------------------------------------
uniformPanToStereo(N) = si.bus(N) <: par(i,2*N,_) :
		      (par(i,N,*(i/(N-1))) :> _),
		      (par(i,N,*(1-i/(N-1))) :> _);

// end jos section
/************************************************************************
************************************************************************
FAUST library file, GRAME section

Except where noted otherwise, Copyright (C) 2003-2017 by GRAME,
Centre National de Creation Musicale.
----------------------------------------------------------------------
GRAME LICENSE

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.
************************************************************************
************************************************************************/

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

//----------`(ef.)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
echo(maxDuration,duration,feedback) = +~de.delay(maxDel,del)*feedback
with{
  maxDel = ma.SR*maxDuration;
  del = ma.SR*duration;
};

// TODO demo function for echo

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

//--------------`(ef.)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)) ~ _;
};

//////////////////////////////////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)));