src/spectral/specdesc.h

   1 /*
   2   Copyright (C) 2003-2009 Paul Brossier <piem@aubio.org>
   3
   4   This file is part of aubio.
   5
   6   aubio is free software: you can redistribute it and/or modify
   7   it under the terms of the GNU General Public License as published by
   8   the Free Software Foundation, either version 3 of the License, or
   9   (at your option) any later version.
  10
  11   aubio is distributed in the hope that it will be useful,
  12   but WITHOUT ANY WARRANTY; without even the implied warranty of
  13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14   GNU General Public License for more details.
  15
  16   You should have received a copy of the GNU General Public License
  17   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 */
  20
  21 /** \file
  22
  23   Spectral description functions
  24
  25   All of the following spectral description functions take as arguments the FFT
  26   of a windowed signal (as created with aubio_pvoc). They output one smpl_t per
  27   buffer (stored in a vector of size [1]).
  28
  29   A list of the spectral description methods currently available follows.
  30
  31   \section onsetdesc Onset detection functions
  32
  33   These functions are designed to raise at notes attacks in music signals.
  34
  35   \b \p energy : Energy based onset detection function
  36
  37   This function calculates the local energy of the input spectral frame.
  38
  39   \b \p hfc : High Frequency Content onset detection function
  40
  41   This method computes the High Frequency Content (HFC) of the input spectral
  42   frame. The resulting function is efficient at detecting percussive onsets.
  43
  44   Paul Masri. Computer modeling of Sound for Transformation and Synthesis of
  45   Musical Signal. PhD dissertation, University of Bristol, UK, 1996.
  46
  47   \b \p complex : Complex Domain Method onset detection function
  48
  49   Christopher Duxbury, Mike E. Davies, and Mark B. Sandler. Complex domain
  50   onset detection for musical signals. In Proceedings of the Digital Audio
  51   Effects Conference, DAFx-03, pages 90-93, London, UK, 2003.
  52
  53   \b \p phase : Phase Based Method onset detection function
  54
  55   Juan-Pablo Bello, Mike P. Davies, and Mark B. Sandler. Phase-based note onset
  56   detection for music signals. In Proceedings of the IEEE International
  57   Conference on Acoustics Speech and Signal Processing, pages 441444,
  58   Hong-Kong, 2003.
  59
  60   \b \p specdiff : Spectral difference method onset detection function
  61
  62   Jonhatan Foote and Shingo Uchihashi. The beat spectrum: a new approach to
  63   rhythm analysis. In IEEE International Conference on Multimedia and Expo
  64   (ICME 2001), pages 881884, Tokyo, Japan, August 2001.
  65
  66   \b \p kl : Kullback-Liebler onset detection function
  67
  68   Stephen Hainsworth and Malcom Macleod. Onset detection in music audio
  69   signals. In Proceedings of the International Computer Music Conference
  70   (ICMC), Singapore, 2003.
  71
  72   \b \p mkl : Modified Kullback-Liebler onset detection function
  73
  74   Paul Brossier, ``Automatic annotation of musical audio for interactive
  75   systems'', Chapter 2, Temporal segmentation, PhD thesis, Centre for Digital
  76   music, Queen Mary University of London, London, UK, 2006.
  77
  78   \b \p specflux : Spectral Flux
  79
  80   Simon Dixon, Onset Detection Revisited, in ``Proceedings of the 9th
  81   International Conference on Digital Audio Effects'' (DAFx-06), Montreal,
  82   Canada, 2006.
  83
  84   \section shapedesc Spectral shape descriptors
  85
  86   The following descriptors are described in:
  87
  88   Geoffroy Peeters, <i>A large set of audio features for sound description
  89   (similarity and classification) in the CUIDADO project</i>, CUIDADO I.S.T.
  90   Project Report 2004 (<a
  91   href="http://www.ircam.fr/anasyn/peeters/ARTICLES/Peeters_2003_cuidadoaudiofeatures.pdf">pdf</a>)
  92
  93   \b \p centroid : Spectral centroid
  94
  95   The spectral centroid represents the barycenter of the spectrum.
  96
  97   \e Note: This function returns the result in bin. To get the spectral
  98   centroid in Hz, aubio_bintofreq() should be used.
  99
 100   \b \p spread : Spectral spread
 101
 102   The spectral spread is the variance of the spectral distribution around its
 103   centroid.
 104
 105   See also <a href="http://en.wikipedia.org/wiki/Standard_deviation">Standard
 106   deviation</a> on Wikipedia.
 107
 108   \b \p skewness : Spectral skewness
 109
 110   Similarly, the skewness is computed from the third order moment of the
 111   spectrum. A negative skewness indicates more energy on the lower part of the
 112   spectrum. A positive skewness indicates more energy on the high frequency of
 113   the spectrum.
 114
 115   See also <a href="http://en.wikipedia.org/wiki/Skewness">Skewness</a> on
 116   Wikipedia.
 117
 118   \b \p kurtosis : Spectral kurtosis
 119
 120   The kurtosis is a measure of the flatness of the spectrum, computed from the
 121   fourth order moment.
 122
 123   See also <a href="http://en.wikipedia.org/wiki/Kurtosis">Kurtosis</a> on
 124   Wikipedia.
 125
 126   \b \p slope : Spectral slope
 127
 128   The spectral slope represents decreasing rate of the spectral amplitude,
 129   computed using a linear regression.
 130
 131   \b \p decrease : Spectral decrease
 132
 133   The spectral decrease is another representation of the decreasing rate,
 134   based on perceptual criteria.
 135
 136   \b \p rolloff : Spectral roll-off
 137
 138   This function returns the bin number below which 95% of the spectrum energy
 139   is found.
 140
 141 */
 142
 143
 144 #ifndef ONSETDETECTION_H
 145 #define ONSETDETECTION_H
 146
 147 #ifdef __cplusplus
 148 extern "C" {
 149 #endif
 150
 151 /** spectral description structure */
 152 typedef struct _aubio_specdesc_t aubio_specdesc_t;
 153
 154 /** execute spectral description function on a spectral frame
 155
 156   Generic function to compute spectral detescription.
 157
 158   \param o spectral description object as returned by new_aubio_specdesc()
 159   \param fftgrain input signal spectrum as computed by aubio_pvoc_do
 160   \param desc output vector (one sample long, to send to the peak picking)
 161
 162 */
 163 void aubio_specdesc_do (aubio_specdesc_t * o, cvec_t * fftgrain,
 164     fvec_t * desc);
 165
 166 /** creation of a spectral description object
 167
 168   \param method spectral description method
 169   \param buf_size length of the input spectrum frame
 170
 171 */
 172 aubio_specdesc_t *new_aubio_specdesc (char_t * method, uint_t buf_size);
 173
 174 /** deletion of a spectral descriptor
 175
 176   \param o spectral descriptor object as returned by new_aubio_specdesc()
 177
 178 */
 179 void del_aubio_specdesc (aubio_specdesc_t * o);
 180
 181 #ifdef __cplusplus
 182 }
 183 #endif
 184
 185 #endif /* ONSETDETECTION_H */