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

DESCRIPTION::
This class computes the histogram of the energy contained within each chroma class. Also known as chromagram, this typically allows to get a contour of how much each semitone is represented in the spectrum. Tuning the central frequency reference, and how many bands are computed, allow for a flexible imprint of octaviated pitch classes. This implementation allows to select the range and number of chroma classes dynamically. It is part of the LINK:: Guides/FluidDecomposition:: of LINK:: Guides/FluCoMa::. 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 algorythm, 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 decide how many channels are produce per channel of the source.

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

ARGUMENT:: normalize
This flag enables the scaling of the output. It is off (0) by default. (1) will normalise to the FFT size. (2) normalises each frame independently.

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

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

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

ARGUMENT:: windowSize
	The window size. As sinusoidal estimation 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 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 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;
	var source = PlayBuf.ar(1,c,loop:1);
	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.04;

//instead, let's normalise each frame independently
~winRange = 0.2;
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)

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

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