source: python/ext/py-musicutils.h

Last change on this file was bc66f1d, checked in by Paul Brossier <piem@piem.org>, 20 months ago

[py] add meltohz and hztomel with minimal doc

  • Property mode set to 100644
File size: 8.4 KB
Line 
1#ifndef PY_AUBIO_MUSICUTILS_H
2#define PY_AUBIO_MUSICUTILS_H
3
4static 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
95PyObject * Py_aubio_window(PyObject *self, PyObject *args);
96
97static 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
129PyObject * Py_aubio_level_lin(PyObject *self, PyObject *args);
130
131static 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
169PyObject * Py_aubio_db_spl(PyObject *self, PyObject *args);
170
171static 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
202PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
203
204static 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
235PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);
236
237static 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"";
268PyObject * Py_aubio_shift(PyObject *self, PyObject *args);
269
270static 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"";
301PyObject * Py_aubio_ishift(PyObject *self, PyObject *args);
302
303static 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"";
324PyObject * Py_aubio_hztomel(PyObject *self, PyObject *args);
325
326static 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"";
347PyObject * Py_aubio_meltohz(PyObject *self, PyObject *args);
348
349static 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"";
358PyObject * Py_aubio_hztomel_htk(PyObject *self, PyObject *args);
359
360static 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"";
369PyObject * Py_aubio_meltohz_htk(PyObject *self, PyObject *args);
370
371#endif /* PY_AUBIO_MUSICUTILS_H */
Note: See TracBrowser for help on using the repository browser.