update onsetdetection.h docs

update onsetdetection.h docs

diff --git a/src/onsetdetection.h b/src/onsetdetection.h
index 3f20a4594438aec56f22d0627b8fb7b2d71ebe3e..c6bae9b92a286f16eba55b1c0f33843edc91ccf7 100644 (file)
--- a/src/onsetdetection.h
+++ b/src/onsetdetection.h
@@ -17,27 +17,21 @@
         
 */
 
-/** @file
- *
- * Onset detection functions
- *
- * These functions are adapted from Juan Pablo Bello matlab code.
- *
- * - all of the following onset detection function take as arguments the fft of
- *   a windowed signal ( be created with an aubio_pvoc).
- *
- *
- * (the phasevocoder implementation does implement an fftshift like)
- *
- * - they output one smpl_t per frame and per channel (stored in a fvec_t * of
- *   size [channels][1])
- *
- *  Some of the functions should be improved by - downsampling the input of the
- *  phasevocoder - oversampling the ouput 
- *
- *  \todo write a generic driver (with a phase vocoder and the appropriate 
- *  resampling)
- */
+/** \file
+ 
+  Onset detection functions
+ 
+  All of the following onset detection function take as arguments the FFT of a
+  windowed signal (as created with aubio_pvoc). They output one smpl_t per
+  buffer and per channel (stored in a vector of size [channels]x[1]).
+ 
+  These functions were first adapted from Juan Pablo Bello's code, and now
+  include further improvements and modifications made within aubio.
+ 
+  \todo Write a generic driver similar to pitchdetection.c, including the phase
+  vocoder, the silence detection, and the peak picking.
+
+*/
 
 
 #ifndef ONSETDETECTION_H
@@ -54,61 +48,120 @@ typedef enum {
         aubio_onset_hfc,            /**< high frequency content */
         aubio_onset_complex,        /**< complex domain */        
         aubio_onset_phase,          /**< phase fast */            
-        aubio_onset_kl,             /**< Kullback Liebler (Hainsworth et al.,  Onset detection in musical audio signals) */
-        aubio_onset_mkl             /**< modified Kullback Liebler (Hainsworth et al.,  Onset detection in musical audio signals) */
+        aubio_onset_kl,             /**< Kullback Liebler */
+        aubio_onset_mkl             /**< modified Kullback Liebler */
 } aubio_onsetdetection_type;
 
 /** onsetdetection structure */
 typedef struct _aubio_onsetdetection_t aubio_onsetdetection_t;
 /** Energy based onset detection function 
- *
- * calculates the local energy profile
- *
- *     - buffer 1024
- *     - overlap 512
- */
+ 
+  This function calculates the local energy of the input spectral frame.
+  
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_energy(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
 /** High Frequency Content onset detection function
- *
- *     - buffer 1024
- *     - overlap 512
- */
+ 
+  This method computes the High Frequency Content (HFC) of the input spectral
+  frame. The resulting function is efficient at detecting percussive onsets.
+
+  Paul Masri. Computer modeling of Sound for Transformation and Synthesis of
+  Musical Signal. PhD dissertation, University of Bristol, UK, 1996.
+  
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_hfc(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
 /** Complex Domain Method onset detection function 
- * 
- *     From C. Duxbury & J. Pablo Bello
- *             
- *     - buffer 512
- *     - overlap 128
- *     - dowfact 8
- *     - interpfact 2
- */
+ 
+  Christopher Duxbury, Mike E. Davies, and Mark B. Sandler. Complex domain
+  onset detection for musical signals. In Proceedings of the Digital Audio
+  Effects Conference, DAFx-03, pages 90­93, London, UK, 2003.
+
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_complex(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
 /** Phase Based Method onset detection function 
- *
- *     - buffer 512
- *     - overlap 128
- *     - dowfact 8
- *     - interpfact 2
- */
+
+  Juan-Pablo Bello, Mike P. Davies, and Mark B. Sandler. Phase-based note onset
+  detection for music signals. In Proceedings of the IEEE International
+  Conference on Acoustics Speech and Signal Processing, pages 441­444,
+  Hong-Kong, 2003.
+
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_phase(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
 /** Spectral difference method onset detection function 
- *
- *     - buffer 512
- *     - overlap 128
- *     - dowfact 8
- *     - interpfact 2
- */
+
+  Jonhatan Foote and Shingo Uchihashi. The beat spectrum: a new approach to
+  rhythm analysis. In IEEE International Conference on Multimedia and Expo
+  (ICME 2001), pages 881­884, Tokyo, Japan, August 2001.
+
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_specdiff(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
-/** Kullback-Liebler onset detection function */
+/** Kullback-Liebler onset detection function 
+  
+  Stephen Hainsworth and Malcom Macleod. Onset detection in music audio
+  signals. In Proceedings of the International Computer Music Conference
+  (ICMC), Singapore, 2003.
+  
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_kl(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
-/** Modified Kullback-Liebler onset detection function */
+/** Modified Kullback-Liebler onset detection function 
+
+  Paul Brossier, ``Automatic annotation of musical audio for interactive
+  systems'', Chapter 2, Temporal segmentation, PhD thesis, Centre for Digital
+  music, Queen Mary University of London, London, UK, 2003.
+
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+  \param fftgrain input spectral frame
+  \param onset output onset detection function
+
+*/
 void aubio_onsetdetection_mkl(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
-/** Generic function pointing to the choosen one */
+/** execute onset detection function on a spectral frame 
+
+  Generic function to compute onset detection.
+ 
+  \param o onset detection object as returned by new_aubio_onsetdetection
+  \param fftgrain input signal spectrum as computed by aubio_pvoc_do
+  \param onset output vector (one sample long, to send to the peak picking)
+
+*/
 void aubio_onsetdetection(aubio_onsetdetection_t *o, cvec_t * fftgrain, fvec_t * onset);
-/** Allocate memory for an onset detection */
+/** creation of an onset detection object 
+
+  \param type onset detection mode
+  \param size length of the input spectrum frame
+  \param channels number of input channels
+
+*/
 aubio_onsetdetection_t * new_aubio_onsetdetection(aubio_onsetdetection_type type, uint_t size, uint_t channels);
-/** Free memory for an onset detection */
+/** deletion of an onset detection object
+
+  \param o onset detection object as returned by new_aubio_pitchfcomb
+
+*/
 void aubio_onsetdetection_free(aubio_onsetdetection_t *o);
 
 #ifdef __cplusplus