annotate README.md @ 117:ca2d83d29814 tip master

Merge branch 'release/1.0.5'
author Adam Stark <adamstark.uk@gmail.com>
date Fri, 18 Aug 2023 20:07:33 +0200
parents c58f01834337 75aacd17ad03
children
rev   line source
adamstark@40 1 BTrack - A Real-Time Beat Tracker
adamstark@40 2 =================================
adamstark@40 3
adamstark@48 4 *by Adam Stark, Matthew Davies and Mark Plumbley.*
adamstark@48 5
adamstark@116 6 ![Version](https://img.shields.io/badge/version-1.0.5-green.svg?style=flat-square)
adamstark@116 7 ![Licence](https://img.shields.io/badge/licence-GPLv3-blue.svg?style=flat-square)
adamstark@116 8 ![Language](https://img.shields.io/badge/language-C++-yellow.svg?style=flat-square)
adamstark@48 9
adamstark@48 10 About BTrack
adamstark@48 11 ------------
adamstark@48 12
adamstark@67 13 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 14
adamstark@48 15 Full details of the working of the algorithm can be found in:
adamstark@48 16
adamstark@48 17 * 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 18
adamstark@48 19 * 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 20
adamstark@81 21 BTrack is made available under the GNU General Public License, version 3. Please see the included LICENSE.txt for more details.
adamstark@48 22
adamstark@49 23 Versions
adamstark@49 24 --------
adamstark@49 25
adamstark@116 26 ==== 1.0.5 ==== (18th August 2023)
adamstark@116 27
adamstark@116 28 * Code improvements and modernisation
adamstark@116 29 * Move to CMake
adamstark@116 30 * Move to doctest for unit tests
adamstark@116 31
adamstark@94 32 ==== 1.0.4 ==== (18th June 2016)
adamstark@94 33
adamstark@94 34 * Added option of using Kiss FFT
adamstark@94 35 * Implementation changes to improve efficiency
adamstark@94 36
adamstark@86 37 ==== 1.0.3 ==== (10th January 2016)
adamstark@86 38
adamstark@86 39 * Fixed implementation error in complex spectral difference (thanks to @zbanks for pointing it out)
adamstark@86 40 * Small change to python module build script
adamstark@86 41
adamstark@82 42 ==== 1.0.2 ==== (25th November 2014)
adamstark@82 43
adamstark@82 44 * Added updated Max external project and associated files
adamstark@82 45 * Fixed a couple of bugs
adamstark@82 46
adamstark@82 47 ==== 1.0.1 ==== (21st November 2014)
adamstark@75 48
adamstark@75 49 * Moved to git & updated README
adamstark@75 50 * No implementation changes
adamstark@75 51
adamstark@70 52 ==== 1.0.0 ==== (8th July 2014)
adamstark@70 53
adamstark@70 54 * Many updates to stability and improvements to implementation
adamstark@70 55
adamstark@70 56 ==== 0.9.0 ==== (circa 2008/2009)
adamstark@49 57
adamstark@49 58 * This is the original version of the BTrack algorithm
adamstark@49 59
adamstark@49 60
adamstark@49 61
adamstark@61 62 Usage - C++
adamstark@61 63 -----------
adamstark@61 64
adamstark@61 65 **STEP 1**
adamstark@61 66
adamstark@61 67 Include the BTrack header file as follows:
adamstark@61 68
adamstark@61 69 #include "BTrack.h"
adamstark@61 70
adamstark@61 71 **STEP 2**
adamstark@61 72
adamstark@61 73 Instantiate the algorithm by one of the following:
adamstark@61 74
adamstark@61 75 // to use the default 512 hop size and 1024 frame size
adamstark@61 76 BTrack b;
adamstark@61 77
adamstark@61 78 or:
adamstark@61 79
adamstark@61 80 // to specify a hop size (e.g. 512) and have a frame size of 2 x the hop size
adamstark@61 81 BTrack b(512);
adamstark@61 82
adamstark@61 83 or:
adamstark@61 84
adamstark@61 85 // to specify both the hop size and frame size
adamstark@61 86 BTrack b(512,1024);
adamstark@61 87
adamstark@61 88 **STEP 3.1 - Audio Input**
adamstark@61 89
adamstark@61 90 In the processing loop, fill a double precision array with one frame of audio samples (as determined in step 2):
adamstark@61 91
adamstark@61 92 double *frame;
adamstark@61 93
adamstark@61 94 // !
adamstark@61 95 // do something here to fill the frame with audio samples
adamstark@61 96 // !
adamstark@61 97
adamstark@61 98 and then call:
adamstark@61 99
adamstark@61 100 b.processAudioFrame(frame);
adamstark@61 101
adamstark@61 102 and to check for beats, simply call:
adamstark@61 103
adamstark@61 104 if (b.beatDueInCurrentFrame())
adamstark@61 105 {
adamstark@61 106 // do something on the beat
adamstark@61 107 }
adamstark@61 108
adamstark@61 109 **STEP 3.2 - Onset Detection Function Input**
adamstark@61 110
adamstark@75 111 The algorithm can process onset detection function samples. Given a double precision onset detection function sample called 'newSample', at each step, call:
adamstark@61 112
adamstark@61 113 b.processOnsetDetectionFunctionSample(newSample);
adamstark@61 114
adamstark@61 115 and then check for beats with:
adamstark@61 116
adamstark@61 117 if (b.beatDueInCurrentFrame())
adamstark@61 118 {
adamstark@61 119 // do something on the beat
adamstark@61 120 }
adamstark@70 121
adamstark@81 122 Requirements
adamstark@81 123 ------------
adamstark@81 124
adamstark@81 125 To compile BTrack, you will require the following libraries:
adamstark@81 126
adamstark@81 127 * libsamplerate
adamstark@81 128
adamstark@95 129 And either:
adamstark@95 130
adamstark@95 131 * FFTW (add the flag -DUSE_FFTW)
adamstark@95 132
adamstark@95 133 or:
adamstark@95 134
adamstark@95 135 * Kiss FFT (included with project, use the flag -DUSE_KISS_FFT)
adamstark@95 136
adamstark@113 137 Please ensure that if you are using these libraries that you have secured any required licences for your project. The licence on this library does not cover any third party licences.
adamstark@70 138
adamstark@70 139 License
adamstark@70 140 -------
adamstark@70 141
adamstark@70 142 Copyright (c) 2014 Queen Mary University of London
adamstark@70 143
adamstark@70 144 This program is free software: you can redistribute it and/or modify
adamstark@70 145 it under the terms of the GNU General Public License as published by
adamstark@70 146 the Free Software Foundation, either version 3 of the License, or
adamstark@70 147 (at your option) any later version.
adamstark@70 148
adamstark@70 149 This program is distributed in the hope that it will be useful,
adamstark@70 150 but WITHOUT ANY WARRANTY; without even the implied warranty of
adamstark@70 151 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
adamstark@70 152 GNU General Public License for more details.
adamstark@70 153
adamstark@70 154 You should have received a copy of the GNU General Public License
adamstark@70 155 along with this program. If not, see <http://www.gnu.org/licenses/>.