1 | /* |
---|
2 | Copyright (C) 2003-2009 Paul Brossier <piem@aubio.org> |
---|
3 | |
---|
4 | This file is part of aubio. |
---|
5 | |
---|
6 | aubio is free software: you can redistribute it and/or modify |
---|
7 | it under the terms of the GNU General Public License as published by |
---|
8 | the Free Software Foundation, either version 3 of the License, or |
---|
9 | (at your option) any later version. |
---|
10 | |
---|
11 | aubio is distributed in the hope that it will be useful, |
---|
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
---|
14 | GNU General Public License for more details. |
---|
15 | |
---|
16 | You should have received a copy of the GNU General Public License |
---|
17 | along with aubio. If not, see <http://www.gnu.org/licenses/>. |
---|
18 | |
---|
19 | */ |
---|
20 | |
---|
21 | /** \mainpage |
---|
22 | |
---|
23 | \section introduction Introduction |
---|
24 | |
---|
25 | aubio is a library to extract annotations from audio signals: it provides a |
---|
26 | set of functions that take an input audio signal, and output pitch estimates, |
---|
27 | attack times (onset), beat location estimates, and other annotation tasks. |
---|
28 | |
---|
29 | \section basics Basics |
---|
30 | |
---|
31 | All object structures in aubio share the same function prefixes and suffixes: |
---|
32 | |
---|
33 | - \p new_aubio_foo creates the object \p foo |
---|
34 | - \p aubio_foo_do executes the object \p foo |
---|
35 | - \p del_aubio_foo destroys the object \p foo |
---|
36 | |
---|
37 | All memory allocation and deallocation take place in the \p new_ and \p del_ |
---|
38 | functions. Optionally, more than one \p _do methods are available. |
---|
39 | Additional parameters can be adjusted and observed using: |
---|
40 | |
---|
41 | - \p aubio_foo_get_param, getter function, gets the value of a parameter |
---|
42 | - \p aubio_foo_set_param, setter function, changes the value of a parameter |
---|
43 | |
---|
44 | Unless specified in its documentation, no memory operations take place in the |
---|
45 | getter functions. However, memory resizing can take place in setter |
---|
46 | functions. |
---|
47 | |
---|
48 | \subsection vectors Vectors |
---|
49 | |
---|
50 | Two basic structures are being used in aubio: ::fvec_t and ::cvec_t. The |
---|
51 | ::fvec_t structures are used to store vectors of floating pointer number, |
---|
52 | optionally on several channels. ::cvec_t are used to store complex number, |
---|
53 | as two vectors of norm and phase elements, also on several channels. |
---|
54 | |
---|
55 | Additionally, the ::lvec_t structure can be used to store floating point |
---|
56 | numbers in double precision. They are mostly used to store filter |
---|
57 | coefficients, to avoid instability. |
---|
58 | |
---|
59 | \subsection objects Available objects |
---|
60 | |
---|
61 | Here is a list of some of the most common objects for aubio: |
---|
62 | |
---|
63 | \code |
---|
64 | |
---|
65 | // fast Fourier transform (FFT) |
---|
66 | aubio_fft_t *fft = new_aubio_fft (winsize, channels); |
---|
67 | // phase vocoder |
---|
68 | aubio_pvoc_t *pv = new_aubio_pvoc (winsize, stepsize, channels); |
---|
69 | // onset detection |
---|
70 | aubio_onset_t *onset = new_aubio_onset (method, winsize, stepsize, channels, samplerate); |
---|
71 | // pitch detection |
---|
72 | aubio_pitch_t *pitch = new_aubio_pitch (method, winsize, stepsize, channels, samplerate); |
---|
73 | // beat tracking |
---|
74 | aubio_tempo_t *tempo = new_aubio_tempo (method, winsize, stepsize, channels, samplerate); |
---|
75 | |
---|
76 | \endcode |
---|
77 | |
---|
78 | See the <a href="globals_type.html">list of typedefs</a> for a complete list. |
---|
79 | |
---|
80 | \subsection example Example |
---|
81 | |
---|
82 | Here is a simple example that creates an A-Weighting filter and applies it to a |
---|
83 | vector. |
---|
84 | |
---|
85 | \code |
---|
86 | |
---|
87 | // set channels, window size, and sampling rate |
---|
88 | uint_t channels = 2, winsize = 1024, sr = 44100; |
---|
89 | // create a vector |
---|
90 | fvec_t *this_buffer = new_fvec (winsize, channels); |
---|
91 | // create the a-weighting filter |
---|
92 | aubio_filter_t *this_filter = new_aubio_filter_a_weighting (channels, sr); |
---|
93 | |
---|
94 | while (running) { |
---|
95 | // here some code to put some data in this_buffer |
---|
96 | // ... |
---|
97 | |
---|
98 | // apply the filter, in place |
---|
99 | aubio_filter_do (this_filter, this_buffer); |
---|
100 | |
---|
101 | // here some code to get some data from this_buffer |
---|
102 | // ... |
---|
103 | } |
---|
104 | |
---|
105 | // and free the structures |
---|
106 | del_aubio_filter (this_filter); |
---|
107 | del_fvec (this_buffer); |
---|
108 | |
---|
109 | \endcode |
---|
110 | |
---|
111 | Several examples of C programs are available in the \p examples/ and \p tests/src |
---|
112 | directory of the source tree. |
---|
113 | |
---|
114 | \subsection unstable_api Unstable API |
---|
115 | |
---|
116 | Several more functions are available and used within aubio, but not |
---|
117 | documented here, either because they are not considered useful to the user, |
---|
118 | or because they may need to be changed in the future. However, they can still |
---|
119 | be used by defining AUBIO_UNSTABLE to 1 before including the aubio header: |
---|
120 | |
---|
121 | \code |
---|
122 | #define AUBIO_UNSTABLE 1 |
---|
123 | #include <aubio/aubio.h> |
---|
124 | \endcode |
---|
125 | |
---|
126 | Future versions of aubio could break API compatibility with these functions |
---|
127 | without warning. If you choose to use functions in AUBIO_UNSTABLE, you are on |
---|
128 | your own. |
---|
129 | |
---|
130 | \section download Download |
---|
131 | |
---|
132 | Latest versions, further documentation, examples, wiki, and mailing lists can |
---|
133 | be found at http://aubio.org . |
---|
134 | |
---|
135 | */ |
---|
136 | |
---|
137 | #ifndef AUBIO_H |
---|
138 | #define AUBIO_H |
---|
139 | |
---|
140 | /** @file aubio.h Global aubio include file. |
---|
141 | |
---|
142 | Programmers just need to include this file as: |
---|
143 | |
---|
144 | @code |
---|
145 | #include <aubio/aubio.h> |
---|
146 | @endcode |
---|
147 | |
---|
148 | */ |
---|
149 | |
---|
150 | #ifdef __cplusplus |
---|
151 | extern "C" |
---|
152 | { |
---|
153 | #endif |
---|
154 | |
---|
155 | /* in this order */ |
---|
156 | #include "types.h" |
---|
157 | #include "fvec.h" |
---|
158 | #include "cvec.h" |
---|
159 | #include "lvec.h" |
---|
160 | #include "musicutils.h" |
---|
161 | #include "temporal/resampler.h" |
---|
162 | #include "temporal/filter.h" |
---|
163 | #include "temporal/biquad.h" |
---|
164 | #include "temporal/a_weighting.h" |
---|
165 | #include "temporal/c_weighting.h" |
---|
166 | #include "spectral/fft.h" |
---|
167 | #include "spectral/phasevoc.h" |
---|
168 | #include "spectral/mfcc.h" |
---|
169 | #include "spectral/specdesc.h" |
---|
170 | #include "pitch/pitch.h" |
---|
171 | #include "onset/onset.h" |
---|
172 | #include "onset/peakpicker.h" |
---|
173 | #include "tempo/tempo.h" |
---|
174 | |
---|
175 | #if AUBIO_UNSTABLE |
---|
176 | #include "vecutils.h" |
---|
177 | #include "mathutils.h" |
---|
178 | #include "utils/scale.h" |
---|
179 | #include "utils/hist.h" |
---|
180 | #include "spectral/tss.h" |
---|
181 | #include "spectral/filterbank.h" |
---|
182 | #include "spectral/filterbank_mel.h" |
---|
183 | #include "pitch/pitchmcomb.h" |
---|
184 | #include "pitch/pitchyin.h" |
---|
185 | #include "pitch/pitchyinfft.h" |
---|
186 | #include "pitch/pitchschmitt.h" |
---|
187 | #include "pitch/pitchfcomb.h" |
---|
188 | #include "tempo/beattracking.h" |
---|
189 | #endif |
---|
190 | |
---|
191 | #ifdef __cplusplus |
---|
192 | } /* extern "C" */ |
---|
193 | #endif |
---|
194 | |
---|
195 | #endif |
---|