webaudio.lib

//#################################### webaudio.lib ########################################
//An implementation of the WebAudio API filters (https://www.w3.org/TR/webaudio/). Its official prefix is `wa`.
//
// This library implement WebAudio filters, using their C++ version as a starting point, 
// taken from Mozilla Firefox implementation.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/webaudio.lib>
//########################################################################################

/************************************************************************
************************************************************************
FAUST library file
Copyright (C) 2019-2020 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");
fi = library("filters.lib");

declare name "Faust WebAudio Filters Library";
declare author "GRAME";
declare copyright "GRAME";
declare version "1.1.0";
declare license "LGPL with exception";

//---------------------------------------------------
// biquad coeffs for various filters
// usage : BiquadFilter(f0, dBgain, Q, aDetune).xxx
//---------------------------------------------------

BiquadFilter(f0, dBgain, Q, aDetune) = environment
{
    lowpass2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        g = pow(10.0, -0.05 * Q);
        w0 = ma.PI * cutoff;
        cos_w0 = cos(w0);
        alpha = 0.5 * sin(w0) * g;

        b1 = 1.0 - cos_w0;
        b0 = 0.5 * b1;
        b2 = b0;
        a0 = 1.0 + alpha;
        a1 = -2.0 * cos_w0;
        a2 = 1.0 - alpha;
    };
    
    highpass2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        g = pow(10.0, -0.05 * Q);
        w0 = ma.PI * cutoff;
        cos_w0 = cos(w0);
        alpha = 0.5 * sin(w0) * g;

        b1 = -1.0 - cos_w0;
        b0 = -0.5 * b1;
        b2 = b0;
        a0 = 1.0 + alpha;
        a1 = -2.0 * cos_w0;
        a2 = 1.0 - alpha;
    };

    bandpass2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        // Don't let Q go negative, which causes an unstable filter.
        Qaux = max(0.01, Q);

        w0 = ma.PI * cutoff;
        alpha = sin(w0) / (2 * Qaux);
        k = cos(w0);

        b0 = alpha;
        b1 = 0;
        b2 = -alpha;
        a0 = 1 + alpha;
        a1 = -2 * k;
        a2 = 1 - alpha;
    };

    notch2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        // Don't let Q go negative, which causes an unstable filter.
        Qaux = max(0.01, Q);

        w0 = ma.PI * cutoff;
        alpha = sin(w0) / (2 * Qaux);
        k = cos(w0);

        b0 = 1;
        b1 = -2 * k;
        b2 = 1;
        a0 = 1 + alpha;
        a1 = -2 * k;
        a2 = 1 - alpha;
    };

    allpass2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        // Don't let Q go negative, which causes an unstable filter.
        Qaux = max(0.01, Q);
        
        w0 = ma.PI * cutoff;
        alpha = sin(w0) / (2 * Qaux);
        k = cos(w0);

        b0 = 1 - alpha;
        b1 = -2 * k;
        b2 = 1 + alpha;
        a0 = 1 + alpha;
        a1 = -2 * k;
        a2 = 1 - alpha; 
    };

    peaking2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        // Don't let Q go negative, which causes an unstable filter.
        Qaux = max(0.01, Q);
        
        A = pow(10.0, dBgain / 40);
        w0 = ma.PI * cutoff;
        alpha = sin(w0) / (2 * Qaux);
        k = cos(w0);

        b0 = 1 + alpha * A;
        b1 = -2 * k;
        b2 = 1 - alpha * A;
        a0 = 1 + alpha / A;
        a1 = -2 * k;
        a2 = 1 - alpha / A;
   };
    
    lowshelf2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        A = pow(10.0, dBgain / 40);

        w0 = ma.PI * cutoff;
        S = 1;  // filter slope (1 is max value)
        alpha = 0.5 * sin(w0) * sqrt((A + 1 / A) * (1 / S - 1) + 2);
        k = cos(w0);
        k2 = 2 * sqrt(A) * alpha;
        aPlusOne = A + 1;
        aMinusOne = A - 1;

        b0 = A * (aPlusOne - aMinusOne * k + k2);
        b1 = 2 * A * (aMinusOne - aPlusOne * k);
        b2 = A * (aPlusOne - aMinusOne * k - k2);
        a0 = aPlusOne + aMinusOne * k + k2;
        a1 = -2 * (aMinusOne + aPlusOne * k);
        a2 = aPlusOne + aMinusOne * k - k2;
    };
    
    highshelf2 = setNormCoeffs(b0, b1, b2, a0, a1, a2)
    with {
        A = pow(10.0, dBgain / 40);

        w0 = ma.PI * cutoff;
        S = 1;  // filter slope (1 is max value)
        alpha = 0.5 * sin(w0) * sqrt((A + 1 / A) * (1 / S - 1) + 2);
        k = cos(w0);
        k2 = 2 * sqrt(A) * alpha;
        aPlusOne = A + 1;
        aMinusOne = A - 1;

        b0 = A * (aPlusOne - aMinusOne * k + k2);
        b1 = 2 * A * (aMinusOne - aPlusOne * k);
        b2 = A * (aPlusOne - aMinusOne * k - k2);
        a0 = aPlusOne + aMinusOne * k + k2;
        a1 = -2 * (aMinusOne + aPlusOne * k);
        a2 = aPlusOne + aMinusOne * k - k2;
    };

    // --------------------- implementation ------------------------------

    // Convert rbj coeffs to fi.tf2 coeffs
    setNormCoeffs(b0,b1,b2,a0,a1,a2) = (b0/a0, b1/a0, b2/a0, a1/a0, a2/a0);

    nyquist = ma.SR * 0.5;
    nFreq = (f0 / nyquist) * pow(2, aDetune / 1200);
  
    // Limit cutoff between 0.01 and 0.99.
    cutoff = max(0.01, min(nFreq, 0.99));

};

//-------------------------------------------------------------------------
// Implementation of filters using BiquadFilter and fi.tf2
//-------------------------------------------------------------------------

//--------------`(wa.)lowpass2`--------------
// Standard second-order resonant lowpass filter with 12dB/octave rolloff.
// Frequencies below the cutoff pass through, frequencies above it are attenuated.
//
// #### Usage
//
// ```
// _ : lowpass2(f0, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#98>
//--------------------------------------

lowpass2(f0, Q, dtune, x) = BiquadFilter(f0, 1, Q, dtune).lowpass2, x : fi.tf2;


//--------------`(wa.)highpass2`--------------
// Standard second-order resonant highpass filter with 12dB/octave rolloff.
// Frequencies below the cutoff are attenuated, frequencies above it pass through.
//
// #### Usage
//
// ```
// _ : highpass2(f0, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#127>
//--------------------------------------

highpass2(f0, Q, dtune, x) = BiquadFilter(f0, 1, Q, dtune).highpass2, x : fi.tf2;


//--------------`(wa.)bandpass2`--------------
// Standard second-order bandpass filter.
// Frequencies outside the given range of frequencies are attenuated, the frequencies inside it pass through.
//
// #### Usage
//
// ```
// _ : bandpass2(f0, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#334>
//--------------------------------------

bandpass2(f0, Q, dtune, x) = BiquadFilter(f0, 1, Q, dtune).bandpass2, x : fi.tf2;


//--------------`(wa.)notch2`--------------
// Standard notch filter, also called a band-stop or band-rejection filter.
// It is the opposite of a bandpass filter: frequencies outside the give range of frequencies 
// pass through, frequencies inside it are attenuated.
//
// #### Usage
//
// ```
// _ : notch2(f0, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#301>
//--------------------------------------

notch2(f0, Q, dtune, x) = BiquadFilter(f0, 1, Q, dtune).notch2, x : fi.tf2;


//--------------`(wa.)allpass2`--------------
// Standard second-order allpass filter. It lets all frequencies through,
// but changes the phase-relationship between the various frequencies.
//
// #### Usage
//
// ```
// _ : allpass2(f0, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#268>
//--------------------------------------

allpass2(f0, Q, dtune, x) = BiquadFilter(f0, 1, Q, dtune).allpass2, x : fi.tf2;


//--------------`(wa.)peaking2`--------------
// Frequencies inside the range get a boost or an attenuation, frequencies outside it are unchanged.
//
// #### Usage
//
// ```
// _ : peaking2(f0, gain, Q, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `gain`: the gain in dB
// * `Q`: the quality factor
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#233>
//--------------------------------------

peaking2(f0, gain, Q, dtune, x) = BiquadFilter(f0, gain, Q, dtune).peaking2, x : fi.tf2;


//--------------`(wa.)lowshelf2`--------------
// Standard second-order lowshelf filter.
// Frequencies lower than the frequency get a boost, or an attenuation, frequencies over it are unchanged.
//
// ```
// _ : lowshelf2(f0, gain, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `gain`: the gain in dB
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#169>
//--------------------------------------

lowshelf2(f0, gain, dtune, x) = BiquadFilter(f0, gain, 1, dtune).lowshelf2, x : fi.tf2;


//--------------`(wa.)highshelf2`--------------
// Standard second-order highshelf filter.
// Frequencies higher than the frequency get a boost or an attenuation, frequencies lower than it are unchanged.
//
// ```
// _ : highshelf2(f0, gain, dtune) : _
// ```
//
// Where:
//
// * `f0`: cutoff frequency in Hz
// * `gain`: the gain in dB
// * `dtune`: detuning of the frequency in cents
//
// #### Reference
//
// <https://searchfox.org/mozilla-central/source/dom/media/webaudio/blink/Biquad.cpp#201>
//--------------------------------------

highshelf2(f0, gain, dtune, x) = BiquadFilter(f0, gain, 1, dtune).highshelf2, x : fi.tf2;