root/README

AUBIO LIBRARY 

Aubio is a library for real time audio labelling. 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. The name aubio
comes from 'audio' with a typo: several transcription errors are likely to be
found in the results too.

A few examples of applications are provided in examples/ and python/: 

 - aubioonset output the onset detected, 
 - aubionotes emits midi-like notes,
 - aubiocut is a python script that takes an input sound and creates one new
   sample at each detected onset or beat,
 - aubiopitch is a python script to extract pitch tracks from sound files.

aubioonset and aubionotes can work either off-line or online, outputting the
results on the console or playing a wood-block sound at each detected onset.
Both Python scripts can plot the results with Gnuplot.

Aubio is now being used in various projects:

  - Audacity (http://audacity.sourceforge.net/ , see plugins/audacity)
  - Wavesurfer (http://www.speech.kth.se/wavesurfer/ , see plugins/wavesurfer)
  - Puredata (http://puredata.info/ , see plugins/puredata)
  - Freecycle (http://www.redsteamrecords.com/freecycle/)
  - Sonic Visualiser (http://www.sonicvisualiser.org)
  - CLAM (http://clam.iua.upf.edu/)

BUILDING AUBIO

This package depends on the following libraries and utilities: 

  - automake 1.8
  - libsndfile1
  - fftw3
  - libsamplerate
  - libjack (optional)
  - libasound2 (optional)
  - swig (>= 1.3, optional, for the python interface)
  - python, python-gnuplot, python-numarray (optional)

The usual invocation `./configure && make' should do the job. Read on the
generic INSTALL file for more information.

On a Debian based system, you will need the following packages to compile
aubio: automake libsndfile1-dev libjack-dev fftw3-dev libsamplerate0-dev python
python-dev python-numarray swig. Alternatively, you could try the debian
package (see http://piem.org/debian/).

Aubio has been successfully compiled on Mac OS X and can compile on Windows
using mingw, although cross compiling it from Linux was found much simpler.
Note that this code was developed and tested on a Linux box.

STATUS

The shared library libaubio provides the following tools:

  - various math utilities
  - phase vocoder 
  - up/down-sampling
  - filtering (n pole/zero pairs)
  - onset detection functions
  - onset peak picking
  - pitch detection functions 
  - beat tracking function
  - transient/steady-state separation
  - alsa midi and jack input outputs

A swig wrapper is provided in swig/. For now, I have only been playing with the
python interface, but swig should make it easy to obtain a wrapper for any
other supported language, such as Perl or Ruby.

`Make it run, make it right, make it fast.'[1] Aubio is currently in the "Make
it right" process. Almost no optimisation has been done to the code, and its
speed could probably be improved.

[1] see http://c2.com/cgi/wiki?MakeItWorkMakeItRightMakeItFast

EXTEND

The C API is designed in the following old school way:

    void del_aubio_thing(aubio_thing_t * t);
    aubio_thing_t * new_aubio_thing(void * args);
    audio_thing_methods(aubio_thing_t * t, void * args);

Memory allocation or freeing should never take place in execution function
(aubio_thing_methods), and should all be bound to the new_ and del_ methods.
Also, note that most GCC warning flags are turned on, so functions must be
prototyped, and variables must be used.

CREDITS

This library gathers music signal processing algorithms designed at the Centre
for Digital Music and elsewhere. This software project was developed along the
research I did at the Centre for Digital Music, Queen Mary, University of
London. Most of this C code was written by myself, starting from published
papers and existing code. The header files of each algorithm contains brief
descriptions and references to the corresponding papers.

Results obtained with aubio were discussed in the following papers:
  
  P. M. Brossier and J. P. Bello and M. D. Plumbley, Real-time temporal
  segmentation of note objects in music signals, Proceedings of the
  International Computer Music Conference, 2004, Miami, Florida, ICMA

  P. M. Brossier and J. P. Bello and M. D. Plumbley, Fast labelling of note
  objects in music signals, Proceedings of the International Symposium on Music
  Information Retrieval, 2004, Barcelona, Spain

Substantial informations about the algorithms developed in aubio and their
evaluation are gathered in:

  Paul Brossier, ``Automatic annotation of musical audio for interactive
  systems'', PhD thesis, Centre for Digital music, Queen Mary University of
  London, London, UK, 2006.

CONTACT

The home page of this project can be found at http://aubio.org/. Feel free
to drop me a comment (piem@altern.org) or on the mailing list, aubio@piem.org.
Suggestions and feedback are most welcome.