source: src/spectral/specdesc.h @ c0608bd

feature/autosinkfeature/constantqfeature/pitchshiftfeature/pydocstringsfeature/timestretchpitchshiftsamplertimestretchyinfft+
Last change on this file since c0608bd was c0608bd, checked in by Paul Brossier <piem@piem.org>, 8 years ago

src/spectral/: improve documentation

  • Property mode set to 100644
File size: 6.3 KB
Line 
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  \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 441­444,
60  Hong-Kong, 2003.
61
62  \b \p specdiff : Spectral difference method onset detection function
63
64  Jonhatan Foote and Shingo Uchihashi. The beat spectrum: a new approach to
65  rhythm analysis. In IEEE International Conference on Multimedia and Expo
66  (ICME 2001), pages 881­884, Tokyo, Japan, August 2001.
67
68  \b \p kl : Kullback-Liebler onset detection function
69 
70  Stephen Hainsworth and Malcom Macleod. Onset detection in music audio
71  signals. In Proceedings of the International Computer Music Conference
72  (ICMC), Singapore, 2003.
73
74  \b \p mkl : Modified Kullback-Liebler onset detection function
75
76  Paul Brossier, ``Automatic annotation of musical audio for interactive
77  systems'', Chapter 2, Temporal segmentation, PhD thesis, Centre for Digital
78  music, Queen Mary University of London, London, UK, 2006.
79
80  \b \p specflux : Spectral Flux
81
82  Simon Dixon, Onset Detection Revisited, in ``Proceedings of the 9th
83  International Conference on Digital Audio Effects'' (DAFx-06), Montreal,
84  Canada, 2006.
85
86  \subsection shapedesc Spectral shape descriptors
87
88  The following descriptors are described in:
89
90  Geoffroy Peeters, <i>A large set of audio features for sound description
91  (similarity and classification) in the CUIDADO project</i>, CUIDADO I.S.T.
92  Project Report 2004 (<a
93  href="http://www.ircam.fr/anasyn/peeters/ARTICLES/Peeters_2003_cuidadoaudiofeatures.pdf">pdf</a>)
94
95  \b \p centroid : Spectral centroid
96
97  The spectral centroid represents the barycenter of the spectrum.
98
99  \e Note: This function returns the result in bin. To get the spectral
100  centroid in Hz, aubio_bintofreq() should be used.
101
102  \b \p spread : Spectral spread
103
104  The spectral spread is the variance of the spectral distribution around its
105  centroid.
106
107  See also <a href="http://en.wikipedia.org/wiki/Standard_deviation">Standard
108  deviation</a> on Wikipedia.
109
110  \b \p skewness : Spectral skewness
111
112  Similarly, the skewness is computed from the third order moment of the
113  spectrum. A negative skewness indicates more energy on the lower part of the
114  spectrum. A positive skewness indicates more energy on the high frequency of
115  the spectrum.
116
117  See also <a href="http://en.wikipedia.org/wiki/Skewness">Skewness</a> on
118  Wikipedia.
119
120  \b \p kurtosis : Spectral kurtosis
121
122  The kurtosis is a measure of the flatness of the spectrum, computed from the
123  fourth order moment.
124
125  See also <a href="http://en.wikipedia.org/wiki/Kurtosis">Kurtosis</a> on
126  Wikipedia.
127
128  \b \p slope : Spectral slope
129
130  The spectral slope represents decreasing rate of the spectral amplitude,
131  computed using a linear regression.
132
133  \b \p decrease : Spectral decrease
134
135  The spectral decrease is another representation of the decreasing rate, 
136  based on perceptual criteria.
137
138  \b \p rolloff : Spectral roll-off
139
140  This function returns the bin number below which 95% of the spectrum energy
141  is found.
142
143  \example spectral/test-specdesc.c
144
145*/
146
147
148#ifndef ONSETDETECTION_H
149#define ONSETDETECTION_H
150
151#ifdef __cplusplus
152extern "C" {
153#endif
154
155/** spectral description structure */
156typedef struct _aubio_specdesc_t aubio_specdesc_t;
157
158/** execute spectral description function on a spectral frame
159
160  Generic function to compute spectral detescription.
161 
162  \param o spectral description object as returned by new_aubio_specdesc()
163  \param fftgrain input signal spectrum as computed by aubio_pvoc_do
164  \param desc output vector (one sample long, to send to the peak picking)
165
166*/
167void aubio_specdesc_do (aubio_specdesc_t * o, cvec_t * fftgrain,
168    fvec_t * desc);
169
170/** creation of a spectral description object
171
172  \param method spectral description method
173  \param buf_size length of the input spectrum frame
174
175  The parameter \p method is a string that can be any of:
176
177    - `energy`, `hfc`, `complex`, `phase`, `specdiff`, `kl`, `mkl`, `specflux`
178    - `centroid`, `spread`, `skewness`, `kurtosis`, `slope`, `decrease`, `rolloff`
179
180*/
181aubio_specdesc_t *new_aubio_specdesc (char_t * method, uint_t buf_size);
182
183/** deletion of a spectral descriptor
184
185  \param o spectral descriptor object as returned by new_aubio_specdesc()
186
187*/
188void del_aubio_specdesc (aubio_specdesc_t * o);
189
190#ifdef __cplusplus
191}
192#endif
193
194#endif /* ONSETDETECTION_H */
Note: See TracBrowser for help on using the repository browser.