Changeset 07382d8


Ignore:
Timestamp:
Oct 31, 2018, 5:37:35 PM (6 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:
7a54b37
Parents:
9b23815e (diff), 78561f7 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'feature/docstrings' (see #73)

Files:
5 added
19 edited

Legend:

Unmodified
Added
Removed

  • doc/aubio.txt

    r9b23815e r07382d8  
    9999NOTES
    100100
    101   The "note" command accepts all common options and no additional options.
     101  The following additional options can be used with the "notes" subcommand.
     102
     103  -s <value>, --silence <value>  silence threshold, in dB (default: -70)
     104
     105  -d <value>, --release-drop <value>  release drop level, in dB. If the level
     106  drops more than this amount since the last note started, the note will be
     107  turned off (default: 10).
    102108
    103109MFCC

  • doc/aubionotes.txt

    r9b23815e r07382d8  
    6969  loudest ones. A value of -90.0 would select all onsets. Defaults to -90.0.
    7070
    71   -d, --release-drop  Set the release drop threshold, in dB. If the level is
    72   found to drop more than this amount since the last note has started, the
    73   note will be turned-off. Defaults to 10.
     71  -d, --release-drop  Set the release drop threshold, in dB. If the level drops
     72  more than this amount since the last note started, the note will be turned
     73  off. Defaults to 10.
    7474
    7575  -T, --timeformat format  Set time format (samples, ms, seconds). Defaults to

  • doc/conf.py

    r9b23815e r07382d8  
    3030# Add any Sphinx extension module names here, as strings. They can be extensions
    3131# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
    32 extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc']
     32extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc',
     33        'sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
     34
     35autodoc_member_order = 'groupwise'
     36
     37intersphinx_mapping = {
     38        'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     39        }
    3340
    3441# Add any paths that contain templates here, relative to this directory.

  • doc/index.rst

    r9b23815e r07382d8  
    7171   installing
    7272   python_module
     73   python
    7374   cli
    7475   develop

  • doc/installing.rst

    r9b23815e r07382d8  
    3232    sudo ./waf install
    3333
    34 - :ref:`install python-aubio from source <python>`::
     34- :ref:`install python-aubio from source <python-install>`::
    3535
    3636    # from git
    … …  
    4646    pip install -v .
    4747
    48 - :ref:`install python-aubio from a pre-compiled binary <python>`::
     48- :ref:`install python-aubio from a pre-compiled binary <python-install>`::
    4949
    5050      # conda [osx, linux, win]

  • doc/python_module.rst

    r9b23815e r07382d8  
    1 .. _python:
     1.. _python-install:
    22
    3 Python module
    4 =============
     3Installing aubio for Python
     4===========================
    55
    66The aubio extension for Python is available for Python 2.7 and Python 3.
    … …  
    2626    $ sudo ./setup.py install
    2727
    28 Using aubio in python
    29 ---------------------
     28
     29.. _py-doubleprecision:
     30
     31Double precision
     32----------------
     33
     34This module can be compiled in double-precision mode, in which case the
     35default type for floating-point samples will be 64-bit. The default is
     36single precision mode (32-bit, recommended).
     37
     38To build the aubio module with double precision, use the option
     39`--enable-double` of the `build_ext` subcommand:
     40
     41.. code:: bash
     42
     43    $ ./setup.py clean
     44    $ ./setup.py build_ext --enable-double
     45    $ pip install -v .
     46
     47**Note**: If linking against `libaubio`, make sure the library was also
     48compiled in :ref:`doubleprecision` mode.
     49
     50
     51Checking your installation
     52--------------------------
    3053
    3154Once the python module is installed, its version can be checked with:
    … …  
    4164    $ aubio -h
    4265
    43 A simple example
    44 ................
    45 
    46 Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
    47 that reads all the samples from a media file:
    48 
    49 .. literalinclude:: ../python/demos/demo_source_simple.py
    50    :language: python
    51 
    52 Filtering an input sound file
    53 .............................
    54 
    55 Here is a more complete example, :download:`demo_filter.py
    56 <../python/demos/demo_filter.py>`. This files executes the following:
    57 
    58 * read an input media file (``aubio.source``)
    59 
    60 * filter it using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
    61   filter (``aubio.digital_filter``)
    62 
    63 * write result to a new file (``aubio.sink``)
    64 
    65 .. literalinclude:: ../python/demos/demo_filter.py
    66    :language: python
    67 
    68 More demos
    69 ..........
    70 
    71 Check out the `python demos folder`_ for more examples.
    7266
    7367Python tests
    … …  
    7771``python/tests/run_all_tests``.
    7872
    79 .. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
    8073.. _demo_filter.py: https://github.com/aubio/aubio/blob/master/python/demos/demo_filter.py
    8174.. _python tests: https://github.com/aubio/aubio/blob/master/python/tests

  • doc/requirements.rst

    r9b23815e r07382d8  
    298298                uninstall clean distclean dist distcheck
    299299
     300.. _doubleprecision:
     301
    300302Double precision
    301303................
    … …  
    303305To compile aubio in double precision mode, configure with ``--enable-double``.
    304306
    305 To compile aubio in single precision mode, use ``--disable-double`` (default).
     307To compile aubio in single precision mode, use ``--disable-double`` (default,
     308recommended).
    306309
    307310Disabling the tests

  • python/demos/demo_filter.py

    r9b23815e r07382d8  
    11#! /usr/bin/env python
    22
     3import sys
     4import os.path
     5import aubio
    36
    4 def apply_filter(path):
    5     from aubio import source, sink, digital_filter
    6     from os.path import basename, splitext
    7 
     7def apply_filter(path, target):
    88    # open input file, get its samplerate
    9     s = source(path)
     9    s = aubio.source(path)
    1010    samplerate = s.samplerate
    1111
    1212    # create an A-weighting filter
    13     f = digital_filter(7)
     13    f = aubio.digital_filter(7)
    1414    f.set_a_weighting(samplerate)
    15     # alternatively, apply another filter
    1615
    1716    # create output file
    18     o = sink("filtered_" + splitext(basename(path))[0] + ".wav", samplerate)
     17    o = aubio.sink(target, samplerate)
    1918
    2019    total_frames = 0
    2120    while True:
     21        # read from source
    2222        samples, read = s()
     23        # filter samples
    2324        filtered_samples = f(samples)
     25        # write to sink
    2426        o(filtered_samples, read)
     27        # count frames read
    2528        total_frames += read
     29        # end of file reached
    2630        if read < s.hop_size: break
    2731
     32    # print some info
    2833    duration = total_frames / float(samplerate)
    29     print ("read {:s}".format(s.uri))
    30     print ("applied A-weighting filtered ({:d} Hz)".format(samplerate))
    31     print ("wrote {:s} ({:.2f} s)".format(o.uri, duration))
     34    input_str = "input: {:s} ({:.2f} s, {:d} Hz)"
     35    output_str = "output: {:s}, A-weighting filtered ({:d} frames total)"
     36    print (input_str.format(s.uri, duration, samplerate))
     37    print (output_str.format(o.uri, total_frames))
    3238
    3339if __name__ == '__main__':
    34     import sys
    35     for f in sys.argv[1:]:
    36         apply_filter(f)
     40    usage = "{:s} <input_file> [output_file]".format(sys.argv[0])
     41    if not 1 < len(sys.argv) < 4:
     42        print (usage)
     43        sys.exit(1)
     44    if len(sys.argv) < 3:
     45        input_path = sys.argv[1]
     46        basename = os.path.splitext(os.path.basename(input_path))[0] + ".wav"
     47        output_path = "filtered_" + basename
     48    else:
     49        input_path, output_path = sys.argv[1:]
     50    # run function
     51    apply_filter(input_path, output_path)

  • python/demos/demo_source_simple.py

    r9b23815e r07382d8  
    11#! /usr/bin/env python
    2 import sys, aubio
     2import sys
     3import aubio
    34
    4 samplerate = 0  # use original source samplerate
     5samplerate = 0 # use original source samplerate
    56hop_size = 256 # number of frames to read in one block
    6 s = aubio.source(sys.argv[1], samplerate, hop_size)
     7src = aubio.source(sys.argv[1], samplerate, hop_size)
    78total_frames = 0
    89
    9 while True: # reading loop
    10     samples, read = s()
    11     total_frames += read
     10while True:
     11    samples, read = src()     # read hop_size new samples from source
     12    total_frames += read      # increment total number of frames
    1213    if read < hop_size: break # end of file reached
    1314
    1415fmt_string = "read {:d} frames at {:d}Hz from {:s}"
    15 print (fmt_string.format(total_frames, s.samplerate, sys.argv[1]))
    16 
     16print (fmt_string.format(total_frames, src.samplerate, src.uri))

  • python/ext/aubiomodule.c

    r9b23815e r07382d8  
    1111
    1212static char Py_alpha_norm_doc[] = ""
    13 "alpha_norm(fvec, integer) -> float\n"
    14 "\n"
    15 "Compute alpha normalisation factor on vector, given alpha\n"
     13"alpha_norm(vec, alpha)\n"
     14"\n"
     15"Compute `alpha` normalisation factor of vector `vec`.\n"
     16"\n"
     17"Parameters\n"
     18"----------\n"
     19"vec : fvec\n"
     20"   input vector\n"
     21"alpha : float\n"
     22"   norm factor\n"
     23"\n"
     24"Returns\n"
     25"-------\n"
     26"float\n"
     27"   p-norm of the input vector, where `p=alpha`\n"
    1628"\n"
    1729"Example\n"
    1830"-------\n"
    1931"\n"
    20 ">>> b = alpha_norm(a, 9)";
     32">>> a = aubio.fvec(np.arange(10)); alpha = 2\n"
     33">>> aubio.alpha_norm(a, alpha), (sum(a**alpha)/len(a))**(1./alpha)\n"
     34"(5.338539123535156, 5.338539126015656)\n"
     35"\n"
     36"Note\n"
     37"----\n"
     38"Computed as:\n"
     39"\n"
     40".. math::\n"
     41"  l_{\\alpha} = \n"
     42"       \\|\\frac{\\sum_{n=0}^{N-1}{{x_n}^{\\alpha}}}{N}\\|^{1/\\alpha}\n"
     43"";
    2144
    2245static char Py_bintomidi_doc[] = ""
    23 "bintomidi(float, samplerate = integer, fftsize = integer) -> float\n"
    24 "\n"
    25 "Convert bin (float) to midi (float), given the sampling rate and the FFT size\n"
     46"bintomidi(fftbin, samplerate, fftsize)\n"
     47"\n"
     48"Convert FFT bin to frequency in midi note, given the sampling rate\n"
     49"and the size of the FFT.\n"
     50"\n"
     51"Parameters\n"
     52"----------\n"
     53"fftbin : float\n"
     54"   input frequency bin\n"
     55"samplerate : float\n"
     56"   sampling rate of the signal\n"
     57"fftsize : float\n"
     58"   size of the FFT\n"
     59"\n"
     60"Returns\n"
     61"-------\n"
     62"float\n"
     63"   Frequency converted to midi note.\n"
    2664"\n"
    2765"Example\n"
    2866"-------\n"
    2967"\n"
    30 ">>> midi = bintomidi(float, samplerate = 44100, fftsize = 1024)";
     68">>> aubio.bintomidi(10, 44100, 1024)\n"
     69"68.62871551513672\n"
     70"";
    3171
    3272static char Py_miditobin_doc[] = ""
    33 "miditobin(float, samplerate = integer, fftsize = integer) -> float\n"
    34 "\n"
    35 "Convert midi (float) to bin (float), given the sampling rate and the FFT size\n"
     73"miditobin(midi, samplerate, fftsize)\n"
     74"\n"
     75"Convert frequency in midi note to FFT bin, given the sampling rate\n"
     76"and the size of the FFT.\n"
     77"\n"
     78"Parameters\n"
     79"----------\n"
     80"midi : float\n"
     81"   input frequency, in midi note\n"
     82"samplerate : float\n"
     83"   sampling rate of the signal\n"
     84"fftsize : float\n"
     85"   size of the FFT\n"
     86"\n"
     87"Returns\n"
     88"-------\n"
     89"float\n"
     90"   Frequency converted to FFT bin.\n"
     91"\n"
     92"Examples\n"
     93"--------\n"
     94"\n"
     95">>> aubio.miditobin(69, 44100, 1024)\n"
     96"10.216779708862305\n"
     97">>> aubio.miditobin(75.08, 32000, 512)\n"
     98"10.002175331115723\n"
     99"";
     100
     101static char Py_bintofreq_doc[] = ""
     102"bintofreq(fftbin, samplerate, fftsize)\n"
     103"\n"
     104"Convert FFT bin to frequency in Hz, given the sampling rate\n"
     105"and the size of the FFT.\n"
     106"\n"
     107"Parameters\n"
     108"----------\n"
     109"fftbin : float\n"
     110"   input frequency bin\n"
     111"samplerate : float\n"
     112"   sampling rate of the signal\n"
     113"fftsize : float\n"
     114"   size of the FFT\n"
     115"\n"
     116"Returns\n"
     117"-------\n"
     118"float\n"
     119"   Frequency converted to Hz.\n"
    36120"\n"
    37121"Example\n"
    38122"-------\n"
    39123"\n"
    40 ">>> bin = miditobin(midi, samplerate = 44100, fftsize = 1024)";
    41 
    42 static char Py_bintofreq_doc[] = ""
    43 "bintofreq(float, samplerate = integer, fftsize = integer) -> float\n"
    44 "\n"
    45 "Convert bin number (float) in frequency (Hz), given the sampling rate and the FFT size\n"
     124">>> aubio.bintofreq(10, 44100, 1024)\n"
     125"430.6640625\n"
     126"";
     127
     128static char Py_freqtobin_doc[] = ""
     129"freqtobin(freq, samplerate, fftsize)\n"
     130"\n"
     131"Convert frequency in Hz to FFT bin, given the sampling rate\n"
     132"and the size of the FFT.\n"
     133"\n"
     134"Parameters\n"
     135"----------\n"
     136"midi : float\n"
     137"   input frequency, in midi note\n"
     138"samplerate : float\n"
     139"   sampling rate of the signal\n"
     140"fftsize : float\n"
     141"   size of the FFT\n"
     142"\n"
     143"Returns\n"
     144"-------\n"
     145"float\n"
     146"   Frequency converted to FFT bin.\n"
     147"\n"
     148"Examples\n"
     149"--------\n"
     150"\n"
     151">>> aubio.freqtobin(440, 44100, 1024)\n"
     152"10.216779708862305\n"
     153"";
     154
     155static char Py_zero_crossing_rate_doc[] = ""
     156"zero_crossing_rate(vec)\n"
     157"\n"
     158"Compute zero-crossing rate of `vec`.\n"
     159"\n"
     160"Parameters\n"
     161"----------\n"
     162"vec : fvec\n"
     163"   input vector\n"
     164"\n"
     165"Returns\n"
     166"-------\n"
     167"float\n"
     168"   Zero-crossing rate.\n"
    46169"\n"
    47170"Example\n"
    48171"-------\n"
    49172"\n"
    50 ">>> freq = bintofreq(bin, samplerate = 44100, fftsize = 1024)";
    51 
    52 static char Py_freqtobin_doc[] = ""
    53 "freqtobin(float, samplerate = integer, fftsize = integer) -> float\n"
    54 "\n"
    55 "Convert frequency (Hz) in bin number (float), given the sampling rate and the FFT size\n"
     173">>> a = np.linspace(-1., 1., 1000, dtype=aubio.float_type)\n"
     174">>> aubio.zero_crossing_rate(a), 1/1000\n"
     175"(0.0010000000474974513, 0.001)\n"
     176"";
     177
     178static char Py_min_removal_doc[] = ""
     179"min_removal(vec)\n"
     180"\n"
     181"Remove the minimum value of a vector to each of its element.\n"
     182"\n"
     183"Modifies the input vector in-place and returns a reference to it.\n"
     184"\n"
     185"Parameters\n"
     186"----------\n"
     187"vec : fvec\n"
     188"   input vector\n"
     189"\n"
     190"Returns\n"
     191"-------\n"
     192"fvec\n"
     193"   modified input vector\n"
    56194"\n"
    57195"Example\n"
    58196"-------\n"
    59197"\n"
    60 ">>> bin = freqtobin(freq, samplerate = 44100, fftsize = 1024)";
    61 
    62 static char Py_zero_crossing_rate_doc[] = ""
    63 "zero_crossing_rate(fvec) -> float\n"
    64 "\n"
    65 "Compute Zero crossing rate of a vector\n"
    66 "\n"
    67 "Example\n"
    68 "-------\n"
    69 "\n"
    70 ">>> z = zero_crossing_rate(a)";
    71 
    72 static char Py_min_removal_doc[] = ""
    73 "min_removal(fvec) -> float\n"
    74 "\n"
    75 "Remove the minimum value of a vector, in-place modification\n"
    76 "\n"
    77 "Example\n"
    78 "-------\n"
    79 "\n"
    80 ">>> min_removal(a)";
     198">>> aubio.min_removal(aubio.fvec(np.arange(1,4)))\n"
     199"array([0., 1., 2.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
     200"";
    81201
    82202extern void add_ufuncs ( PyObject *m );

  • python/ext/py-cvec.c

    r9b23815e r07382d8  
    2020} Py_cvec;
    2121
    22 static char Py_cvec_doc[] = "cvec object";
     22static char Py_cvec_doc[] = ""
     23"cvec(size)\n"
     24"\n"
     25"A container holding spectral data.\n"
     26"\n"
     27"Create one `cvec` to store the spectral information of a window\n"
     28"of `size` points. The data will be stored  in two vectors,\n"
     29":attr:`phas` and :attr:`norm`, each of shape (:attr:`length`,),\n"
     30"with `length = size // 2 + 1`.\n"
     31"\n"
     32"Parameters\n"
     33"----------\n"
     34"size: int\n"
     35"   Size of spectrum to create.\n"
     36"\n"
     37"Examples\n"
     38"--------\n"
     39">>> c = aubio.cvec(1024)\n"
     40">>> c\n"
     41"aubio cvec of 513 elements\n"
     42">>> c.length\n"
     43"513\n"
     44">>> c.norm.dtype, c.phas.dtype\n"
     45"(dtype('float32'), dtype('float32'))\n"
     46">>> c.norm.shape, c.phas.shape\n"
     47"((513,), (513,))\n"
     48"\n"
     49"See Also\n"
     50"--------\n"
     51"fvec, fft, pvoc\n"
     52"";
    2353
    2454
    … …  
    183213  // TODO remove READONLY flag and define getter/setter
    184214  {"length", T_INT, offsetof (Py_cvec, length), READONLY,
    185       "length attribute"},
     215      "int: Length of `norm` and `phas` vectors."},
    186216  {NULL}                        /* Sentinel */
    187217};
    … …  
    192222
    193223static PyGetSetDef Py_cvec_getseters[] = {
    194   {"norm", (getter)Py_cvec_get_norm, (setter)Py_cvec_set_norm, 
    195       "Numpy vector of shape (length,) containing the magnitude",
     224  {"norm", (getter)Py_cvec_get_norm, (setter)Py_cvec_set_norm,
     225      "numpy.ndarray: Vector of shape `(length,)` containing the magnitude.",
    196226      NULL},
    197   {"phas", (getter)Py_cvec_get_phas, (setter)Py_cvec_set_phas, 
    198       "Numpy vector of shape (length,) containing the phase",
     227  {"phas", (getter)Py_cvec_get_phas, (setter)Py_cvec_set_phas,
     228      "numpy.ndarray: Vector of shape `(length,)` containing the phase.",
    199229      NULL},
    200230  {NULL} /* sentinel */

  • python/ext/py-musicutils.h

    r9b23815e r07382d8  
    33
    44static char Py_aubio_window_doc[] = ""
    5 "window(string, integer) -> fvec\n"
    6 "\n"
    7 "Create a window\n"
    8 "\n"
    9 "Example\n"
    10 "-------\n"
    11 "\n"
    12 ">>> window('hanningz', 1024)\n"
     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"
    1343"array([  0.00000000e+00,   9.41753387e-06,   3.76403332e-05, ...,\n"
    14 "         8.46982002e-05,   3.76403332e-05,   9.41753387e-06], dtype=float32)";
     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"";
    1594
    1695PyObject * Py_aubio_window(PyObject *self, PyObject *args);
    1796
    1897static char Py_aubio_level_lin_doc[] = ""
    19 "level_lin(fvec) -> fvec\n"
    20 "\n"
    21 "Compute sound level on a linear scale.\n"
    22 "\n"
    23 "This gives the average of the square amplitudes.\n"
    24 "\n"
    25 "Example\n"
    26 "-------\n"
    27 "\n"
    28 ">>> level_Lin(numpy.ones(1024))\n"
    29 "1.0";
     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"";
    30128
    31129PyObject * Py_aubio_level_lin(PyObject *self, PyObject *args);
    32130
    33131static char Py_aubio_db_spl_doc[] = ""
    34 "Compute sound pressure level (SPL) in dB\n"
    35 "\n"
    36 "This quantity is often wrongly called 'loudness'.\n"
    37 "\n"
    38 "This gives ten times the log10 of the average of the square amplitudes.\n"
    39 "\n"
    40 "Example\n"
    41 "-------\n"
    42 "\n"
    43 ">>> db_spl(numpy.ones(1024))\n"
    44 "1.0";
     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"";
    45168
    46169PyObject * Py_aubio_db_spl(PyObject *self, PyObject *args);
    47170
    48171static char Py_aubio_silence_detection_doc[] = ""
    49 "Check if buffer level in dB SPL is under a given threshold\n"
    50 "\n"
    51 "Return 0 if level is under the given threshold, 1 otherwise.\n"
    52 "\n"
    53 "Example\n"
    54 "-------\n"
    55 "\n"
    56 ">>> import numpy\n"""
    57 ">>> silence_detection(numpy.ones(1024, dtype=\"float32\"), -80)\n"
    58 "0";
     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"";
    59201
    60202PyObject * Py_aubio_silence_detection(PyObject *self, PyObject *args);
    61203
    62204static char Py_aubio_level_detection_doc[] = ""
    63 "Get buffer level in dB SPL if over a given threshold, 1. otherwise.\n"
    64 "\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";
     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"";
    71234
    72235PyObject * Py_aubio_level_detection(PyObject *self, PyObject *args);
    73236
    74237static char Py_aubio_shift_doc[] = ""
    75 "Swap left and right partitions of a vector\n"
    76 "\n"
    77 "Returns the swapped vector. The input vector is also modified.\n"
     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"
    78255"\n"
    79256"For a vector of length N, the partition is split at index N - N//2.\n"
    … …  
    82259"-------\n"
    83260"\n"
    84 ">>> import numpy\n"
    85 ">>> shift(numpy.arange(3, dtype=aubio.float_type))\n"
    86 "array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")";
     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"";
    87268PyObject * Py_aubio_shift(PyObject *self, PyObject *args);
    88269
    89270static char Py_aubio_ishift_doc[] = ""
    90 "Swap right and left partitions of a vector\n"
    91 "\n"
    92 "Returns the swapped vector. The input vector is also modified.\n"
    93 "\n"
    94 "Unlike with shift(), the partition is split at index N//2.\n"
    95 "\n"
    96 "Example\n"
    97 "-------\n"
    98 "\n"
    99 ">>> import numpy\n"
    100 ">>> ishift(numpy.arange(3, dtype=aubio.float_type))\n"
    101 "array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")";
     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"";
    102301PyObject * Py_aubio_ishift(PyObject *self, PyObject *args);
    103302

  • python/ext/py-phasevoc.c

    r9b23815e r07382d8  
    11#include "aubio-types.h"
    22
    3 static char Py_pvoc_doc[] = "pvoc object";
     3static char Py_pvoc_doc[] = ""
     4"pvoc(win_s=512, hop_s=256)\n"
     5"\n"
     6"Phase vocoder.\n"
     7"\n"
     8"`pvoc` creates callable object implements a phase vocoder [1]_,\n"
     9"using the tricks detailed in [2]_.\n"
     10"\n"
     11"The call function takes one input of type `fvec` and of size\n"
     12"`hop_s`, and returns a `cvec` of length `win_s//2+1`.\n"
     13"\n"
     14"Parameters\n"
     15"----------\n"
     16"win_s : int\n"
     17"  number of channels in the phase-vocoder.\n"
     18"hop_s : int\n"
     19"  number of samples expected between each call\n"
     20"\n"
     21"Examples\n"
     22"--------\n"
     23">>> x = aubio.fvec(256)\n"
     24">>> pv = aubio.pvoc(512, 256)\n"
     25">>> pv(x)\n"
     26"aubio cvec of 257 elements\n"
     27"\n"
     28"Default values for hop_s and win_s are provided:\n"
     29"\n"
     30">>> pv = aubio.pvoc()\n"
     31">>> pv.win_s, pv.hop_s\n"
     32"512, 256\n"
     33"\n"
     34"A `cvec` can be resynthesised using `rdo()`:\n"
     35"\n"
     36">>> pv = aubio.pvoc(512, 256)\n"
     37">>> y = aubio.cvec(512)\n"
     38">>> x_reconstructed = pv.rdo(y)\n"
     39">>> x_reconstructed.shape\n"
     40"(256,)\n"
     41"\n"
     42"References\n"
     43"----------\n"
     44".. [1] James A. Moorer. The use of the phase vocoder in computer music\n"
     45"   applications. `Journal of the Audio Engineering Society`,\n"
     46"   26(1/2):42–45, 1978.\n"
     47".. [2] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional\n"
     48"   (?) implementations of a phase vocoder: the tricks of the trade.\n"
     49"   In `Proceedings of the International Conference on Digital Audio\n"
     50"   Effects` (DAFx-00), pages 37–44, University of Verona, Italy, 2000.\n"
     51"   (`online version <"
     52"https://www.cs.princeton.edu/courses/archive/spr09/cos325/Bernardini.pdf"
     53">`_).\n"
     54"";
     55
    456
    557typedef struct
    … …  
    122174static PyMemberDef Py_pvoc_members[] = {
    123175  {"win_s", T_INT, offsetof (Py_pvoc, win_s), READONLY,
    124     "size of the window"},
     176    "int: Size of phase vocoder analysis windows, in samples.\n"
     177    ""},
    125178  {"hop_s", T_INT, offsetof (Py_pvoc, hop_s), READONLY,
    126     "size of the hop"},
     179    "int: Interval between two analysis, in samples.\n"
     180    ""},
    127181  { NULL } // sentinel
    128182};
    … …  
    176230static PyMethodDef Py_pvoc_methods[] = {
    177231  {"rdo", (PyCFunction) Py_pvoc_rdo, METH_VARARGS,
    178     "synthesis of spectral grain"},
    179   {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS, ""},
     232    "rdo(fftgrain)\n"
     233    "\n"
     234    "Read a new spectral grain and resynthesise the next `hop_s`\n"
     235    "output samples.\n"
     236    "\n"
     237    "Parameters\n"
     238    "----------\n"
     239    "fftgrain : cvec\n"
     240    "    new input `cvec` to synthesize from, should be of size `win_s/2+1`\n"
     241    "\n"
     242    "Returns\n"
     243    "-------\n"
     244    "fvec\n"
     245    "    re-synthesised output of shape `(hop_s,)`\n"
     246    "\n"
     247    "Example\n"
     248    "-------\n"
     249    ">>> pv = aubio.pvoc(2048, 512)\n"
     250    ">>> out = pv.rdo(aubio.cvec(2048))\n"
     251    ">>> out.shape\n"
     252    "(512,)\n"
     253    ""},
     254  {"set_window", (PyCFunction) Pyaubio_pvoc_set_window, METH_VARARGS,
     255    "set_window(window_type)\n"
     256    "\n"
     257    "Set window function\n"
     258    "\n"
     259    "Parameters\n"
     260    "----------\n"
     261    "window_type : str\n"
     262    "    the window type to use for this phase vocoder\n"
     263    "\n"
     264    "Raises\n"
     265    "------\n"
     266    "ValueError\n"
     267    "    If an unknown window type was given.\n"
     268    "\n"
     269    "See Also\n"
     270    "--------\n"
     271    "window : create a window.\n"
     272    ""},
    180273  {NULL}
    181274};

  • python/ext/py-sink.c

    r9b23815e r07382d8  
    1313
    1414static char Py_sink_doc[] = ""
    15 "  __new__(path, samplerate = 44100, channels = 1)\n"
    16 "\n"
    17 "      Create a new sink, opening the given path for writing.\n"
    18 "\n"
    19 "      Examples\n"
    20 "      --------\n"
    21 "\n"
    22 "      Create a new sink at 44100Hz, mono:\n"
    23 "\n"
    24 "      >>> sink('/tmp/t.wav')\n"
    25 "\n"
    26 "      Create a new sink at 8000Hz, mono:\n"
    27 "\n"
    28 "      >>> sink('/tmp/t.wav', samplerate = 8000)\n"
    29 "\n"
    30 "      Create a new sink at 32000Hz, stereo:\n"
    31 "\n"
    32 "      >>> sink('/tmp/t.wav', samplerate = 32000, channels = 2)\n"
    33 "\n"
    34 "      Create a new sink at 32000Hz, 5 channels:\n"
    35 "\n"
    36 "      >>> sink('/tmp/t.wav', channels = 5, samplerate = 32000)\n"
    37 "\n"
    38 "  __call__(vec, write)\n"
    39 "      x(vec,write) <==> x.do(vec, write)\n"
    40 "\n"
    41 "      Write vector to sink.\n"
    42 "\n"
    43 "      See also\n"
    44 "      --------\n"
    45 "      aubio.sink.do\n"
     15"sink(path, samplerate=44100, channels=1)\n"
     16"\n"
     17"Open `path` to write a WAV file.\n"
     18"\n"
     19"Parameters\n"
     20"----------\n"
     21"path : str\n"
     22"   Pathname of the file to be opened for writing.\n"
     23"samplerate : int\n"
     24"   Sampling rate of the file, in Hz.\n"
     25"channels : int\n"
     26"   Number of channels to create the file with.\n"
     27"\n"
     28"Examples\n"
     29"--------\n"
     30"\n"
     31"Create a new sink at 44100Hz, mono:\n"
     32"\n"
     33">>> snk = aubio.sink('out.wav')\n"
     34"\n"
     35"Create a new sink at 32000Hz, stereo, write 100 samples into it:\n"
     36"\n"
     37">>> snk = aubio.sink('out.wav', samplerate=16000, channels=3)\n"
     38">>> snk(aubio.fvec(100), 100)\n"
     39"\n"
     40"Open a new sink at 48000Hz, stereo, write `1234` samples into it:\n"
     41"\n"
     42">>> with aubio.sink('out.wav', samplerate=48000, channels=2) as src:\n"
     43"...     snk(aubio.fvec(1024), 1024)\n"
     44"...     snk(aubio.fvec(210), 210)\n"
     45"...\n"
     46"\n"
     47"See also\n"
     48"--------\n"
     49"source: read audio samples from a file.\n"
    4650"\n";
    4751
    4852static char Py_sink_do_doc[] = ""
    49 "x.do(vec, write) <==> x(vec, write)\n"
    50 "\n"
    51 "write monophonic vector to sink";
     53"do(vec, write)\n"
     54"\n"
     55"Write a single channel vector to sink.\n"
     56"\n"
     57"Parameters\n"
     58"----------\n"
     59"vec : fvec\n"
     60"   input vector `(n,)` where `n >= 0`.\n"
     61"write : int\n"
     62"   Number of samples to write.\n"
     63"";
    5264
    5365static char Py_sink_do_multi_doc[] = ""
    54 "x.do_multi(mat, write)\n"
    55 "\n"
    56 "write polyphonic vector to sink";
     66"do_multi(mat, write)\n"
     67"\n"
     68"Write a matrix containing vectors from multiple channels to sink.\n"
     69"\n"
     70"Parameters\n"
     71"----------\n"
     72"mat : numpy.ndarray\n"
     73"   input matrix of shape `(channels, n)`, where `n >= 0`.\n"
     74"write : int\n"
     75"   Number of frames to write.\n"
     76"";
    5777
    5878static char Py_sink_close_doc[] = ""
    59 "x.close()\n"
    60 "\n"
    61 "close this sink now";
     79"close()\n"
     80"\n"
     81"Close this sink now.\n"
     82"\n"
     83"By default, the sink will be closed before being deleted.\n"
     84"Explicitely closing a sink can be useful to control the number\n"
     85"of files simultaneously opened.\n"
     86"";
    6287
    6388static PyObject *
    … …  
    189214static PyMemberDef Py_sink_members[] = {
    190215  {"uri", T_STRING, offsetof (Py_sink, uri), READONLY,
    191     "path at which the sink was created"},
     216    "str (read-only): Path at which the sink was created."},
    192217  {"samplerate", T_INT, offsetof (Py_sink, samplerate), READONLY,
    193     "samplerate at which the sink was created"},
     218    "int (read-only): Samplerate at which the sink was created."},
    194219  {"channels", T_INT, offsetof (Py_sink, channels), READONLY,
    195     "number of channels with which the sink was created"},
     220    "int (read-only): Number of channels with which the sink was created."},
    196221  { NULL } // sentinel
    197222};

  • python/ext/py-source.c

    r9b23815e r07382d8  
    1717
    1818static char Py_source_doc[] = ""
    19 "   __new__(path, samplerate = 0, hop_size = 512, channels = 1)\n"
    20 "\n"
    21 "       Create a new source, opening the given path for reading.\n"
    22 "\n"
    23 "       Examples\n"
    24 "       --------\n"
    25 "\n"
    26 "       Create a new source, using the original samplerate, with hop_size = 512:\n"
    27 "\n"
    28 "       >>> source('/tmp/t.wav')\n"
    29 "\n"
    30 "       Create a new source, resampling the original to 8000Hz:\n"
    31 "\n"
    32 "       >>> source('/tmp/t.wav', samplerate = 8000)\n"
    33 "\n"
    34 "       Create a new source, resampling it at 32000Hz, hop_size = 32:\n"
    35 "\n"
    36 "       >>> source('/tmp/t.wav', samplerate = 32000, hop_size = 32)\n"
    37 "\n"
    38 "       Create a new source, using its original samplerate:\n"
    39 "\n"
    40 "       >>> source('/tmp/t.wav', samplerate = 0)\n"
    41 "\n"
    42 "   __call__()\n"
    43 "       vec, read = x() <==> vec, read = x.do()\n"
    44 "\n"
    45 "       Read vector from source.\n"
    46 "\n"
    47 "       See also\n"
    48 "       --------\n"
    49 "       aubio.source.do\n"
    50 "\n";
     19"source(path, samplerate=0, hop_size=512, channels=0)\n"
     20"\n"
     21"Create a new source, opening the given pathname for reading.\n"
     22"\n"
     23"`source` open the file specified in `path` and creates a callable\n"
     24"returning `hop_size` new audio samples at each invocation.\n"
     25"\n"
     26"If `samplerate=0` (default), the original sampling rate of `path`\n"
     27"will be used. Otherwise, the output audio samples will be\n"
     28"resampled at the desired sampling-rate.\n"
     29"\n"
     30"If `channels=0` (default), the original number of channels\n"
     31"in `path` will be used. Otherwise, the output audio samples\n"
     32"will be down-mixed or up-mixed to the desired number of\n"
     33"channels.\n"
     34"\n"
     35"If `path` is a URL, a remote connection will be attempted to\n"
     36"open the resource and stream data from it.\n"
     37"\n"
     38"The parameter `hop_size` determines how many samples should be\n"
     39"read at each consecutive calls.\n"
     40"\n"
     41"Parameters\n"
     42"----------\n"
     43"path : str\n"
     44"   pathname (or URL) of the file to be opened for reading\n"
     45"samplerate : int, optional\n"
     46"   sampling rate of the file\n"
     47"hop_size : int, optional\n"
     48"   number of samples to be read per iteration\n"
     49"channels : int, optional\n"
     50"   number of channels of the file\n"
     51"\n"
     52"Examples\n"
     53"--------\n"
     54"By default, when only `path` is given, the file will be opened\n"
     55"with its original sampling rate and channel:\n"
     56"\n"
     57">>> src = aubio.source('stereo.wav')\n"
     58">>> src.uri, src.samplerate, src.channels, src.duration\n"
     59"('stereo.wav', 48000, 2, 86833)\n"
     60"\n"
     61"A typical loop to read all samples from a local file could\n"
     62"look like this:\n"
     63"\n"
     64">>> src = aubio.source('stereo.wav')\n"
     65">>> total_read = 0\n"
     66">>> while True:\n"
     67"...     samples, read = src()\n"
     68"...     # do something with samples\n"
     69"...     total_read += read\n"
     70"...     if read < src.hop_size:\n"
     71"...         break\n"
     72"...\n"
     73"\n"
     74"In a more Pythonic way, it can also look like this:\n"
     75"\n"
     76">>> total_read = 0\n"
     77">>> with aubio.source('stereo.wav') as src:\n"
     78"...     for frames in src:\n"
     79"...         total_read += samples.shape[-1]\n"
     80"...\n"
     81"\n"
     82".. rubric:: Basic interface\n"
     83"\n"
     84"`source` is a **callable**; its :meth:`__call__` method\n"
     85"returns a tuple containing:\n"
     86"\n"
     87"- a vector of shape `(hop_size,)`, filled with the `read` next\n"
     88"  samples available, zero-padded if `read < hop_size`\n"
     89"- `read`, an integer indicating the number of samples read\n"
     90"\n"
     91"To read the first `hop_size` samples from the source, simply call\n"
     92"the instance itself, with no argument:\n"
     93"\n"
     94">>> src = aubio.source('song.ogg')\n"
     95">>> samples, read = src()\n"
     96">>> samples.shape, read, src.hop_size\n"
     97"((512,), 512, 512)\n"
     98"\n"
     99"The first call returned the slice of samples `[0 : hop_size]`.\n"
     100"The next call will return samples `[hop_size: 2*hop_size]`.\n"
     101"\n"
     102"After several invocations of :meth:`__call__`, when reaching the end\n"
     103"of the opened stream, `read` might become less than `hop_size`:\n"
     104"\n"
     105">>> samples, read = src()\n"
     106">>> samples.shape, read\n"
     107"((512,), 354)\n"
     108"\n"
     109"The end of the vector `samples` is filled with zeros.\n"
     110"\n"
     111"After the end of the stream, `read` will be `0` since no more\n"
     112"samples are available:\n"
     113"\n"
     114">>> samples, read = src()\n"
     115">>> samples.shape, read\n"
     116"((512,), 0)\n"
     117"\n"
     118"**Note**: when the source has more than one channels, they\n"
     119"are be down-mixed to mono when invoking :meth:`__call__`.\n"
     120"To read from each individual channel, see :meth:`__next__`.\n"
     121"\n"
     122".. rubric:: ``for`` statements\n"
     123"\n"
     124"The `source` objects are **iterables**. This allows using them\n"
     125"directly in a ``for`` loop, which calls :meth:`__next__` until\n"
     126"the end of the stream is reached:\n"
     127"\n"
     128">>> src = aubio.source('stereo.wav')\n"
     129">>> for frames in src:\n"
     130">>>     print (frames.shape)\n"
     131"...\n"
     132"(2, 512)\n"
     133"(2, 512)\n"
     134"(2, 230)\n"
     135"\n"
     136"**Note**: When `next(self)` is called on a source with multiple\n"
     137"channels, an array of shape `(channels, read)` is returned,\n"
     138"unlike with :meth:`__call__` which always returns the down-mixed\n"
     139"channels.\n"
     140"\n"
     141"If the file is opened with a single channel, `next(self)` returns\n"
     142"an array of shape `(read,)`:\n"
     143"\n"
     144">>> src = aubio.source('stereo.wav', channels=1)\n"
     145">>> next(src).shape\n"
     146"(512,)\n"
     147"\n"
     148".. rubric:: ``with`` statements\n"
     149"\n"
     150"The `source` objects are **context managers**, which allows using\n"
     151"them in ``with`` statements:\n"
     152"\n"
     153">>> with aubio.source('audiotrack.wav') as source:\n"
     154"...     n_frames=0\n"
     155"...     for samples in source:\n"
     156"...         n_frames += len(samples)\n"
     157"...     print('read', n_frames, 'samples in', samples.shape[0], 'channels',\n"
     158"...         'from file \"\%s\"' \% source.uri)\n"
     159"...\n"
     160"read 239334 samples in 2 channels from file \"audiotrack.wav\"\n"
     161"\n"
     162"The file will be closed before exiting the statement.\n"
     163"\n"
     164"See also the methods implementing the context manager,\n"
     165":meth:`__enter__` and :meth:`__exit__`.\n"
     166"\n"
     167".. rubric:: Seeking and closing\n"
     168"\n"
     169"At any time, :meth:`seek` can be used to move to any position in\n"
     170"the file. For instance, to rewind to the start of the stream:\n"
     171"\n"
     172">>> src.seek(0)\n"
     173"\n"
     174"The opened file will be automatically closed when the object falls\n"
     175"out of scope and is scheduled for garbage collection.\n"
     176"\n"
     177"In some cases, it is useful to manually :meth:`close` a given source,\n"
     178"for instance to limit the number of simultaneously opened files:\n"
     179"\n"
     180">>> src.close()\n"
     181"\n"
     182".. rubric:: Input formats\n"
     183"\n"
     184"Depending on how aubio was compiled, :class:`source` may or may not\n"
     185"open certain **files format**. Below are some examples that assume\n"
     186"support for compressed files and remote urls was compiled in:\n"
     187"\n"
     188"- open a local file using its original sampling rate and channels,\n"
     189"  and with the default hop size:\n"
     190"\n"
     191">>> s = aubio.source('sample.wav')\n"
     192">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
     193"('sample.wav', 44100, 2, 512)\n"
     194"\n"
     195"- open a local compressed audio file, resampling to 32000Hz if needed:\n"
     196"\n"
     197">>> s = aubio.source('song.mp3', samplerate=32000)\n"
     198">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
     199"('song.mp3', 32000, 2, 512)\n"
     200"\n"
     201"- open a local video file, down-mixing and resampling it to 16kHz:\n"
     202"\n"
     203">>> s = aubio.source('movie.mp4', samplerate=16000, channels=1)\n"
     204">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
     205"('movie.mp4', 16000, 1, 512)\n"
     206"\n"
     207"- open a remote resource, with hop_size = 1024:\n"
     208"\n"
     209">>> s = aubio.source('https://aubio.org/drum.ogg', hop_size=1024)\n"
     210">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
     211"('https://aubio.org/drum.ogg', 48000, 2, 1024)\n"
     212"\n"
     213"See Also\n"
     214"--------\n"
     215"sink: write audio samples to a file.\n"
     216"";
    51217
    52218static char Py_source_get_samplerate_doc[] = ""
    53 "x.get_samplerate() -> source samplerate\n"
    54 "\n"
    55 "Get samplerate of source.";
     219"get_samplerate()\n"
     220"\n"
     221"Get sampling rate of source.\n"
     222"\n"
     223"Returns\n"
     224"-------\n"
     225"int\n"
     226"    Sampling rate, in Hz.\n"
     227"";
    56228
    57229static char Py_source_get_channels_doc[] = ""
    58 "x.get_channels() -> number of channels\n"
    59 "\n"
    60 "Get number of channels in source.";
     230"get_channels()\n"
     231"\n"
     232"Get number of channels in source.\n"
     233"\n"
     234"Returns\n"
     235"-------\n"
     236"int\n"
     237"    Number of channels.\n"
     238"";
    61239
    62240static char Py_source_do_doc[] = ""
    63 "vec, read = x.do() <==> vec, read = x()\n"
    64 "\n"
    65 "Read monophonic vector from source.";
     241"source.do()\n"
     242"\n"
     243"Read vector of audio samples.\n"
     244"\n"
     245"If the audio stream in the source has more than one channel,\n"
     246"the channels will be down-mixed.\n"
     247"\n"
     248"Returns\n"
     249"-------\n"
     250"samples : numpy.ndarray, shape `(hop_size,)`, dtype aubio.float_type\n"
     251"    `fvec` of size `hop_size` containing the new samples.\n"
     252"read : int\n"
     253"    Number of samples read from the source, equals to `hop_size`\n"
     254"    before the end-of-file is reached, less when it is reached,\n"
     255"    and `0` after.\n"
     256"\n"
     257"See Also\n"
     258"--------\n"
     259"do_multi\n"
     260"\n"
     261"Examples\n"
     262"--------\n"
     263">>> src = aubio.source('sample.wav', hop_size=1024)\n"
     264">>> src.do()\n"
     265"(array([-0.00123001, -0.00036685,  0.00097106, ..., -0.2031033 ,\n"
     266"       -0.2025854 , -0.20221856], dtype=" AUBIO_NPY_SMPL_STR "), 1024)\n"
     267"";
    66268
    67269static char Py_source_do_multi_doc[] = ""
    68 "mat, read = x.do_multi()\n"
    69 "\n"
    70 "Read polyphonic vector from source.";
     270"do_multi()\n"
     271"\n"
     272"Read multiple channels of audio samples.\n"
     273"\n"
     274"If the source was opened with the same number of channels\n"
     275"found in the stream, each channel will be read individually.\n"
     276"\n"
     277"If the source was opened with less channels than the number\n"
     278"of channels in the stream, only the first channels will be read.\n"
     279"\n"
     280"If the source was opened with more channels than the number\n"
     281"of channel in the original stream, the first channels will\n"
     282"be duplicated on the additional output channel.\n"
     283"\n"
     284"Returns\n"
     285"-------\n"
     286"samples : np.ndarray([hop_size, channels], dtype=aubio.float_type)\n"
     287"    NumPy array of shape `(hop_size, channels)` containing the new\n"
     288"    audio samples.\n"
     289"read : int\n"
     290"    Number of samples read from the source, equals to `hop_size`\n"
     291"    before the end-of-file is reached, less when it is reached,\n"
     292"    and `0` after.\n"
     293"\n"
     294"See Also\n"
     295"--------\n"
     296"do\n"
     297"\n"
     298"Examples\n"
     299"--------\n"
     300">>> src = aubio.source('sample.wav')\n"
     301">>> src.do_multi()\n"
     302"(array([[ 0.00668335,  0.0067749 ,  0.00714111, ..., -0.05737305,\n"
     303"        -0.05856323, -0.06018066],\n"
     304"       [-0.00842285, -0.0072937 , -0.00576782, ..., -0.09405518,\n"
     305"        -0.09558105, -0.09725952]], dtype=" AUBIO_NPY_SMPL_STR "), 512)\n"
     306"";
    71307
    72308static char Py_source_close_doc[] = ""
    73 "x.close()\n"
    74 "\n"
    75 "Close this source now.";
     309"close()\n"
     310"\n"
     311"Close this source now.\n"
     312"\n"
     313".. note:: Closing twice a source will **not** raise any exception.\n"
     314"";
    76315
    77316static char Py_source_seek_doc[] = ""
    78 "x.seek(position)\n"
    79 "\n"
    80 "Seek to resampled frame position.";
     317"seek(position)\n"
     318"\n"
     319"Seek to position in file.\n"
     320"\n"
     321"If the source was not opened with its original sampling-rate,\n"
     322"`position` corresponds to the position in the re-sampled file.\n"
     323"\n"
     324"Parameters\n"
     325"----------\n"
     326"position : str\n"
     327"   position to seek to, in samples\n"
     328"";
    81329
    82330static PyObject *
    … …  
    218466static PyMemberDef Py_source_members[] = {
    219467  {"uri", T_STRING, offsetof (Py_source, uri), READONLY,
    220     "path at which the source was created"},
     468    "str (read-only): pathname or URL"},
    221469  {"samplerate", T_INT, offsetof (Py_source, samplerate), READONLY,
    222     "samplerate at which the source is viewed"},
     470    "int (read-only): sampling rate"},
    223471  {"channels", T_INT, offsetof (Py_source, channels), READONLY,
    224     "number of channels found in the source"},
     472    "int (read-only): number of channels"},
    225473  {"hop_size", T_INT, offsetof (Py_source, hop_size), READONLY,
    226     "number of consecutive frames that will be read at each do or do_multi call"},
     474    "int (read-only): number of samples read per iteration"},
    227475  {"duration", T_INT, offsetof (Py_source, duration), READONLY,
    228     "total number of frames in the source (estimated)"},
     476    "int (read-only): total number of frames in the source\n"
     477    "\n"
     478    "Can be estimated, for instance if the opened stream is\n"
     479    "a compressed media or a remote resource.\n"
     480    "\n"
     481    "Example\n"
     482    "-------\n"
     483    ">>> n = 0\n"
     484    ">>> src = aubio.source('track1.mp3')\n"
     485    ">>> for samples in src:\n"
     486    "...     n += samples.shape[-1]\n"
     487    "...\n"
     488    ">>> n, src.duration\n"
     489    "(9638784, 9616561)\n"
     490    ""},
    229491  { NULL } // sentinel
    230492};

  • python/ext/ufuncs.c

    r9b23815e r07382d8  
    5959};
    6060
    61 static char Py_unwrap2pi_doc[] = "map angle to unit circle [-pi, pi[";
     61// Note: these docstrings should *not* include the function signatures
     62
     63static char Py_unwrap2pi_doc[] = ""
     64"\n"
     65"Map angle to unit circle :math:`[-\\pi, \\pi[`.\n"
     66"\n"
     67"Parameters\n"
     68"----------\n"
     69"x : numpy.ndarray\n"
     70"   input array\n"
     71"\n"
     72"Returns\n"
     73"-------\n"
     74"numpy.ndarray\n"
     75"   values clamped to the unit circle :math:`[-\\pi, \\pi[`\n"
     76"";
    6277
    6378static void* Py_unwrap2pi_data[] = {
    … …  
    6883};
    6984
    70 static char Py_freqtomidi_doc[] = "convert frequency to midi";
     85static char Py_freqtomidi_doc[] = ""
     86"\n"
     87"Convert frequency `[0; 23000[` to midi `[0; 128[`.\n"
     88"\n"
     89"Parameters\n"
     90"----------\n"
     91"x : numpy.ndarray\n"
     92"    Array of frequencies, in Hz.\n"
     93"\n"
     94"Returns\n"
     95"-------\n"
     96"numpy.ndarray\n"
     97"    Converted frequencies, in midi note.\n"
     98"";
    7199
    72100static void* Py_freqtomidi_data[] = {
    … …  
    75103};
    76104
    77 static char Py_miditofreq_doc[] = "convert midi to frequency";
     105static char Py_miditofreq_doc[] = ""
     106"\n"
     107"Convert midi `[0; 128[` to frequency `[0, 23000]`.\n"
     108"\n"
     109"Parameters\n"
     110"----------\n"
     111"x : numpy.ndarray\n"
     112"    Array of frequencies, in midi note.\n"
     113"\n"
     114"Returns\n"
     115"-------\n"
     116"numpy.ndarray\n"
     117"    Converted frequencies, in Hz\n"
     118"";
    78119
    79120static void* Py_miditofreq_data[] = {

  • python/lib/aubio/__init__.py

    r9b23815e r07382d8  
    11#! /usr/bin/env python
     2# -*- coding: utf8 -*-
     3
     4"""
     5aubio
     6=====
     7
     8Provides a number of classes and functions for music and audio signal
     9analysis.
     10
     11How to use the documentation
     12----------------------------
     13
     14Documentation of the python module is available as docstrings provided
     15within the code, and a reference guide available online from `the
     16aubio homepage <https://aubio.org/documentation>`_.
     17
     18The docstrings examples are written assuming `aubio` and `numpy` have been
     19imported with:
     20
     21>>> import aubio
     22>>> import numpy as np
     23"""
    224
    325import numpy
    … …  
    931
    1032class fvec(numpy.ndarray):
    11     """a numpy vector holding audio samples"""
     33    """fvec(input_arg=1024, **kwargs)
     34    A vector holding float samples.
    1235
     36    If `input_arg` is an `int`, a 1-dimensional vector of length `input_arg`
     37    will be created and filled with zeros. Otherwise, if `input_arg` is an
     38    `array_like` object, it will be converted to a 1-dimensional vector of
     39    type :data:`float_type`.
     40
     41    Parameters
     42    ----------
     43    input_arg : `int` or `array_like`
     44        Can be a positive integer, or any object that can be converted to
     45        a numpy array with :func:`numpy.array`.
     46    **kwargs
     47        Additional keyword arguments passed to :func:`numpy.zeros`, if
     48        `input_arg` is an integer, or to :func:`numpy.array`. Should not
     49        include `dtype`, which is already specified as
     50        :data:`aubio.float_type`.
     51
     52    Returns
     53    -------
     54    numpy.ndarray
     55        Array of shape `(length,)`.
     56
     57    Examples
     58    --------
     59    >>> aubio.fvec(10)
     60    array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], dtype=float32)
     61    >>> aubio.fvec([0,1,2])
     62    array([0., 1., 2.], dtype=float32)
     63    >>> a = np.arange(10); type(a), type(aubio.fvec(a))
     64    (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)
     65    >>> a.dtype, aubio.fvec(a).dtype
     66    (dtype('int64'), dtype('float32'))
     67
     68    Notes
     69    -----
     70
     71    In the Python world, `fvec` is simply a subclass of
     72    :class:`numpy.ndarray`. In practice, any 1-dimensional `numpy.ndarray` of
     73    `dtype` :data:`float_type` may be passed to methods accepting
     74    `fvec` as parameter. For instance, `sink()` or `pvoc()`.
     75
     76    See Also
     77    --------
     78    cvec : a container holding spectral data
     79    numpy.ndarray : parent class of :class:`fvec`
     80    numpy.zeros : create a numpy array filled with zeros
     81    numpy.array : create a numpy array from an existing object
     82    """
    1383    def __new__(cls, input_arg=1024, **kwargs):
    1484        if isinstance(input_arg, int):

  • python/lib/aubio/midiconv.py

    r9b23815e r07382d8  
    1616
    1717def note2midi(note):
    18     " convert note name to midi note number, e.g. [C-1, G9] -> [0, 127] "
     18    """Convert note name to midi note number.
     19
     20    Input string `note` should be composed of one note root
     21    and one octave, with optionally one modifier in between.
     22
     23    List of valid components:
     24
     25    - note roots: `C`, `D`, `E`, `F`, `G`, `A`, `B`,
     26    - modifiers: `b`, `#`, as well as unicode characters
     27      `𝄫`, `♭`, `♮`, `♯` and `𝄪`,
     28    - octave numbers: `-1` -> `11`.
     29
     30    Parameters
     31    ----------
     32    note : str
     33        note name
     34
     35    Returns
     36    -------
     37    int
     38        corresponding midi note number
     39
     40    Examples
     41    --------
     42    >>> aubio.note2midi('C#4')
     43    61
     44    >>> aubio.note2midi('B♭5')
     45    82
     46
     47    Raises
     48    ------
     49    TypeError
     50        If `note` was not a string.
     51    ValueError
     52        If an error was found while converting `note`.
     53
     54    See Also
     55    --------
     56    midi2note, freqtomidi, miditofreq
     57    """
    1958    _valid_notenames = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11}
    2059    _valid_modifiers = {
    … …  
    62101
    63102def midi2note(midi):
    64     " convert midi note number to note name, e.g. [0, 127] -> [C-1, G9] "
     103    """Convert midi note number to note name.
     104
     105    Parameters
     106    ----------
     107    midi : int [0, 128]
     108        input midi note number
     109
     110    Returns
     111    -------
     112    str
     113        note name
     114
     115    Examples
     116    --------
     117    >>> aubio.midi2note(70)
     118    'A#4'
     119    >>> aubio.midi2note(59)
     120    'B3'
     121
     122    Raises
     123    ------
     124    TypeError
     125        If `midi` was not an integer.
     126    ValueError
     127        If `midi` is out of the range `[0, 128]`.
     128
     129    See Also
     130    --------
     131    note2midi, miditofreq, freqtomidi
     132    """
    65133    if not isinstance(midi, int_instances):
    66134        raise TypeError("an integer is required, got %s" % midi)
    … …  
    73141
    74142def freq2note(freq):
    75     " convert frequency in Hz to nearest note name, e.g. [0, 22050.] -> [C-1, G9] "
     143    """Convert frequency in Hz to nearest note name.
     144
     145    Parameters
     146    ----------
     147    freq : float [0, 23000[
     148        input frequency, in Hz
     149
     150    Returns
     151    -------
     152    str
     153        name of the nearest note
     154
     155    Example
     156    -------
     157    >>> aubio.freq2note(440)
     158    'A4'
     159    >>> aubio.freq2note(220.1)
     160    'A3'
     161    """
    76162    nearest_note = int(freqtomidi(freq) + .5)
    77163    return midi2note(nearest_note)

  • python/lib/aubio/slicing.py

    r9b23815e r07382d8  
    99                           output_dir=None, samplerate=0, hopsize=256,
    1010                           create_first=False):
    11     """ slice a sound file at given timestamps """
     11    """Slice a sound file at given timestamps.
     12
     13    This function reads `source_file` and creates slices, new smaller
     14    files each starting at `t` in `timestamps`, a list of integer
     15    corresponding to time locations in `source_file`, in samples.
     16
     17    If `timestamps_end` is unspecified, the slices will end at
     18    `timestamps_end[n] = timestamps[n+1]-1`, or the end of file.
     19    Otherwise, `timestamps_end` should be a list with the same length
     20    as `timestamps` containing the locations of the end of each slice.
     21
     22    If `output_dir` is unspecified, the new slices will be written in
     23    the current directory. If `output_dir` is a string, new slices
     24    will be written in `output_dir`, after creating the directory if
     25    required.
     26
     27    The default `samplerate` is 0, meaning the original sampling rate
     28    of `source_file` will be used. When using a sampling rate
     29    different to the one of the original files, `timestamps` and
     30    `timestamps_end` should be expressed in the re-sampled signal.
     31
     32    The `hopsize` parameter simply tells :class:`source` to use this
     33    hopsize and does not change the output slices.
     34
     35    If `create_first` is True and `timestamps` does not start with `0`, the
     36    first slice from `0` to `timestamps[0] - 1` will be automatically added.
     37
     38    Parameters
     39    ----------
     40    source_file : str
     41        path of the resource to slice
     42    timestamps : :obj:`list` of :obj:`int`
     43        time stamps at which to slice, in samples
     44    timestamps_end : :obj:`list` of :obj:`int` (optional)
     45        time stamps at which to end the slices
     46    output_dir : str (optional)
     47        output directory to write the slices to
     48    samplerate : int (optional)
     49        samplerate to read the file at
     50    hopsize : int (optional)
     51        number of samples read from source per iteration
     52    create_first : bool (optional)
     53        always create the slice at the start of the file
     54
     55    Examples
     56    --------
     57    Create two slices: the first slice starts at the beginning of the
     58    input file `loop.wav` and lasts exactly one second, starting at
     59    sample `0` and ending at sample `44099`; the second slice starts
     60    at sample `44100` and lasts until the end of the input file:
     61
     62    >>> aubio.slice_source_at_stamps('loop.wav', [0, 44100])
     63
     64    Create one slice, from 1 second to 2 seconds:
     65
     66    >>> aubio.slice_source_at_stamps('loop.wav', [44100], [44100 * 2 - 1])
     67
     68    Notes
     69    -----
     70    Slices may be overlapping. If `timestamps_end` is `1` element
     71    shorter than `timestamps`, the last slice will end at the end of
     72    the file.
     73    """
    1274
    1375    if timestamps is None or len(timestamps) == 0:
Note: See TracChangeset for help on using the changeset viewer.