aubio  0.4.9
musicutils.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003-2015 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  * various functions useful in audio signal processing
23  */
24 
25 #ifndef AUBIO_MUSICUTILS_H
26 #define AUBIO_MUSICUTILS_H
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /** create window
33 
34  \param window_type type of the window to create
35  \param size length of the window to create (see fvec_set_window())
36 
37 */
38 fvec_t *new_aubio_window (char_t * window_type, uint_t size);
39 
40 /** set elements of a vector to window coefficients
41 
42  \param window exsting ::fvec_t to use
43  \param window_type type of the window to create
44 
45  List of available window types: "rectangle", "hamming", "hanning",
46  "hanningz", "blackman", "blackman_harris", "gaussian", "welch", "parzen",
47  "default".
48 
49  "default" is equivalent to "hanningz".
50 
51  References:
52 
53  - <a href="http://en.wikipedia.org/wiki/Window_function">Window
54 function</a> on Wikipedia
55  - Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional (?)
56 implementations of a phase vocoder: the tricks of the trade. In Proceedings of
57 the International Conference on Digital Audio Effects (DAFx-00), pages 37–44,
58 Uni- versity of Verona, Italy, 2000.
59  (<a href="http://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf">
60  pdf</a>)
61 
62  */
63 uint_t fvec_set_window (fvec_t * window, char_t * window_type);
64 
65 /** compute the principal argument
66 
67  This function maps the input phase to its corresponding value wrapped in the
68 range \f$ [-\pi, \pi] \f$.
69 
70  \param phase unwrapped phase to map to the unit circle
71 
72  \return equivalent phase wrapped to the unit circle
73 
74 */
76 
77 /** convert frequency bin to midi value */
78 smpl_t aubio_bintomidi (smpl_t bin, smpl_t samplerate, smpl_t fftsize);
79 
80 /** convert midi value to frequency bin */
81 smpl_t aubio_miditobin (smpl_t midi, smpl_t samplerate, smpl_t fftsize);
82 
83 /** convert frequency bin to frequency (Hz) */
84 smpl_t aubio_bintofreq (smpl_t bin, smpl_t samplerate, smpl_t fftsize);
85 
86 /** convert frequency (Hz) to frequency bin */
87 smpl_t aubio_freqtobin (smpl_t freq, smpl_t samplerate, smpl_t fftsize);
88 
89 /** convert frequency (Hz) to mel
90 
91  \param freq input frequency, in Hz
92 
93  \return output mel
94 
95  Converts a scalar from the frequency domain to the mel scale using Slaney
96  Auditory Toolbox's implementation:
97 
98  If \f$ f < 1000 \f$, \f$ m = 3 f / 200 \f$.
99 
100  If \f$ f >= 1000 \f$, \f$ m = 1000 + 27 \frac{{ln}(f) - ln(1000))}
101  {{ln}(6400) - ln(1000)}
102  \f$
103 
104  See also
105  --------
106 
107  aubio_meltohz(), aubio_hztomel_htk().
108 
109 */
111 
112 /** convert mel to frequency (Hz)
113 
114  \param mel input mel
115 
116  \return output frequency, in Hz
117 
118  Converts a scalar from the mel scale to the frequency domain using Slaney
119  Auditory Toolbox's implementation:
120 
121  If \f$ f < 1000 \f$, \f$ f = 200 m/3 \f$.
122 
123  If \f$ f \geq 1000 \f$, \f$ f = 1000 + \left(\frac{6400}{1000}\right)
124  ^{\frac{m - 1000}{27}} \f$
125 
126  See also
127  --------
128 
129  aubio_hztomel(), aubio_meltohz_htk().
130 
131  References
132  ----------
133 
134  Malcolm Slaney, *Auditory Toolbox Version 2, Technical Report #1998-010*
135  https://engineering.purdue.edu/~malcolm/interval/1998-010/
136 
137 */
139 
140 /** convert frequency (Hz) to mel
141 
142  \param freq input frequency, in Hz
143 
144  \return output mel
145 
146  Converts a scalar from the frequency domain to the mel scale, using the
147  equation defined by O'Shaughnessy, as implemented in the HTK speech
148  recognition toolkit:
149 
150  \f$ m = 1127 + ln(1 + \frac{f}{700}) \f$
151 
152  See also
153  --------
154 
155  aubio_meltohz_htk(), aubio_hztomel().
156 
157  References
158  ----------
159 
160  Douglas O'Shaughnessy (1987). *Speech communication: human and machine*.
161  Addison-Wesley. p. 150. ISBN 978-0-201-16520-3.
162 
163  HTK Speech Recognition Toolkit: http://htk.eng.cam.ac.uk/
164 
165  */
167 
168 /** convert mel to frequency (Hz)
169 
170  \param mel input mel
171 
172  \return output frequency, in Hz
173 
174  Converts a scalar from the mel scale to the frequency domain, using the
175  equation defined by O'Shaughnessy, as implemented in the HTK speech
176  recognition toolkit:
177 
178  \f$ f = 700 * {e}^\left(\frac{f}{1127} - 1\right) \f$
179 
180  See also
181  --------
182 
183  aubio_hztomel_htk(), aubio_meltohz().
184 
185 */
187 
188 /** convert frequency (Hz) to midi value (0-128) */
190 
191 /** convert midi value (0-128) to frequency (Hz) */
193 
194 /** clean up cached memory at the end of program
195 
196  This function should be used at the end of programs to purge all cached
197  memory. So far it is only useful to clean FFTW's cache.
198 
199 */
200 void aubio_cleanup (void);
201 
202 /** zero-crossing rate (ZCR)
203 
204  The zero-crossing rate is the number of times a signal changes sign,
205  divided by the length of this signal.
206 
207  \param v vector to compute ZCR from
208 
209  \return zero-crossing rate of v
210 
211 */
213 
214 /** compute sound level on a linear scale
215 
216  This gives the average of the square amplitudes.
217 
218  \param v vector to compute level from
219 
220  \return level of v
221 
222 */
223 smpl_t aubio_level_lin (const fvec_t * v);
224 
225 /** compute sound pressure level (SPL) in dB
226 
227  This quantity is often wrongly called 'loudness'.
228 
229  This gives ten times the log10 of the average of the square amplitudes.
230 
231  \param v vector to compute dB SPL from
232 
233  \return level of v in dB SPL
234 
235 */
236 smpl_t aubio_db_spl (const fvec_t * v);
237 
238 /** check if buffer level in dB SPL is under a given threshold
239 
240  \param v vector to get level from
241  \param threshold threshold in dB SPL
242 
243  \return 0 if level is under the given threshold, 1 otherwise
244 
245 */
246 uint_t aubio_silence_detection (const fvec_t * v, smpl_t threshold);
247 
248 /** get buffer level if level >= threshold, 1. otherwise
249 
250  \param v vector to get level from
251  \param threshold threshold in dB SPL
252 
253  \return level in dB SPL if level >= threshold, 1. otherwise
254 
255 */
256 smpl_t aubio_level_detection (const fvec_t * v, smpl_t threshold);
257 
258 /** clamp the values of a vector within the range [-abs(max), abs(max)]
259 
260  \param in vector to clamp
261  \param absmax maximum value over which input vector elements should be clamped
262 
263 */
264 void fvec_clamp(fvec_t *in, smpl_t absmax);
265 
266 #ifdef __cplusplus
267 }
268 #endif
269 
270 #endif /* AUBIO_MUSICUTILS_H */
smpl_t aubio_bintofreq(smpl_t bin, smpl_t samplerate, smpl_t fftsize)
convert frequency bin to frequency (Hz)
smpl_t aubio_meltohz(smpl_t mel)
convert mel to frequency (Hz)
smpl_t aubio_bintomidi(smpl_t bin, smpl_t samplerate, smpl_t fftsize)
convert frequency bin to midi value
smpl_t aubio_unwrap2pi(smpl_t phase)
compute the principal argument
smpl_t aubio_level_lin(const fvec_t *v)
compute sound level on a linear scale
void aubio_cleanup(void)
clean up cached memory at the end of program
smpl_t aubio_freqtobin(smpl_t freq, smpl_t samplerate, smpl_t fftsize)
convert frequency (Hz) to frequency bin
smpl_t aubio_level_detection(const fvec_t *v, smpl_t threshold)
get buffer level if level >= threshold, 1.
float smpl_t
short sample format (32 or 64 bits)
Definition: types.h:41
smpl_t aubio_miditofreq(smpl_t midi)
convert midi value (0-128) to frequency (Hz)
void fvec_clamp(fvec_t *in, smpl_t absmax)
clamp the values of a vector within the range [-abs(max), abs(max)]
smpl_t aubio_freqtomidi(smpl_t freq)
convert frequency (Hz) to midi value (0-128)
uint_t fvec_set_window(fvec_t *window, char_t *window_type)
set elements of a vector to window coefficients
smpl_t aubio_miditobin(smpl_t midi, smpl_t samplerate, smpl_t fftsize)
convert midi value to frequency bin
smpl_t aubio_hztomel_htk(smpl_t freq)
convert frequency (Hz) to mel
smpl_t aubio_meltohz_htk(smpl_t mel)
convert mel to frequency (Hz)
Buffer for real data.
Definition: fvec.h:67
fvec_t * new_aubio_window(char_t *window_type, uint_t size)
create window
smpl_t aubio_db_spl(const fvec_t *v)
compute sound pressure level (SPL) in dB
unsigned int uint_t
unsigned integer
Definition: types.h:60
smpl_t aubio_zero_crossing_rate(fvec_t *v)
zero-crossing rate (ZCR)
uint_t aubio_silence_detection(const fvec_t *v, smpl_t threshold)
check if buffer level in dB SPL is under a given threshold
char char_t
character
Definition: types.h:64
smpl_t aubio_hztomel(smpl_t freq)
convert frequency (Hz) to mel