TITLE:: FluidChroma
SUMMARY:: An histogram of pitch classes in Real-Time
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED::  Guides/FluidCorpusManipulation, Classes/FluidBufChroma

DESCRIPTION::
This class computes a histogram of the energy contained for each pitch class across the analysis frequency range. Also known as a chromagram, this typically allows you to get a contour of how much each semitone is represented in the spectrum over time. The number of bands (and, thus, pitch classes) and the central reference frequency can be adjusted.

It is part of the LINK:: Guides/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/

The process will return a multichannel control steam of size STRONG::maxNumChroma::, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the server's kr period.

CLASSMETHODS::

METHOD:: kr
	The audio rate in, control rate out version of the object.

ARGUMENT:: in
	The audio to be processed.

ARGUMENT:: numChroma
	The number of chroma bands per octave. It will determine how many channels of the output stream are filled.

ARGUMENT:: ref
	The reference frequency in Hz for the tuning to middle A (default: 440 Hz)

ARGUMENT:: normalize
This flag enables the scaling of the output. It is off (0) by default. (1) will normalise each frame to sum to 1. (2) normalises each frame relative to the loudest chroma being 1.

ARGUMENT:: minFreq
	The lower frequency included in the analysis, in Hz.

ARGUMENT:: maxFreq
	The highest frequency included in the analysis, in Hz.

ARGUMENT:: maxNumChroma
	The maximum number of pitch classes. This sets the number of channels of the output stream, and therefore cannot be modulated.

ARGUMENT:: windowSize
	The window size. As chroma computation relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. http://www.subsurfwiki.org/wiki/Gabor_uncertainty

ARGUMENT:: hopSize
	The window hop size. As chroma computation 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 should 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 or above the windowSize.

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

RETURNS::
	A  KR signal of STRONG::maxNumChroma:: channels, giving the measure amplitudes for each chroma. The latency is windowSize.


EXAMPLES::

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

//create a monitoring window for the values

(
w = Window("Chroma Bands Monitor", Rect(10, 10, 620, 320)).front;
a = MultiSliderView(w,Rect(10, 10, 600, 300)).elasticMode_(1).isFilled_(1);
)

//run the window updating routine.
(
~winRange = 0.1;
r = Routine {
    {
        b.get({ arg val;
            {
                if(w.isClosed.not) {
                    a.value = val/~winRange;
                }
            }.defer
        });
        0.01.wait;
    }.loop
}.play
)

//play a simple sound to observe the values
(
x = 	{
	var source = SinOsc.ar(LFTri.kr(0.1).exprange(80,800),0,0.1);
	Out.kr(b,FluidChroma.kr(source, numChroma: 24, maxNumChroma:24));
	source.dup;
}.play;
)

//we can observe that in the low end, the precision of the fft is not good enough to give a sharp pitch centre. We still can observe the octaviation quantized in quarter tones.

// free this source
x.free

// load a more exciting one
c = Buffer.read(s,File.realpath(FluidChroma.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SlideChoirAdd-M.wav");

// analyse with parameters to be changed
(
x = 	{arg chroma = 24, low = 20, high = 20000, norm=1, t_cue, sel=0;
	var source = Select.ar(sel, [
		PlayBuf.ar(1,c,loop:1),
		Saw.ar(TIRand.kr(60.dup(3),96,t_cue).poll(t_cue).midicps,0.05).sum;
	]);
	Out.kr(b,FluidChroma.kr(source ,numChroma: chroma, minFreq: low, maxFreq: high, normalize: norm, maxNumChroma: 24, windowSize: 4096) / 10);
	source.dup;
}.play;
)

//set the winRange to a more informative value
~winRange = 0.03;

//instead, let's normalise each frame independently
~winRange = 0.12;
x.set(\norm, 2);

// observe the number of chroma. The unused ones at the top are not updated
x.set(\chroma,12)

// back to the full range
x.set(\chroma,24)

// change the source to random three-note chords
x.set(\sel, 1)

// trigger new chords and observe the chroma contour
x.set(\t_cue, 1)

// focus all the bands on a low mid range (there might be nothing!)
x.set(\low,320, \high, 800)

// or on a specific octave
x.set(\low, 60.midicps, \high, 72.midicps)

// back to full range
x.set(\low,20, \high, 20000)

// free everything
x.free;b.free;c.free;r.stop;
::

STRONG::A musical example::

CODE::
//something will happen here.
::