flucoma-sc/release-packaging/HelpSource/Classes/FluidChroma.schelp

TITLE:: FluidChroma
SUMMARY:: A histogram of pitch classes in Real-Time
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED:: Classes/FluidBufChroma,Classes/FluidPitch,Classes/FluidLoudness,Classes/FluidMFCC,Classes/FluidSpectralShape,Guides/FluidCorpusManipulationToolkit,Classes/FluidMFCC
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 chroma bins (and, thus, pitch classes) and the central reference frequency can be adjusted.

    The process will return a multichannel control steam of size maxNumChroma, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the signal vector size.


CLASSMETHODS::

METHOD:: kr

ARGUMENT:: in

  Audio-rate signal to analyze

ARGUMENT:: numChroma

    
    The number of chroma bins per octave. It will determine how many channels are output per input channel.

    STRONG::Constraints::

    LIST::
    ## 
    Minimum: 2

    ## 
    Maximum: CODE::maxNumChroma::

    ::

ARGUMENT:: ref

    
    STRONG::Constraints::

    LIST::
    ## 
    Minimum: 0

    ## 
    Maximum: 22000

    ::

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 bin being 1.


ARGUMENT:: minFreq

    
    The lower frequency included in the analysis, in Hz.

    STRONG::Constraints::

    LIST::
    ## 
    Minimum: 0

    ::

ARGUMENT:: maxFreq

    
    The highest frequency included in the analysis, in Hz.

    STRONG::Constraints::

    LIST::
    ## 
    Minimum: -1

    ::

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. LINK::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 default to windowSize.


 
ARGUMENT:: maxNumChroma

    
    The maximum number of chroma bins. This sets the number of channels of the output stream, and therefore cannot be modulated.

    STRONG::Constraints::

    LIST::
    ## 
    Minimum: 2

    ## 
    Maximum: (max FFFT Size / 2) + 1`` (see maxFFTSize)

    ::

ARGUMENT:: maxFFTSize

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


 

INSTANCEMETHODS::
  
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 Bins 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 chroma bin 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.
::