README.md

   1 aubio library
   2 =============
   3 [![Travis build status](https://travis-ci.org/aubio/aubio.svg?branch=master)](https://travis-ci.org/aubio/aubio "Travis build status")
   4 [![Appveyor build status](https://ci.appveyor.com/api/projects/status/f3lhy3a57rkgn5yi?svg=true)](https://ci.appveyor.com/project/aubio/aubio/branch/master "Appveyor build status")
   5 [![Landscape code health](https://landscape.io/github/aubio/aubio/master/landscape.svg?style=flat)](https://landscape.io/github/aubio/aubio/master "Landscape code health")
   6 [![Documentation Status](https://readthedocs.org/projects/aubio/badge/?version=latest)](http://aubio.readthedocs.io/en/latest/?badge=latest "Documentation status")
   7 [![Commits since last release](https://img.shields.io/github/commits-since/aubio/aubio/0.4.4.svg?maxAge=2592000)](https://github.com/aubio/aubio "Commits since last release")
   8
   9 aubio is a library to label music and sounds. It listens to audio signals and
  10 attempts to detect events. For instance, when a drum is hit, at which frequency
  11 is a note, or at what tempo is a rhythmic melody.
  12
  13 Its features include segmenting a sound file before each of its attacks,
  14 performing pitch detection, tapping the beat and producing midi streams from
  15 live audio.
  16
  17 aubio provide several algorithms and routines, including:
  18
  19   - several onset detection methods
  20   - different pitch detection methods
  21   - tempo tracking and beat detection
  22   - MFCC (mel-frequency cepstrum coefficients)
  23   - FFT and phase vocoder
  24   - up/down-sampling
  25   - digital filters (low pass, high pass, and more)
  26   - spectral filtering
  27   - transient/steady-state separation
  28   - sound file and audio devices read and write access
  29   - various mathematics utilities for music applications
  30
  31 The name aubio comes from _audio_ with a typo: some errors are likely to be
  32 found in the results.
  33
  34 Python module
  35 -------------
  36
  37 A python module to access the library functions is also provided. Please see
  38 the file [`python/README.md`](python/README.md) for more information on how to
  39 use it.
  40
  41 Examples tools
  42 --------------
  43
  44 A few simple command line tools are included along with the library:
  45
  46  - `aubioonset` outputs the time stamp of detected note onsets
  47  - `aubiopitch` attempts to identify a fundamental frequency, or pitch, for
  48    each frame of the input sound
  49  - `aubiomfcc` computes Mel-frequency Cepstrum Coefficients
  50  - `aubiotrack` outputs the time stamp of detected beats
  51  - `aubionotes` emits midi-like notes, with an onset, a pitch, and a duration
  52  - `aubioquiet` extracts quiet and loud regions
  53
  54 Additionally, the python module comes with the following script:
  55
  56  - `aubiocut` slices sound files at onset or beat timestamps
  57
  58 Implementation and Design Basics
  59 --------------------------------
  60
  61 The library is written in C and is optimised for speed and portability.
  62
  63 The C API is designed in the following way:
  64
  65     aubio_something_t * new_aubio_something (void * args);
  66     audio_something_do (aubio_something_t * t, void * args);
  67     smpl_t aubio_something_get_a_parameter (aubio_something_t *t);
  68     uint_t aubio_something_set_a_parameter (aubio_something_t *t, smpl_t a_parameter);
  69     void del_aubio_something (aubio_something_t * t);
  70
  71 For performance and real-time operation, no memory allocation or freeing take
  72 place in the `_do` methods. Instead, memory allocation should always take place
  73 in the `new_` methods, whereas free operations are done in the `del_` methods.
  74
  75 The latest version of the documentation can be found at:
  76
  77   https://aubio.org/documentation
  78
  79 Build Instructions
  80 ------------------
  81
  82 A number of distributions already include aubio. Check your favorite package
  83 management system, or have a look at the [download
  84 page](https://aubio.org/download).
  85
  86 aubio uses [waf](https://waf.io/) to configure, compile, and test the source:
  87
  88     ./waf configure
  89     ./waf build
  90
  91 If waf is not found in the directory, you can download and install it with:
  92
  93     make getwaf
  94
  95 aubio compiles on Linux, Mac OS X, Windows, Cygwin, and iOS.
  96
  97 Installation
  98 ------------
  99
 100 To install aubio library and headers on your system, use:
 101
 102     sudo ./waf install
 103
 104 To uninstall:
 105
 106     sudo ./waf uninstall
 107
 108 If you don't have root access to install libaubio on your system, you can use
 109 libaubio without installing libaubio either by setting `LD_LIBRARY_PATH`, or by
 110 copying it to `~/lib`.
 111
 112 On Linux, you should be able to set `LD_LIBRARY_PATH` with:
 113
 114     $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/build/src
 115
 116 On Mac OS X, a copy or a symlink can be made in `~/lib`:
 117
 118     $ mkdir -p ~/lib
 119     $ ln -sf $PWD/build/src/libaubio*.dylib ~/lib/
 120
 121 Note on Mac OS X systems older than El Capitan (10.11), the `DYLD_LIBRARY_PATH`
 122 variable can be set as follows:
 123
 124     $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$PWD/build/src
 125
 126 Credits and Publications
 127 ------------------------
 128
 129 This library gathers music signal processing algorithms designed at the Centre
 130 for Digital Music and elsewhere. This software project was developed along the
 131 research I did at the Centre for Digital Music, Queen Mary, University of
 132 London. Most of this C code was written by myself, starting from published
 133 papers and existing code. The header files of each algorithm contains brief
 134 descriptions and references to the corresponding papers.
 135
 136 Special thanks go Juan Pablo Bello, Chris Duxbury, Samer Abdallah, Alain de
 137 Cheveigne for their help and publications. Also many thanks to Miguel Ramirez
 138 and Nicolas Wack for their bug fixing.
 139
 140 Substantial informations about the algorithms and their evaluation are gathered
 141 in:
 142
 143   - Paul Brossier, _[Automatic annotation of musical audio for interactive
 144     systems](https://aubio.org/phd)_, PhD thesis, Centre for Digital music,
 145 Queen Mary University of London, London, UK, 2006.
 146
 147 Additional results obtained with this software were discussed in the following
 148 papers:
 149
 150   - P. M. Brossier and J. P. Bello and M. D. Plumbley, [Real-time temporal
 151     segmentation of note objects in music signals](https://aubio.org/articles/brossier04fastnotes.pdf),
 152 in _Proceedings of the International Computer Music Conference_, 2004, Miami,
 153 Florida, ICMA
 154
 155   -  P. M. Brossier and J. P. Bello and M. D. Plumbley, [Fast labelling of note
 156      objects in music signals] (https://aubio.org/articles/brossier04fastnotes.pdf),
 157 in _Proceedings of the International Symposium on Music Information Retrieval_,
 158 2004, Barcelona, Spain
 159
 160
 161 Contact Info and Mailing List
 162 -----------------------------
 163
 164 The home page of this project can be found at: https://aubio.org/
 165
 166 Questions, comments, suggestions, and contributions are welcome. Use the
 167 mailing list: <aubio-user@aubio.org>.
 168
 169 To subscribe to the list, use the mailman form:
 170 https://lists.aubio.org/listinfo/aubio-user/
 171
 172 Alternatively, feel free to contact directly the author.
 173
 174
 175 Copyright and License Information
 176 ---------------------------------
 177
 178 Copyright (C) 2003-2016 Paul Brossier <piem@aubio.org>
 179
 180 aubio is free software: you can redistribute it and/or modify it under the
 181 terms of the GNU General Public License as published by the Free Software
 182 Foundation, either version 3 of the License, or (at your option) any later
 183 version.