//#################################### vaeffects.lib ########################################
// A library of virtual analog filter effects. Its official prefix is `ve`.
//########################################################################################

ma = library("maths.lib");
si = library("signals.lib");
an = library("analyzers.lib");
fi = library("filters.lib");

declare name "Faust Virtual Analog Filter Effect Library";
declare version "0.0";

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

Except where noted otherwise, The Faust functions below in this
section are Copyright (C) 2003-2017 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.

All MarkDown comments in this section are Copyright 2016-2017 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!)

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

//=============================Functions Reference========================================
//========================================================================================

//-------------------------`(ve.)moog_vcf`---------------------------
// Moog "Voltage Controlled Filter" (VCF) in "analog" form. Moog VCF
// implemented using the same logical block diagram as the classic
// analog circuit.  As such, it neglects the one-sample delay associated
// with the feedback path around the four one-poles.
// This extra delay alters the response, especially at high frequencies
// (see reference [1] for details).
// See `moog_vcf_2b` below for a more accurate implementation.
//
// #### Usage
//
// ```
// moog_vcf(res,fr)
// ```
// Where:
//
// * `res`: normalized amount of corner-resonance between 0 and 1 
// (0 is no resonance, 1 is maximum)
// * `fr`: corner-resonance frequency in Hz (less than SR/6.3 or so)
//
// #### References
// * <https://ccrma.stanford.edu/~stilti/papers/moogvcf.pdf>
// * <https://ccrma.stanford.edu/~jos/pasp/vegf.html>
//------------------------------------------------------------
moog_vcf(res,fr) = (+ : seq(i,4,fi.pole(p)) : *(unitygain(p))) ~ *(mk)
with {
     p = 1.0 - fr * 2.0 * ma.PI / ma.SR; // good approximation for fr << SR
     unitygain(p) = pow(1.0-p,4.0); // one-pole unity-gain scaling
     mk = -4.0*max(0,min(res,0.999999)); // need mk > -4 for stability
};

//-----------------------`(ve.)moog_vcf_2b[n]`---------------------------
// Moog "Voltage Controlled Filter" (VCF) as two biquads. Implementation
// of the ideal Moog VCF transfer function factored into second-order
// sections. As a result, it is more accurate than `moog_vcf` above, but
// its coefficient formulas are more complex when one or both parameters
// are varied.  Here, res is the fourth root of that in `moog_vcf`, so, as
// the sampling rate approaches infinity, `moog_vcf(res,fr)` becomes equivalent
// to `moog_vcf_2b[n](res^4,fr)` (when res and fr are constant).
// `moog_vcf_2b` uses two direct-form biquads (`tf2`).
// `moog_vcf_2bn` uses two protected normalized-ladder biquads (`tf2np`).
//
// #### Usage
//
// ```
// moog_vcf_2b(res,fr)
// moog_vcf_2bn(res,fr)
// ```
//
// Where:
//
// * `res`: normalized amount of corner-resonance between 0 and 1
// 	(0 is min resonance, 1 is maximum)
// * `fr`: corner-resonance frequency in Hz
//------------------------------------------------------------
moog_vcf_2b(res,fr) = fi.tf2s(0,0,b0,a11,a01,w1) : fi.tf2s(0,0,b0,a12,a02,w1)
with {
 s = 1; // minus the open-loop location of all four poles
 frl = max(20,min(10000,fr)); // limit fr to reasonable 20-10k Hz range
 w1 = 2*ma.PI*frl; // frequency-scaling parameter for bilinear xform
 // Equivalent: w1 = 1; s = 2*PI*frl;
 kmax = sqrt(2)*0.99999; // 0.99999 gives stability margin (tf2 is unprotected)
 k = min(kmax,sqrt(2)*res); // fourth root of Moog VCF feedback gain
 b0 = s^2;
 s2k = sqrt(2) * k;
 a11 = s * (2 + s2k);
 a12 = s * (2 - s2k);
 a01 = b0 * (1 + s2k + k^2);
 a02 = b0 * (1 - s2k + k^2);
};

moog_vcf_2bn(res,fr) = fi.tf2snp(0,0,b0,a11,a01,w1) : fi.tf2snp(0,0,b0,a12,a02,w1)
with {
 s = 1; // minus the open-loop location of all four poles
 w1 = 2*ma.PI*max(fr,20); // frequency-scaling parameter for bilinear xform
 k = sqrt(2)*0.99999*res; // fourth root of Moog VCF feedback gain
 b0 = s^2;
 s2k = sqrt(2) * k;
 a11 = s * (2 + s2k);
 a12 = s * (2 - s2k);
 a01 = b0 * (1 + s2k + k^2);
 a02 = b0 * (1 - s2k + k^2);
};

//--------------------------`(ve.)wah4`-------------------------------
// Wah effect, 4th order.
// `wah4` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : wah4(fr) : _
// ```
//
// Where:
//
// * `fr`: resonance frequency in Hz
//
// #### Reference
//
// <https://ccrma.stanford.edu/~jos/pasp/vegf.html>
//------------------------------------------------------------
wah4(fr) = 4*moog_vcf((3.2/4),fr:si.smooth(0.999));

//------------------------`(ve.)autowah`-----------------------------
// Auto-wah effect.
// `autowah` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : autowah(level) : _;
// ```
//
// Where:
//
// * `level`: amount of effect desired (0 to 1).
//------------------------------------------------------------
autowah(level,x) = level * crybaby(an.amp_follower(0.1,x),x) + (1.0-level)*x;

//--------------------------`(ve.)crybaby`-----------------------------
// Digitized CryBaby wah pedal.
// `crybaby` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : crybaby(wah) : _
// ```
//
// Where:
//
// * `wah`: "pedal angle" from 0 to 1
//
// #### Reference
//
// <https://ccrma.stanford.edu/~jos/pasp/vegf.html>
//------------------------------------------------------------
crybaby(wah) = *(gs) : fi.tf2(1,-1,0,a1s,a2s)
with {
  Q  = pow(2.0,(2.0*(1.0-wah)+1.0)); // Resonance "quality factor"
  fr = 450.0*pow(2.0,2.3*wah);       // Resonance tuning
  g  = 0.1*pow(4.0,wah);             // gain (optional)

  // Biquad fit using z = exp(s T) ~ 1 + sT for low frequencies:
  frn = fr/ma.SR; // Normalized pole frequency (cycles per sample)
  R = 1 - ma.PI*frn/Q; // pole radius
  theta = 2*ma.PI*frn; // pole angle
  a1 = 0-2.0*R*cos(theta); // biquad coeff
  a2 = R*R;                // biquad coeff

  // dezippering of slider-driven signals:
  s = 0.999; // smoothing parameter (one-pole pole location)
  a1s = a1 : si.smooth(s);
  a2s = a2 : si.smooth(s);
  gs =  g  : si.smooth(s);

  //tf2 = component("filters.lib").tf2;
};

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

//----------------------------`(ve.)vocoder`-------------------------
// A very simple vocoder where the spectrum of the modulation signal
// is analyzed using a filter bank.
// `vocoder` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : vocoder(nBands,att,rel,BWRatio,source,excitation) : _;
// ```
//
// Where:
//
// * `nBands`: Number of vocoder bands
// * `att`: Attack time in seconds
// * `rel`: Release time in seconds
// * `BWRatio`: Coefficient to adjust the bandwidth of each band (0.1 - 2)
// * `source`: Modulation signal
// * `excitation`: Excitation/Carrier signal
//------------------------------------------------------------
// TODO: author RM
oneVocoderBand(band,bandsNumb,bwRatio,bandGain,x) = x : fi.resonbp(bandFreq,bandQ,bandGain) with{
        bandFreq = 25*pow(2,(band+1)*(9/bandsNumb));
        BW = (bandFreq - 25*pow(2,(band)*(9/bandsNumb)))*bwRatio;
        bandQ = bandFreq/BW;
};

vocoder(nBands,att,rel,BWRatio,source,excitation) = source <: par(i,nBands,oneVocoderBand(i,nBands,BWRatio,1) :
	an.amp_follower_ar(att,rel) : _,excitation : oneVocoderBand(i,nBands,BWRatio)) :> _ ;

//########################################################################################
/************************************************************************
FAUST library file, further contributions section

All contributions below should indicate both the contributor and terms
of license.  If no such indication is found, "git blame" will say who
last edited each line, and that person can be emailed to inquire about
license disposition, if their license choice is not already indicated
elsewhere among the libraries.  It is expected that all software will be
released under LGPL, STK-4.3, MIT, BSD, or a similar FOSS license.
************************************************************************/

// end further further contributions section