Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: e28db25801
Fetching contributors…

Cannot retrieve contributors at this time

276 lines (230 sloc) 10.679 kB
/*
OnsetsDS - real time musical onset detection library.
Copyright (c) 2007 Dan Stowell. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/** \file */
#ifndef _OnsetsDS_
#define _OnsetsDS_
#ifdef __cplusplus
extern "C" {
#endif
#include <stdio.h>
#include <string.h>
#include <stdbool.h>
#include <math.h>
////////////////////////////////////////////////////////////////////////////////
// Macros and consts
//log(0.1)
#define ods_log1 -2.30258509
#define PI 3.1415926535898f
#define MINUSPI -3.1415926535898f
#define TWOPI 6.28318530717952646f
#define INV_TWOPI 0.1591549430919f
#define ods_abs(a) ((a)<0? -(a) : (a))
#define ods_max(a,b) (((a) > (b)) ? (a) : (b))
#define ods_min(a,b) (((a) < (b)) ? (a) : (b))
#define ODS_LOG_LOWER_LIMIT 2e-42
#define ODS_LOGOF_LOG_LOWER_LIMIT -96.0154267
#define ODS_ABSINVOF_LOGOF_LOG_LOWER_LIMIT 0.010414993
////////////////////////////////////////////////////////////////////////////////
// Constants
/**
* Types of incoming FFT data format. OnsetsDS needs to know where the FFT
* data comes from in order to interpret it correctly.
*/
enum onsetsds_fft_types {
ODS_FFT_SC3_COMPLEX, ///< SuperCollider, cartesian co-ords ("SCComplexBuf") - NB it's more efficient to provide polar data from SC
ODS_FFT_SC3_POLAR, ///< SuperCollider, polar co-ords ("SCPolarBuf")
ODS_FFT_FFTW3_HC, ///< FFTW <a href="http://www.fftw.org/fftw3_doc/The-Halfcomplex_002dformat-DFT.html">"halfcomplex"</a> format
ODS_FFT_FFTW3_R2C ///< FFTW regular format, typically produced using <a href="http://www.fftw.org/fftw3_doc/One_002dDimensional-DFTs-of-Real-Data.html#One_002dDimensional-DFTs-of-Real-Data">real-to-complex</a> transform
};
/**
* Types of onset detection function
*/
enum onsetsds_odf_types {
ODS_ODF_POWER, ///< Power
ODS_ODF_MAGSUM, ///< Sum of magnitudes
ODS_ODF_COMPLEX, ///< Complex-domain deviation
ODS_ODF_RCOMPLEX, ///< Complex-domain deviation, rectified (only increases counted)
ODS_ODF_PHASE, ///< Phase deviation
ODS_ODF_WPHASE, ///< Weighted phase deviation
ODS_ODF_MKL ///< Modified Kullback-Liebler deviation
};
/**
* Types of whitening - may not all be implemented yet.
*/
enum onsetsds_wh_types {
ODS_WH_NONE, ///< No whitening - onsetsds_whiten() becomes a no-op
ODS_WH_ADAPT_MAX1, ///< Adaptive whitening - tracks recent-peak-magnitude in each bin, normalises that to 1
ODS_WH_NORMMAX, ///< Simple normalisation - each frame is normalised (independent of others) so largest magnitude becomes 1. Not implemented.
ODS_WH_NORMMEAN ///< Simple normalisation - each frame is normalised (independent of others) so mean magnitude becomes 1. Not implemented.
};
////////////////////////////////////////////////////////////////////////////////
// Structs
typedef struct OdsPolarBin { float mag, phase; } OdsPolarBin;
typedef struct OdsPolarBuf {
float dc, nyq;
OdsPolarBin bin[1];
} OdsPolarBuf;
/// The main data structure for the onset detection routine
typedef struct OnsetsDS {
/// "data" is a pointer to the memory that must be EXTERNALLY allocated.
/// Other pointers will point to locations within this memory.
float *data,
*psp, ///< Peak Spectral Profile - size is numbins+2, data is stored in order dc through to nyquist
*odfvals, // odfvals[0] will be the current val, odfvals[1] prev, etc
*sortbuf, // Used to calculate the median
*other; // Typically stores data about the previous frame
OdsPolarBuf* curr; // Current FFT frame, as polar
float
srate, ///< The sampling rate of the input audio. Set by onsetsds_init()
// Adaptive whitening params
relaxtime, ///< Do NOT set this directly. Use onsetsds_setrelax() which will also update relaxcoef.
relaxcoef, ///< Relaxation coefficient (memory coefficient). See also onsetsds_setrelax()
floor, ///< floor - the lowest value that a PSP magnitude can take.
/// A parameter for the ODF. For most this is a magnitude threshold for a single bin to be considered;
/// but for #ODS_ODF_MKL it is the "epsilon" parameter.
odfparam,
/// Value used internally to scale ODF value according to the FFT frame size. Automatically set by onsetsds_init()
normfactor,
// ODF val after median processing
odfvalpost,
// Previous val is needed for threshold-crossing detection
odfvalpostprev,
/// Threshold (of ODF value, after median processing) for detection.
/// Values between 0 and 1 are expected, but outside this range may
/// sometimes be appropriate too.
thresh;
int odftype, ///< Choose from #onsetsds_odf_types
whtype, ///< Choose from #onsetsds_wh_types
fftformat; ///< Choose from #onsetsds_fft_types
bool whiten, ///< Whether to apply whitening - onsetsds_init() decides this on your behalf
detected,///< Output val - true if onset detected in curr frame
/**
NOT YET USED: Whether to convert magnitudes to log domain before processing. This is done as follows:
Magnitudes below a log-lower-limit threshold (ODS_LOG_LOWER_LIMIT) are pushed up to that threshold (to avoid log(0) infinity problems),
then the log is taken. The values are re-scaled to a similar range as the linear-domain values (assumed to lie
between zero and approximately one) by subtracting log(ODS_LOG_LOWER_LIMIT) and then dividing by abs(log(ODS_LOG_LOWER_LIMIT)).
*/
logmags,
med_odd; ///< Whether median span is odd or not (used internally)
unsigned int
/// Number of frames used in median calculation
medspan,
/// Size of enforced gap between detections, measured in FFT frames.
mingap, gapleft;
size_t fftsize, numbins; // numbins is the count not including DC/nyq
} OnsetsDS;
////////////////////////////////////////////////////////////////////////////////
// Function prototypes
/**
* \defgroup MainUserFuncs Main user functions
*/
//@{
/**
* Determine how many bytes of memory must be allocated (e.g. using malloc) to
* accompany the OnsetsDS struct, operating using the specified settings (used to
* store part-processed FFT data etc). The user must
* call this, and then allocate the memory, BEFORE calling onsetsds_init().
* @param odftype Which onset detection function (ODF) you'll be using, chosen from #onsetsds_odf_types
* @param fftsize Size of FFT: 512 is recommended.
* @param medspan The number of past frames that will be used for median calculation during triggering
*/
size_t onsetsds_memneeded (int odftype, size_t fftsize, unsigned int medspan);
/**
* Initialise the OnsetsDS struct and its associated memory, ready to detect
* onsets using the specified settings. Must be called before any call to
* onsetsds_process().
*
* Note: you can change the onset detection function type in mid-operation
* by calling onsetsds_init() again, but because memory will be reset this
* will behave as if starting from scratch (rather than being aware of the past
* few frames of sound). Do not attempt to change the
* onset detection function in a more hacky way (e.g. fiddling with the struct)
* because memory is set up differently for each of the different ODFs.
* @param ods An instance of the OnsetsDS struct
* @param odsdata A pointer to the memory allocated, size given by onsetsds_memneeded().
* @param fftformat Which format of FFT data is to be expected, chosen from #onsetsds_fft_types
* @param odftype Which onset detection function (ODF) you'll be using, chosen from #onsetsds_odf_types
* @param fftsize Size of FFT: 512 or 1024 is recommended.
* @param medspan The number of past frames that will be used for median calculation during triggering
* @param srate The sampling rate of the input audio
*/
void onsetsds_init(OnsetsDS* ods, float* odsdata, int fftformat,
int odftype, size_t fftsize, unsigned int medspan, float srate);
/**
* Process a single FFT data frame in the audio signal. Note that processing
* assumes that each call to onsetsds_process() is on a subsequent frame in
* the same audio stream - to handle multiple streams you must use separate
* OnsetsDS structs and memory!
*
* This function's main purpose is to call some of the library's other functions,
* in the expected sequence.
*/
bool onsetsds_process(OnsetsDS* ods, float* fftbuf);
//@}
////////////////////////////////////////////////////////////////////////////////
// Function prototypes less commonly called by users
/**
* \defgroup LessCommonFuncs Other useful functions
*/
//@{
/**
* Set the "memory coefficient" indirectly via the time for the
* memory to decay by 60 dB.
* @param ods The OnsetsDS
* @param time The time in seconds
* @param hopsize The FFT frame hopsize (typically this will be half the FFT frame size)
*/
void onsetsds_setrelax(OnsetsDS* ods, float time, size_t hopsize);
//@}
////////////////////////////////////////////////////////////////////////////////
// Function prototypes not typically called by users
/**
* \defgroup OtherFuncs Other functions, not typically called by users
*/
//@{
/**
* Load the current frame of FFT data into the OnsetsDS struct.
*
* Not typically called directly by users since onsetsds_process() calls this.
*/
void onsetsds_loadframe(OnsetsDS* ods, float* fftbuf);
/**
* Apply adaptive whitening to the FFT data in the OnsetsDS struct.
*
* Not typically called directly by users since onsetsds_process() calls this.
*/
void onsetsds_whiten(OnsetsDS* ods);
/**
* Calculate the Onset Detection Function (includes scaling ODF outputs to
* similar range)
*
* Not typically called directly by users since onsetsds_process() calls this.
*/
void onsetsds_odf(OnsetsDS* ods);
/**
* Detects salient peaks in Onset Detection Function by removing the median,
* then thresholding. Afterwards, the member ods.detected will indicate whether
* or not an onset was detected.
*
* Not typically called directly by users since onsetsds_process() calls this.
*/
void onsetsds_detect(OnsetsDS* ods);
//@}
////////////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
}
#endif
#endif
Jump to Line
Something went wrong with that request. Please try again.