adamstark@40: BTrack - A Real-Time Beat Tracker
adamstark@40: =================================
adamstark@40: 
adamstark@86: ** Version 1.0.3 **
adamstark@48: 
adamstark@48: *by Adam Stark, Matthew Davies and Mark Plumbley.*
adamstark@48: 
adamstark@48: 
adamstark@48: About BTrack
adamstark@48: ------------
adamstark@48: 
adamstark@67: BTrack is a causal beat tracking algorithm intended for real-time use. It is implemented in C++ with wrappers for Python and the Vamp plug-in framework.
adamstark@48: 
adamstark@48: Full details of the working of the algorithm can be found in:
adamstark@48: 
adamstark@48: * Musicians and Machines: Bridging the Semantic Gap in Live Performance, Chapter 3, A. M. Stark, PhD Thesis, Queen Mary, University of London, 2011.
adamstark@48: 
adamstark@48: * Real-Time Beat-Synchronous Analysis of Musical Audio, A. M. Stark, M. E. P. Davies and M. D. Plumbley. In Proceedings of the 12th International Conference on Digital Audio Effects (DAFx-09), Como, Italy, September 1-4, 2009.
adamstark@48: 
adamstark@81: BTrack is made available under the GNU General Public License, version 3. Please see the included LICENSE.txt for more details.
adamstark@48: 
adamstark@49: Versions
adamstark@49: --------
adamstark@49: 
adamstark@86: ==== 1.0.3 ==== (10th January 2016)
adamstark@86: 
adamstark@86: * Fixed implementation error in complex spectral difference (thanks to @zbanks for pointing it out)
adamstark@86: * Small change to python module build script
adamstark@86: 
adamstark@82: ==== 1.0.2 ==== (25th November 2014)
adamstark@82: 
adamstark@82: * Added updated Max external project and associated files
adamstark@82: * Fixed a couple of bugs
adamstark@82: 
adamstark@82: ==== 1.0.1 ==== (21st November 2014)
adamstark@75: 
adamstark@75: * Moved to git & updated README
adamstark@75: * No implementation changes
adamstark@75: 
adamstark@70: ==== 1.0.0 ==== (8th July 2014)
adamstark@70: 
adamstark@70: * Many updates to stability and improvements to implementation
adamstark@70: 
adamstark@70: ==== 0.9.0 ==== (circa 2008/2009)
adamstark@49: 
adamstark@49: * This is the original version of the BTrack algorithm
adamstark@49: 
adamstark@49: 
adamstark@49: 
adamstark@61: Usage - C++
adamstark@61: -----------
adamstark@61: 
adamstark@61: **STEP 1**
adamstark@61: 
adamstark@61: Include the BTrack header file as follows:
adamstark@61: 
adamstark@61: 	#include "BTrack.h"
adamstark@61: 	
adamstark@61: **STEP 2**
adamstark@61: 
adamstark@61: Instantiate the algorithm by one of the following:
adamstark@61: 
adamstark@61: 	// to use the default 512 hop size and 1024 frame size
adamstark@61: 	BTrack b; 
adamstark@61: 
adamstark@61: or:	
adamstark@61: 
adamstark@61: 	// to specify a hop size (e.g. 512) and have a frame size of 2 x the hop size
adamstark@61: 	BTrack b(512); 
adamstark@61: 	
adamstark@61: or:
adamstark@61: 
adamstark@61: 	// to specify both the hop size and frame size
adamstark@61: 	BTrack b(512,1024);
adamstark@61: 	
adamstark@61: **STEP 3.1 - Audio Input**
adamstark@61: 
adamstark@61: In the processing loop, fill a double precision array with one frame of audio samples (as determined in step 2): 
adamstark@61: 
adamstark@61: 	double *frame; 
adamstark@61: 	
adamstark@61: 	// !
adamstark@61: 	// do something here to fill the frame with audio samples
adamstark@61: 	// !
adamstark@61: 
adamstark@61: and then call:
adamstark@61: 
adamstark@61: 	b.processAudioFrame(frame);
adamstark@61: 	
adamstark@61: and to check for beats, simply call:
adamstark@61: 
adamstark@61: 	if (b.beatDueInCurrentFrame())
adamstark@61: 	{
adamstark@61: 		// do something on the beat
adamstark@61: 	}
adamstark@61: 
adamstark@61: **STEP 3.2 - Onset Detection Function Input**	
adamstark@61: 
adamstark@75: The algorithm can process onset detection function samples. Given a double precision onset detection function sample called 'newSample', at each step, call:
adamstark@61: 
adamstark@61: 	b.processOnsetDetectionFunctionSample(newSample);
adamstark@61: 	
adamstark@61: and then check for beats with:
adamstark@61: 
adamstark@61: 	if (b.beatDueInCurrentFrame())
adamstark@61: 	{
adamstark@61: 		// do something on the beat
adamstark@61: 	}
adamstark@70: 
adamstark@81: Requirements
adamstark@81: ------------
adamstark@81: 
adamstark@81: To compile BTrack, you will require the following libraries:
adamstark@81: 
adamstark@81: * FFTW
adamstark@81: * libsamplerate
adamstark@81: 
adamstark@70: 
adamstark@70: License
adamstark@70: -------
adamstark@70: 
adamstark@70: Copyright (c) 2014 Queen Mary University of London
adamstark@70: 
adamstark@70: This program is free software: you can redistribute it and/or modify
adamstark@70: it under the terms of the GNU General Public License as published by
adamstark@70: the Free Software Foundation, either version 3 of the License, or
adamstark@70: (at your option) any later version.
adamstark@70: 
adamstark@70: This program is distributed in the hope that it will be useful,
adamstark@70: but WITHOUT ANY WARRANTY; without even the implied warranty of
adamstark@70: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
adamstark@70: GNU General Public License for more details.
adamstark@70: 
adamstark@70: You should have received a copy of the GNU General Public License
adamstark@70: along with this program.  If not, see <http://www.gnu.org/licenses/>.