python/ext/py-musicutils.h

   1 #ifndef PY_AUBIO_MUSICUTILS_H
   2 #define PY_AUBIO_MUSICUTILS_H
   3
   4 static char Py_aubio_window_doc[] = ""
   5 "window(window_type, size)\n"
   6 "\n"
   7 "Create a window of length `size`. `window_type` should be one\n"
   8 "of the following:\n"
   9 "\n"
  10 "- `default` (same as `hanningz`).\n"
  11 "- `ones`\n"
  12 "- `rectangle`\n"
  13 "- `hamming`\n"
  14 "- `hanning`\n"
  15 "- `hanningz` [1]_\n"
  16 "- `blackman`\n"
  17 "- `blackman_harris`\n"
  18 "- `gaussian`\n"
  19 "- `welch`\n"
  20 "- `parzen`\n"
  21 "\n"
  22 "Parameters\n"
  23 "----------\n"
  24 "window_type : str\n"
  25 "   Type of window.\n"
  26 "size : int\n"
  27 "   Length of window.\n"
  28 "\n"
  29 "Returns\n"
  30 "-------\n"
  31 "fvec\n"
  32 "   Array of shape `(length,)` containing the new window.\n"
  33 "\n"
  34 "See Also\n"
  35 "--------\n"
  36 "pvoc, fft\n"
  37 "\n"
  38 "Examples\n"
  39 "--------\n"
  40 "Compute a zero-phase Hann window on `1024` points:\n"
  41 "\n"
  42 ">>> aubio.window('hanningz', 1024)\n"
  43 "array([  0.00000000e+00,   9.41753387e-06,   3.76403332e-05, ...,\n"
  44 "         8.46982002e-05,   3.76403332e-05,   9.41753387e-06], dtype=float32)\n"
  45 "\n"
  46 "Plot different window types with `matplotlib <https://matplotlib.org/>`_:\n"
  47 "\n"
  48 ">>> import matplotlib.pyplot as plt\n"
  49 ">>> modes = ['default', 'ones', 'rectangle', 'hamming', 'hanning',\n"
  50 "...          'hanningz', 'blackman', 'blackman_harris', 'gaussian',\n"
  51 "...          'welch', 'parzen']; n = 2048\n"
  52 ">>> for m in modes: plt.plot(aubio.window(m, n), label=m)\n"
  53 "...\n"
  54 ">>> plt.legend(); plt.show()\n"
  55 "\n"
  56 "Note\n"
  57 "----\n"
  58 "The following examples contain the equivalent source code to compute\n"
  59 "each type of window with `NumPy <https://numpy.org>`_:\n"
  60 "\n"
  61 ">>> n = 1024; x = np.arange(n, dtype=aubio.float_type)\n"
  62 ">>> ones = np.ones(n).astype(aubio.float_type)\n"
  63 ">>> rectangle = 0.5 * ones\n"
  64 ">>> hanning = 0.5 - 0.5 * np.cos(2 * np.pi * x / n)\n"
  65 ">>> hanningz = 0.5 * (1 - np.cos(2 * np.pi * x / n))\n"
  66 ">>> hamming = 0.54 - 0.46 * np.cos(2.*np.pi * x / (n - 1))\n"
  67 ">>> blackman = 0.42 \\\n"
  68 "...          - 0.50 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
  69 "...          + 0.08 * np.cos(4 * np.pi * x / (n - 1))\n"
  70 ">>> blackman_harris = 0.35875 \\\n"
  71 "...       - 0.48829 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
  72 "...       + 0.14128 * np.cos(4 * np.pi * x / (n - 1)) \\\n"
  73 "...       + 0.01168 * np.cos(6 * np.pi * x / (n - 1))\n"
  74 ">>> gaussian = np.exp( - 0.5 * ((x - 0.5 * (n - 1)) \\\n"
  75 "...                            / (0.25 * (n - 1)) )**2 )\n"
  76 ">>> welch = 1 - ((2 * x - n) / (n + 1))**2\n"
  77 ">>> parzen = 1 - np.abs((2 * x - n) / (n + 1))\n"
  78 ">>> default = hanningz\n"
  79 "References\n"
  80 "----------\n"
  81 #if 0
  82 "`Window function <https://en.wikipedia.org/wiki/Window_function>`_ on\n"
  83 "Wikipedia.\n"
  84 "\n"
  85 #endif
  86 ".. [1] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional\n"
  87 "   (?) implementations of a phase vocoder: the tricks of the trade.\n"
  88 "   In *Proceedings of the International Conference on Digital Audio\n"
  89 "   Effects* (DAFx-00), pages 37–44, University of Verona, Italy, 2000.\n"
  90 "   (`online version <"
  91 "https://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf"
  92 ">`_).\n"
  93 "";
  94
  95 PyObject * Py_aubio_window(PyObject *self, PyObject *args);
  96
  97 static char Py_aubio_level_lin_doc[] = ""
  98 "level_lin(x)\n"
  99 "\n"
 100 "Compute sound pressure level of `x`, on a linear scale.\n"
 101 "\n"
 102 "Parameters\n"
 103 "----------\n"
 104 "x : fvec\n"
 105 "   input vector\n"
 106 "\n"
 107 "Returns\n"
 108 "-------\n"
 109 "float\n"
 110 "   Linear level of `x`.\n"
 111 "\n"
 112 "Example\n"
 113 "-------\n"
 114 "\n"
 115 ">>> aubio.level_lin(aubio.fvec(numpy.ones(1024)))\n"
 116 "1.0\n"
 117 "\n"
 118 "Note\n"
 119 "----\n"
 120 "Computed as the average of the squared amplitudes:\n"
 121 "\n"
 122 ".. math:: L = \\frac {\\sum_{n=0}^{N-1} {x_n}^2} {N}\n"
 123 "\n"
 124 "See Also\n"
 125 "--------\n"
 126 "db_spl, silence_detection, level_detection\n"
 127 "";
 128
 129 PyObject * Py_aubio_level_lin(PyObject *self, PyObject *args);
 130
 131 static char Py_aubio_db_spl_doc[] = ""
 132 "db_spl(x)\n"
 133 "\n"
 134 "Compute Sound Pressure Level (SPL) of `x`, in dB.\n"
 135 "\n"
 136 "Parameters\n"
 137 "----------\n"
 138 "x : fvec\n"
 139 "   input vector\n"
 140 "\n"
 141 "Returns\n"
 142 "-------\n"
 143 "float\n"
 144 "   Level of `x`, in dB SPL.\n"
 145 "\n"
 146 "Example\n"
 147 "-------\n"
 148 "\n"
 149 ">>> aubio.db_spl(aubio.fvec(np.ones(1024)))\n"
 150 "1.0\n"
 151 ">>> aubio.db_spl(0.7*aubio.fvec(np.ones(32)))\n"
 152 "-3.098040819168091\n"
 153 "\n"
 154 "Note\n"
 155 "----\n"
 156 "Computed as `log10` of :py:func:`level_lin`:\n"
 157 "\n"
 158 ".. math::\n"
 159 "\n"
 160 "   {SPL}_{dB} = log10{\\frac {\\sum_{n=0}^{N-1}{x_n}^2} {N}}\n"
 161 "\n"
 162 "This quantity is often incorrectly called 'loudness'.\n"
 163 "\n"
 164 "See Also\n"
 165 "--------\n"
 166 "level_lin, silence_detection, level_detection\n"
 167 "";
 168
 169 PyObject * Py_aubio_db_spl(PyObject *self, PyObject *args);
 170
 171 static char Py_aubio_silence_detection_doc[] = ""
 172 "silence_detection(vec, level)\n"
 173 "\n"
 174 "Check if level of `vec`, in dB SPL, is under a given threshold.\n"
 175 "\n"
 176 "Parameters\n"
 177 "----------\n"
 178 "vec : fvec\n"
 179 "   input vector\n"
 180 "level : float\n"
 181 "   level threshold, in dB SPL\n"
 182 "\n"
 183 "Returns\n"
 184 "-------\n"
 185 "int\n"
 186 "   `1` if level of `vec`, in dB SPL, is under `level`,\n"
 187 "   `0` otherwise.\n"
 188 "\n"
 189 "Examples\n"
 190 "--------\n"
 191 "\n"
 192 ">>> aubio.silence_detection(aubio.fvec(32), -100.)\n"
 193 "1\n"
 194 ">>> aubio.silence_detection(aubio.fvec(np.ones(32)), 0.)\n"
 195 "0\n"
 196 "\n"
 197 "See Also\n"
 198 "--------\n"
 199 "level_detection, db_spl, level_lin\n"
 200 "";
 201
 202 PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
 203
 204 static char Py_aubio_level_detection_doc[] = ""
 205 "level_detection(vec, level)\n"
 206 "\n"
 207 "Check if `vec` is above threshold `level`, in dB SPL.\n"
 208 "\n"
 209 "Parameters\n"
 210 "----------\n"
 211 "vec : fvec\n"
 212 "   input vector\n"
 213 "level : float\n"
 214 "   level threshold, in dB SPL\n"
 215 "\n"
 216 "Returns\n"
 217 "-------\n"
 218 "float\n"
 219 "   `1.0` if level of `vec` in dB SPL is under `level`,\n"
 220 "   `db_spl(vec)` otherwise.\n"
 221 "\n"
 222 "Example\n"
 223 "-------\n"
 224 "\n"
 225 ">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -3.)\n"
 226 "1.0\n"
 227 ">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -4.)\n"
 228 "-3.0980708599090576\n"
 229 "\n"
 230 "See Also\n"
 231 "--------\n"
 232 "silence_detection, db_spl, level_lin\n"
 233 "";
 234
 235 PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);
 236
 237 static char Py_aubio_shift_doc[] = ""
 238 "shift(vec)\n"
 239 "\n"
 240 "Swap left and right partitions of a vector, in-place.\n"
 241 "\n"
 242 "Parameters\n"
 243 "----------\n"
 244 "vec : fvec\n"
 245 "   input vector to shift\n"
 246 "\n"
 247 "Returns\n"
 248 "-------\n"
 249 "fvec\n"
 250 "   The swapped vector.\n"
 251 "\n"
 252 "Notes\n"
 253 "-----\n"
 254 "The input vector is also modified.\n"
 255 "\n"
 256 "For a vector of length N, the partition is split at index N - N//2.\n"
 257 "\n"
 258 "Example\n"
 259 "-------\n"
 260 "\n"
 261 ">>> aubio.shift(aubio.fvec(np.arange(3)))\n"
 262 "array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
 263 "\n"
 264 "See Also\n"
 265 "--------\n"
 266 "ishift\n"
 267 "";
 268 PyObject * Py_aubio_shift(PyObject *self, PyObject *args);
 269
 270 static char Py_aubio_ishift_doc[] = ""
 271 "ishift(vec)\n"
 272 "\n"
 273 "Swap right and left partitions of a vector, in-place.\n"
 274 "\n"
 275 "Parameters\n"
 276 "----------\n"
 277 "vec : fvec\n"
 278 "   input vector to shift\n"
 279 "\n"
 280 "Returns\n"
 281 "-------\n"
 282 "fvec\n"
 283 "   The swapped vector.\n"
 284 "\n"
 285 "Notes\n"
 286 "-----\n"
 287 "The input vector is also modified.\n"
 288 "\n"
 289 "Unlike with :py:func:`shift`, the partition is split at index N//2.\n"
 290 "\n"
 291 "Example\n"
 292 "-------\n"
 293 "\n"
 294 ">>> aubio.ishift(aubio.fvec(np.arange(3)))\n"
 295 "array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
 296 "\n"
 297 "See Also\n"
 298 "--------\n"
 299 "shift\n"
 300 "";
 301 PyObject * Py_aubio_ishift(PyObject *self, PyObject *args);
 302
 303 static char Py_aubio_hztomel_doc[] = ""
 304 "hztomel(f, htk=False)\n"
 305 "\n"
 306 "Convert a scalar from frequency to mel scale.\n"
 307 "\n"
 308 "Parameters\n"
 309 "----------\n"
 310 "m : float\n"
 311 "   input frequency, in Hz\n"
 312 "htk : bool\n"
 313 "   if `True`, use Htk mel scale instead of Slaney.\n"
 314 "\n"
 315 "Returns\n"
 316 "-------\n"
 317 "float\n"
 318 "   output mel\n"
 319 "\n"
 320 "See Also\n"
 321 "--------\n"
 322 "meltohz\n"
 323 "";
 324 PyObject * Py_aubio_hztomel(PyObject *self, PyObject *args);
 325
 326 static char Py_aubio_meltohz_doc[] = ""
 327 "meltohz(m, htk=False)\n"
 328 "\n"
 329 "Convert a scalar from mel scale to frequency.\n"
 330 "\n"
 331 "Parameters\n"
 332 "----------\n"
 333 "m : float\n"
 334 "   input mel\n"
 335 "htk : bool\n"
 336 "   if `True`, use Htk mel scale instead of Slaney.\n"
 337 "\n"
 338 "Returns\n"
 339 "-------\n"
 340 "float\n"
 341 "   output frequency, in Hz\n"
 342 "\n"
 343 "See Also\n"
 344 "--------\n"
 345 "hztomel\n"
 346 "";
 347 PyObject * Py_aubio_meltohz(PyObject *self, PyObject *args);
 348
 349 static char Py_aubio_hztomel_htk_doc[] = ""
 350 "hztomel_htk(m)\n"
 351 "\n"
 352 "Same as `hztomel(m, htk=True)`\n"
 353 "\n"
 354 "See Also\n"
 355 "--------\n"
 356 "hztomel\n"
 357 "";
 358 PyObject * Py_aubio_hztomel_htk(PyObject *self, PyObject *args);
 359
 360 static char Py_aubio_meltohz_htk_doc[] = ""
 361 "meltohz_htk(m)\n"
 362 "\n"
 363 "Same as `meltohz(m, htk=True)`\n"
 364 "\n"
 365 "See Also\n"
 366 "--------\n"
 367 "meltohz\n"
 368 "";
 369 PyObject * Py_aubio_meltohz_htk(PyObject *self, PyObject *args);
 370
 371 #endif /* PY_AUBIO_MUSICUTILS_H */