TITLE:: FluidPitch
SUMMARY:: A Selection of Pitch Descriptors in Real-Time
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED::  Guides/FluidCorpusManipulation, Classes/Pitch

DESCRIPTION::
FluidPitch implements three popular pitch descriptors. It outputs two values: the computed frequency and the confidence in the accuracy of that frequency. It is part of the LINK:: Guides/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. For more explanations, learning materials, and discussions on its musicianly uses, visit https://www.flucoma.org/reference/pitch

FluidPitch outputs a multichannel control steam of [pitch, confidence] values. The 'unit' argument changes the unit of the pitch output. 'unit' set to 0 will return a frequency in Hz, 'unit' set to 1 will return the MIDI note (with a decimal for microtonal values). If the chosen algorithm cannot determine a fundamental pitch at all, a frequency of 0 Hz is returned (or -999.0 when the unit is in MIDI note).

When the hopSize is larger than the server's kr period, the returned values will be repeated until the next window is computed.

CLASSMETHODS::

METHOD:: kr
	The audio rate in, control rate out

ARGUMENT:: in
	The audio to be processed.

ARGUMENT:: algorithm
	The algorithm to estimate the pitch. The options are:
	TABLE::
	## 0 || Cepstrum: Returns a pitch estimate as the location of the second highest peak in the Cepstrum of the signal (after DC).
	## 1 || Harmonic Product Spectrum: Implements the Harmonic Product Spectrum algorithm for pitch detection . See e.g. FOOTNOTE:: A. Lerch, "An Introduction to Audio Content Analysis: Applications in Signal Processing and Music Informatics." John Wiley & Sons, 2012.https://onlinelibrary.wiley.com/doi/book/10.1002/9781118393550 ::
	## 2 || YinFFT: Implements the frequency domain version of the YIN algorithm, as described in FOOTNOTE::P. M. Brossier, "Automatic Annotation of Musical Audio for Interactive Applications.” QMUL, London, UK, 2007. :: See also FOOTNOTE::https://essentia.upf.edu/documentation/reference/streaming_PitchYinFFT.html::
	::

ARGUMENT:: minFreq
The minimum frequency that the algorithm will search for an estimated fundamental. This sets the lowest value that will be generated. The default is 20.

ARGUMENT:: maxFreq
The maximum frequency that the algorithm will search for an estimated fundamental. This sets the highest value that will be generated. The default is 10000.

ARGUMENT:: unit
The unit of the estimated frequency. The default of 0 is in Hz. A value of 1 will convert to MIDI note values.

ARGUMENT:: windowSize
	The window size. The number of samples used to calculate the FFT.

ARGUMENT:: hopSize
	The window hop size. As sinusoidal estimation relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2).

ARGUMENT:: fftSize
	The inner FFT/IFFT size. It must be at least 4 samples long, at least the size of the window, and a power of 2. Making it larger allows an oversampling of the spectral precision. The -1 default value will use the next power of 2 equal to or above the windowSize.

ARGUMENT:: maxFFTSize
	How large can the FFT be, by allocating memory at instantiation time. This cannot be modulated.

RETURNS::
	A 2-channel KR signal with the [pitch, confidence] descriptors. The latency is windowSize.


EXAMPLES::


code::
//create a monitoring bus for the descriptors
b = Bus.new(\control,0,4);

//create a monitoring window for the values
(
w = Window("Frequency Monitor", Rect(10, 10, 220, 115)).front;

c = Array.fill(4, {arg i; StaticText(w, Rect(10, i * 25 + 10, 135, 20)).background_(Color.grey(0.7)).align_(\right)});
c[0].string = ("FluidPitch: ");
c[1].string = ("confidence: ");
c[2].string = ("SC Pitch: ");
c[3].string = ("Confidence: ");

a = Array.fill(4, {arg i;
	StaticText(w, Rect(150, i * 25 + 10, 60, 20)).background_(Color.grey(0.7)).align_(\center);
});
)

//routine to update the parameters
(
r = Routine {
	{

		b.get({ arg val;
			{
				if(w.isClosed.not) {
					val.do({arg item,index;
						a[index].string = item.round(0.01)})
				}
			}.defer
		});

		0.1.wait;
	}.loop

}.play
)

//test signals, all in one synth
(
x = {
	arg freq=220, type = 0, noise = 0;
			var source = PinkNoise.ar(noise) + Select.ar(type,[SinOsc.ar(freq,mul:0.1), VarSaw.ar(freq,mul:0.1), Saw.ar(freq,0.1), Pulse.ar(freq,mul:0.1), Mix.new(Array.fill(8, {arg i; SinOsc.ar(LFNoise1.kr(0.1.rand,10,220*(i+1)),mul:(i+1).reciprocal * 0.1)}))]);
	Out.kr(b, FluidPitch.kr(source) ++ Pitch.kr(source));
	source.dup;
}.play;
)

// the built-in is slightly better on pure sinewaves
x.set(\freq, 440)

// adding harmonics, by changing to triangle (1), saw (2) or square (3) shows that spectral algo are more resilient when signal are richer
x.set(\type, 1)
x.set(\type, 2)
x.set(\type, 3)

// adding noise shows the comparative sturdiness of the spectral pitch tracker
x.set(\noise, 0.05)

//if latency is no issue, getting a higher windowSize will stabilise the algorithm even more
::

STRONG::a more musical example::
CODE::
// play a noisy synth file
b = Buffer.read(s,File.realpath(FluidPitch.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-ASWINE-ScratchySynth-M.wav");
b.play(true);

//insert a selective reverb - sending only the material with very high pitch confidence
(
f = {var source, rev;
	source = In.ar(0,2);
	rev = FreeVerb.ar(DelayN.ar(source,delaytime:1024/s.sampleRate) * Lag.kr((FluidPitch.kr(source.sum)[1] > 0.98),0.01), 1);
	ReplaceOut.ar(0, rev+ source);
}.play(addAction:\addToTail);
)

// free the effect
f.free

// insert a stereo delay instead (as well) using the same
(
f = {
	var source, todelay, delay1, delay2, delay3, feedback, mod1, mod2, mod3, mod4;
	//read the source
	source = In.ar(0,2);

	// generate modulators that are coprime in frequency
	mod1 = SinOsc.ar(1, 0, 0.001);
	mod2 = SinOsc.ar(((617 * 181) / (461 * 991)), 0, 0.001);
	mod3 = SinOsc.ar(((607 * 193) / (491 * 701)), 0, 0.001);
	mod4 = SinOsc.ar(((613 * 191) / (463 * 601)), 0, 0.001);

	// gate the signal to send to the delays
	todelay = DelayN.ar(source,delaytime:1024/s.sampleRate) * Lag.kr((FluidPitch.kr(source.sum)[1] > 0.98),0.01);

	// delay network
	feedback = LocalIn.ar(3);// take the feedback in for the delays
	delay1 = DelayC.ar(BPF.ar(todelay+feedback[1]+(feedback[2] * 0.3), 987, 6.7,0.35),0.123,0.122+(mod1*mod2));
	delay2 = DelayC.ar(BPF.ar(todelay+feedback[0]+(feedback[2] * 0.3), 1987, 6.7,0.35),0.345,0.344+(mod3*mod4));
	delay3 = DelayC.ar(BPF.ar(todelay+feedback[1], 1456, 6.7,0.35),0.567,0.566+(mod1*mod3),0.6);
	LocalOut.ar([delay1,delay2, delay3]); // write the feedback for the delays

			ReplaceOut.ar(0, source + [delay1+delay3,delay2+delay3]);
}.play(addAction:\addToTail);
)
::