From: Paul Brossier Date: Sat, 4 Jul 2015 13:02:56 +0000 (+0200) Subject: doc/*.rst: add simple documentation basis X-Git-Tag: 0.4.2~28 X-Git-Url: https://git.aubio.org/?a=commitdiff_plain;h=34abeafaf74675f164509cf7a72628fd9e3f9d6d;p=aubio.git doc/*.rst: add simple documentation basis --- diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..939f73ef --- /dev/null +++ b/doc/index.rst @@ -0,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: . + +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 diff --git a/doc/installing.rst b/doc/installing.rst new file mode 100644 index 00000000..6629e385 --- /dev/null +++ b/doc/installing.rst @@ -0,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 +`_. + +aubio uses `waf `_ 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 `_ 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 diff --git a/doc/python_api.rst b/doc/python_api.rst new file mode 100644 index 00000000..2f829437 --- /dev/null +++ b/doc/python_api.rst @@ -0,0 +1,9 @@ +aubio Python API +================ + +.. automodule:: aubio + :members: + :undoc-members: + :show-inheritance: + + diff --git a/doc/python_module.rst b/doc/python_module.rst new file mode 100644 index 00000000..eab5cd4a --- /dev/null +++ b/doc/python_module.rst @@ -0,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 +`_ for more examples. +