noises.lib

//##################################### noises.lib ########################################
// Faust Noise Generator Library. Its official prefix is `no`.
//
// #### References
// * <https://github.com/grame-cncm/faustlibraries/blob/master/noises.lib>
//########################################################################################

ma = library("maths.lib");
ba = library("basics.lib");
fi = library("filters.lib");
os = library("oscillators.lib");
no = library("noises.lib"); // for compatible copy/paste out of this file

declare name "Faust Noise Generator Library";
declare version "1.4.1";

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

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

noise_env(seed) = environment {

	RANDMAX	= 2147483647.0; // = 2^31-1 = MAX_SIGNED_INT in 32 bits
	
	noise = random / RANDMAX
	with {
		random = +(seed) ~ *(1103515245); // "linear congruential"
	};	
	
	multirandom(N) = randomize(N) ~_
	with {
		randomize(1) = +(seed) : *(1103515245);
		randomize(N) = randomize(1) <: randomize(N-1),_;
	};
	
	multinoise(N) = multirandom(N) : par(i, N, /(RANDMAX)) : par(i, N, float);
	
	noises(N,i) = multinoise(N) : ba.selector(i,N);

};


//-------`(no.)noise`----------
// White noise generator (outputs random number between -1 and 1).
// `noise` is a standard Faust function.
//
// #### Usage
//
// ```
// noise : _
// ```
//------------------------
noise = noise_env(12345).noise;


//---------------------`(no.)multirandom`--------------------------
// Generates multiple decorrelated random numbers in parallel.
//
// #### Usage
// ```
// multirandom(N) : si.bus(N)
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel, a constant numerical expression
//-------------------------------------------------------------
multirandom(N) = noise_env(12345).multirandom(N);


//-----------------------`(no.)multinoise`------------------------
// Generates multiple decorrelated noises in parallel.
//
// #### Usage
//
// ```
// multinoise(N) : si.bus(N)
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel, a constant numerical expression
//------------------------------------------------------------
multinoise(N) = noise_env(12345).multinoise(N);


//-----------------------`(no.)noises`------------------------
// A convenient wrapper around multinoise.
//
// #### Usage
//
// ```
// noises(N,i) : _
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel, a constant numerical expression
// * `i`: the selected random number (i in [0..N[)
//----------------------------------------------------------
noises(N,i) = noise_env(12345).noises(N,i);


//-----------------------`(no.)randomseed`------------------------
// A random seed based on the foreign function `arc4random`
// (see man arc4random). Used in `rnoise`, `rmultirandom`, etc. to 
// avoid having the same pseudo random sequence at each run.
//
// WARNING: using the foreign function `arc4random`, so only available in C/C++ and LLVM backends.
//
// #### Usage
//
// ```
// randomseed : _
// ```
//
//------------------------------------------------------------
randomseed = ffunction(int arc4random(), <stdlib.h>, ""), 12345 : select2(1');


//-----------------------`(no.)rnoise`-----------------------
// A randomized white noise generator (outputs random number between -1 and 1).
//
// WARNING: using the foreign function `arc4random`, so only available in C/C++ and LLVM backends.
//
// #### Usage
//
// ```
// rnoise : _
// ```
//------------------------
rnoise = noise_env(randomseed).noise;


//---------------------`(no.)rmultirandom`--------------------------
// Generates multiple decorrelated random numbers in parallel.
//
// WARNING: using the foreign function `arc4random`, so only available in C/C++ and LLVM backends.
//
// #### Usage
// ```
// rmultirandom(N) : _
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel, a constant numerical expression
//-------------------------------------------------------------
rmultirandom(N) = noise_env(randomseed).multirandom(N);


//-----------------------`(no.)rmultinoise`------------------------
// Generates multiple decorrelated noises in parallel.
//
// WARNING: using the foreign function `arc4random`, so only available in C/C++ and LLVM backends.
//
// #### Usage
//
// ```
// rmultinoise(N) : _
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel, a constant numerical expression
//------------------------------------------------------------
rmultinoise(N) = noise_env(randomseed).multinoise(N);


//-----------------------`(no.)rnoises`------------------------
// A convenient wrapper around rmultinoise.
//
// WARNING: using the foreign function `arc4random`, so only available in C/C++ and LLVM backends.
//
// #### Usage
//
// ```
// rnoises(N,i) : _
// ```
//
// Where:
//
// * `N`: the number of decorrelated random numbers in parallel
// * `i`: the selected random number (i in [0..N[)
//----------------------------------------------------------
rnoises(N,i) = noise_env(randomseed).noises(N,i);


//########################################################################################
/************************************************************************
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/or Julius O. Smith III, and are released under the
[CCA4I](https://creativecommons.org/licenses/by/4.0/) license (TODO: if/when Romain agrees)

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

//---------------------------`(no.)pink_noise`--------------------------
// Pink noise (1/f noise) generator (third-order approximation covering the audio band well).
// `pink_noise` is a standard Faust function.
//
// #### Usage
// ```
// pink_noise : _
// ```
//
// #### Reference
// <https://ccrma.stanford.edu/~jos/sasp/Example_Synthesis_1_F_Noise.html>
//
// #### Alternatives
// Higher-order approximations covering any frequency band can be obtained using
// ```
// no.noise : fi.spectral_tilt(order,lowerBandLimit,Bandwidth,p)
// ```
// where `p=-0.5` means filter rolloff `f^(-1/2)` which gives 1/f rolloff in the
// power spectral density, and can be changed to other real values.
//
// #### Example
// // pink_noise_compare.dsp - compare three pinking filters
// ```
// process = pink_noises with {
//     f0 = 35; // Lower bandlimit in Hz
//     bw3 = 0.7 * ma.SR/2.0 - f0; // Bandwidth in Hz, 3rd order case
//     bw9 = 0.8 * ma.SR/2.0 - f0; // Bandwidth in Hz, 9th order case
//     pink_tilt_3 = fi.spectral_tilt(3,f0,bw3,-0.5);
//     pink_tilt_9 = fi.spectral_tilt(9,f0,bw9,-0.5);
//     pink_noises = 1-1' <:
//       no.pink_filter, // original designed by invfreqz in Octave
//       pink_tilt_3,    // newer method using the same filter order
//       pink_tilt_9;    // newer method using a higher filter order
// };
// ```
//
// #### Output of Example
// ```
// faust2octave pink_noise_compare.dsp
// Octave:1> semilogx(20*log10(abs(fft(faustout,8192))(1:4096,:)));
// ...
// ```
// <img alt="pink_noise_demo figure" src="https://ccrma.stanford.edu/wiki/Images/8/86/Tpinkd.jpg" width="600" />
//------------------------------------------------------------
pink_filter = fi.iir((0.049922035, -0.095993537, 0.050612699, -0.004408786),
                    (-2.494956002, 2.017265875, -0.522189400));

pink_noise = noise : pink_filter;

pink_noise_m = pink_noise * 12.5; // Equalizes loudness to that of no.noise (thanks Mykle Hansen) - beware of clipping


//-------------------------`(no.)pink_noise_vm`-------------------
// Multi pink noise generator.
//
// #### Usage
//
// ```
// pink_noise_vm(N) : _
// ```
//
// Where:
//
// * `N`: number of latched white-noise processes to sum,
// 	not to exceed sizeof(int) in C++ (typically 32).
//
// #### References
//
// * <http://www.dsprelated.com/showarticle/908.php>
// * <http://www.firstpr.com.au/dsp/pink-noise/#Voss-McCartney>
//------------------------------------------------------------
pink_noise_vm(N) = noise <: _,par(i,N,ba.latch(clock(i))) :> _
with {
	clock(i) = (ba.time>>i)&1; // i'th latch clock signal
};


//--------------------`(no.)lfnoise`, `(no.)lfnoise0` and `(no.)lfnoiseN`-----------------
// Low-frequency noise generators (Butterworth-filtered downsampled white noise).
//
// #### Usage
//
// ```
// lfnoise0(rate) : _   // new random number every int(ma.SR/rate) samples or so
// lfnoiseN(N,rate) : _ // same as "lfnoise0(rate) : fi.lowpass(N,rate)" [see filters.lib]
// lfnoise(rate) : _    // same as "lfnoise0(rate) : seq(i,5,fi.lowpass(N,rate))" (no overshoot)
// ```
//
// #### Example
//
// (view waveforms in faust2octave):
//
// ```
// rate = ma.SR/100.0; // new random value every 100 samples (ma.SR from maths.lib)
// process = lfnoise0(rate),   // sampled/held noise (piecewise constant)
//           lfnoiseN(3,rate), // lfnoise0 smoothed by 3rd order Butterworth LPF
//           lfnoise(rate);    // lfnoise0 smoothed with no overshoot
// ```
//------------------------------------------------------------
lfnoise0(freq) = noise : ba.latch(os.oscrs(freq));
lfnoiseN(N,freq) = lfnoise0(freq) : fi.lowpass(N,freq);       // Nth-order Butterworth lowpass
lfnoise(freq) = lfnoise0(freq) : seq(i,5,fi.lowpass(1,freq)); // non-overshooting lowpass


//-------------------------`(no.)sparse_noise`-------------------
// Sparse noise generator.
//
// #### Usage
//
// ```
// sparse_noise(f0) : _
// ```
//
// Where:
//
// * `f0`: average frequency of noise impulses per second
//
// Random impulses in the amplitude range -1 to 1 are generated
// at an average rate of f0 impulses per second.
//
// #### Reference
//
// * See velvet_noise
//------------------------------------------------------------
sparse_noise(f0) = sn
with {
    saw = os.lf_sawpos(f0);
    sawdiff = saw - saw';
    e = float(no.noise); // float() keeps 4.656613e-10f scaling here instead of later
    eHeld = e : ba.latch(sawdiff);
    eHeldPos = 0.5 + 0.5 * eHeld;
    crossed = (saw >= eHeldPos) * (saw' < eHeldPos);
    sn = e' * float(crossed);
};


//-------------------------`(no.)velvet_noise_vm`-------------------
// Velvet noise generator.
//
// #### Usage
//
// ```
// velvet_noise(amp, f0) : _
// ```
//
// Where:
//
// * `amp`: amplitude of noise impulses (positive and negative)
// * `f0`: average frequency of noise impulses per second
//
// #### Reference
//
// * Matti Karjalainen and Hanna Jarvelainen,
//   "Reverberation Modeling Using Velvet Noise",
//   in Proc. 30th Int. Conf. Intelligent Audio Environments (AES07),
//   March 2007.
//
//------------------------------------------------------------
velvet_noise(amp, f0) = vn
with {
    sn = no.sparse_noise(f0);
    vn = amp * ma.signum(sn);
};


//----------------------------`(no.)gnoise`------------------------
// Approximate zero-mean, unit-variance Gaussian white noise generator.
//
// #### Usage
//
// ```
// gnoise(N) : _
// ```
//
// Where:
//
// * `N`: number of uniform random numbers added to approximate Gaussian white noise
//
// #### Reference
//
// * See Central Limit Theorem
//
//------------------------------------------------------------
gnoise(N) = uvgwn
with {
    uwn = no.multinoise(N); // uniform white noise in [-1,1] on N channels
    gwn = uwn :> _;         // sum of uniform approaches Gaussian by centeral limit thm
    sigma = sqrt(N/3.0);    // rms of each uwn channel
    uvgwn = gwn / sigma;	// approaches zero-mean, unit-variance Gaussian white noise, for large N
};

gnoisem(N) = gnoise(N) * 0.625; // Equalizes loudness to that of no.noise (thanks Mykle Hansen)


/*** END jos section ***/

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

//-----------------`(no.)colored_noise`--------------------
// Generates a colored noise signal with an arbitrary spectral
// roll-off factor (alpha) over the entire audible frequency range
// (20-20000 Hz). The output is normalized so that an equal RMS
// level is maintained for different values of alpha.
//
// #### Usage
//
// ```
// colored_noise(N,alpha) : _
// ```
//
// Where:
//
// * `N`: desired integer filter order (constant numerical expression)
// * `alpha`: slope of roll-off, between -1 and 1. -1 corresponds to 
// brown/red noise, -1/2 pink noise, 0 white noise, 1/2 blue noise,
// and 1 violet/azure noise.
//
// #### Examples
// See `dm.colored_noise_demo`.
//
//-------------------------------------------------
declare colored_noise author "Constantinos Odysseas Economou";
declare colored_noise copyright "Copyright (C) 2022 Constantinos Odysseas Economou <c.economou@sirenfx.io>";
declare colored_noise license "MIT-style STK-4.3 license";

colored_noise(N,alpha) = no.noise : fi.dcblocker : fi.spectral_tilt(N,fmin,bw,alpha) : *(uniNorm(alpha * 2)) : max(-1.0) : min(1.0)
with {
    fmin = 20.0;
    fmax = 20000.0;
    bw = fmax - fmin;

    uniNorm(alpha) = (a*exp(-alpha*b))+(c*exp(-alpha*d)) : pow(-1)
    with {
        a = ba.if(ma.signum(alpha) > 0, 1, 0.8016);
        b = ba.if(ma.signum(alpha) > 0, -4.28, -2.633);
        c = ba.if(ma.signum(alpha) > 0, 0, 0.1984);
        d = ba.if(ma.signum(alpha) > 0, 0, -0.7196);
    };
};