README.md

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