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

//#################################### compressor.lib ####################################
// A library of compressor effects.
//
// It should be used using the `co` environment:
//
// ```
// co = library("compressor.lib");
// process = co.functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `co`
// environment:
//
// ```
// import("stdfaust.lib");
// process = co.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");
an = library("analyzer.lib");


declare name "Faust Compressor Effect Library";
declare version "0.0";

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

//--------------------`compressor_mono`-------------------
// Mono dynamic range compressors.
// `compressor_mono` is a standard Faust function
//
// #### Usage
//
// ```
// _ : compressor_mono(ratio,thresh,att,rel) : _
// ```
//
// Where:
//
// * `ratio`: compression ratio (1 = no compression, >1 means compression)
// * `thresh`: dB level threshold above which compression kicks in (0 dB = max level)
// * `att`: attack time = time constant (sec) when level & compression going up
// * `rel`: release time = time constant (sec) coming out of compression
//
// #### References
//
// * <http://en.wikipedia.org/wiki/Dynamic_range_compression>
// * <https://ccrma.stanford.edu/~jos/filters/Nonlinear_Filter_Example_Dynamic.html>
// * Albert Graef's "faust2pd"/examples/synth/compressor_.dsp
// * More features: <https://github.com/magnetophon/faustCompressors>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
compressor_mono(ratio,thresh,att,rel,x) = x * compression_gain_mono(ratio,thresh,att,rel,x);


//--------------------`compressor_stereo`-------------------
// Stereo dynamic range compressors.
//
// #### Usage
//
// ```
// _,_ : compressor_stereo(ratio,thresh,att,rel) : _,_
// ```
//
// Where:
//
// * `ratio`: compression ratio (1 = no compression, >1 means compression)
// * `thresh`: dB level threshold above which compression kicks in (0 dB = max level)
// * `att`: attack time = time constant (sec) when level & compression going up
// * `rel`: release time = time constant (sec) coming out of compression
//
// #### References
//
// * <http://en.wikipedia.org/wiki/Dynamic_range_compression>
// * <https://ccrma.stanford.edu/~jos/filters/Nonlinear_Filter_Example_Dynamic.html>
// * Albert Graef's "faust2pd"/examples/synth/compressor_.dsp
// * More features: <https://github.com/magnetophon/faustCompressors>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
compressor_stereo(ratio,thresh,att,rel,x,y) = cgm*x, cgm*y with {
  cgm = compression_gain_mono(ratio,thresh,att,rel,abs(x)+abs(y));
};

compression_gain_mono(ratio,thresh,att,rel) =
  an.amp_follower_ar(att,rel) : ba.linear2db : outminusindb(ratio,thresh) :
  kneesmooth(att) : ba.db2linear
with {
  // kneesmooth(att) installs a "knee" in the dynamic-range compression,
  // where knee smoothness is set equal to half that of the compression-attack.
  // A general 'knee' parameter could be used instead of tying it to att/2:
  kneesmooth(att)  = si.smooth(ba.tau2pole(att/2.0));
  // compression gain in dB:
   outminusindb(ratio,thresh,level) = max(level-thresh,0.0) * (1.0/float(ratio)-1.0);
  // Note: "float(ratio)" REQUIRED when ratio is an integer > 1!
};


//----------------`limiter_1176_R4_mono`----------------------
// A limiter guards against hard-clipping.  It can be can be
// implemented as a compressor having a high threshold (near the
// clipping level), fast attack and release, and high ratio.  Since
// the ratio is so high, some knee smoothing is
// desirable ("soft limiting").  This example is intended
// to get you started using compressor_* as a limiter, so all
// parameters are hardwired to nominal values here.
// Ratios: 4 (moderate compression), 8 (severe compression),
//          12 (mild limiting), or 20 to 1 (hard limiting)
//   Att: 20-800 MICROseconds (Note: scaled by ratio in the 1176)
//   Rel: 50-1100 ms (Note: scaled by ratio in the 1176)
//   Mike Shipley likes 4:1 (Grammy-winning mixer for Queen, Tom Petty, etc.)
//     Faster attack gives "more bite" (e.g. on vocals)
//     He hears a bright, clear eq effect as well (not implemented here)
// `limiter_1176_R4_mono` is a standard Faust function.
//
// #### Usage
//
// ```
//  _ : limiter_1176_R4_mono : _;
// ```
//
// #### Reference:
//
// <http://en.wikipedia.org/wiki/1176_Peak_Limiter>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
limiter_1176_R4_mono = compressor_mono(4,-6,0.0008,0.5);


//-------------------`limiter_1176_R4_stereo`---------------------
// A limiter guards against hard-clipping.  It can be can be
// implemented as a compressor having a high threshold (near the
// clipping level), fast attack and release, and high ratio.  Since
// the ratio is so high, some knee smoothing is
// desirable ("soft limiting").  This example is intended
// to get you started using compressor_* as a limiter, so all
// parameters are hardwired to nominal values here.
// Ratios: 4 (moderate compression), 8 (severe compression),
//          12 (mild limiting), or 20 to 1 (hard limiting)
//   Att: 20-800 MICROseconds (Note: scaled by ratio in the 1176)
//   Rel: 50-1100 ms (Note: scaled by ratio in the 1176)
//   Mike Shipley likes 4:1 (Grammy-winning mixer for Queen, Tom Petty, etc.)
//     Faster attack gives "more bite" (e.g. on vocals)
//     He hears a bright, clear eq effect as well (not implemented here)
//
// #### Usage
//
// ```
//  _,_ : limiter_1176_R4_stereo : _,_;
// ```
//
// #### Reference:
//
// <http://en.wikipedia.org/wiki/1176_Peak_Limiter>
//------------------------------------------------------------
// TODO: author JOS, revised by RM
limiter_1176_R4_stereo = compressor_stereo(4,-6,0.0008,0.5);