src/musicutils.h

   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 */
  75 smpl_t aubio_unwrap2pi (smpl_t phase);
  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 */
 110 smpl_t aubio_hztomel (smpl_t freq);
 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 */
 138 smpl_t aubio_meltohz (smpl_t mel);
 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  */
 166 smpl_t aubio_hztomel_htk (smpl_t freq);
 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 */
 186 smpl_t aubio_meltohz_htk (smpl_t mel);
 187
 188 /** convert frequency (Hz) to midi value (0-128) */
 189 smpl_t aubio_freqtomidi (smpl_t freq);
 190
 191 /** convert midi value (0-128) to frequency (Hz) */
 192 smpl_t aubio_miditofreq (smpl_t midi);
 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 */
 212 smpl_t aubio_zero_crossing_rate (fvec_t * v);
 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 */