ref: 0bb2d633db7f614b18087b1c0adbe391e1259ef0
parent: 55b62606a151b9343b509dda6cc46a7bc54174e9
author: Paul Brossier <piem@piem.org>
date: Fri Oct 26 15:02:39 EDT 2018
[python] improve docstrings for db_spl, level_lin, level_detection, silence_detection
--- a/python/ext/py-musicutils.h
+++ b/python/ext/py-musicutils.h
@@ -16,58 +16,142 @@
PyObject * Py_aubio_window(PyObject *self, PyObject *args);
static char Py_aubio_level_lin_doc[] = ""
-"level_lin(fvec) -> fvec\n"
+"level_lin(x)\n"
"\n"
-"Compute sound level on a linear scale.\n"
+"Compute sound pressure level of `x`, on a linear scale.\n"
"\n"
-"This gives the average of the square amplitudes.\n"
+"Parameters\n"
+"----------\n"
+"x : fvec\n"
+" input vector\n"
"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" Linear level of `x`.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> level_Lin(numpy.ones(1024))\n"
-"1.0";
+">>> aubio.level_lin(aubio.fvec(numpy.ones(1024)))\n"
+"1.0\n"
+"\n"
+"Note\n"
+"----\n"
+"Computed as the average of the squared amplitudes:\n"
+"\n"
+".. math:: L = \\frac {\\sum_{n=0}^{N-1} {x_n}^2} {N}\n"+"\n"
+"See Also\n"
+"--------\n"
+"db_spl, silence_detection, level_detection\n"
+"";
PyObject * Py_aubio_level_lin(PyObject *self, PyObject *args);
static char Py_aubio_db_spl_doc[] = ""
-"Compute sound pressure level (SPL) in dB\n"
+"db_spl(x)\n"
"\n"
-"This quantity is often wrongly called 'loudness'.\n"
+"Compute Sound Pressure Level (SPL) of `x`, in dB.\n"
"\n"
-"This gives ten times the log10 of the average of the square amplitudes.\n"
+"Parameters\n"
+"----------\n"
+"x : fvec\n"
+" input vector\n"
"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" Level of `x`, in dB SPL.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> db_spl(numpy.ones(1024))\n"
-"1.0";
+">>> aubio.db_spl(aubio.fvec(np.ones(1024)))\n"
+"1.0\n"
+">>> aubio.db_spl(0.7*aubio.fvec(np.ones(32)))\n"
+"-3.098040819168091\n"
+"\n"
+"Note\n"
+"----\n"
+"Computed as `log10` of :py:func:`level_lin`:\n"
+"\n"
+".. math::\n"
+"\n"
+" {SPL}_{dB} = log10{\\frac {\\sum_{n=0}^{N-1}{x_n}^2} {N}}\n"+"\n"
+"This quantity is often incorrectly called 'loudness'.\n"
+"\n"
+"See Also\n"
+"--------\n"
+"level_lin, silence_detection, level_detection\n"
+"";
PyObject * Py_aubio_db_spl(PyObject *self, PyObject *args);
static char Py_aubio_silence_detection_doc[] = ""
-"Check if buffer level in dB SPL is under a given threshold\n"
+"silence_detection(vec, level)\n"
"\n"
-"Return 0 if level is under the given threshold, 1 otherwise.\n"
+"Check if level of `vec`, in dB SPL, is under a given threshold.\n"
"\n"
-"Example\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector\n"
+"level : float\n"
+" level threshold, in dB SPL\n"
+"\n"
+"Returns\n"
"-------\n"
+"int\n"
+" `1` if level of `vec`, in dB SPL, is under `level`,\n"
+" `0` otherwise.\n"
"\n"
-">>> import numpy\n"""
-">>> silence_detection(numpy.ones(1024, dtype=\"float32\"), -80)\n"
-"0";
+"Examples\n"
+"--------\n"
+"\n"
+">>> aubio.silence_detection(aubio.fvec(32), -100.)\n"
+"1\n"
+">>> aubio.silence_detection(aubio.fvec(np.ones(32)), 0.)\n"
+"0\n"
+"\n"
+"See Also\n"
+"--------\n"
+"level_detection, db_spl, level_lin\n"
+"";
PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
static char Py_aubio_level_detection_doc[] = ""
-"Get buffer level in dB SPL if over a given threshold, 1. otherwise.\n"
+"level_detection(vec, level)\n"
"\n"
+"Check if `vec` is above threshold `level`, in dB SPL.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector\n"
+"level : float\n"
+" level threshold, in dB SPL\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" `1.0` if level of `vec` in dB SPL is under `level`,\n"
+" `db_spl(vec)` otherwise.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> import numpy\n"""
-">>> level_detection(0.7*numpy.ones(1024, dtype=\"float32\"), -80)\n"
-"0";
+">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -3.)\n"
+"1.0\n"
+">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -4.)\n"
+"-3.0980708599090576\n"
+"\n"
+"See Also\n"
+"--------\n"
+"silence_detection, db_spl, level_lin\n"
+"";
PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);