OnsetsDS

/*

        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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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") [dc, nyq, real[1], imag[1], real[2], imag[2]...] - NB it's more efficient to provide polar data from SC

        ODS_FFT_SC3_POLAR,          ///< SuperCollider, polar co-ords ("SCPolarBuf") [dc, nyq, mag[1], phase[1], mag[2], phase[2]...]

        ODS_FFT_FFTW3_HC, ///< FFTW <a href="http://www.fftw.org/fftw3_doc/The-Halfcomplex_002dformat-DFT.html">"halfcomplex"</a> format - [dc, real[1], real[2] ... nyq, imag[nyq-1] ... imag[1]]

        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