README

   1 AUBIO LIBRARY
   2
   3 Aubio is a library for real time audio labelling. Its features include
   4 segmenting a sound file before each of its attacks, performing pitch detection,
   5 tapping the beat and producing midi streams from live audio. The name aubio
   6 comes from 'audio' with a typo: several transcription errors are likely to be
   7 found in the results too.
   8
   9 A few examples of applications are provided in examples/ and python/:
  10
  11  - aubioonset output the onset detected,
  12  - aubionotes emits midi-like notes,
  13  - aubiocut is a python script that takes an input sound and creates one new
  14    sample at each detected onset or beat,
  15  - aubiopitch is a python script to extract pitch tracks from sound files.
  16
  17 aubioonset and aubionotes can work either off-line or online, outputting the
  18 results on the console or playing a wood-block sound at each detected onset.
  19 Both Python scripts can plot the results with Gnuplot.
  20
  21 Aubio is now being used in various projects:
  22
  23   - Audacity (http://audacity.sourceforge.net/ , see plugins/audacity)
  24   - Wavesurfer (http://www.speech.kth.se/wavesurfer/ , see plugins/wavesurfer)
  25   - Puredata (http://puredata.info/ , see plugins/puredata)
  26   - Freecycle (http://www.redsteamrecords.com/freecycle/)
  27   - Sonic Visualiser (http://www.sonicvisualiser.org)
  28   - CLAM (http://clam.iua.upf.edu/)
  29
  30 BUILDING AUBIO
  31
  32 This package depends on the following libraries and utilities:
  33
  34   - automake 1.8
  35   - libsndfile1
  36   - fftw3
  37   - libsamplerate
  38   - libjack (optional)
  39   - libasound2 (optional)
  40   - swig (>= 1.3, optional, for the python interface)
  41   - python, python-gnuplot, python-numarray (optional)
  42
  43 The usual invocation `./configure && make' should do the job. Read on the
  44 generic INSTALL file for more information.
  45
  46 On a Debian based system, you will need the following packages to compile
  47 aubio: automake libsndfile1-dev libjack-dev fftw3-dev libsamplerate0-dev python
  48 python-dev python-numarray swig. Alternatively, you could try the debian
  49 package (see http://piem.org/debian/).
  50
  51 Aubio has been successfully compiled on Mac OS X and can compile on Windows
  52 using mingw, although cross compiling it from Linux was found much simpler.
  53 Note that this code was developed and tested on a Linux box.
  54
  55 STATUS
  56
  57 The shared library libaubio provides the following tools:
  58
  59   - various math utilities
  60   - phase vocoder
  61   - up/down-sampling
  62   - filtering (n pole/zero pairs)
  63   - onset detection functions
  64   - onset peak picking
  65   - pitch detection functions
  66   - beat tracking function
  67   - transient/steady-state separation
  68   - alsa midi and jack input outputs
  69
  70 A swig wrapper is provided in swig/. For now, I have only been playing with the
  71 python interface, but swig should make it easy to obtain a wrapper for any
  72 other supported language, such as Perl or Ruby.
  73
  74 `Make it run, make it right, make it fast.'[1] Aubio is currently in the "Make
  75 it right" process. Almost no optimisation has been done to the code, and its
  76 speed could probably be improved.
  77
  78 [1] see http://c2.com/cgi/wiki?MakeItWorkMakeItRightMakeItFast
  79
  80 EXTEND
  81
  82 The C API is designed in the following old school way:
  83
  84     void del_aubio_thing(aubio_thing_t * t);
  85     aubio_thing_t * new_aubio_thing(void * args);
  86     audio_thing_methods(aubio_thing_t * t, void * args);
  87
  88 Memory allocation or freeing should never take place in execution function
  89 (aubio_thing_methods), and should all be bound to the new_ and del_ methods.
  90 Also, note that most GCC warning flags are turned on, so functions must be
  91 prototyped, and variables must be used.
  92
  93 CREDITS
  94
  95 This library gathers music signal processing algorithms designed at the Centre
  96 for Digital Music and elsewhere. This software project was developed along the
  97 research I did at the Centre for Digital Music, Queen Mary, University of
  98 London. Most of this C code was written by myself, starting from published
  99 papers and existing code. The header files of each algorithm contains brief
 100 descriptions and references to the corresponding papers.
 101
 102 Results obtained with aubio were discussed in the following papers:
 103
 104   P. M. Brossier and J. P. Bello and M. D. Plumbley, Real-time temporal
 105   segmentation of note objects in music signals, Proceedings of the
 106   International Computer Music Conference, 2004, Miami, Florida, ICMA
 107
 108   P. M. Brossier and J. P. Bello and M. D. Plumbley, Fast labelling of note
 109   objects in music signals, Proceedings of the International Symposium on Music
 110   Information Retrieval, 2004, Barcelona, Spain
 111
 112 Substantial informations about the algorithms developed in aubio and their
 113 evaluation are gathered in:
 114
 115   Paul Brossier, ``Automatic annotation of musical audio for interactive
 116   systems'', PhD thesis, Centre for Digital music, Queen Mary University of
 117   London, London, UK, 2006.
 118
 119 CONTACT
 120
 121 The home page of this project can be found at http://aubio.org/. Feel free
 122 to drop me a comment (piem@altern.org) or on the mailing list, aubio@piem.org.
 123 Suggestions and feedback are most welcome.