ref: 07382d8c0476840e5a86b3807577c988cc52e28a
parent: 9b23815ef6b80c6bdea50649cbd97f831b12bb31
parent: 78561f7924523d31ef3a4fb6c101e7c93e491a34
author: Paul Brossier <piem@piem.org>
date: Wed Oct 31 13:37:35 EDT 2018
Merge branch 'feature/docstrings' (see #73)
--- a/doc/aubio.txt
+++ b/doc/aubio.txt
@@ -98,7 +98,13 @@
NOTES
- The "note" command accepts all common options and no additional options.
+ The following additional options can be used with the "notes" subcommand.
+
+ -s <value>, --silence <value> silence threshold, in dB (default: -70)
+
+ -d <value>, --release-drop <value> release drop level, in dB. If the level
+ drops more than this amount since the last note started, the note will be
+ turned off (default: 10).
MFCC
--- a/doc/aubionotes.txt
+++ b/doc/aubionotes.txt
@@ -68,9 +68,9 @@
will not be detected. A value of -20.0 would eliminate most onsets but the
loudest ones. A value of -90.0 would select all onsets. Defaults to -90.0.
- -d, --release-drop Set the release drop threshold, in dB. If the level is
- found to drop more than this amount since the last note has started, the
- note will be turned-off. Defaults to 10.
+ -d, --release-drop Set the release drop threshold, in dB. If the level drops
+ more than this amount since the last note started, the note will be turned
+ off. Defaults to 10.
-T, --timeformat format Set time format (samples, ms, seconds). Defaults to
seconds.
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -29,7 +29,14 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc']
+extensions = ['sphinx.ext.viewcode', 'sphinx.ext.autodoc',
+ 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx']
+
+autodoc_member_order = 'groupwise'
+
+intersphinx_mapping = {+ 'numpy': ('https://docs.scipy.org/doc/numpy/', None),+ }
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -70,6 +70,7 @@
installing
python_module
+ python
cli
develop
about
--- a/doc/installing.rst
+++ b/doc/installing.rst
@@ -31,7 +31,7 @@
./waf build
sudo ./waf install
-- :ref:`install python-aubio from source <python>`::
+- :ref:`install python-aubio from source <python-install>`::
# from git
pip install git+https://git.aubio.org/aubio/aubio/
@@ -45,7 +45,7 @@
cd aubio
pip install -v .
-- :ref:`install python-aubio from a pre-compiled binary <python>`::
+- :ref:`install python-aubio from a pre-compiled binary <python-install>`::
# conda [osx, linux, win]
conda install -c conda-forge aubio
--- /dev/null
+++ b/doc/py_datatypes.rst
@@ -1,0 +1,43 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Data-types
+----------
+
+This section contains the documentation for :data:`float_type`,
+:class:`fvec`, and :class:`cvec`.
+
+.. defined in rst only
+
+.. data:: float_type
+
+ A string constant describing the floating-point representation used in
+ :class:`fvec`, :class:`cvec`, and elsewhere in this module.
+
+ Defaults to `"float32"`.
+
+ If `aubio` was built specifically with the option `--enable-double`, this
+ string will be defined to `"float64"`. See :ref:`py-doubleprecision` in
+ :ref:`python-install` for more details on building aubio in double
+ precision mode.
+
+ .. rubric:: Examples
+
+ >>> aubio.float_type
+ 'float32'
+ >>> numpy.zeros(10).dtype
+ 'float64'
+ >>> aubio.fvec(10).dtype
+ 'float32'
+ >>> np.arange(10, dtype=aubio.float_type).dtype
+ 'float32'
+
+.. defined in `python/lib/aubio/__init__.py`
+
+.. autoclass:: fvec
+ :members:
+
+.. defined in `python/ext/py-cvec.h`
+
+.. autoclass:: cvec
+ :members:
--- /dev/null
+++ b/doc/py_examples.rst
@@ -1,0 +1,42 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Examples
+--------
+
+Below is a short selection of examples using the aubio module.
+
+Read a sound file
+.................
+
+Here is a simple script, :download:`demo_source_simple.py
+<../python/demos/demo_source_simple.py>` that reads all the samples from a
+media file using :class:`source`:
+
+.. literalinclude:: ../python/demos/demo_source_simple.py
+ :language: python
+
+Filter a sound file
+...................
+
+Here is another example, :download:`demo_filter.py
+<../python/demos/demo_filter.py>`, which applies a filter to a sound file
+and writes the filtered signal in another file:
+
+* read audio samples from a file with :class:`source`
+
+* filter them using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
+ filter using :class:`digital_filter`
+
+* write the filtered samples to a new file with :class:`sink`.
+
+.. literalinclude:: ../python/demos/demo_filter.py
+ :language: python
+
+More examples
+.............
+
+For more examples showing how to use other components of the module, see
+the `python demos folder`_.
+
+.. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
--- /dev/null
+++ b/doc/py_io.rst
@@ -1,0 +1,118 @@
+.. currentmodule:: aubio
+.. default-domain:: py
+
+Input/Output
+------------
+
+This section contains the documentation for two classes:
+:class:`source`, to read audio samples from files, and :class:`sink`,
+to write audio samples to disk.
+
+.. defined in `python/ext`
+
+..
+ Note: __call__ docstrings of objects defined in C must be written
+ specifically in RST, since there is no known way to add them to
+ their C implementation.
+
+..
+ TODO: remove special-members documentation
+
+.. defined in py-source.c
+
+.. autoclass:: source
+ :members:
+ :special-members: __enter__
+ :no-special-members:
+
+ .. function:: __call__()
+
+ Read at most `hop_size` new samples from self, return them in
+ a tuple with the number of samples actually read.
+
+ The returned tuple contains:
+
+ - a vector of shape `(hop_size,)`, filled with the `read` next
+ samples available, zero-padded if `read < hop_size`
+ - `read`, an integer indicating the number of samples read
+
+ If opened with more than one channel, the frames will be
+ down-mixed to produce the new samples.
+
+ return: A tuple of one array of samples and one integer.
+ :rtype: (array, int)
+
+ .. seealso:: :meth:`__next__`
+
+ .. rubric:: Example
+
+ >>> src = aubio.source('stereo.wav')+ >>> while True:
+ ... samples, read = src()
+ ... if read < src.hop_size:
+ ... break
+
+ .. function:: __next__()
+
+ Read at most `hop_size` new frames from self, return them in
+ an array.
+
+ If source was opened with one channel, next(self) returns
+ an array of shape `(read,)`, where `read` is the actual
+ number of frames read (`0 <= read <= hop_size`).
+
+ If `source` was opened with more then one channel, the
+ returned arrays will be of shape `(channels, read)`, where
+ `read` is the actual number of frames read (`0 <= read <=
+ hop_size`).
+
+ :return: A tuple of one array of frames and one integer.
+ :rtype: (array, int)
+
+ .. seealso:: :meth:`__call__`
+
+ .. rubric:: Example
+
+ >>> for frames in aubio.source('song.flac')+ ... print(samples.shape)
+
+ .. function:: __iter__()
+
+ Implement iter(self).
+
+ .. seealso:: :meth:`__next__`
+
+ .. function:: __enter__()
+
+ Implement context manager interface. The file will be opened
+ upon entering the context. See `with` statement.
+
+ .. rubric:: Example
+
+ >>> with aubio.source('loop.ogg') as src:+ ... src.uri, src.samplerate, src.channels
+
+ .. function:: __exit__()
+
+ Implement context manager interface. The file will be closed
+ before exiting the context. See `with` statement.
+
+ .. seealso:: :meth:`__enter__`
+
+.. py-sink.c
+ TODO: remove special-members documentation
+
+.. autoclass:: aubio.sink
+ :members:
+
+ .. function:: __call__(vec, length)
+
+ Write `length` samples from `vec`.
+
+ :param array vec: input vector to write from
+ :param int length: number of samples to write
+ :example:
+
+ >>> with aubio.sink('foo.wav') as snk:+ ... snk(aubio.fvec(1025), 1025)
+
--- /dev/null
+++ b/doc/py_utils.rst
@@ -1,0 +1,78 @@
+.. default-domain:: py
+.. currentmodule:: aubio
+
+Utilities
+---------
+
+This section documents various helper functions included in the aubio library.
+
+Note name conversion
+....................
+
+.. midiconv.py
+
+.. autofunction:: note2midi
+
+.. autofunction:: midi2note
+
+.. autofunction:: freq2note
+
+.. autofunction:: note2freq
+
+Frequency conversion
+....................
+
+.. python/ext/ufuncs.c
+
+.. autofunction:: freqtomidi
+
+.. autofunction:: miditofreq
+
+.. python/ext/aubiomodule.c
+
+.. autofunction:: bintomidi
+.. autofunction:: miditobin
+.. autofunction:: bintofreq
+.. autofunction:: freqtobin
+
+Audio file slicing
+..................
+
+.. slicing.py
+
+.. autofunction:: slice_source_at_stamps
+
+Windowing
+.........
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: window
+
+Audio level detection
+.....................
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: level_lin
+.. autofunction:: db_spl
+.. autofunction:: silence_detection
+.. autofunction:: level_detection
+
+Vector utilities
+................
+
+.. python/ext/aubiomodule.c
+
+.. autofunction:: alpha_norm
+.. autofunction:: zero_crossing_rate
+.. autofunction:: min_removal
+
+.. python/ext/py-musicutils.h
+
+.. autofunction:: shift
+.. autofunction:: ishift
+
+.. python/ext/ufuncs.c
+
+.. autofunction:: unwrap2pi
--- /dev/null
+++ b/doc/python.rst
@@ -1,0 +1,55 @@
+.. make sure our default-domain is python here
+.. default-domain:: py
+
+.. set current module
+.. currentmodule:: aubio
+
+..
+ we follow numpy type docstrings, see:
+ https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
+..
+ note: we do not import aubio's docstring, which will be displayed from an
+ interpreter.
+
+.. .. automodule:: aubio
+
+
+.. _python:
+
+Python documentation
+====================
+
+This module provides a number of classes and functions for the analysis of
+music and audio signals.
+
+Contents
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ py_datatypes
+ py_io
+ py_utils
+ py_examples
+
+Introduction
+------------
+
+This document provides a reference guide. For documentation on how to
+install aubio, see :ref:`python-install`.
+
+Examples included in this guide and within the code are written assuming
+both `aubio` and `numpy`_ have been imported:
+
+.. code-block:: python
+
+ >>> import aubio
+ >>> import numpy as np
+
+`Changed in 0.4.8` : Prior to this version, almost no documentation was
+provided with the python module. This version adds documentation for some
+classes, including :class:`fvec`, :class:`cvec`, :class:`source`, and
+:class:`sink`.
+
+.. _numpy: https://www.numpy.org
--- a/doc/python_module.rst
+++ b/doc/python_module.rst
@@ -1,7 +1,7 @@
-.. _python:
+.. _python-install:
-Python module
-=============
+Installing aubio for Python
+===========================
The aubio extension for Python is available for Python 2.7 and Python 3.
@@ -25,51 +25,45 @@
$ ./setup.py build
$ sudo ./setup.py install
-Using aubio in python
----------------------
-Once the python module is installed, its version can be checked with:
+.. _py-doubleprecision:
-.. code-block:: console
-
- $ python -c "import aubio; print(aubio.version, aubio.float_type)"
+Double precision
+----------------
-The command line `aubio` is also installed:
+This module can be compiled in double-precision mode, in which case the
+default type for floating-point samples will be 64-bit. The default is
+single precision mode (32-bit, recommended).
-.. code-block:: console
+To build the aubio module with double precision, use the option
+`--enable-double` of the `build_ext` subcommand:
- $ aubio -h
+.. code:: bash
-A simple example
-................
+ $ ./setup.py clean
+ $ ./setup.py build_ext --enable-double
+ $ pip install -v .
+
+**Note**: If linking against `libaubio`, make sure the library was also
+compiled in :ref:`doubleprecision` mode.
-Here is a :download:`simple script <../python/demos/demo_source_simple.py>`
-that reads all the samples from a media file:
-.. literalinclude:: ../python/demos/demo_source_simple.py
- :language: python
+Checking your installation
+--------------------------
-Filtering an input sound file
-.............................
+Once the python module is installed, its version can be checked with:
-Here is a more complete example, :download:`demo_filter.py
-<../python/demos/demo_filter.py>`. This files executes the following:
+.. code-block:: console
-* read an input media file (``aubio.source``)
+ $ python -c "import aubio; print(aubio.version, aubio.float_type)"
-* filter it using an `A-weighting <https://en.wikipedia.org/wiki/A-weighting>`_
- filter (``aubio.digital_filter``)
+The command line `aubio` is also installed:
-* write result to a new file (``aubio.sink``)
+.. code-block:: console
-.. literalinclude:: ../python/demos/demo_filter.py
- :language: python
+ $ aubio -h
-More demos
-..........
-Check out the `python demos folder`_ for more examples.
-
Python tests
------------
@@ -76,6 +70,5 @@
A number of `python tests`_ are provided. To run them, use
``python/tests/run_all_tests``.
-.. _python demos folder: https://github.com/aubio/aubio/blob/master/python/demos
.. _demo_filter.py: https://github.com/aubio/aubio/blob/master/python/demos/demo_filter.py
.. _python tests: https://github.com/aubio/aubio/blob/master/python/tests
--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -297,12 +297,15 @@
--manpagesdir=/opt/share/man \
uninstall clean distclean dist distcheck
+.. _doubleprecision:
+
Double precision
................
To compile aubio in double precision mode, configure with ``--enable-double``.
-To compile aubio in single precision mode, use ``--disable-double`` (default).
+To compile aubio in single precision mode, use ``--disable-double`` (default,
+recommended).
Disabling the tests
...................
--- a/python/demos/demo_filter.py
+++ b/python/demos/demo_filter.py
@@ -1,36 +1,51 @@
#! /usr/bin/env python
+import sys
+import os.path
+import aubio
-def apply_filter(path):
- from aubio import source, sink, digital_filter
- from os.path import basename, splitext
-
+def apply_filter(path, target):
# open input file, get its samplerate
- s = source(path)
+ s = aubio.source(path)
samplerate = s.samplerate
# create an A-weighting filter
- f = digital_filter(7)
+ f = aubio.digital_filter(7)
f.set_a_weighting(samplerate)
- # alternatively, apply another filter
# create output file
- o = sink("filtered_" + splitext(basename(path))[0] + ".wav", samplerate)+ o = aubio.sink(target, samplerate)
total_frames = 0
while True:
+ # read from source
samples, read = s()
+ # filter samples
filtered_samples = f(samples)
+ # write to sink
o(filtered_samples, read)
+ # count frames read
total_frames += read
+ # end of file reached
if read < s.hop_size: break
+ # print some info
duration = total_frames / float(samplerate)
- print ("read {:s}".format(s.uri))- print ("applied A-weighting filtered ({:d} Hz)".format(samplerate))- print ("wrote {:s} ({:.2f} s)".format(o.uri, duration))+ input_str = "input: {:s} ({:.2f} s, {:d} Hz)"+ output_str = "output: {:s}, A-weighting filtered ({:d} frames total)"+ print (input_str.format(s.uri, duration, samplerate))
+ print (output_str.format(o.uri, total_frames))
if __name__ == '__main__':
- import sys
- for f in sys.argv[1:]:
- apply_filter(f)
+ usage = "{:s} <input_file> [output_file]".format(sys.argv[0])+ if not 1 < len(sys.argv) < 4:
+ print (usage)
+ sys.exit(1)
+ if len(sys.argv) < 3:
+ input_path = sys.argv[1]
+ basename = os.path.splitext(os.path.basename(input_path))[0] + ".wav"
+ output_path = "filtered_" + basename
+ else:
+ input_path, output_path = sys.argv[1:]
+ # run function
+ apply_filter(input_path, output_path)
--- a/python/demos/demo_source_simple.py
+++ b/python/demos/demo_source_simple.py
@@ -1,16 +1,16 @@
#! /usr/bin/env python
-import sys, aubio
+import sys
+import aubio
-samplerate = 0 # use original source samplerate
+samplerate = 0 # use original source samplerate
hop_size = 256 # number of frames to read in one block
-s = aubio.source(sys.argv[1], samplerate, hop_size)
+src = aubio.source(sys.argv[1], samplerate, hop_size)
total_frames = 0
-while True: # reading loop
- samples, read = s()
- total_frames += read
+while True:
+ samples, read = src() # read hop_size new samples from source
+ total_frames += read # increment total number of frames
if read < hop_size: break # end of file reached
fmt_string = "read {:d} frames at {:d}Hz from {:s}"-print (fmt_string.format(total_frames, s.samplerate, sys.argv[1]))
-
+print (fmt_string.format(total_frames, src.samplerate, src.uri))
--- a/python/ext/aubiomodule.c
+++ b/python/ext/aubiomodule.c
@@ -10,74 +10,194 @@
static char aubio_module_doc[] = "Python module for the aubio library";
static char Py_alpha_norm_doc[] = ""
-"alpha_norm(fvec, integer) -> float\n"
+"alpha_norm(vec, alpha)\n"
"\n"
-"Compute alpha normalisation factor on vector, given alpha\n"
+"Compute `alpha` normalisation factor of vector `vec`.\n"
"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector\n"
+"alpha : float\n"
+" norm factor\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" p-norm of the input vector, where `p=alpha`\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> b = alpha_norm(a, 9)";
+">>> a = aubio.fvec(np.arange(10)); alpha = 2\n"
+">>> aubio.alpha_norm(a, alpha), (sum(a**alpha)/len(a))**(1./alpha)\n"
+"(5.338539123535156, 5.338539126015656)\n"
+"\n"
+"Note\n"
+"----\n"
+"Computed as:\n"
+"\n"
+".. math::\n"
+" l_{\\alpha} = \n"+" \\|\\frac{\\sum_{n=0}^{N-1}{{x_n}^{\\alpha}}}{N}\\|^{1/\\alpha}\n"+"";
static char Py_bintomidi_doc[] = ""
-"bintomidi(float, samplerate = integer, fftsize = integer) -> float\n"
+"bintomidi(fftbin, samplerate, fftsize)\n"
"\n"
-"Convert bin (float) to midi (float), given the sampling rate and the FFT size\n"
+"Convert FFT bin to frequency in midi note, given the sampling rate\n"
+"and the size of the FFT.\n"
"\n"
+"Parameters\n"
+"----------\n"
+"fftbin : float\n"
+" input frequency bin\n"
+"samplerate : float\n"
+" sampling rate of the signal\n"
+"fftsize : float\n"
+" size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" Frequency converted to midi note.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> midi = bintomidi(float, samplerate = 44100, fftsize = 1024)";
+">>> aubio.bintomidi(10, 44100, 1024)\n"
+"68.62871551513672\n"
+"";
static char Py_miditobin_doc[] = ""
-"miditobin(float, samplerate = integer, fftsize = integer) -> float\n"
+"miditobin(midi, samplerate, fftsize)\n"
"\n"
-"Convert midi (float) to bin (float), given the sampling rate and the FFT size\n"
+"Convert frequency in midi note to FFT bin, given the sampling rate\n"
+"and the size of the FFT.\n"
"\n"
-"Example\n"
+"Parameters\n"
+"----------\n"
+"midi : float\n"
+" input frequency, in midi note\n"
+"samplerate : float\n"
+" sampling rate of the signal\n"
+"fftsize : float\n"
+" size of the FFT\n"
+"\n"
+"Returns\n"
"-------\n"
+"float\n"
+" Frequency converted to FFT bin.\n"
"\n"
-">>> bin = miditobin(midi, samplerate = 44100, fftsize = 1024)";
+"Examples\n"
+"--------\n"
+"\n"
+">>> aubio.miditobin(69, 44100, 1024)\n"
+"10.216779708862305\n"
+">>> aubio.miditobin(75.08, 32000, 512)\n"
+"10.002175331115723\n"
+"";
static char Py_bintofreq_doc[] = ""
-"bintofreq(float, samplerate = integer, fftsize = integer) -> float\n"
+"bintofreq(fftbin, samplerate, fftsize)\n"
"\n"
-"Convert bin number (float) in frequency (Hz), given the sampling rate and the FFT size\n"
+"Convert FFT bin to frequency in Hz, given the sampling rate\n"
+"and the size of the FFT.\n"
"\n"
+"Parameters\n"
+"----------\n"
+"fftbin : float\n"
+" input frequency bin\n"
+"samplerate : float\n"
+" sampling rate of the signal\n"
+"fftsize : float\n"
+" size of the FFT\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" Frequency converted to Hz.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> freq = bintofreq(bin, samplerate = 44100, fftsize = 1024)";
+">>> aubio.bintofreq(10, 44100, 1024)\n"
+"430.6640625\n"
+"";
static char Py_freqtobin_doc[] = ""
-"freqtobin(float, samplerate = integer, fftsize = integer) -> float\n"
+"freqtobin(freq, samplerate, fftsize)\n"
"\n"
-"Convert frequency (Hz) in bin number (float), given the sampling rate and the FFT size\n"
+"Convert frequency in Hz to FFT bin, given the sampling rate\n"
+"and the size of the FFT.\n"
"\n"
-"Example\n"
+"Parameters\n"
+"----------\n"
+"midi : float\n"
+" input frequency, in midi note\n"
+"samplerate : float\n"
+" sampling rate of the signal\n"
+"fftsize : float\n"
+" size of the FFT\n"
+"\n"
+"Returns\n"
"-------\n"
+"float\n"
+" Frequency converted to FFT bin.\n"
"\n"
-">>> bin = freqtobin(freq, samplerate = 44100, fftsize = 1024)";
+"Examples\n"
+"--------\n"
+"\n"
+">>> aubio.freqtobin(440, 44100, 1024)\n"
+"10.216779708862305\n"
+"";
static char Py_zero_crossing_rate_doc[] = ""
-"zero_crossing_rate(fvec) -> float\n"
+"zero_crossing_rate(vec)\n"
"\n"
-"Compute Zero crossing rate of a vector\n"
+"Compute zero-crossing rate of `vec`.\n"
"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector\n"
+"\n"
+"Returns\n"
+"-------\n"
+"float\n"
+" Zero-crossing rate.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> z = zero_crossing_rate(a)";
+">>> a = np.linspace(-1., 1., 1000, dtype=aubio.float_type)\n"
+">>> aubio.zero_crossing_rate(a), 1/1000\n"
+"(0.0010000000474974513, 0.001)\n"
+"";
static char Py_min_removal_doc[] = ""
-"min_removal(fvec) -> float\n"
+"min_removal(vec)\n"
"\n"
-"Remove the minimum value of a vector, in-place modification\n"
+"Remove the minimum value of a vector to each of its element.\n"
"\n"
+"Modifies the input vector in-place and returns a reference to it.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector\n"
+"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+" modified input vector\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> min_removal(a)";
+">>> aubio.min_removal(aubio.fvec(np.arange(1,4)))\n"
+"array([0., 1., 2.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"";
extern void add_ufuncs ( PyObject *m );
extern int generated_types_ready(void);
--- a/python/ext/py-cvec.c
+++ b/python/ext/py-cvec.c
@@ -19,7 +19,37 @@
uint_t length;
} Py_cvec;
-static char Py_cvec_doc[] = "cvec object";
+static char Py_cvec_doc[] = ""
+"cvec(size)\n"
+"\n"
+"A container holding spectral data.\n"
+"\n"
+"Create one `cvec` to store the spectral information of a window\n"
+"of `size` points. The data will be stored in two vectors,\n"
+":attr:`phas` and :attr:`norm`, each of shape (:attr:`length`,),\n"
+"with `length = size // 2 + 1`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"size: int\n"
+" Size of spectrum to create.\n"
+"\n"
+"Examples\n"
+"--------\n"
+">>> c = aubio.cvec(1024)\n"
+">>> c\n"
+"aubio cvec of 513 elements\n"
+">>> c.length\n"
+"513\n"
+">>> c.norm.dtype, c.phas.dtype\n"
+"(dtype('float32'), dtype('float32'))\n"+">>> c.norm.shape, c.phas.shape\n"
+"((513,), (513,))\n"
+"\n"
+"See Also\n"
+"--------\n"
+"fvec, fft, pvoc\n"
+"";
PyObject *
@@ -182,7 +212,7 @@
static PyMemberDef Py_cvec_members[] = {// TODO remove READONLY flag and define getter/setter
{"length", T_INT, offsetof (Py_cvec, length), READONLY,- "length attribute"},
+ "int: Length of `norm` and `phas` vectors."},
{NULL} /* Sentinel */};
@@ -191,11 +221,11 @@
};
static PyGetSetDef Py_cvec_getseters[] = {- {"norm", (getter)Py_cvec_get_norm, (setter)Py_cvec_set_norm, - "Numpy vector of shape (length,) containing the magnitude",
+ {"norm", (getter)Py_cvec_get_norm, (setter)Py_cvec_set_norm,+ "numpy.ndarray: Vector of shape `(length,)` containing the magnitude.",
NULL},
- {"phas", (getter)Py_cvec_get_phas, (setter)Py_cvec_set_phas, - "Numpy vector of shape (length,) containing the phase",
+ {"phas", (getter)Py_cvec_get_phas, (setter)Py_cvec_set_phas,+ "numpy.ndarray: Vector of shape `(length,)` containing the phase.",
NULL},
{NULL} /* sentinel */};
--- a/python/ext/py-musicutils.h
+++ b/python/ext/py-musicutils.h
@@ -2,103 +2,302 @@
#define PY_AUBIO_MUSICUTILS_H
static char Py_aubio_window_doc[] = ""
-"window(string, integer) -> fvec\n"
+"window(window_type, size)\n"
"\n"
-"Create a window\n"
+"Create a window of length `size`. `window_type` should be one\n"
+"of the following:\n"
"\n"
-"Example\n"
+"- `default` (same as `hanningz`).\n"
+"- `ones`\n"
+"- `rectangle`\n"
+"- `hamming`\n"
+"- `hanning`\n"
+"- `hanningz` [1]_\n"
+"- `blackman`\n"
+"- `blackman_harris`\n"
+"- `gaussian`\n"
+"- `welch`\n"
+"- `parzen`\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"window_type : str\n"
+" Type of window.\n"
+"size : int\n"
+" Length of window.\n"
+"\n"
+"Returns\n"
"-------\n"
+"fvec\n"
+" Array of shape `(length,)` containing the new window.\n"
"\n"
-">>> window('hanningz', 1024)\n"+"See Also\n"
+"--------\n"
+"pvoc, fft\n"
+"\n"
+"Examples\n"
+"--------\n"
+"Compute a zero-phase Hann window on `1024` points:\n"
+"\n"
+">>> aubio.window('hanningz', 1024)\n""array([ 0.00000000e+00, 9.41753387e-06, 3.76403332e-05, ...,\n"
-" 8.46982002e-05, 3.76403332e-05, 9.41753387e-06], dtype=float32)";
+" 8.46982002e-05, 3.76403332e-05, 9.41753387e-06], dtype=float32)\n"
+"\n"
+"Plot different window types with `matplotlib <https://matplotlib.org/>`_:\n"
+"\n"
+">>> import matplotlib.pyplot as plt\n"
+">>> modes = ['default', 'ones', 'rectangle', 'hamming', 'hanning',\n"
+"... 'hanningz', 'blackman', 'blackman_harris', 'gaussian',\n"
+"... 'welch', 'parzen']; n = 2048\n"
+">>> for m in modes: plt.plot(aubio.window(m, n), label=m)\n"
+"...\n"
+">>> plt.legend(); plt.show()\n"
+"\n"
+"Note\n"
+"----\n"
+"The following examples contain the equivalent source code to compute\n"
+"each type of window with `NumPy <https://numpy.org>`_:\n"
+"\n"
+">>> n = 1024; x = np.arange(n, dtype=aubio.float_type)\n"
+">>> ones = np.ones(n).astype(aubio.float_type)\n"
+">>> rectangle = 0.5 * ones\n"
+">>> hanning = 0.5 - 0.5 * np.cos(2 * np.pi * x / n)\n"
+">>> hanningz = 0.5 * (1 - np.cos(2 * np.pi * x / n))\n"
+">>> hamming = 0.54 - 0.46 * np.cos(2.*np.pi * x / (n - 1))\n"
+">>> blackman = 0.42 \\\n"
+"... - 0.50 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
+"... + 0.08 * np.cos(4 * np.pi * x / (n - 1))\n"
+">>> blackman_harris = 0.35875 \\\n"
+"... - 0.48829 * np.cos(2 * np.pi * x / (n - 1)) \\\n"
+"... + 0.14128 * np.cos(4 * np.pi * x / (n - 1)) \\\n"
+"... + 0.01168 * np.cos(6 * np.pi * x / (n - 1))\n"
+">>> gaussian = np.exp( - 0.5 * ((x - 0.5 * (n - 1)) \\\n"
+"... / (0.25 * (n - 1)) )**2 )\n"
+">>> welch = 1 - ((2 * x - n) / (n + 1))**2\n"
+">>> parzen = 1 - np.abs((2 * x - n) / (n + 1))\n"
+">>> default = hanningz\n"
+"References\n"
+"----------\n"
+#if 0
+"`Window function <https://en.wikipedia.org/wiki/Window_function>`_ on\n"
+"Wikipedia.\n"
+"\n"
+#endif
+".. [1] 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"
+"";
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);
static char Py_aubio_shift_doc[] = ""
-"Swap left and right partitions of a vector\n"
+"shift(vec)\n"
"\n"
-"Returns the swapped vector. The input vector is also modified.\n"
+"Swap left and right partitions of a vector, in-place.\n"
"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector to shift\n"
+"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+" The swapped vector.\n"
+"\n"
+"Notes\n"
+"-----\n"
+"The input vector is also modified.\n"
+"\n"
"For a vector of length N, the partition is split at index N - N//2.\n"
"\n"
"Example\n"
"-------\n"
"\n"
-">>> import numpy\n"
-">>> shift(numpy.arange(3, dtype=aubio.float_type))\n"
-"array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")";
+">>> aubio.shift(aubio.fvec(np.arange(3)))\n"
+"array([2., 0., 1.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"\n"
+"See Also\n"
+"--------\n"
+"ishift\n"
+"";
PyObject * Py_aubio_shift(PyObject *self, PyObject *args);
static char Py_aubio_ishift_doc[] = ""
-"Swap right and left partitions of a vector\n"
+"ishift(vec)\n"
"\n"
-"Returns the swapped vector. The input vector is also modified.\n"
+"Swap right and left partitions of a vector, in-place.\n"
"\n"
-"Unlike with shift(), the partition is split at index N//2.\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector to shift\n"
"\n"
+"Returns\n"
+"-------\n"
+"fvec\n"
+" The swapped vector.\n"
+"\n"
+"Notes\n"
+"-----\n"
+"The input vector is also modified.\n"
+"\n"
+"Unlike with :py:func:`shift`, the partition is split at index N//2.\n"
+"\n"
"Example\n"
"-------\n"
"\n"
-">>> import numpy\n"
-">>> ishift(numpy.arange(3, dtype=aubio.float_type))\n"
-"array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")";
+">>> aubio.ishift(aubio.fvec(np.arange(3)))\n"
+"array([1., 2., 0.], dtype=" AUBIO_NPY_SMPL_STR ")\n"
+"\n"
+"See Also\n"
+"--------\n"
+"shift\n"
+"";
PyObject * Py_aubio_ishift(PyObject *self, PyObject *args);
#endif /* PY_AUBIO_MUSICUTILS_H */
--- 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}};
--- a/python/ext/py-sink.c
+++ b/python/ext/py-sink.c
@@ -12,53 +12,78 @@
} Py_sink;
static char Py_sink_doc[] = ""
-" __new__(path, samplerate = 44100, channels = 1)\n"
+"sink(path, samplerate=44100, channels=1)\n"
"\n"
-" Create a new sink, opening the given path for writing.\n"
+"Open `path` to write a WAV file.\n"
"\n"
-" Examples\n"
-" --------\n"
+"Parameters\n"
+"----------\n"
+"path : str\n"
+" Pathname of the file to be opened for writing.\n"
+"samplerate : int\n"
+" Sampling rate of the file, in Hz.\n"
+"channels : int\n"
+" Number of channels to create the file with.\n"
"\n"
-" Create a new sink at 44100Hz, mono:\n"
+"Examples\n"
+"--------\n"
"\n"
-" >>> sink('/tmp/t.wav')\n"+"Create a new sink at 44100Hz, mono:\n"
"\n"
-" Create a new sink at 8000Hz, mono:\n"
+">>> snk = aubio.sink('out.wav')\n""\n"
-" >>> sink('/tmp/t.wav', samplerate = 8000)\n"+"Create a new sink at 32000Hz, stereo, write 100 samples into it:\n"
"\n"
-" Create a new sink at 32000Hz, stereo:\n"
+">>> snk = aubio.sink('out.wav', samplerate=16000, channels=3)\n"+">>> snk(aubio.fvec(100), 100)\n"
"\n"
-" >>> sink('/tmp/t.wav', samplerate = 32000, channels = 2)\n"+"Open a new sink at 48000Hz, stereo, write `1234` samples into it:\n"
"\n"
-" Create a new sink at 32000Hz, 5 channels:\n"
+">>> with aubio.sink('out.wav', samplerate=48000, channels=2) as src:\n"+"... snk(aubio.fvec(1024), 1024)\n"
+"... snk(aubio.fvec(210), 210)\n"
+"...\n"
"\n"
-" >>> sink('/tmp/t.wav', channels = 5, samplerate = 32000)\n"-"\n"
-" __call__(vec, write)\n"
-" x(vec,write) <==> x.do(vec, write)\n"
-"\n"
-" Write vector to sink.\n"
-"\n"
-" See also\n"
-" --------\n"
-" aubio.sink.do\n"
+"See also\n"
+"--------\n"
+"source: read audio samples from a file.\n"
"\n";
static char Py_sink_do_doc[] = ""
-"x.do(vec, write) <==> x(vec, write)\n"
+"do(vec, write)\n"
"\n"
-"write monophonic vector to sink";
+"Write a single channel vector to sink.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"vec : fvec\n"
+" input vector `(n,)` where `n >= 0`.\n"
+"write : int\n"
+" Number of samples to write.\n"
+"";
static char Py_sink_do_multi_doc[] = ""
-"x.do_multi(mat, write)\n"
+"do_multi(mat, write)\n"
"\n"
-"write polyphonic vector to sink";
+"Write a matrix containing vectors from multiple channels to sink.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"mat : numpy.ndarray\n"
+" input matrix of shape `(channels, n)`, where `n >= 0`.\n"
+"write : int\n"
+" Number of frames to write.\n"
+"";
static char Py_sink_close_doc[] = ""
-"x.close()\n"
+"close()\n"
"\n"
-"close this sink now";
+"Close this sink now.\n"
+"\n"
+"By default, the sink will be closed before being deleted.\n"
+"Explicitely closing a sink can be useful to control the number\n"
+"of files simultaneously opened.\n"
+"";
static PyObject *
Py_sink_new (PyTypeObject * pytype, PyObject * args, PyObject * kwds)
@@ -188,11 +213,11 @@
static PyMemberDef Py_sink_members[] = { {"uri", T_STRING, offsetof (Py_sink, uri), READONLY,- "path at which the sink was created"},
+ "str (read-only): Path at which the sink was created."},
{"samplerate", T_INT, offsetof (Py_sink, samplerate), READONLY,- "samplerate at which the sink was created"},
+ "int (read-only): Samplerate at which the sink was created."},
{"channels", T_INT, offsetof (Py_sink, channels), READONLY,- "number of channels with which the sink was created"},
+ "int (read-only): Number of channels with which the sink was created."},
{ NULL } // sentinel};
--- a/python/ext/py-source.c
+++ b/python/ext/py-source.c
@@ -16,68 +16,316 @@
} Py_source;
static char Py_source_doc[] = ""
-" __new__(path, samplerate = 0, hop_size = 512, channels = 1)\n"
+"source(path, samplerate=0, hop_size=512, channels=0)\n"
"\n"
-" Create a new source, opening the given path for reading.\n"
+"Create a new source, opening the given pathname for reading.\n"
"\n"
-" Examples\n"
-" --------\n"
+"`source` open the file specified in `path` and creates a callable\n"
+"returning `hop_size` new audio samples at each invocation.\n"
"\n"
-" Create a new source, using the original samplerate, with hop_size = 512:\n"
+"If `samplerate=0` (default), the original sampling rate of `path`\n"
+"will be used. Otherwise, the output audio samples will be\n"
+"resampled at the desired sampling-rate.\n"
"\n"
-" >>> source('/tmp/t.wav')\n"+"If `channels=0` (default), the original number of channels\n"
+"in `path` will be used. Otherwise, the output audio samples\n"
+"will be down-mixed or up-mixed to the desired number of\n"
+"channels.\n"
"\n"
-" Create a new source, resampling the original to 8000Hz:\n"
+"If `path` is a URL, a remote connection will be attempted to\n"
+"open the resource and stream data from it.\n"
"\n"
-" >>> source('/tmp/t.wav', samplerate = 8000)\n"+"The parameter `hop_size` determines how many samples should be\n"
+"read at each consecutive calls.\n"
"\n"
-" Create a new source, resampling it at 32000Hz, hop_size = 32:\n"
+"Parameters\n"
+"----------\n"
+"path : str\n"
+" pathname (or URL) of the file to be opened for reading\n"
+"samplerate : int, optional\n"
+" sampling rate of the file\n"
+"hop_size : int, optional\n"
+" number of samples to be read per iteration\n"
+"channels : int, optional\n"
+" number of channels of the file\n"
"\n"
-" >>> source('/tmp/t.wav', samplerate = 32000, hop_size = 32)\n"+"Examples\n"
+"--------\n"
+"By default, when only `path` is given, the file will be opened\n"
+"with its original sampling rate and channel:\n"
"\n"
-" Create a new source, using its original samplerate:\n"
+">>> src = aubio.source('stereo.wav')\n"+">>> src.uri, src.samplerate, src.channels, src.duration\n"
+"('stereo.wav', 48000, 2, 86833)\n""\n"
-" >>> source('/tmp/t.wav', samplerate = 0)\n"+"A typical loop to read all samples from a local file could\n"
+"look like this:\n"
"\n"
-" __call__()\n"
-" vec, read = x() <==> vec, read = x.do()\n"
+">>> src = aubio.source('stereo.wav')\n"+">>> total_read = 0\n"
+">>> while True:\n"
+"... samples, read = src()\n"
+"... # do something with samples\n"
+"... total_read += read\n"
+"... if read < src.hop_size:\n"
+"... break\n"
+"...\n"
"\n"
-" Read vector from source.\n"
+"In a more Pythonic way, it can also look like this:\n"
"\n"
-" See also\n"
-" --------\n"
-" aubio.source.do\n"
-"\n";
+">>> total_read = 0\n"
+">>> with aubio.source('stereo.wav') as src:\n"+"... for frames in src:\n"
+"... total_read += samples.shape[-1]\n"
+"...\n"
+"\n"
+".. rubric:: Basic interface\n"
+"\n"
+"`source` is a **callable**; its :meth:`__call__` method\n"
+"returns a tuple containing:\n"
+"\n"
+"- a vector of shape `(hop_size,)`, filled with the `read` next\n"
+" samples available, zero-padded if `read < hop_size`\n"
+"- `read`, an integer indicating the number of samples read\n"
+"\n"
+"To read the first `hop_size` samples from the source, simply call\n"
+"the instance itself, with no argument:\n"
+"\n"
+">>> src = aubio.source('song.ogg')\n"+">>> samples, read = src()\n"
+">>> samples.shape, read, src.hop_size\n"
+"((512,), 512, 512)\n"
+"\n"
+"The first call returned the slice of samples `[0 : hop_size]`.\n"
+"The next call will return samples `[hop_size: 2*hop_size]`.\n"
+"\n"
+"After several invocations of :meth:`__call__`, when reaching the end\n"
+"of the opened stream, `read` might become less than `hop_size`:\n"
+"\n"
+">>> samples, read = src()\n"
+">>> samples.shape, read\n"
+"((512,), 354)\n"
+"\n"
+"The end of the vector `samples` is filled with zeros.\n"
+"\n"
+"After the end of the stream, `read` will be `0` since no more\n"
+"samples are available:\n"
+"\n"
+">>> samples, read = src()\n"
+">>> samples.shape, read\n"
+"((512,), 0)\n"
+"\n"
+"**Note**: when the source has more than one channels, they\n"
+"are be down-mixed to mono when invoking :meth:`__call__`.\n"
+"To read from each individual channel, see :meth:`__next__`.\n"
+"\n"
+".. rubric:: ``for`` statements\n"
+"\n"
+"The `source` objects are **iterables**. This allows using them\n"
+"directly in a ``for`` loop, which calls :meth:`__next__` until\n"
+"the end of the stream is reached:\n"
+"\n"
+">>> src = aubio.source('stereo.wav')\n"+">>> for frames in src:\n"
+">>> print (frames.shape)\n"
+"...\n"
+"(2, 512)\n"
+"(2, 512)\n"
+"(2, 230)\n"
+"\n"
+"**Note**: When `next(self)` is called on a source with multiple\n"
+"channels, an array of shape `(channels, read)` is returned,\n"
+"unlike with :meth:`__call__` which always returns the down-mixed\n"
+"channels.\n"
+"\n"
+"If the file is opened with a single channel, `next(self)` returns\n"
+"an array of shape `(read,)`:\n"
+"\n"
+">>> src = aubio.source('stereo.wav', channels=1)\n"+">>> next(src).shape\n"
+"(512,)\n"
+"\n"
+".. rubric:: ``with`` statements\n"
+"\n"
+"The `source` objects are **context managers**, which allows using\n"
+"them in ``with`` statements:\n"
+"\n"
+">>> with aubio.source('audiotrack.wav') as source:\n"+"... n_frames=0\n"
+"... for samples in source:\n"
+"... n_frames += len(samples)\n"
+"... print('read', n_frames, 'samples in', samples.shape[0], 'channels',\n"+"... 'from file \"\%s\"' \% source.uri)\n"
+"...\n"
+"read 239334 samples in 2 channels from file \"audiotrack.wav\"\n"
+"\n"
+"The file will be closed before exiting the statement.\n"
+"\n"
+"See also the methods implementing the context manager,\n"
+":meth:`__enter__` and :meth:`__exit__`.\n"
+"\n"
+".. rubric:: Seeking and closing\n"
+"\n"
+"At any time, :meth:`seek` can be used to move to any position in\n"
+"the file. For instance, to rewind to the start of the stream:\n"
+"\n"
+">>> src.seek(0)\n"
+"\n"
+"The opened file will be automatically closed when the object falls\n"
+"out of scope and is scheduled for garbage collection.\n"
+"\n"
+"In some cases, it is useful to manually :meth:`close` a given source,\n"
+"for instance to limit the number of simultaneously opened files:\n"
+"\n"
+">>> src.close()\n"
+"\n"
+".. rubric:: Input formats\n"
+"\n"
+"Depending on how aubio was compiled, :class:`source` may or may not\n"
+"open certain **files format**. Below are some examples that assume\n"
+"support for compressed files and remote urls was compiled in:\n"
+"\n"
+"- open a local file using its original sampling rate and channels,\n"
+" and with the default hop size:\n"
+"\n"
+">>> s = aubio.source('sample.wav')\n"+">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
+"('sample.wav', 44100, 2, 512)\n"+"\n"
+"- open a local compressed audio file, resampling to 32000Hz if needed:\n"
+"\n"
+">>> s = aubio.source('song.mp3', samplerate=32000)\n"+">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
+"('song.mp3', 32000, 2, 512)\n"+"\n"
+"- open a local video file, down-mixing and resampling it to 16kHz:\n"
+"\n"
+">>> s = aubio.source('movie.mp4', samplerate=16000, channels=1)\n"+">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
+"('movie.mp4', 16000, 1, 512)\n"+"\n"
+"- open a remote resource, with hop_size = 1024:\n"
+"\n"
+">>> s = aubio.source('https://aubio.org/drum.ogg', hop_size=1024)\n"+">>> s.uri, s.samplerate, s.channels, s.hop_size\n"
+"('https://aubio.org/drum.ogg', 48000, 2, 1024)\n"+"\n"
+"See Also\n"
+"--------\n"
+"sink: write audio samples to a file.\n"
+"";
static char Py_source_get_samplerate_doc[] = ""
-"x.get_samplerate() -> source samplerate\n"
+"get_samplerate()\n"
"\n"
-"Get samplerate of source.";
+"Get sampling rate of source.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"int\n"
+" Sampling rate, in Hz.\n"
+"";
static char Py_source_get_channels_doc[] = ""
-"x.get_channels() -> number of channels\n"
+"get_channels()\n"
"\n"
-"Get number of channels in source.";
+"Get number of channels in source.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"int\n"
+" Number of channels.\n"
+"";
static char Py_source_do_doc[] = ""
-"vec, read = x.do() <==> vec, read = x()\n"
+"source.do()\n"
"\n"
-"Read monophonic vector from source.";
+"Read vector of audio samples.\n"
+"\n"
+"If the audio stream in the source has more than one channel,\n"
+"the channels will be down-mixed.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"samples : numpy.ndarray, shape `(hop_size,)`, dtype aubio.float_type\n"
+" `fvec` of size `hop_size` containing the new samples.\n"
+"read : int\n"
+" Number of samples read from the source, equals to `hop_size`\n"
+" before the end-of-file is reached, less when it is reached,\n"
+" and `0` after.\n"
+"\n"
+"See Also\n"
+"--------\n"
+"do_multi\n"
+"\n"
+"Examples\n"
+"--------\n"
+">>> src = aubio.source('sample.wav', hop_size=1024)\n"+">>> src.do()\n"
+"(array([-0.00123001, -0.00036685, 0.00097106, ..., -0.2031033 ,\n"
+" -0.2025854 , -0.20221856], dtype=" AUBIO_NPY_SMPL_STR "), 1024)\n"
+"";
static char Py_source_do_multi_doc[] = ""
-"mat, read = x.do_multi()\n"
+"do_multi()\n"
"\n"
-"Read polyphonic vector from source.";
+"Read multiple channels of audio samples.\n"
+"\n"
+"If the source was opened with the same number of channels\n"
+"found in the stream, each channel will be read individually.\n"
+"\n"
+"If the source was opened with less channels than the number\n"
+"of channels in the stream, only the first channels will be read.\n"
+"\n"
+"If the source was opened with more channels than the number\n"
+"of channel in the original stream, the first channels will\n"
+"be duplicated on the additional output channel.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"samples : np.ndarray([hop_size, channels], dtype=aubio.float_type)\n"
+" NumPy array of shape `(hop_size, channels)` containing the new\n"
+" audio samples.\n"
+"read : int\n"
+" Number of samples read from the source, equals to `hop_size`\n"
+" before the end-of-file is reached, less when it is reached,\n"
+" and `0` after.\n"
+"\n"
+"See Also\n"
+"--------\n"
+"do\n"
+"\n"
+"Examples\n"
+"--------\n"
+">>> src = aubio.source('sample.wav')\n"+">>> src.do_multi()\n"
+"(array([[ 0.00668335, 0.0067749 , 0.00714111, ..., -0.05737305,\n"
+" -0.05856323, -0.06018066],\n"
+" [-0.00842285, -0.0072937 , -0.00576782, ..., -0.09405518,\n"
+" -0.09558105, -0.09725952]], dtype=" AUBIO_NPY_SMPL_STR "), 512)\n"
+"";
static char Py_source_close_doc[] = ""
-"x.close()\n"
+"close()\n"
"\n"
-"Close this source now.";
+"Close this source now.\n"
+"\n"
+".. note:: Closing twice a source will **not** raise any exception.\n"
+"";
static char Py_source_seek_doc[] = ""
-"x.seek(position)\n"
+"seek(position)\n"
"\n"
-"Seek to resampled frame position.";
+"Seek to position in file.\n"
+"\n"
+"If the source was not opened with its original sampling-rate,\n"
+"`position` corresponds to the position in the re-sampled file.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"position : str\n"
+" position to seek to, in samples\n"
+"";
static PyObject *
Py_source_new (PyTypeObject * pytype, PyObject * args, PyObject * kwds)
@@ -217,15 +465,29 @@
static PyMemberDef Py_source_members[] = { {"uri", T_STRING, offsetof (Py_source, uri), READONLY,- "path at which the source was created"},
+ "str (read-only): pathname or URL"},
{"samplerate", T_INT, offsetof (Py_source, samplerate), READONLY,- "samplerate at which the source is viewed"},
+ "int (read-only): sampling rate"},
{"channels", T_INT, offsetof (Py_source, channels), READONLY,- "number of channels found in the source"},
+ "int (read-only): number of channels"},
{"hop_size", T_INT, offsetof (Py_source, hop_size), READONLY,- "number of consecutive frames that will be read at each do or do_multi call"},
+ "int (read-only): number of samples read per iteration"},
{"duration", T_INT, offsetof (Py_source, duration), READONLY,- "total number of frames in the source (estimated)"},
+ "int (read-only): total number of frames in the source\n"
+ "\n"
+ "Can be estimated, for instance if the opened stream is\n"
+ "a compressed media or a remote resource.\n"
+ "\n"
+ "Example\n"
+ "-------\n"
+ ">>> n = 0\n"
+ ">>> src = aubio.source('track1.mp3')\n"+ ">>> for samples in src:\n"
+ "... n += samples.shape[-1]\n"
+ "...\n"
+ ">>> n, src.duration\n"
+ "(9638784, 9616561)\n"
+ ""},
{ NULL } // sentinel};
--- a/python/ext/ufuncs.c
+++ b/python/ext/ufuncs.c
@@ -58,8 +58,23 @@
//NPY_OBJECT, NPY_OBJECT,
};
-static char Py_unwrap2pi_doc[] = "map angle to unit circle [-pi, pi[";
+// Note: these docstrings should *not* include the function signatures
+static char Py_unwrap2pi_doc[] = ""
+"\n"
+"Map angle to unit circle :math:`[-\\pi, \\pi[`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"x : numpy.ndarray\n"
+" input array\n"
+"\n"
+"Returns\n"
+"-------\n"
+"numpy.ndarray\n"
+" values clamped to the unit circle :math:`[-\\pi, \\pi[`\n"
+"";
+
static void* Py_unwrap2pi_data[] = {(void *)aubio_unwrap2pi,
(void *)aubio_unwrap2pi,
@@ -67,7 +82,20 @@
//(void *)unwrap2pio,
};
-static char Py_freqtomidi_doc[] = "convert frequency to midi";
+static char Py_freqtomidi_doc[] = ""
+"\n"
+"Convert frequency `[0; 23000[` to midi `[0; 128[`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"x : numpy.ndarray\n"
+" Array of frequencies, in Hz.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"numpy.ndarray\n"
+" Converted frequencies, in midi note.\n"
+"";
static void* Py_freqtomidi_data[] = {(void *)aubio_freqtomidi,
@@ -74,7 +102,20 @@
(void *)aubio_freqtomidi,
};
-static char Py_miditofreq_doc[] = "convert midi to frequency";
+static char Py_miditofreq_doc[] = ""
+"\n"
+"Convert midi `[0; 128[` to frequency `[0, 23000]`.\n"
+"\n"
+"Parameters\n"
+"----------\n"
+"x : numpy.ndarray\n"
+" Array of frequencies, in midi note.\n"
+"\n"
+"Returns\n"
+"-------\n"
+"numpy.ndarray\n"
+" Converted frequencies, in Hz\n"
+"";
static void* Py_miditofreq_data[] = {(void *)aubio_miditofreq,
--- a/python/lib/aubio/__init__.py
+++ b/python/lib/aubio/__init__.py
@@ -1,5 +1,27 @@
#! /usr/bin/env python
+# -*- coding: utf8 -*-
+"""
+aubio
+=====
+
+Provides a number of classes and functions for music and audio signal
+analysis.
+
+How to use the documentation
+----------------------------
+
+Documentation of the python module is available as docstrings provided
+within the code, and a reference guide available online from `the
+aubio homepage <https://aubio.org/documentation>`_.
+
+The docstrings examples are written assuming `aubio` and `numpy` have been
+imported with:
+
+>>> import aubio
+>>> import numpy as np
+"""
+
import numpy
from ._aubio import __version__ as version
from ._aubio import float_type
@@ -8,8 +30,56 @@
from .slicing import *
class fvec(numpy.ndarray):
- """a numpy vector holding audio samples"""
+ """fvec(input_arg=1024, **kwargs)
+ A vector holding float samples.
+ If `input_arg` is an `int`, a 1-dimensional vector of length `input_arg`
+ will be created and filled with zeros. Otherwise, if `input_arg` is an
+ `array_like` object, it will be converted to a 1-dimensional vector of
+ type :data:`float_type`.
+
+ Parameters
+ ----------
+ input_arg : `int` or `array_like`
+ Can be a positive integer, or any object that can be converted to
+ a numpy array with :func:`numpy.array`.
+ **kwargs
+ Additional keyword arguments passed to :func:`numpy.zeros`, if
+ `input_arg` is an integer, or to :func:`numpy.array`. Should not
+ include `dtype`, which is already specified as
+ :data:`aubio.float_type`.
+
+ Returns
+ -------
+ numpy.ndarray
+ Array of shape `(length,)`.
+
+ Examples
+ --------
+ >>> aubio.fvec(10)
+ array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], dtype=float32)
+ >>> aubio.fvec([0,1,2])
+ array([0., 1., 2.], dtype=float32)
+ >>> a = np.arange(10); type(a), type(aubio.fvec(a))
+ (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)
+ >>> a.dtype, aubio.fvec(a).dtype
+ (dtype('int64'), dtype('float32'))+
+ Notes
+ -----
+
+ In the Python world, `fvec` is simply a subclass of
+ :class:`numpy.ndarray`. In practice, any 1-dimensional `numpy.ndarray` of
+ `dtype` :data:`float_type` may be passed to methods accepting
+ `fvec` as parameter. For instance, `sink()` or `pvoc()`.
+
+ See Also
+ --------
+ cvec : a container holding spectral data
+ numpy.ndarray : parent class of :class:`fvec`
+ numpy.zeros : create a numpy array filled with zeros
+ numpy.array : create a numpy array from an existing object
+ """
def __new__(cls, input_arg=1024, **kwargs):
if isinstance(input_arg, int):
if input_arg == 0:
--- a/python/lib/aubio/midiconv.py
+++ b/python/lib/aubio/midiconv.py
@@ -15,7 +15,46 @@
int_instances = (int, long)
def note2midi(note):
- " convert note name to midi note number, e.g. [C-1, G9] -> [0, 127] "
+ """Convert note name to midi note number.
+
+ Input string `note` should be composed of one note root
+ and one octave, with optionally one modifier in between.
+
+ List of valid components:
+
+ - note roots: `C`, `D`, `E`, `F`, `G`, `A`, `B`,
+ - modifiers: `b`, `#`, as well as unicode characters
+ `𝄫`, `♭`, `♮`, `♯` and `𝄪`,
+ - octave numbers: `-1` -> `11`.
+
+ Parameters
+ ----------
+ note : str
+ note name
+
+ Returns
+ -------
+ int
+ corresponding midi note number
+
+ Examples
+ --------
+ >>> aubio.note2midi('C#4')+ 61
+ >>> aubio.note2midi('B♭5')+ 82
+
+ Raises
+ ------
+ TypeError
+ If `note` was not a string.
+ ValueError
+ If an error was found while converting `note`.
+
+ See Also
+ --------
+ midi2note, freqtomidi, miditofreq
+ """
_valid_notenames = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11} _valid_modifiers = {u'𝄫': -2, # double flat
@@ -61,7 +100,36 @@
return midi
def midi2note(midi):
- " convert midi note number to note name, e.g. [0, 127] -> [C-1, G9] "
+ """Convert midi note number to note name.
+
+ Parameters
+ ----------
+ midi : int [0, 128]
+ input midi note number
+
+ Returns
+ -------
+ str
+ note name
+
+ Examples
+ --------
+ >>> aubio.midi2note(70)
+ 'A#4'
+ >>> aubio.midi2note(59)
+ 'B3'
+
+ Raises
+ ------
+ TypeError
+ If `midi` was not an integer.
+ ValueError
+ If `midi` is out of the range `[0, 128]`.
+
+ See Also
+ --------
+ note2midi, miditofreq, freqtomidi
+ """
if not isinstance(midi, int_instances):
raise TypeError("an integer is required, got %s" % midi)if midi not in range(0, 128):
@@ -72,7 +140,25 @@
return _valid_notenames[midi % 12] + str(int(midi / 12) - 1)
def freq2note(freq):
- " convert frequency in Hz to nearest note name, e.g. [0, 22050.] -> [C-1, G9] "
+ """Convert frequency in Hz to nearest note name.
+
+ Parameters
+ ----------
+ freq : float [0, 23000[
+ input frequency, in Hz
+
+ Returns
+ -------
+ str
+ name of the nearest note
+
+ Example
+ -------
+ >>> aubio.freq2note(440)
+ 'A4'
+ >>> aubio.freq2note(220.1)
+ 'A3'
+ """
nearest_note = int(freqtomidi(freq) + .5)
return midi2note(nearest_note)
--- a/python/lib/aubio/slicing.py
+++ b/python/lib/aubio/slicing.py
@@ -8,7 +8,69 @@
def slice_source_at_stamps(source_file, timestamps, timestamps_end=None,
output_dir=None, samplerate=0, hopsize=256,
create_first=False):
- """ slice a sound file at given timestamps """
+ """Slice a sound file at given timestamps.
+
+ This function reads `source_file` and creates slices, new smaller
+ files each starting at `t` in `timestamps`, a list of integer
+ corresponding to time locations in `source_file`, in samples.
+
+ If `timestamps_end` is unspecified, the slices will end at
+ `timestamps_end[n] = timestamps[n+1]-1`, or the end of file.
+ Otherwise, `timestamps_end` should be a list with the same length
+ as `timestamps` containing the locations of the end of each slice.
+
+ If `output_dir` is unspecified, the new slices will be written in
+ the current directory. If `output_dir` is a string, new slices
+ will be written in `output_dir`, after creating the directory if
+ required.
+
+ The default `samplerate` is 0, meaning the original sampling rate
+ of `source_file` will be used. When using a sampling rate
+ different to the one of the original files, `timestamps` and
+ `timestamps_end` should be expressed in the re-sampled signal.
+
+ The `hopsize` parameter simply tells :class:`source` to use this
+ hopsize and does not change the output slices.
+
+ If `create_first` is True and `timestamps` does not start with `0`, the
+ first slice from `0` to `timestamps[0] - 1` will be automatically added.
+
+ Parameters
+ ----------
+ source_file : str
+ path of the resource to slice
+ timestamps : :obj:`list` of :obj:`int`
+ time stamps at which to slice, in samples
+ timestamps_end : :obj:`list` of :obj:`int` (optional)
+ time stamps at which to end the slices
+ output_dir : str (optional)
+ output directory to write the slices to
+ samplerate : int (optional)
+ samplerate to read the file at
+ hopsize : int (optional)
+ number of samples read from source per iteration
+ create_first : bool (optional)
+ always create the slice at the start of the file
+
+ Examples
+ --------
+ Create two slices: the first slice starts at the beginning of the
+ input file `loop.wav` and lasts exactly one second, starting at
+ sample `0` and ending at sample `44099`; the second slice starts
+ at sample `44100` and lasts until the end of the input file:
+
+ >>> aubio.slice_source_at_stamps('loop.wav', [0, 44100])+
+ Create one slice, from 1 second to 2 seconds:
+
+ >>> aubio.slice_source_at_stamps('loop.wav', [44100], [44100 * 2 - 1])+
+ Notes
+ -----
+ Slices may be overlapping. If `timestamps_end` is `1` element
+ shorter than `timestamps`, the last slice will end at the end of
+ the file.
+ """
if timestamps is None or len(timestamps) == 0:
raise ValueError("no timestamps given")