class:: BeatTrack
summary:: Autocorrelation beat tracker
categories:: UGens>Analysis, UGens>FFT
related:: Classes/BeatTrack2

description::
Autocorrelation based beat tracker; footnote::
Research note: This UGen is a derivation following:
Davies, M. E. P.  and Plumbley, M. D. Beat Tracking With A Two State Model. Proceedings of the IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP 2005), Philadelphia, USA, March 19-23, 2005

The UGen was converted by Nick Collins for beat tracking research in the course of his PhD and uses an original C implementation of Matthew Davies' MATLAB model. It first appeared as part of BBCut2 as AutoTrack but has now been added to core to enhance SuperCollider's realtime machine listening options.
:: the underlying model assumes 4/4, but it should work on any isochronous beat structure, though there are biases to 100-120 bpm; a fast 7/8 may not be tracked in that sense.
There are four k-rate outputs, being ticks at quarter, eighth and sixteenth level from the determined beat, and the current detected tempo. Note that the sixteenth note output won't necessarily make much sense if the music being tracked has swing; it is provided just as a convenience.

This beat tracker determines the beat, biased to the midtempo range by weighting functions. It does not determine the measure level, only a tactus.
It is also slow reacting, using a 6 second temporal window for its autocorrelation maneouvres. Don't expect human musician level predictive tracking.

On the other hand, it is tireless, relatively general (though obviously best at transient 4/4 heavy material without much expressive tempo variation), and can form the basis of computer processing that is decidedly faster than human.

classmethods::
private:: categories

method:: kr

argument:: chain
[fft] Audio input to track, already passed through an FFT UGen; the expected size of FFT is 1024 for 44100 and 48000 sampling rate, and 2048 for double those. No other sampling rates are supported.
argument:: lock
[sk] If this argument is greater than 0.5, the tracker will lock at its current periodicity and continue from the current phase. Whilst it updates the model's phase and period, this is not reflected in the output until lock goes back below 0.5.
returns::
Four k-rate outputs:
code::
#quarternotetick, eighthnotetick, sixteenthnotetick, tempo = BeatTrack.kr(chain, 0)
::

instancemethods::
private:: init

examples::

code::

//this is a one minute pop song; you should load something equivalent for testing
d = Buffer.read(s, "/Volumes/data/stevebeattrack/samples/100.wav");


//you can also test at 48000 and it should work
(
a = SynthDef(\help_beattrack, { |out, vol=1.0, beepvol=1.0, lock=0|
	var in, fft, resample;
	var trackb, trackh, trackq, tempo;
	var bsound, hsound, qsound, beep;

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

	fft = FFT(LocalBuf(1024), in); // for sampling rates 44100 and 48000

	#trackb, trackh, trackq, tempo = BeatTrack.kr(fft, lock);

	beep = SinOsc.ar(1000, 0.0, Decay.kr(trackb, 0.1));

	Out.ar(out, Pan2.ar((vol * in) + (beepvol * beep), 0.0))

}).play
)

a.set(\vol,0.0);
a.set(\vol,1.0);

a.set(\beepvol,1.0);
a.set(\beepvol,0.0);

a.set(\lock,1); //fix it rigidly from current phase/period solution
a.set(\lock,0); //unfix, back to tracking
::

track audio in (try clapping a beat or beatboxing, but allow up to 6 seconds for tracking to begin) and spawning stuff at quarters, eighths and sixteenths:

code::
(
SynthDef(\help_beattrack2, { |out|
	var trackb, trackh, trackq, tempo;
	var source;
	var bsound, hsound, qsound;

	source = SoundIn.ar(0);

	#trackb, trackh, trackq, tempo = BeatTrack.kr(FFT(LocalBuf(1024)));

	bsound = Pan2.ar(LPF.ar(WhiteNoise.ar * Decay.kr(trackb, 0.05), 1000), 0.0);

	hsound = Pan2.ar(BPF.ar(WhiteNoise.ar * Decay.kr(trackh, 0.05), 3000, 0.66), -0.5);

	qsound = Pan2.ar(HPF.ar(WhiteNoise.ar * Decay.kr(trackq, 0.05),5000), 0.5);

	Out.ar(out, bsound + hsound + qsound);
}).play;
)
::

