ref: 34abeafaf74675f164509cf7a72628fd9e3f9d6d
parent: 2a6cf366b48ebb1287a44d93f9e3409cc1672840
author: Paul Brossier <piem@piem.org>
date: Sat Jul 4 11:02:56 EDT 2015
doc/*.rst: add simple documentation basis
--- /dev/null
+++ b/doc/index.rst
@@ -1,0 +1,114 @@
+aubio documentation
+===================
+
+aubio is a collection of algorithms and tools to label music and sounds. It
+listens to audio signals and attempts to detect events. For instance, when a
+drum is hit, at which frequency is a note, or at what tempo is a rhythmic
+melody.
+
+Its features include segmenting a sound file before each of its attacks,
+performing pitch detection, tapping the beat and producing midi streams from
+live audio.
+
+aubio provide several algorithms and routines, including:
+
+- several onset detection methods
+- different pitch detection methods
+- tempo tracking and beat detection
+- MFCC (mel-frequency cepstrum coefficients)
+- FFT and phase vocoder
+- up/down-sampling
+- digital filters (low pass, high pass, and more)
+- spectral filtering
+- transient/steady-state separation
+- sound file and audio devices read and write access
+- various mathematics utilities for music applications
+
+The name aubio comes from *audio* with a typo: some errors are likely to be
+found in the results.
+
+Python module
+-------------
+
+A python module to access the library functions is also provided. Please see
+the file ``python/README`` for more information on how to use it.
+
+Examples tools
+--------------
+
+A few simple command line tools are included along with the library:
+
+ - ``aubioonset`` outputs the time stamp of detected note onsets
+ - ``aubiopitch`` attempts to identify a fundamental frequency, or pitch, for
+ each frame of the input sound
+ - ``aubiomfcc`` computes Mel-frequency Cepstrum Coefficients
+ - ``aubiotrack`` outputs the time stamp of detected beats
+ - ``aubionotes`` emits midi-like notes, with an onset, a pitch, and a duration
+ - ``aubioquiet`` extracts quiet and loud regions
+
+Additionally, the python module comes with the following script:
+
+ - ``aubiocut`` slices sound files at onset or beat timestamps
+
+C API basics
+------------
+
+The library is written in C and is optimised for speed and portability.
+
+The C API is designed in the following way:
+
+.. code-block:: c
+
+ aubio_something_t * new_aubio_something(void * args);
+ audio_something_do(aubio_something_t * t, void * args);
+ smpl_t aubio_something_get_a_parameter(aubio_something_t * t);
+ uint_t aubio_something_set_a_parameter(aubio_something_t * t, smpl_t a_parameter);
+ void del_aubio_something(aubio_something_t * t);
+
+For performance and real-time operation, no memory allocation or freeing take
+place in the ``_do`` methods. Instead, memory allocation should always take place
+in the ``new_`` methods, whereas free operations are done in the ``del_`` methods.
+
+.. code-block:: bash
+
+ ./waf configure
+ ./waf build
+ sudo ./waf install
+
+aubio compiles on Linux, Mac OS X, Cygwin, and iPhone.
+
+Documentation
+-------------
+
+- Manual pages: http://aubio.org/documentation
+- API documentation: http://aubio.org/doc/latest/
+
+Contribute
+----------
+
+- Issue Tracker: https://github.com/piem/aubio/issues
+- Source Code: https://github.com/piem/aubio
+
+Contact info
+------------
+
+The home page of this project can be found at: http://aubio.org/
+
+Questions, comments, suggestions, and contributions are welcome. Use the
+mailing list: <aubio-user@aubio.org>.
+
+To subscribe to the list, use the mailman form:
+http://lists.aubio.org/listinfo/aubio-user/
+
+Alternatively, feel free to contact directly the author.
+
+
+Contents
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ installing
+ python_module
+ python_api
--- /dev/null
+++ b/doc/installing.rst
@@ -1,0 +1,65 @@
+.. highlight:: bash
+
+Installing aubio
+================
+
+A number of distributions already include aubio. Check your favorite package
+management system, or have a look at the `download page
+<http://aubio.org/download>`_.
+
+aubio uses `waf <https://waf.io/>`_ to configure, compile, and test the source.
+A copy of ``waf`` is included along aubio, so all you need is a ``terminal``
+and a recent ``python`` installed.
+
+Source code
+-----------
+
+Check out the `download page <http://aubio.org/download>`_ for more options:
+http://aubio.org/download.
+
+The latest stable release can be found at http://aubio.org/pub/::
+
+ $ curl -O http://aubio.org/pub/aubio-0.4.1.tar.bz2
+ $ tar xf aubio-0.4.1.tar.bz2
+ $ cd aubio-0.4.1
+
+The latest develop branch can be obtained with::
+
+ $ git clone git://git.aubio.org/git/aubio/ aubio-devel
+ $ cd aubio-devel
+ $ git fetch origin develop:develop
+ $ git checkout develop
+
+Compiling
+---------
+
+To compile the C library, examples programs, and tests, run::
+
+ $ ./waf configure
+
+Check out the available options using ``./waf configure --help | less``. Once
+you are done with configuration, you can start building::
+
+ $ ./waf build
+
+To install the freshly built C library and tools, simply run the following
+command::
+
+ $ sudo ./waf install
+
+Cleaning
+--------
+
+If you wish to uninstall the files installed by the ``install`` command, use
+``uninstall``::
+
+ $ sudo ./waf uninstall
+
+To clean the source directory, use the ``clean`` command::
+
+ $ ./waf clean
+
+To also forget the options previously passed to the last ``./waf configure``
+invocation, use the ``distclean`` command::
+
+ $ ./waf distclean
--- /dev/null
+++ b/doc/python_api.rst
@@ -1,0 +1,9 @@
+aubio Python API
+================
+
+.. automodule:: aubio
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+
--- /dev/null
+++ b/doc/python_module.rst
@@ -1,0 +1,33 @@
+aubio Python module
+===================
+
+Building the module
+-------------------
+
+From ``aubio`` source directory, run the following:
+
+.. code-block:: bash
+
+ $ cd python
+ $ ./setup.py build
+ $ sudo ./setup.py install
+
+Using the module
+----------------
+
+To use the python module, simply import aubio:
+
+.. code-block:: python
+
+ #! /usr/bin/env python
+ import aubio
+
+ s = aubio.source(sys.argv[1], 0, 256)
+ while True:
+ samples, read = s()
+ print samples
+ if read < 256: break
+
+Check out the `python demos for aubio
+<https://github.com/piem/aubio/blob/develop/python/demos/>`_ for more examples.
+