shithub: aubio

Info  •  Files  •  Log  •  Branches

[python] add docstrings for pvoc

--- a/python/ext/py-phasevoc.c

+++ b/python/ext/py-phasevoc.c

@@ -1,7 +1,59 @@

 #include "aubio-types.h"

-static char Py_pvoc_doc[] = "pvoc object";

+static char Py_pvoc_doc[] = ""

+"pvoc(win_s=512, hop_s=256)\n"

+"\n"

+"Phase vocoder.\n"

+"\n"

+"`pvoc` creates callable object implements a phase vocoder [1]_,\n"

+"using the tricks detailed in [2]_.\n"

+"\n"

+"The call function takes one input of type `fvec` and of size\n"

+"`hop_s`, and returns a `cvec` of length `win_s//2+1`.\n"

+"\n"

+"Parameters\n"

+"----------\n"

+"win_s : int\n"

+"  number of channels in the phase-vocoder.\n"

+"hop_s : int\n"

+"  number of samples expected between each call\n"

+"\n"

+"Examples\n"

+"--------\n"

+">>> x = aubio.fvec(256)\n"

+">>> pv = aubio.pvoc(512, 256)\n"

+">>> pv(x)\n"

+"aubio cvec of 257 elements\n"

+"\n"

+"Default values for hop_s and win_s are provided:\n"

+"\n"

+">>> pv = aubio.pvoc()\n"

+">>> pv.win_s, pv.hop_s\n"

+"512, 256\n"

+"\n"

+"A `cvec` can be resynthesised using `rdo()`:\n"

+"\n"

+">>> pv = aubio.pvoc(512, 256)\n"

+">>> y = aubio.cvec(512)\n"

+">>> x_reconstructed = pv.rdo(y)\n"

+">>> x_reconstructed.shape\n"

+"(256,)\n"

+"\n"

+"References\n"

+"----------\n"

+".. [1] James A. Moorer. The use of the phase vocoder in computer music\n"

+"   applications. `Journal of the Audio Engineering Society`,\n"

+"   26(1/2):42–45, 1978.\n"

+".. [2] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional\n"

+"   (?) implementations of a phase vocoder: the tricks of the trade.\n"

+"   In `Proceedings of the International Conference on Digital Audio\n"

+"   Effects` (DAFx-00), pages 37–44, University of Verona, Italy, 2000.\n"

+"   (`online version <"

+"https://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf"

+">`_).\n"

+"";

+

 typedef struct

 {

   PyObject_HEAD

@@ -121,9 +173,11 @@

 static PyMemberDef Py_pvoc_members[] = {

   {"win_s", T_INT, offsetof (Py_pvoc, win_s), READONLY,

-    "size of the window"},

+    "int: Size of phase vocoder analysis windows, in samples.\n"

+    ""},

   {"hop_s", T_INT, offsetof (Py_pvoc, hop_s), READONLY,

-    "size of the hop"},

+    "int: Interval between two analysis, in samples.\n"

+    ""},

   { NULL } // sentinel

 };

@@ -175,8 +229,47 @@

 static PyMethodDef Py_pvoc_methods[] = {

   {"rdo", (PyCFunction) Py_pvoc_rdo, METH_VARARGS,

-    "synthesis of spectral grain"},

-  {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS, ""},

+    "rdo(fftgrain)\n"

+    "\n"

+    "Read a new spectral grain and resynthesise the next `hop_s`\n"

+    "output samples.\n"

+    "\n"

+    "Parameters\n"

+    "----------\n"

+    "fftgrain : cvec\n"

+    "    new input `cvec` to synthesize from, should be of size `win_s/2+1`\n"

+    "\n"

+    "Returns\n"

+    "-------\n"

+    "fvec\n"

+    "    re-synthesised output of shape `(hop_s,)`\n"

+    "\n"

+    "Example\n"

+    "-------\n"

+    ">>> pv = aubio.pvoc(2048, 512)\n"

+    ">>> out = pv.rdo(aubio.cvec(2048))\n"

+    ">>> out.shape\n"

+    "(512,)\n"

+    ""},

+  {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS,

+    "set_window(window_type)\n"

+    "\n"

+    "Set window function\n"

+    "\n"

+    "Parameters\n"

+    "----------\n"

+    "window_type : str\n"

+    "    the window type to use for this phase vocoder\n"

+    "\n"

+    "Raises\n"

+    "------\n"

+    "ValueError\n"

+    "    If an unknown window type was given.\n"

+    "\n"

+    "See Also\n"

+    "--------\n"

+    "window : create a window.\n"

+    ""},

   {NULL}

 };