Ignore:
Timestamp:
Oct 26, 2018, 7:02:39 PM (5 years ago)
Author:
Paul Brossier <piem@piem.org>
Branches:
feature/autosink, feature/cnn, feature/cnn_org, feature/constantq, feature/crepe, feature/crepe_org, feature/pitchshift, feature/pydocstrings, feature/timestretch, fix/ffmpeg5, master
Children:
7a7dea2
Parents:
55b6260
Message:

[python] improve docstrings for db_spl, level_lin, level_detection, silence_detection

File:
1 edited

Legend:

Unmodified
Added
Removed

  • python/ext/py-musicutils.h

    r55b6260 r0bb2d63  
    1717
    1818static char Py_aubio_level_lin_doc[] = ""
    19 "level_lin(fvec) -> fvec\n"
     19"level_lin(x)\n"
    2020"\n"
    21 "Compute sound level on a linear scale.\n"
     21"Compute sound pressure level of `x`, on a linear scale.\n"
    2222"\n"
    23 "This gives the average of the square amplitudes.\n"
     23"Parameters\n"
     24"----------\n"
     25"x : fvec\n"
     26"   input vector\n"
     27"\n"
     28"Returns\n"
     29"-------\n"
     30"float\n"
     31"   Linear level of `x`.\n"
    2432"\n"
    2533"Example\n"
    2634"-------\n"
    2735"\n"
    28 ">>> level_Lin(numpy.ones(1024))\n"
    29 "1.0";
     36">>> aubio.level_lin(aubio.fvec(numpy.ones(1024)))\n"
     37"1.0\n"
     38"\n"
     39"Note\n"
     40"----\n"
     41"Computed as the average of the squared amplitudes:\n"
     42"\n"
     43".. math:: L = \\frac {\\sum_{n=0}^{N-1} {x_n}^2} {N}\n"
     44"\n"
     45"See Also\n"
     46"--------\n"
     47"db_spl, silence_detection, level_detection\n"
     48"";
    3049
    3150PyObject * Py_aubio_level_lin(PyObject *self, PyObject *args);
    3251
    3352static char Py_aubio_db_spl_doc[] = ""
    34 "Compute sound pressure level (SPL) in dB\n"
     53"db_spl(x)\n"
    3554"\n"
    36 "This quantity is often wrongly called 'loudness'.\n"
     55"Compute Sound Pressure Level (SPL) of `x`, in dB.\n"
    3756"\n"
    38 "This gives ten times the log10 of the average of the square amplitudes.\n"
     57"Parameters\n"
     58"----------\n"
     59"x : fvec\n"
     60"   input vector\n"
     61"\n"
     62"Returns\n"
     63"-------\n"
     64"float\n"
     65"   Level of `x`, in dB SPL.\n"
    3966"\n"
    4067"Example\n"
    4168"-------\n"
    4269"\n"
    43 ">>> db_spl(numpy.ones(1024))\n"
    44 "1.0";
     70">>> aubio.db_spl(aubio.fvec(np.ones(1024)))\n"
     71"1.0\n"
     72">>> aubio.db_spl(0.7*aubio.fvec(np.ones(32)))\n"
     73"-3.098040819168091\n"
     74"\n"
     75"Note\n"
     76"----\n"
     77"Computed as `log10` of :py:func:`level_lin`:\n"
     78"\n"
     79".. math::\n"
     80"\n"
     81"   {SPL}_{dB} = log10{\\frac {\\sum_{n=0}^{N-1}{x_n}^2} {N}}\n"
     82"\n"
     83"This quantity is often incorrectly called 'loudness'.\n"
     84"\n"
     85"See Also\n"
     86"--------\n"
     87"level_lin, silence_detection, level_detection\n"
     88"";
    4589
    4690PyObject * Py_aubio_db_spl(PyObject *self, PyObject *args);
    4791
    4892static char Py_aubio_silence_detection_doc[] = ""
    49 "Check if buffer level in dB SPL is under a given threshold\n"
     93"silence_detection(vec, level)\n"
    5094"\n"
    51 "Return 0 if level is under the given threshold, 1 otherwise.\n"
     95"Check if level of `vec`, in dB SPL, is under a given threshold.\n"
     96"\n"
     97"Parameters\n"
     98"----------\n"
     99"vec : fvec\n"
     100"   input vector\n"
     101"level : float\n"
     102"   level threshold, in dB SPL\n"
     103"\n"
     104"Returns\n"
     105"-------\n"
     106"int\n"
     107"   `1` if level of `vec`, in dB SPL, is under `level`,\n"
     108"   `0` otherwise.\n"
     109"\n"
     110"Examples\n"
     111"--------\n"
     112"\n"
     113">>> aubio.silence_detection(aubio.fvec(32), -100.)\n"
     114"1\n"
     115">>> aubio.silence_detection(aubio.fvec(np.ones(32)), 0.)\n"
     116"0\n"
     117"\n"
     118"See Also\n"
     119"--------\n"
     120"level_detection, db_spl, level_lin\n"
     121"";
     122
     123PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
     124
     125static char Py_aubio_level_detection_doc[] = ""
     126"level_detection(vec, level)\n"
     127"\n"
     128"Check if `vec` is above threshold `level`, in dB SPL.\n"
     129"\n"
     130"Parameters\n"
     131"----------\n"
     132"vec : fvec\n"
     133"   input vector\n"
     134"level : float\n"
     135"   level threshold, in dB SPL\n"
     136"\n"
     137"Returns\n"
     138"-------\n"
     139"float\n"
     140"   `1.0` if level of `vec` in dB SPL is under `level`,\n"
     141"   `db_spl(vec)` otherwise.\n"
    52142"\n"
    53143"Example\n"
    54144"-------\n"
    55145"\n"
    56 ">>> import numpy\n"""
    57 ">>> silence_detection(numpy.ones(1024, dtype=\"float32\"), -80)\n"
    58 "0";
    59 
    60 PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
    61 
    62 static char Py_aubio_level_detection_doc[] = ""
    63 "Get buffer level in dB SPL if over a given threshold, 1. otherwise.\n"
     146">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -3.)\n"
     147"1.0\n"
     148">>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -4.)\n"
     149"-3.0980708599090576\n"
    64150"\n"
    65 "Example\n"
    66 "-------\n"
    67 "\n"
    68 ">>> import numpy\n"""
    69 ">>> level_detection(0.7*numpy.ones(1024, dtype=\"float32\"), -80)\n"
    70 "0";
     151"See Also\n"
     152"--------\n"
     153"silence_detection, db_spl, level_lin\n"
     154"";
    71155
    72156PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);
Note: See TracChangeset for help on using the changeset viewer.