ab56a195de0e2cf28a3f51d6a0253872ed0659ca
[aubio.git] / 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 Additionaly, 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://code.google.com/p/waf/) to configure, compile, and
81 test the source:
82
83     ./waf configure
84     ./waf build
85     sudo ./waf install
86
87 aubio compiles on Linux, Mac OS X, Cygwin, and iPhone.
88
89 Credits and Publications
90 ------------------------
91
92 This library gathers music signal processing algorithms designed at the Centre
93 for Digital Music and elsewhere. This software project was developed along the
94 research I did at the Centre for Digital Music, Queen Mary, University of
95 London. Most of this C code was written by myself, starting from published
96 papers and existing code. The header files of each algorithm contains brief
97 descriptions and references to the corresponding papers.
98
99 Special thanks go Juan Pablo Bello, Chris Duxbury, Samer Abdallah, Alain de
100 Cheveigne for their help and publications. Also many thanks to Miguel Ramirez
101 and Nicolas Wack for their bug fixing.
102
103 Substantial informations about the algorithms and their evaluation are gathered
104 in:
105
106   - Paul Brossier, _[Automatic annotation of musical audio for interactive
107     systems](http://aubio.org/phd)_, PhD thesis, Centre for Digital music,
108 Queen Mary University of London, London, UK, 2006.
109
110 Additional results obtained with this software were discussed in the following
111 papers:
112
113   - P. M. Brossier and J. P. Bello and M. D. Plumbley, [Real-time temporal
114     segmentation of note objects in music signals](http://aubio.org/articles/brossier04fastnotes.pdf),
115 in _Proceedings of the International Computer Music Conference_, 2004, Miami,
116 Florida, ICMA
117
118   -  P. M. Brossier and J. P. Bello and M. D. Plumbley, [Fast labelling of note
119      objects in music signals] (http://aubio.org/articles/brossier04fastnotes.pdf),
120 in _Proceedings of the International Symposium on Music Information Retrieval_,
121 2004, Barcelona, Spain
122
123
124 Contact Info and Mailing List
125 -----------------------------
126
127 The home page of this project can be found at: http://aubio.org/
128
129 Questions, comments, suggestions, and contributions are welcome. Use the
130 mailing list: <aubio-user@aubio.org>.
131
132 To subscribe to the list, use the mailman form:
133 http://lists.aubio.org/listinfo/aubio-user/
134
135 Alternatively, feel free to contact directly the author.
136
137
138 Copyright and License Information
139 ---------------------------------
140
141 Copyright (C) 2003-2013 Paul Brossier <piem@aubio.org>
142
143 aubio is free software: you can redistribute it and/or modify it under the
144 terms of the GNU General Public License as published by the Free Software
145 Foundation, either version 3 of the License, or (at your option) any later
146 version.