6 If built without any external dependencies aubio can be somewhat useful, for
7 instance to read, process, and write simple wav files.
9 To support more media input formats and add more features to aubio, you can use
10 one or all of the following `external libraries`_.
12 You may also want to know more about the `other options`_ and the `platform
15 The configure script will automatically for these extra libraries. To make sure
16 the library or feature is used, pass the `--enable-flag` to waf. To disable
17 this feature, use `--disable-feature`.
19 To find out more about the build commands, use the `--verbose` option.
24 External libraries are checked for using ``pkg-config``. Set the
25 ``PKG_CONFIG_PATH`` environment variable if you have them installed in an
31 If ``pkg-config`` is not found in ``PATH``, the configure step will
32 succeed, but none of the external libraries will be used.
40 `libav.org <https://libav.org/>`_, open source audio and video processing
43 If all of the following libraries are found, they will be used to compile
44 ``aubio_source_avcodec``. so that ``aubio_source`` will be able to decode audio
45 from all formats supported by `libav
46 <https://libav.org/documentation/general.html#Audio-Codecs>`_.
53 To enable this option, configure with ``--enable-avcodec``. The build will then
54 failed if the required libraries are not found. To disable this option,
55 configure with ``--disable-avcodec``
61 `libsndfile <http://www.mega-nerd.com/libsndfile/>`_, a C library for reading
62 and writing sampled sound files.
64 With libsndfile built in, ``aubio_source_sndfile`` will be built in and used by
67 To enable this option, configure with ``--enable-sndfile``. The build will then
68 fail if the required library is not found. To disable this option, configure
69 with ``--disable-sndfile``
74 `libsamplerate <http://www.mega-nerd.com/SRC/>`_, a sample rate converter for
77 With libsamplerate built in, ``aubio_source_sndfile`` will support resampling,
78 and ``aubio_resample`` will be fully functional.
80 To enable this option, configure with ``--enable-samplerate``. The build will
81 then fail if the required library is not found. To disable this option,
82 configure with ``--disable-samplerate``
84 Optimisation libraries
85 ----------------------
90 `FFTW <http://fftw.org/>`_, a C subroutine for computing the discrete Fourier
93 With libfftw3 built in, ``aubio_fft`` will use `FFTW`_ to
94 compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length
95 that are not a power of 2.
97 To enable this option, configure with ``--enable-fftw3``. The build will
98 then fail if the required library is not found. To disable this option,
99 configure with ``--disable-fftw3``
105 <https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_ are made
106 available through the Accelerate framework.
108 On Linux, they can be enabled with ``--enable-blas``. On Debian (etch),
109 `atlas`_, `openblas`_, and `libblas`_ have been successfully tested.
111 When enabled, ``waf`` will check for the current blas configuration by running
112 ``pkg-config --libs blas``. Depending of the library path returned by
113 ``pkg-config``, different headers will be searched for.
117 On Debian systems, `multiple versions of BLAS and LAPACK
118 <https://wiki.debian.org/DebianScience/LinearAlgebraLibraries>`_ can be
119 installed. To configure which libblas is being used:
121 .. code-block:: console
123 $ sudo update-alternatives --config libblas.so
126 Expected pkg-config output for each alternative:
127 /usr/lib/atlas-base/atlas/libblas.so
128 -L/usr/lib/atlas-base/atlas -lblas
129 /usr/lib/openblas-base/libblas.so
130 -L/usr/lib/openblas-base -lblas
131 /usr/lib/libblas/libblas.so
137 `ATLAS BLAS APIs <http://math-atlas.sourceforge.net/>`_ will be used the path
138 returned by ``pkg-config --libs blas`` contains ``atlas``.
141 ``<atlas/cblas.h>`` will be included.
145 .. code-block:: console
147 $ pkg-config --libs blas
148 -L/usr/lib/atlas-base/atlas -lblas
149 $ ./waf configure --enable-atlas
151 Checking for 'blas' : yes
152 Checking for header atlas/cblas.h : yes
157 `OpenBlas libraries <https://www.openblas.net/>`_ will be used when the output
158 of ``pkg-config --libs blas`` contains 'openblas',
161 ``<openblas/cblas.h>`` will be included.
165 .. code-block:: console
167 $ pkg-config --libs blas
168 -L/usr/lib/openblas-base -lblas
169 $ ./waf configure --enable-atlas
171 Checking for 'blas' : yes
172 Checking for header openblas/cblas.h : yes
177 `Netlib's libblas (LAPACK) <https://www.netlib.org/lapack/>`_ will be used if
178 no specific library path is specified by ``pkg-config``
181 ``<cblas.h>`` will be included.
185 .. code-block:: console
187 $ pkg-config --libs blas
189 $ ./waf configure --enable-atlas
191 Checking for 'blas' : yes
192 Checking for header cblas.h : yes
198 On all platforms, you will need to have installed:
200 - a compiler (gcc, clang, msvc, ...)
201 - python (any version >= 2.7, including 3.x)
202 - a terminal to run command lines in
207 The following `External libraries`_ will be used if found: `libav`_,
208 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
213 The following system frameworks will be used on Mac OS X systems:
215 - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
216 FFTs and other vectorized operations optimally.
218 - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
219 `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
220 decode audio from files and network streams.
224 To build a fat binary for both ``i386`` and ``x86_64``, use ``./waf configure
227 The following `External libraries`_ will also be checked: `libav`_,
228 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
230 To build a fat binary on a darwin like system (macOS, tvOS, appleOS, ...)
231 platforms, configure with ``--enable-fat``.
236 To use a specific version of the compiler, ``--msvc_version``. To build for a
237 specific architecture, use ``--msvc_target``. For instance, to build aubio
238 for ``x86`` using ``msvc 12.0``, use:
242 waf configure --msvc_version='msvc 12.0' --msvc_target='x86'
245 The following `External libraries`_ will be used if found: `libav`_,
246 `libsamplerate`_, `libsndfile`_, `libfftw3`_.
251 The following system frameworks will be used on iOS and iOS Simulator.
253 - `Accelerate <https://developer.apple.com/reference/accelerate>`_ to compute
254 FFTs and other vectorized operations optimally.
256 - `CoreAudio <https://developer.apple.com/reference/coreaudio>`_ and
257 `AudioToolbox <https://developer.apple.com/reference/audiotoolbox>`_ to
258 decode audio from files and network streams.
260 To build aubio for iOS, configure with ``--with-target-platform=ios``. For the
261 iOS Simulator, use ``--with-target-platform=iosimulator`` instead.
263 By default, aubio is built with the following flags on iOS:
267 CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"
269 and on iOS Simulator:
273 CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"
275 Set ``CFLAGS`` and ``LINKFLAGS`` to change these default values, or edit
276 ``wscript`` directly.
281 Some additional options can be passed to the configure step. For the complete
282 list of options, run:
288 Here is an example of a custom command:
292 $ ./waf --verbose configure build install \
293 --enable-avcodec --enable-wavread --disable-wavwrite \
294 --enable-sndfile --enable-samplerate --enable-docs \
295 --destdir $PWD/build/destdir --testcmd="echo %s" \
296 --prefix=/opt --libdir=/opt/lib/multiarch \
297 --manpagesdir=/opt/share/man \
298 uninstall clean distclean dist distcheck
305 The datatype used to store real numbers in aubio is named `smpl_t`. By default,
306 `smpl_t` is defined as `float`, a `single-precision format
307 <https://en.wikipedia.org/wiki/Single-precision_floating-point_format>`_
308 (32-bit). Some algorithms require a floating point representation with a
309 higher precision, for instance to prevent arithmetic underflow in recursive
310 filters. In aubio, these special samples are named `lsmp_t` and defined as
311 `double` by default (64-bit).
313 Sometimes it may be useful to compile aubio in `double-precision`, for instance
314 to reproduce numerical results obtained with 64-bit routines. In this case,
315 `smpl_t` will be defined as `double`.
317 The following table shows how `smpl_t` and `lsmp_t` are defined in single- and
318 double-precision modes:
320 .. list-table:: Single and double-precision modes
333 To compile aubio in double precision mode, configure with ``--enable-double``.
335 To compile in single-precision mode (default), use ``--disable-double`` (or
336 simply none of these two options).
341 In some case, for instance when cross-compiling, unit tests should not be run.
342 Option ``--notests`` can be used for this purpose. The tests will not be
343 executed, but the binaries will be compiled, ensuring that linking against
344 libaubio works as expected.
348 The ``--notests`` option should be passed to both ``build`` and ``install``
349 targets, otherwise waf will try to run them.
354 Many of the options are gathered in the file `wscript`. a good starting point
355 when looking for additional options.
362 If the following command line tools are found, the documentation will be built
365 - `doxygen <http://doxygen.org>`_ to build the :ref:`doxygen-documentation`.
366 - `txt2man <https://github.com/mvertes/txt2man>`_ to build the :ref:`manpages`
367 - `sphinx <http://sphinx-doc.org>`_ to build this document
369 These tools are searched for in the current ``PATH`` environment variable.
370 By default, the documentation is built only if the tools are found.
372 To disable the documentation, configure with ``--disable-docs``. To build with
373 the documentation, configure with ``--enable-docs``.