README.md

   1 aubio library
   2 =============
   3
   4 aubio is a library to label music and sounds. It listens to audio signals and
   5 attempts to detect events. For instance, when a drum is hit, at which frequency
   6 is a note, or at what tempo is a rhythmic melody.
   7
   8 Its features include segmenting a sound file before each of its attacks,
   9 performing pitch detection, tapping the beat and producing midi streams from
  10 live audio.
  11
  12 aubio provide several algorithms and routines, including:
  13
  14   - several onset detection methods
  15   - different pitch detection methods
  16   - tempo tracking and beat detection
  17   - MFCC (mel-frequency cepstrum coefficients)
  18   - FFT and phase vocoder
  19   - up/down-sampling
  20   - digital filters (low pass, high pass, and more)
  21   - spectral filtering
  22   - transient/steady-state separation
  23   - sound file and audio devices read and write access
  24   - various mathematics utilities for music applications
  25
  26 The name aubio comes from _audio_ with a typo: some errors are likely to be
  27 found in the results.
  28
  29 Python module
  30 -------------
  31
  32 A python module to access the library functions is also provided. Please see
  33 the file `python/README` for more information on how to use it.
  34
  35 Examples tools
  36 --------------
  37
  38 A few simple command line tools are included along with the library:
  39
  40  - `aubioonset` outputs the time stamp of detected note onsets
  41  - `aubiopitch` attempts to identify a fundamental frequency, or pitch, for
  42    each frame of the input sound
  43  - `aubiomfcc` computes Mel-frequency Cepstrum Coefficients
  44  - `aubiotrack` outputs the time stamp of detected beats
  45  - `aubionotes` emits midi-like notes, with an onset, a pitch, and a duration
  46  - `aubioquiet` extracts quiet and loud regions
  47
  48 Additionally, the python module comes with the following script:
  49
  50  - `aubiocut` slices sound files at onset or beat timestamps
  51
  52 Implementation and Design Basics
  53 --------------------------------
  54
  55 The library is written in C and is optimised for speed and portability.
  56
  57 The C API is designed in the following way:
  58
  59     aubio_something_t * new_aubio_something (void * args);
  60     audio_something_do (aubio_something_t * t, void * args);
  61     smpl_t aubio_something_get_a_parameter (aubio_something_t *t);
  62     uint_t aubio_something_set_a_parameter (aubio_something_t *t, smpl_t a_parameter);
  63     void del_aubio_something (aubio_something_t * t);
  64
  65 For performance and real-time operation, no memory allocation or freeing take
  66 place in the `_do` methods. Instead, memory allocation should always take place
  67 in the `new_` methods, whereas free operations are done in the `del_` methods.
  68
  69 The latest version of the documentation can be found at:
  70
  71   http://aubio.org/documentation
  72
  73 Installation and Build Instructions
  74 -----------------------------------
  75
  76 A number of distributions already include aubio. Check your favorite package
  77 management system, or have a look at the [download
  78 page](http://aubio.org/download).
  79
  80 aubio uses [waf](https://waf.io/) to configure, compile, and test the source:
  81
  82     ./waf configure
  83     ./waf build
  84     sudo ./waf install
  85
  86 If waf is not found in the directory, you can download and install it with:
  87
  88     make getwaf
  89
  90 aubio compiles on Linux, Mac OS X, Cygwin, and iOS.
  91
  92 Credits and Publications
  93 ------------------------
  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 Special thanks go Juan Pablo Bello, Chris Duxbury, Samer Abdallah, Alain de
 103 Cheveigne for their help and publications. Also many thanks to Miguel Ramirez
 104 and Nicolas Wack for their bug fixing.
 105
 106 Substantial informations about the algorithms and their evaluation are gathered
 107 in:
 108
 109   - Paul Brossier, _[Automatic annotation of musical audio for interactive
 110     systems](http://aubio.org/phd)_, PhD thesis, Centre for Digital music,
 111 Queen Mary University of London, London, UK, 2006.
 112
 113 Additional results obtained with this software were discussed in the following
 114 papers:
 115
 116   - P. M. Brossier and J. P. Bello and M. D. Plumbley, [Real-time temporal
 117     segmentation of note objects in music signals](http://aubio.org/articles/brossier04fastnotes.pdf),
 118 in _Proceedings of the International Computer Music Conference_, 2004, Miami,
 119 Florida, ICMA
 120
 121   -  P. M. Brossier and J. P. Bello and M. D. Plumbley, [Fast labelling of note
 122      objects in music signals] (http://aubio.org/articles/brossier04fastnotes.pdf),
 123 in _Proceedings of the International Symposium on Music Information Retrieval_,
 124 2004, Barcelona, Spain
 125
 126
 127 Contact Info and Mailing List
 128 -----------------------------
 129
 130 The home page of this project can be found at: http://aubio.org/
 131
 132 Questions, comments, suggestions, and contributions are welcome. Use the
 133 mailing list: <aubio-user@aubio.org>.
 134
 135 To subscribe to the list, use the mailman form:
 136 http://lists.aubio.org/listinfo/aubio-user/
 137
 138 Alternatively, feel free to contact directly the author.
 139
 140
 141 Copyright and License Information
 142 ---------------------------------
 143
 144 Copyright (C) 2003-2013 Paul Brossier <piem@aubio.org>
 145
 146 aubio is free software: you can redistribute it and/or modify it under the
 147 terms of the GNU General Public License as published by the Free Software
 148 Foundation, either version 3 of the License, or (at your option) any later
 149 version.