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

//################################ analyzer.lib ##########################################
// This library contains a collection of tools to analyze signals.
// 
// It should be used using the `an` environment:
//
// ```
// an = library("analyzer.lib");
// process = an.functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `an`
// environment:
//
// ```
// import("stdfaust.lib");
// process = an.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.
************************************************************************
************************************************************************/

ba = library("basic.lib");
si = library("signal.lib");
fi = library("filter.lib");

declare name "Faust Analyzer Library";
declare version "0.0";

//==============================Amplitude Tracking========================================
//========================================================================================

//---------------------------`amp_follower`---------------------------
// Classic analog audio envelope follower with infinitely fast rise and
// exponential decay.  The amplitude envelope instantaneously follows
// the absolute value going up, but then floats down exponentially.
// `amp_follower` is a standard Faust function.
//
// #### Usage
//
// ```
// _ : amp_follower(rel) : _
// ```
//
// Where:
//
// * `rel`: release time = amplitude-envelope time-constant (sec) going down
//
// #### Reference
//
// * Musical Engineer's Handbook, Bernie Hutchins, Ithaca NY, 1975 Electronotes 
// Newsletter, Bernie Hutchins
//------------------------------------------------------------
// TODO: author JOS, revised by RM 
amp_follower(rel) = abs : env with {
 p = ba.tau2pole(rel);
 env(x) = x * (1.0 - p) : (+ : max(x,_)) ~ *(p);
};


//---------------------------`amp_follower_ud`---------------------------
// Envelope follower with different up and down time-constants
// (also called a "peak detector").
//
// #### Usage
//
// ```
//    _ : amp_follower_ud(att,rel) : _
// ```
//
// Where:
//
// * `att`: attack time = amplitude-envelope time constant (sec) going up
// * `rel`: release time = amplitude-envelope time constant (sec) going down
//
// #### Note
//
// We assume rel >> att.  Otherwise, consider rel ~ max(rel,att).
// For audio, att is normally faster (smaller) than rel (e.g., 0.001 and 0.01).
// Use `amp_follower_ar` below to remove this restriction.
//
// #### Reference
//
// * "Digital Dynamic Range Compressor Design --- A Tutorial and Analysis", by
//   Dimitrios Giannoulis, Michael Massberg, and Joshua D. Reiss
//   <http://www.eecs.qmul.ac.uk/~josh/documents/GiannoulisMassbergReiss-dynamicrangecompression-JAES2012.pdf>
//------------------------------------------------------------
// TODO: author JOS, revised by RM 
amp_follower_ud(att,rel) = amp_follower(rel) : si.smooth(ba.tau2pole(att));


//---------------`amp_follower_ar`----------------
// Envelope follower with independent attack and release times. The
// release can be shorter than the attack (unlike in `amp_follower_ud`
// above).
//
// #### Usage
// 
// ```
// _ : amp_follower_ar(att,rel) : _;
// ```
//---------------------------------------------------------
// TODO: author Jonatan Liljedahl, revised by RM
amp_follower_ar(att,rel) = abs : si.lag_ud(att,rel);


//=============================Spectrum-Analyzers=========================================
// Spectrum-analyzers split the input signal into a bank of parallel signals, one for 
// each spectral band. They are related to the Mth-Octave Filter-Banks in `filter.lib`.
// The documentation of this library contains more details about the implementation. 
// The parameters are:
//
// * `M`: number of band-slices per octave (>1)
// * `N`: total number of bands (>2)
// * `ftop` = upper bandlimit of the Mth-octave bands (<SR/2)
//
// In addition to the Mth-octave output signals, there is a highpass signal
// containing frequencies from ftop to SR/2, and a "dc band" lowpass signal 
// containing frequencies from 0 (dc) up to the start of the Mth-octave bands.
// Thus, the N output signals are
// ```
// highpass(ftop), MthOctaveBands(M,N-2,ftop), dcBand(ftop*2^(-M*(N-1)))
// ```
// 
// A Spectrum-Analyzer is defined here as any band-split whose bands span
// the relevant spectrum, but whose band-signals do not
// necessarily sum to the original signal, either exactly or to within an
// allpass filtering. Spectrum analyzer outputs are normally at least nearly
// "power complementary", i.e., the power spectra of the individual bands
// sum to the original power spectrum (to within some negligible tolerance).
//
// #### Increasing Channel Isolation
//
// Go to higher filter orders - see Regalia et al. or Vaidyanathan (cited 
// below) regarding the construction of more aggressive recursive 
// filter-banks using elliptic or Chebyshev prototype filters.
//   
// #### References
//
// * "Tree-structured complementary filter banks using all-pass sections",
//   Regalia et al., IEEE Trans. Circuits & Systems, CAS-34:1470-1484, Dec. 1987
// * "Multirate Systems and Filter Banks", P. Vaidyanathan, Prentice-Hall, 1993
// * Elementary filter theory: https://ccrma.stanford.edu/~jos/filters/
//========================================================================================


//-------------------------`mth_octave_analyzer`----------------------------
// Octave analyzer.
// `mth_octave_analyzer[N]` are standard Faust functions.
//
// #### Usage
// ```
// _ : mth_octave_analyzer(O,M,ftop,N) : par(i,N,_); // Oth-order Butterworth
// _ : mth_octave_analyzer6e(M,ftop,N) : par(i,N,_); // 6th-order elliptic
// ```
//
// Also for convenience:
//
// ```
// _ : mth_octave_analyzer3(M,ftop,N) : par(i,N,_); // 3d-order Butterworth
// _ : mth_octave_analyzer5(M,ftop,N) : par(i,N,_); // 5th-roder Butterworth
// mth_octave_analyzer_default = mth_octave_analyzer6e;
// ```
//
// Where: 
//
// * `O`: order of filter used to split each frequency band into two
// * `M`: number of band-slices per octave
// * `ftop`: highest band-split crossover frequency (e.g., 20 kHz)
// * `N`: total number of bands (including dc and Nyquist)
//------------------------------------------------------------
// TODO: author JOS and Orlarey, revised by RM
mth_octave_analyzer6e(M,ftop,N) = _ <: bsplit(N-1) with {
  fc(n) = ftop * 2^(float(n-N+1)/float(M)); // -3dB crossover frequencies
  lp(n) = fi.lowpass6e(fc(n));  // 6th-order elliptic - see other choices above
  hp(n) = fi.highpass6e(fc(n)); //   (search for lowpass* and highpass*)
  bsplit(0)  = _; 
  bsplit(i) = hp(i), (lp(i) <: bsplit(i-1));
};

// Butterworth analyzers may be cascaded with allpass
// delay-equalizers to make (allpass-complementary) filter banks:

mth_octave_analyzer(O,M,ftop,N) = _ <: bsplit(N-1) with {
  fc(n) = ftop * 2^(float(n-N+1)/float(M));
  lp(n) = fi.lowpass(O,fc(n)); // Order O Butterworth
  hp(n) = fi.highpass(O,fc(n));
  bsplit(0)  = _; 
  bsplit(i) = hp(i), (lp(i) <: bsplit(i-1));
};

mth_octave_analyzer3(M,ftop,N) = mth_octave_analyzer(3,M,ftop,N);
mth_octave_analyzer5(M,ftop,N) = mth_octave_analyzer(5,M,ftop,N);
mth_octave_analyzer_default = mth_octave_analyzer6e; // default analyzer


//============================Mth-Octave Spectral Level===================================
// Spectral Level: Display (in bar graphs) the average signal level in each spectral band.
//========================================================================================


//------------------------`mth_octave_spectral_level6e`-------------------------
// Spectral level display.
//
// #### Usage:
//
// ```
// _ : mth_octave_spectral_level6e(M,ftop,NBands,tau,dB_offset) : _;
// ```
//
// Where: 
//
// * `M`: bands per octave
// * `ftop`: lower edge frequency of top band
// * `NBands`: number of passbands (including highpass and dc bands),
// * `tau`: spectral display averaging-time (time constant) in seconds,
// * `dB_offset`: constant dB offset in all band level meters.
//
// Also for convenience:
//
// ```
// mth_octave_spectral_level_default = mth_octave_spectral_level6e;
// spectral_level = mth_octave_spectral_level(2,10000,20);
// ``` 
//------------------------------------------------------------
// TODO: author JOS and Orlarey, revised by RM 
// TODO: is the "6e" really necessary here?
mth_octave_spectral_level6e(M,ftop,N,tau,dB_offset) = _<:
    _,mth_octave_analyzer6e(M,ftop,N) : 
    _,(display:>_):attach with {
  display = par(i,N,dbmeter(i));
  dbmeter(i) = abs : si.smooth(ba.tau2pole(tau)) : ba.linear2db : +(dB_offset) : 
     meter(N-i-1);
    meter(i) = speclevel_group(vbargraph("[%2i] [unit:dB] 
     [tooltip: Spectral Band Level in dB]", -50, 10));
  O = int(((N-2)/M)+0.4999);
  speclevel_group(x)  = hgroup("[0] CONSTANT-Q SPECTRUM ANALYZER (6E), %N bands spanning 
  	LP, %O octaves below %ftop Hz, HP
     [tooltip: See Faust's filter.lib for documentation and references]", x);
};

mth_octave_spectral_level_default = mth_octave_spectral_level6e;
spectral_level = mth_octave_spectral_level(2,10000,20);  // simple default


//---------------`[third|half]_octave_[analyzer|filterbank]`----------------
// A bunch of special cases based on the different analyzer functions described above:
//
// ```
// third_octave_analyzer(N) = mth_octave_analyzer_default(3,10000,N);
// third_octave_filterbank(N) = mth_octave_filterbank_default(3,10000,N);
// half_octave_analyzer(N) = mth_octave_analyzer_default(2,10000,N);
// half_octave_filterbank(N) = mth_octave_filterbank_default(2,10000,N);
// octave_filterbank(N) = mth_octave_filterbank_default(1,10000,N);
// octave_analyzer(N) = mth_octave_analyzer_default(1,10000,N);
// ```
//
// #### Usage
//
// See `mth_octave_spectral_level_demo`.
//------------------------------------------------------------
// TODO: author JOS and Orlarey, revised by RM 
third_octave_analyzer(N) = mth_octave_analyzer_default(3,10000,N);
third_octave_filterbank(N) = mth_octave_filterbank_default(3,10000,N);
// Third-Octave Filter-Banks have been used in audio for over a century.
// See, e.g.,
//   Acoustics [the book], by L. L. Beranek
//   Amer. Inst. Physics for the Acoustical Soc. America,
//   http://asa.aip.org/publications.html, 1986 (1st ed.1954)

// Third-octave bands across the audio spectrum are too wide for current
// typical computer screens, so half-octave bands are the default:
half_octave_analyzer(N) = mth_octave_analyzer_default(2,10000,N);
half_octave_filterbank(N) = mth_octave_filterbank_default(2,10000,N);

octave_filterbank(N) = mth_octave_filterbank_default(1,10000,N);
octave_analyzer(N) = mth_octave_analyzer_default(1,10000,N);


//===============Arbritary-Crossover Filter-Banks and Spectrum Analyzers==================
// These are similar to the Mth-octave analyzers above, except that the
// band-split frequencies are passed explicitly as arguments. 
//========================================================================================

// ACKNOWLEDGMENT
// Technique for processing a variable number of signal arguments due
// to Yann Orlarey (as is the entire Faust framework!)

//---------------`analyzer`--------------------------
// Analyzer.
//
// #### Usage
//
// ```
// _ : analyzer(O,freqs) : par(i,N,_); // No delay equalizer
// ```
//
// Where: 
//
// * `O`: band-split filter order (ODD integer required for filterbank[i])
// * `freqs`: (fc1,fc2,...,fcNs) [in numerically ascending order], where
//           Ns=N-1 is the number of octave band-splits 
//           (total number of bands N=Ns+1). 
// 
// If frequencies are listed explicitly as arguments, enclose them in parens:
//
// ```
// _ : analyzer(3,(fc1,fc2)) : _,_,_
// ```
//---------------------------------------------------
// TODO: author JOS, revised by RM 
analyzer(O,lfreqs) = _ <: bsplit(nb) with
{
   nb = ba.count(lfreqs);
   fc(n) = ba.take(n, lfreqs);
   lp(n) = fi.lowpass(O,fc(n));
   hp(n) = fi.highpass(O,fc(n));
   bsplit(0) = _;
   bsplit(i) = hp(i), (lp(i) <: bsplit(i-1));
};