src/spectral/specdesc.h

   1 /*
   2   Copyright (C) 2003-2013 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   \section specdesc Spectral description functions
  30
  31   A list of the spectral description methods currently available follows.
  32
  33   \subsection onsetdesc Onset detection functions
  34
  35   These functions are designed to raise at notes attacks in music signals.
  36
  37   \b \p energy : Energy based onset detection function
  38
  39   This function calculates the local energy of the input spectral frame.
  40
  41   \b \p hfc : High Frequency Content onset detection function
  42
  43   This method computes the High Frequency Content (HFC) of the input spectral
  44   frame. The resulting function is efficient at detecting percussive onsets.
  45
  46   Paul Masri. Computer modeling of Sound for Transformation and Synthesis of
  47   Musical Signal. PhD dissertation, University of Bristol, UK, 1996.
  48
  49   \b \p complex : Complex Domain Method onset detection function
  50
  51   Christopher Duxbury, Mike E. Davies, and Mark B. Sandler. Complex domain
  52   onset detection for musical signals. In Proceedings of the Digital Audio
  53   Effects Conference, DAFx-03, pages 90-93, London, UK, 2003.
  54
  55   \b \p phase : Phase Based Method onset detection function
  56
  57   Juan-Pablo Bello, Mike P. Davies, and Mark B. Sandler. Phase-based note onset
  58   detection for music signals. In Proceedings of the IEEE International
  59   Conference on Acoustics Speech and Signal Processing, pages 441444,
  60   Hong-Kong, 2003.
  61
  62   \b \p wphase : Weighted Phase Deviation onset detection function
  63
  64   S. Dixon. Onset detection revisited. In Proceedings of the 9th International
  65   Conference on Digital Audio Ef- fects (DAFx) , pages 133–137, 2006.
  66
  67   http://www.eecs.qmul.ac.uk/~simond/pub/2006/dafx.pdf
  68
  69   \b \p specdiff : Spectral difference method onset detection function
  70
  71   Jonhatan Foote and Shingo Uchihashi. The beat spectrum: a new approach to
  72   rhythm analysis. In IEEE International Conference on Multimedia and Expo
  73   (ICME 2001), pages 881884, Tokyo, Japan, August 2001.
  74
  75   \b \p kl : Kullback-Liebler onset detection function
  76
  77   Stephen Hainsworth and Malcom Macleod. Onset detection in music audio
  78   signals. In Proceedings of the International Computer Music Conference
  79   (ICMC), Singapore, 2003.
  80
  81   \b \p mkl : Modified Kullback-Liebler onset detection function
  82
  83   Paul Brossier, ``Automatic annotation of musical audio for interactive
  84   systems'', Chapter 2, Temporal segmentation, PhD thesis, Centre for Digital
  85   music, Queen Mary University of London, London, UK, 2006.
  86
  87   \b \p specflux : Spectral Flux
  88
  89   Simon Dixon, Onset Detection Revisited, in ``Proceedings of the 9th
  90   International Conference on Digital Audio Effects'' (DAFx-06), Montreal,
  91   Canada, 2006.
  92
  93   \subsection shapedesc Spectral shape descriptors
  94
  95   The following descriptors are described in:
  96
  97   Geoffroy Peeters, <i>A large set of audio features for sound description
  98   (similarity and classification) in the CUIDADO project</i>, CUIDADO I.S.T.
  99   Project Report 2004 (<a
 100   href="http://www.ircam.fr/anasyn/peeters/ARTICLES/Peeters_2003_cuidadoaudiofeatures.pdf">pdf</a>)
 101
 102   \b \p centroid : Spectral centroid
 103
 104   The spectral centroid represents the barycenter of the spectrum.
 105
 106   \e Note: This function returns the result in bin. To get the spectral
 107   centroid in Hz, aubio_bintofreq() should be used.
 108
 109   \b \p spread : Spectral spread
 110
 111   The spectral spread is the variance of the spectral distribution around its
 112   centroid.
 113
 114   See also <a href="http://en.wikipedia.org/wiki/Standard_deviation">Standard
 115   deviation</a> on Wikipedia.
 116
 117   \b \p skewness : Spectral skewness
 118
 119   Similarly, the skewness is computed from the third order moment of the
 120   spectrum. A negative skewness indicates more energy on the lower part of the
 121   spectrum. A positive skewness indicates more energy on the high frequency of
 122   the spectrum.
 123
 124   See also <a href="http://en.wikipedia.org/wiki/Skewness">Skewness</a> on
 125   Wikipedia.
 126
 127   \b \p kurtosis : Spectral kurtosis
 128
 129   The kurtosis is a measure of the flatness of the spectrum, computed from the
 130   fourth order moment.
 131
 132   See also <a href="http://en.wikipedia.org/wiki/Kurtosis">Kurtosis</a> on
 133   Wikipedia.
 134
 135   \b \p slope : Spectral slope
 136
 137   The spectral slope represents decreasing rate of the spectral amplitude,
 138   computed using a linear regression.
 139
 140   \b \p decrease : Spectral decrease
 141
 142   The spectral decrease is another representation of the decreasing rate,
 143   based on perceptual criteria.
 144
 145   \b \p rolloff : Spectral roll-off
 146
 147   This function returns the bin number below which 95% of the spectrum energy
 148   is found.
 149
 150   \example spectral/test-specdesc.c
 151
 152 */
 153
 154
 155 #ifndef AUBIO_SPECDESC_H
 156 #define AUBIO_SPECDESC_H
 157
 158 #ifdef __cplusplus
 159 extern "C" {
 160 #endif
 161
 162 /** spectral description structure */
 163 typedef struct _aubio_specdesc_t aubio_specdesc_t;
 164
 165 /** execute spectral description function on a spectral frame
 166
 167   Generic function to compute spectral description.
 168
 169   \param o spectral description object as returned by new_aubio_specdesc()
 170   \param fftgrain input signal spectrum as computed by aubio_pvoc_do
 171   \param desc output vector (one sample long, to send to the peak picking)
 172
 173 */
 174 void aubio_specdesc_do (aubio_specdesc_t * o, const cvec_t * fftgrain,
 175     fvec_t * desc);
 176
 177 /** creation of a spectral description object
 178
 179   \param method spectral description method
 180   \param buf_size length of the input spectrum frame
 181
 182   The parameter \p method is a string that can be any of:
 183
 184     - onset novelty functions: `complex`, `energy`, `hfc`, `kl`, `mkl`,
 185     `phase`, `specdiff`, `specflux`, `wphase`,
 186
 187     - spectral descriptors: `centroid`, `decrease`, `kurtosis`, `rolloff`,
 188     `skewness`, `slope`, `spread`.
 189
 190 */
 191 aubio_specdesc_t *new_aubio_specdesc (const char_t * method, uint_t buf_size);
 192
 193 /** deletion of a spectral descriptor
 194
 195   \param o spectral descriptor object as returned by new_aubio_specdesc()
 196
 197 */
 198 void del_aubio_specdesc (aubio_specdesc_t * o);
 199
 200 #ifdef __cplusplus
 201 }
 202 #endif
 203
 204 #endif /* AUBIO_SPECDESC_H */