adamstark@5: //=======================================================================
adamstark@5: /** @file BTrack.h
adamstark@6:  *  @brief BTrack - a real-time beat tracker
adamstark@5:  *  @author Adam Stark
adamstark@5:  *  @copyright Copyright (C) 2008-2014  Queen Mary University of London
adamstark@5:  *
adamstark@5:  * This program is free software: you can redistribute it and/or modify
adamstark@5:  * it under the terms of the GNU General Public License as published by
adamstark@5:  * the Free Software Foundation, either version 3 of the License, or
adamstark@5:  * (at your option) any later version.
adamstark@5:  *
adamstark@5:  * This program is distributed in the hope that it will be useful,
adamstark@5:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
adamstark@5:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
adamstark@5:  * GNU General Public License for more details.
adamstark@5:  *
adamstark@5:  * You should have received a copy of the GNU General Public License
adamstark@5:  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
adamstark@5:  */
adamstark@5: //=======================================================================
adamstark@5: 
adamstark@5: #ifndef __BTRACK_H
adamstark@5: #define __BTRACK_H
adamstark@5: 
adamstark@18: #include "OnsetDetectionFunction.h"
adamstark@26: #include <vector>
adamstark@18: 
adamstark@23: //=======================================================================
adamstark@23: /** The main beat tracking class and the interface to the BTrack
adamstark@23:  * beat tracking algorithm. The algorithm can process either
adamstark@23:  * audio frames or onset detection function samples and also
adamstark@23:  * contains some static functions for calculating beat times in seconds
adamstark@23:  */
adamstark@5: class BTrack {
adamstark@5: 	
adamstark@5: public:
adamstark@14:     
adamstark@21:     //=======================================================================
adamstark@24:     /** Constructor assuming hop size of 512 and frame size of 1024 */
adamstark@19:     BTrack();
adamstark@14:     
adamstark@24:     /** Constructor assuming frame size will be double the hopSize
adamstark@23:      * @param hopSize the hop size in audio samples
adamstark@18:      */
adamstark@20:     BTrack(int hopSize_);
adamstark@18:     
adamstark@24:     /** Constructor taking both hopSize and frameSize
adamstark@23:      * @param hopSize the hop size in audio samples
adamstark@23:      * @param frameSize the frame size in audio samples
adamstark@18:      */
adamstark@20:     BTrack(int hopSize_,int frameSize_);
adamstark@18:     
adamstark@21:     //=======================================================================
adamstark@28:     /** Updates the hop and frame size used by the beat tracker 
adamstark@28:      * @param hopSize the hop size in audio samples
adamstark@28:      * @param frameSize the frame size in audio samples
adamstark@28:      */
adamstark@28:     void updateHopAndFrameSize(int hopSize_,int frameSize_);
adamstark@28:     
adamstark@28:     //=======================================================================
adamstark@23:     /** Process a single audio frame 
adamstark@23:      * @param frame a pointer to an array containing an audio frame. The number of samples should 
adamstark@23:      * match the frame size that the algorithm was initialised with.
adamstark@23:      */
adamstark@19:     void processAudioFrame(double *frame);
adamstark@18:     
adamstark@23:     /** Add new onset detection function sample to buffer and apply beat tracking 
adamstark@23:      * @param sample an onset detection function sample
adamstark@23:      */
adamstark@19:     void processOnsetDetectionFunctionSample(double sample);
adamstark@14:    
adamstark@21:     //=======================================================================
adamstark@20:     /** @returns the current hop size being used by the beat tracker */
adamstark@20:     int getHopSize();
adamstark@20:     
adamstark@21:     /** @returns true if a beat should occur in the current audio frame */
adamstark@21:     bool beatDueInCurrentFrame();
adamstark@21: 
adamstark@21:     /** @returns the current tempo estimate being used by the beat tracker */
adamstark@21:     double getCurrentTempoEstimate();
adamstark@21:     
adamstark@21:     /** @returns the most recent value of the cumulative score function */
adamstark@21:     double getLatestCumulativeScoreValue();
adamstark@21:     
adamstark@21:     //=======================================================================
adamstark@23:     /** Set the tempo of the beat tracker 
adamstark@23:      * @param tempo the tempo in beats per minute (bpm)
adamstark@23:      */
adamstark@20:     void setTempo(double tempo);
adamstark@14:     
adamstark@24:     /** Fix tempo to roughly around some value, so that the algorithm will only try to track
adamstark@23:      * tempi around the given tempo
adamstark@23:      * @param tempo the tempo in beats per minute (bpm)
adamstark@23:      */
adamstark@20:     void fixTempo(double tempo);
adamstark@14:     
adamstark@24:     /** Tell the algorithm to not fix the tempo anymore */
adamstark@20:     void doNotFixTempo();
adamstark@18:     
adamstark@21:     //=======================================================================
adamstark@24:     /** Calculates a beat time in seconds, given the frame number, hop size and sampling frequency.
adamstark@23:      * This version uses a long to represent the frame number
adamstark@23:      * @param frameNumber the index of the current frame 
adamstark@23:      * @param hopSize the hop size in audio samples
adamstark@23:      * @param fs the sampling frequency in Hz
adamstark@23:      * @returns a beat time in seconds
adamstark@23:      */
adamstark@18:     static double getBeatTimeInSeconds(long frameNumber,int hopSize,int fs);
adamstark@18:     
adamstark@24:     /** Calculates a beat time in seconds, given the frame number, hop size and sampling frequency.
adamstark@23:      * This version uses an int to represent the frame number
adamstark@23:      * @param frameNumber the index of the current frame
adamstark@23:      * @param hopSize the hop size in audio samples
adamstark@23:      * @param fs the sampling frequency in Hz
adamstark@23:      * @returns a beat time in seconds
adamstark@23:      */
adamstark@18:     static double getBeatTimeInSeconds(int frameNumber,int hopSize,int fs);
adamstark@18:     
adamstark@21: 		
adamstark@5: private:
adamstark@14:     
adamstark@23:     /** Initialises the algorithm, setting internal parameters and creating weighting vectors 
adamstark@23:      * @param hopSize_ the hop size in audio samples
adamstark@23:      * @param frameSize_ the frame size in audio samples
adamstark@23:      */
adamstark@20:     void initialise(int hopSize_,int frameSize_);
adamstark@19:     
adamstark@23:     /** Initialise with hop size and set all array sizes accordingly
adamstark@23:      * @param hopSize_ the hop size in audio samples
adamstark@23:      */
adamstark@20:     void setHopSize(int hopSize_);
adamstark@19:     
adamstark@23:     /** Resamples the onset detection function from an arbitrary number of samples to 512 */
adamstark@20:     void resampleOnsetDetectionFunction();
adamstark@14:     
adamstark@23:     /** Updates the cumulative score function with a new onset detection function sample 
adamstark@23:      * @param odfSample an onset detection function sample
adamstark@23:      */
adamstark@22:     void updateCumulativeScore(double odfSample);
adamstark@14: 	
adamstark@24:     /** Predicts the next beat, based upon the internal program state */
adamstark@20:     void predictBeat();
adamstark@14:     
adamstark@14:     /** Calculates the current tempo expressed as the beat period in detection function samples */
adamstark@20:     void calculateTempo();
adamstark@14:     
adamstark@24:     /** Calculates an adaptive threshold which is used to remove low level energy from detection
adamstark@14:      * function and emphasise peaks 
adamstark@23:      * @param x a pointer to an array containing onset detection function samples
adamstark@23:      * @param N the length of the array, x
adamstark@14:      */
adamstark@20:     void adaptiveThreshold(double *x,int N);
adamstark@14:     
adamstark@24:     /** Calculates the mean of values in an array between index locations [startIndex,endIndex]
adamstark@23:      * @param array a pointer to an array that contains the values we wish to find the mean from
adamstark@23:      * @param startIndex the start index from which we would like to calculate the mean
adamstark@23:      * @param endIndex the final index to which we would like to calculate the mean
adamstark@23:      * @returns the mean of the sub-section of the array
adamstark@23:      */
adamstark@22:     double calculateMeanOfArray(double *array,int startIndex,int endIndex);
adamstark@14:     
adamstark@24:     /** Normalises a given array
adamstark@23:      * @param array a pointer to the array we wish to normalise
adamstark@23:      * @param N the length of the array
adamstark@23:      */
adamstark@20:     void normaliseArray(double *array,int N);
adamstark@14:     
adamstark@24:     /** Calculates the balanced autocorrelation of the smoothed onset detection function
adamstark@23:      * @param onsetDetectionFunction a pointer to an array containing the onset detection function
adamstark@23:      */
adamstark@23:     void calculateBalancedACF(double *onsetDetectionFunction);
adamstark@14:     
adamstark@24:     /** Calculates the output of the comb filter bank */
adamstark@20:     void calculateOutputOfCombFilterBank();
adamstark@5: 	
adamstark@21:     //=======================================================================
adamstark@21: 
adamstark@24:     /** An OnsetDetectionFunction instance for calculating onset detection functions */
adamstark@21:     OnsetDetectionFunction odf;
adamstark@21:     
adamstark@21:     //=======================================================================
adamstark@5: 	// buffers
adamstark@26:     
adamstark@26:     std::vector<double> onsetDF;            /**< to hold onset detection function */
adamstark@26:     std::vector<double> cumulativeScore;    /**< to hold cumulative score */
adamstark@26:     
adamstark@21:     double resampledOnsetDF[512];           /**< to hold resampled detection function */
adamstark@5: 	
adamstark@21:     double acf[512];                        /**<  to hold autocorrelation function */
adamstark@5: 	
adamstark@21:     double weightingVector[128];            /**<  to hold weighting vector */
adamstark@5: 	
adamstark@21:     double combFilterBankOutput[128];       /**<  to hold comb filter output */
adamstark@21:     double tempoObservationVector[41];      /**<  to hold tempo version of comb filter output */
adamstark@5: 	
adamstark@21:     double delta[41];                       /**<  to hold final tempo candidate array */
adamstark@21:     double prevDelta[41];                   /**<  previous delta */
adamstark@21:     double prevDeltaFixed[41];              /**<  fixed tempo version of previous delta */
adamstark@5: 	
adamstark@21:     double tempoTransitionMatrix[41][41];   /**<  tempo transition matrix */
adamstark@5: 	
adamstark@21:     
adamstark@23: 	//=======================================================================
adamstark@19:     // parameters
adamstark@23:     
adamstark@23:     
adamstark@23:     double tightness;                       /**< the tightness of the weighting used to calculate cumulative score */
adamstark@23:     
adamstark@23:     double alpha;                           /**< the mix between the current detection function sample and the cumulative score's "momentum" */
adamstark@23:     
adamstark@23:     double beatPeriod;                      /**< the beat period, in detection function samples */
adamstark@23:     
adamstark@23:     double tempo;                           /**< the tempo in beats per minute */
adamstark@5: 	
adamstark@21:     double estimatedTempo;                  /**< the current tempo estimation being used by the algorithm */
adamstark@21:     
adamstark@21:     double latestCumulativeScoreValue;      /**< holds the latest value of the cumulative score function */
adamstark@21:     
adamstark@22:     double tempoToLagFactor;                /**< factor for converting between lag and tempo */
adamstark@5: 	
adamstark@22:     int m0;                                 /**< indicates when the next point to predict the next beat is */
adamstark@21:     
adamstark@21:     int beatCounter;                        /**< keeps track of when the next beat is - will be zero when the beat is due, and is set elsewhere in the algorithm to be positive once a beat prediction is made */
adamstark@5: 	
adamstark@21:     int hopSize;                            /**< the hop size being used by the algorithm */
adamstark@21:     
adamstark@21:     int onsetDFBufferSize;                  /**< the onset detection function buffer size */
adamstark@5: 	
adamstark@21:     bool tempoFixed;                        /**< indicates whether the tempo should be fixed or not */
adamstark@20:     
adamstark@21:     bool beatDueInFrame;                    /**< indicates whether a beat is due in the current frame */
adamstark@5: 
adamstark@5: };
adamstark@5: 
adamstark@5: #endif