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://profs.sci.univr.it/%7Edafx/Final-Papers/ps/Bernardini.ps.gz">
  60   ps.gz</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 midi value (0-128) */
  90 smpl_t aubio_freqtomidi (smpl_t freq);
  91
  92 /** convert midi value (0-128) to frequency (Hz) */
  93 smpl_t aubio_miditofreq (smpl_t midi);
  94
  95 /** clean up cached memory at the end of program
  96
  97   This function should be used at the end of programs to purge all cached
  98   memory. So far it is only useful to clean FFTW's cache.
  99
 100 */
 101 void aubio_cleanup (void);
 102
 103 /** zero-crossing rate (ZCR)
 104
 105   The zero-crossing rate is the number of times a signal changes sign,
 106   divided by the length of this signal.
 107
 108   \param v vector to compute ZCR from
 109
 110   \return zero-crossing rate of v
 111
 112 */
 113 smpl_t aubio_zero_crossing_rate (fvec_t * v);
 114
 115 /** compute sound level on a linear scale
 116
 117   This gives the average of the square amplitudes.
 118
 119   \param v vector to compute level from
 120
 121   \return level of v
 122
 123 */
 124 smpl_t aubio_level_lin (fvec_t * v);
 125
 126 /** compute sound pressure level (SPL) in dB
 127
 128   This quantity is often wrongly called 'loudness'.
 129
 130   This gives ten times the log10 of the average of the square amplitudes.
 131
 132   \param v vector to compute dB SPL from
 133
 134   \return level of v in dB SPL
 135
 136 */
 137 smpl_t aubio_db_spl (fvec_t * v);
 138
 139 /** check if buffer level in dB SPL is under a given threshold
 140
 141   \param v vector to get level from
 142   \param threshold threshold in dB SPL
 143
 144   \return 0 if level is under the given threshold, 1 otherwise
 145
 146 */
 147 uint_t aubio_silence_detection (fvec_t * v, smpl_t threshold);
 148
 149 /** get buffer level if level >= threshold, 1. otherwise
 150
 151   \param v vector to get level from
 152   \param threshold threshold in dB SPL
 153
 154   \return level in dB SPL if level >= threshold, 1. otherwise
 155
 156 */
 157 smpl_t aubio_level_detection (fvec_t * v, smpl_t threshold);
 158
 159 #ifdef __cplusplus
 160 }
 161 #endif
 162
 163 #endif /* _AUBIO__MUSICUTILS_H */