class:: KeyClarity
summary:: Running score of maximum correlation of chromagram with key profiles
categories:: UGens>Analysis>Pitch
related:: Classes/BeatTrack, Classes/Loudness, Classes/MFCC, Classes/Onsets, Classes/Pitch

description::
A (12TET major/minor) key tracker based on a pitch class profile of energy across FFT bins and matching this to templates for major and minor scales in all transpositions. It assumes a 440 Hz concert A reference. Output is the strength of the match to scales, e.g. maximal correlation with key profiles. Provides a measure of the level of key clarity, e.g. unambiguous key. 

classmethods::

method:: kr

argument:: chain
[fft] Audio input to track. This must have been pre-analysed by a 4096 size FFT. No other FFT sizes are valid except as noted below.
code::
// With standard hop of half FFT size = 2048 samples
b = Buffer.alloc(s,4096,1); // for sampling rates 44100 and 48000
//b = Buffer.alloc(s,8192,1); // for sampling rates 88200 and 96000
::

argument:: keydecay
[sk] Number of seconds for the influence of a window on the final key decision to decay by 40dB (to 0.01 its original value).

argument:: chromaleak
[sk] Each frame, the chroma values are set to the previous value multiplied by the chromadecay. 0.0 will start each frame afresh with no memory.

examples::

code::
d = Buffer.read(s, "/data/audio/mirdata/pixiesivebeentired.wav")

d = Buffer.read(s,"/data/audio/mirdata/Beethoven8mvt4.wav")

b = Buffer.alloc(s, 4096, 1); // for sampling rates 44100 and 48000

(
{
var in, fft, resample;
var key, transientdetection;

in = PlayBuf.ar(1, d, BufRateScale.kr(d), 1, 0, 1);

fft = FFT(b, in);

key=KeyClarity.kr(fft, 2.0, 0.5);

key.poll;

Out.ar(0,Pan2.ar(in));
}.play
)
::

