source: README.md @ 3156153

feature/autosinkfeature/constantqfeature/pitchshiftfeature/pydocstringsfeature/timestretchsampler
Last change on this file since 3156153 was 3156153, checked in by Martin Hermant <martin.hermant@gmail.com>, 3 years ago

nicer badges

  • Property mode set to 100644
File size: 6.8 KB
Line 
1aubio library
2=============
3[![Build Status](https://travis-ci.org/aubio/aubio.svg?branch=master)](https://travis-ci.org/aubio/aubio)
4[![Build status](https://ci.appveyor.com/api/projects/status/f3lhy3a57rkgn5yi?svg=true)](https://ci.appveyor.com/project/aubio/aubio/branch/master)
5[![Code Health](https://landscape.io/github/aubio/aubio/master/landscape.svg?style=flat)](https://landscape.io/github/aubio/aubio/master)
6[![Documentation Status](https://readthedocs.org/projects/aubio/badge/?version=latest)](http://aubio.readthedocs.io/en/latest/?badge=latest)
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)
8
9aubio is a library to label music and sounds. It listens to audio signals and
10attempts to detect events. For instance, when a drum is hit, at which frequency
11is a note, or at what tempo is a rhythmic melody.
12
13Its features include segmenting a sound file before each of its attacks,
14performing pitch detection, tapping the beat and producing midi streams from
15live audio.
16
17aubio 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
31The name aubio comes from _audio_ with a typo: some errors are likely to be
32found in the results.
33
34Python module
35-------------
36
37A python module to access the library functions is also provided. Please see
38the file [`python/README.md`](python/README.md) for more information on how to
39use it.
40
41Examples tools
42--------------
43
44A 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
54Additionally, the python module comes with the following script:
55
56 - `aubiocut` slices sound files at onset or beat timestamps
57
58Implementation and Design Basics
59--------------------------------
60
61The library is written in C and is optimised for speed and portability.
62
63The 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
71For performance and real-time operation, no memory allocation or freeing take
72place in the `_do` methods. Instead, memory allocation should always take place
73in the `new_` methods, whereas free operations are done in the `del_` methods.
74
75The latest version of the documentation can be found at:
76
77  https://aubio.org/documentation
78
79Build Instructions
80------------------
81
82A number of distributions already include aubio. Check your favorite package
83management system, or have a look at the [download
84page](https://aubio.org/download).
85
86aubio uses [waf](https://waf.io/) to configure, compile, and test the source:
87
88    ./waf configure
89    ./waf build
90
91If waf is not found in the directory, you can download and install it with:
92
93    make getwaf
94
95aubio compiles on Linux, Mac OS X, Windows, Cygwin, and iOS.
96
97Installation
98------------
99
100To install aubio library and headers on your system, use:
101
102    sudo ./waf install
103
104To uninstall:
105
106    sudo ./waf uninstall
107
108If you don't have root access to install libaubio on your system, you can use
109libaubio without installing libaubio either by setting `LD_LIBRARY_PATH`, or by
110copying it to `~/lib`.
111
112On Linux, you should be able to set `LD_LIBRARY_PATH` with:
113
114    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/build/src
115
116On 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
121Note on Mac OS X systems older than El Capitan (10.11), the `DYLD_LIBRARY_PATH`
122variable can be set as follows:
123
124    $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$PWD/build/src
125
126Credits and Publications
127------------------------
128
129This library gathers music signal processing algorithms designed at the Centre
130for Digital Music and elsewhere. This software project was developed along the
131research I did at the Centre for Digital Music, Queen Mary, University of
132London. Most of this C code was written by myself, starting from published
133papers and existing code. The header files of each algorithm contains brief
134descriptions and references to the corresponding papers.
135
136Special thanks go Juan Pablo Bello, Chris Duxbury, Samer Abdallah, Alain de
137Cheveigne for their help and publications. Also many thanks to Miguel Ramirez
138and Nicolas Wack for their bug fixing.
139
140Substantial informations about the algorithms and their evaluation are gathered
141in:
142
143  - Paul Brossier, _[Automatic annotation of musical audio for interactive
144    systems](https://aubio.org/phd)_, PhD thesis, Centre for Digital music,
145Queen Mary University of London, London, UK, 2006.
146
147Additional results obtained with this software were discussed in the following
148papers:
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),
152in _Proceedings of the International Computer Music Conference_, 2004, Miami,
153Florida, 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),
157in _Proceedings of the International Symposium on Music Information Retrieval_,
1582004, Barcelona, Spain
159
160
161Contact Info and Mailing List
162-----------------------------
163
164The home page of this project can be found at: https://aubio.org/
165
166Questions, comments, suggestions, and contributions are welcome. Use the
167mailing list: <aubio-user@aubio.org>.
168
169To subscribe to the list, use the mailman form:
170https://lists.aubio.org/listinfo/aubio-user/
171
172Alternatively, feel free to contact directly the author.
173
174
175Copyright and License Information
176---------------------------------
177
178Copyright (C) 2003-2016 Paul Brossier <piem@aubio.org>
179
180aubio is free software: you can redistribute it and/or modify it under the
181terms of the GNU General Public License as published by the Free Software
182Foundation, either version 3 of the License, or (at your option) any later
183version.
Note: See TracBrowser for help on using the repository browser.