Installing aubio — aubio 0.4.8 documentation

# Installing aubio

aubio runs on Linux, Windows, macOS, iOS, Android, and probably a few others operating systems.

Aubio is available as a C library and as a python module.

## Cheat sheet

- get aubio latest source code:

      # official repo
      git clone https://git.aubio.org/aubio/aubio
      # mirror
      git clone https://github.com/aubio/aubio
      # latest release
      wget https://aubio.org/pub/aubio-<version>.tar.gz

- build aubio from source:

      # 1. simple
      cd aubio
      make

      # 2. step by step
      ./scripts/get_waf.sh
      ./waf configure
      ./waf build
      sudo ./waf install

- install python-aubio from source:

      # from git
      pip install git+https://git.aubio.org/aubio/aubio/
      # mirror
      pip install git+https://github.com/aubio/aubio/
      # from latest release
      pip install https://aubio.org/pub/aubio-latest.tar.bz2
      # from pypi
      pip install aubio
      # from source directory
      cd aubio
      pip install -v .

- install python-aubio from a pre-compiled binary:

      # conda [osx, linux, win]
      conda install -c conda-forge aubio
      # .deb (debian, ubuntu) [linux]
      sudo apt-get install python3-aubio python-aubio aubio-tools
      # brew [osx]
      brew install aubio --with-python

- get a pre-compiled version of libaubio:

      # .deb (linux) WARNING: old version
      sudo apt-get install aubio-tools

      # python module
      ./setup.py install
      # using pip
      pip install .

- check the list of optional dependencies:

      # debian / ubuntu
      dpkg -l libavcodec-dev libavutil-dev libavformat-dev \
              libswresample-dev libavresample-dev \
              libsamplerate-dev libsndfile-dev \
              txt2man doxygen

# Downloading aubio

A number of distributions already include aubio. Check your favorite package management system, or have a look at the aubio download page for more options.

To use aubio in an android project, see Android build.

To compile aubio from source, read Building aubio.

## Pre-compiled binaries

Pre-compiled binaries are available for macOS, iOS, and windows

To use aubio in a macOS or iOS application, see Frameworks for Xcode.

## Debian/Ubuntu packages

For the latest Debian packages, see https://packages.debian.org/src:aubio.

For the latest Ubuntu packages, see http://packages.ubuntu.com/src:aubio.

For the latest version of the packages, see https://anonscm.debian.org/cgit/collab-maint/aubio.git/. Use `git-buildpackage` to build from the git repository. For instance:

    $ git clone git://anonscm.debian.org/collab-maint/aubio.git
    $ cd aubio
    $ git buildpackage

# Building aubio

Note

To download a prebuilt version of aubio, see Downloading aubio.

aubio uses waf to configure, compile, and test the source. A copy of waf is included in aubio tarball, so all you need is a terminal, a compiler, and a recent version of python installed.

Note

Make sure you have all the Build options you want before building.

## Latest release

The latest stable release can be downloaded from https://aubio.org/download:

    $ curl -O http://aubio.org/pub/aubio-<version>.tar.bz2
    $ tar xf aubio-<version>.tar.bz2
    $ cd aubio-<version>/

## Git repository

The latest git branch can be obtained with:

    $ git clone git://git.aubio.org/git/aubio
    $ cd aubio/

The following command will fetch the correct waf version (not included in aubio’s git):

    $ ./scripts/get_waf.sh

Note

Windows users without Git Bash installed will want to use the following commands instead:

    $ curl -fsS -o waf https://waf.io/waf-1.8.22
    $ curl -fsS -o waf.bat https://raw.githubusercontent.com/waf-project/waf/master/utils/waf.bat

## Compiling

To compile the C library, examples programs, and tests, run:

    $ ./waf configure

Check out the available options using `./waf configure --help`. Once you are done with configuration, you can start building:

    $ ./waf build

To install the freshly built C library and tools, simply run the following command:

    $ sudo ./waf install

Note

Windows users should simply run `waf`, without the leading `./`. For instance:

    $ waf configure build

## Running as a user

To use aubio without actually installing, for instance if you don’t have root access to install libaubio on your system,

On Linux or macOS, sourcing the script `scripts/setenv_local.sh` should help:

    $ source ./scripts/setenv_local.sh

This script sets `LD_LIBRARY_PATH`, for libaubio, and `PYTHONPATH` for the python module.

On Linux, you should be able to set `LD_LIBRARY_PATH` with:

    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD/build/src

On Mac OS X, a copy or a symlink can be made in `~/lib`:

    $ mkdir -p ~/lib
    $ ln -sf $PWD/build/src/libaubio*.dylib ~/lib/

Note on Mac OS X systems older than El Capitan (10.11), the `DYLD_LIBRARY_PATH` variable can be set as follows:

    $ export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$PWD/build/src

## Cleaning

If you wish to uninstall the files installed by the `install` command, use `uninstall`:

    $ sudo ./waf uninstall

To clean the source directory, use the `clean` command:

    $ ./waf clean

To also forget the options previously passed to the last `./waf configure` invocation, use the `distclean` command:

    $ ./waf distclean

## Frameworks for Xcode

Binary frameworks are available and ready to use in your XCode project, for iOS and macOS.

1. Download and extract the corresponding `framework.zip` file from the Download page
2. Select Build Phases in your project setting and unfold Link Binary with Libraries
3. Add AudioToolbox and Accelerate system frameworks (or make sure they are listed)
4. Add `aubio.framework` from the unzipped `framework.zip`
5. Include the aubio header in your code:

> - in C/C++:

>     #include <aubio/aubio.h>

> - in Obj-C:

>     #import <aubio/aubio.h>

> - in Swift:

>     import aubio

## Using aubio from swift

Once you have downloaded and installed aubio.framework, you sould be able to use aubio from C, Obj-C, and Swift source files.

Here is a short example showing how to read a sound file in swift:

>     import aubio

>     let path = Bundle.main.path(forResource: "example", ofType: "mp4")
>     if (path != nil) {
>         let hop_size : uint_t = 512
>         let a = new_fvec(hop_size)
>         let b = new_aubio_source(path, 0, hop_size)
>         var read: uint_t = 0
>         var total_frames : uint_t = 0
>         while (true) {
>             aubio_source_do(b, a, &read)
>             total_frames += read
>             if (read < hop_size) { break }
>         }
>         print("read", total_frames, "frames at", aubio_source_get_samplerate(b), "Hz")
>         del_aubio_source(b)
>         del_fvec(a)
>     } else {
>         print("could not find file")
>     }

## Android build

To compile aubio for android, you will need to get the Android Native Development Toolkit (NDK), prepare a standalone toolchain, and tell waf to use the NDK toolchain. An example script to complete these tasks is available in `scripts/build_android`.

# Build options

If built without any external dependencies aubio can be somewhat useful, for instance to read, process, and write simple wav files.

To support more media input formats and add more features to aubio, you can use one or all of the following external libraries.

You may also want to know more about the other options and the platform notes

The configure script will automatically for these extra libraries. To make sure the library or feature is used, pass the –enable-flag to waf. To disable this feature, use –disable-feature.

To find out more about the build commands, use the –verbose option.

## External libraries

External libraries are checked for using `pkg-config`. Set the `PKG_CONFIG_PATH` environment variable if you have them installed in an unusual location.

Note

If `pkg-config` is not found in `PATH`, the configure step will succeed, but none of the external libraries will be used.

## Media libraries

### libav

> libav.org, open source audio and video processing tools.

If all of the following libraries are found, they will be used to compile `aubio_source_avcodec`. so that `aubio_source` will be able to decode audio from all formats supported by libav.

- libavcodec
- libavformat
- libavutil
- libavresample

To enable this option, configure with `--enable-avcodec`. The build will then failed if the required libraries are not found. To disable this option, configure with `--disable-avcodec`

### libsndfile

> libsndfile, a C library for reading and writing sampled sound files.

With libsndfile built in, `aubio_source_sndfile` will be built in and used by `aubio_source`.

To enable this option, configure with `--enable-sndfile`. The build will then fail if the required library is not found. To disable this option, configure with `--disable-sndfile`

### libsamplerate

> libsamplerate, a sample rate converter for audio.

With libsamplerate built in, `aubio_source_sndfile` will support resampling, and `aubio_resample` will be fully functional.

To enable this option, configure with `--enable-samplerate`. The build will then fail if the required library is not found. To disable this option, configure with `--disable-samplerate`

## Optimisation libraries

### libfftw3

> FFTW, a C subroutine for computing the discrete Fourier transform

With libfftw3 built in, `aubio_fft` will use FFTW to compute Fast Fourier Transform (FFT), allowing aubio to compute FFT on length that are not a power of 2.

To enable this option, configure with `--enable-fftw3`. The build will then fail if the required library is not found. To disable this option, configure with `--disable-fftw3`

### blas

On macOs/iOS, blas are made available through the Accelerate framework.

On Linux, they can be enabled with `--enable-blas`. On Debian (etch), atlas, openblas, and libblas have been successfully tested.

When enabled, `waf` will check for the current blas configuration by running `pkg-config --libs blas`. Depending of the library path returned by `pkg-config`, different headers will be searched for.

Note

On Debian systems, multiple versions of BLAS and LAPACK can be installed. To configure which libblas is being used:

    $ sudo update-alternatives --config libblas.so

### atlas

ATLAS BLAS APIs will be used the path returned by `pkg-config --libs blas` contains `atlas`.

Example:

    $ pkg-config --libs blas
    -L/usr/lib/atlas-base/atlas -lblas
    $ ./waf configure --enable-atlas
    [...]
    Checking for 'blas'                      : yes
    Checking for header atlas/cblas.h        : yes

### openblas

OpenBlas libraries will be used when the output of `pkg-config --libs blas` contains ‘openblas’,

Example:

    $ pkg-config --libs blas
    -L/usr/lib/openblas-base -lblas
    $ ./waf configure --enable-atlas
    [...]
    Checking for 'blas'                      : yes
    Checking for header openblas/cblas.h     : yes

### libblas

Netlib’s libblas (LAPACK) will be used if no specific library path is specified by `pkg-config`

Example:

    $ pkg-config --libs blas
    -lblas
    $ ./waf configure --enable-atlas
    [...]
    Checking for 'blas'                      : yes
    Checking for header cblas.h              : yes

## Platform notes

On all platforms, you will need to have installed:

> - a compiler (gcc, clang, msvc, …)
> - python (any version >= 2.7, including 3.x)
> - a terminal to run command lines in

### Linux

The following External libraries will be used if found: libav, libsamplerate, libsndfile, libfftw3.

### macOS

The following system frameworks will be used on Mac OS X systems:

> - Accelerate to compute FFTs and other vectorized operations optimally.
> - CoreAudio and AudioToolbox to decode audio from files and network streams.

Note

To build a fat binary for both `i386` and `x86_64`, use `./waf configure --enable-fat`.

The following External libraries will also be checked: libav, libsamplerate, libsndfile, libfftw3.

To build a fat binary on a darwin like system (macOS, tvOS, appleOS, …) platforms, configure with `--enable-fat`.

### Windows

To use a specific version of the compiler, `--msvc_version`. To build for a specific architecture, use `--msvc_target`. For instance, to build aubio for `x86` using `msvc 12.0`, use:

    waf configure --msvc_version='msvc 12.0' --msvc_target='x86'

The following External libraries will be used if found: libav, libsamplerate, libsndfile, libfftw3.

### iOS

The following system frameworks will be used on iOS and iOS Simulator.

> - Accelerate to compute FFTs and other vectorized operations optimally.
> - CoreAudio and AudioToolbox to decode audio from files and network streams.

To build aubio for iOS, configure with `--with-target-platform=ios`. For the iOS Simulator, use `--with-target-platform=iosimulator` instead.

By default, aubio is built with the following flags on iOS:

    CFLAGS="-fembed-bitcode -arch arm64 -arch armv7 -arch armv7s -miphoneos-version-min=6.1"

and on iOS Simulator:

    CFLAGS="-arch i386 -arch x86_64 -mios-simulator-version-min=6.1"

Set `CFLAGS` and `LINKFLAGS` to change these default values, or edit `wscript` directly.

## Other options

Some additional options can be passed to the configure step. For the complete list of options, run:

    $ ./waf --help

Here is an example of a custom command:

    $ ./waf --verbose configure build install \
                --enable-avcodec --enable-wavread --disable-wavwrite \
                --enable-sndfile --enable-samplerate --enable-docs \
                --destdir $PWD/build/destdir --testcmd="echo %s" \
                --prefix=/opt --libdir=/opt/lib/multiarch \
                --manpagesdir=/opt/share/man  \
                uninstall clean distclean dist distcheck

### Double precision

The datatype used to store real numbers in aubio is named smpl_t. By default, smpl_t is defined as float, a single-precision format (32-bit). Some algorithms require a floating point representation with a higher precision, for instance to prevent arithmetic underflow in recursive filters. In aubio, these special samples are named lsmp_t and defined as double by default (64-bit).

Sometimes it may be useful to compile aubio in double-precision, for instance to reproduce numerical results obtained with 64-bit routines. In this case, smpl_t will be defined as double.

The following table shows how smpl_t and lsmp_t are defined in single- and double-precision modes:

Single and double-precision modes
| single | double
smpl_t | `float` | `double`
lsmp_t | `double` | `long double`

To compile aubio in double precision mode, configure with `--enable-double`.

To compile in single-precision mode (default), use `--disable-double` (or simply none of these two options).

### Disabling the tests

In some case, for instance when cross-compiling, unit tests should not be run. Option `--notests` can be used for this purpose. The tests will not be executed, but the binaries will be compiled, ensuring that linking against libaubio works as expected.

Note

The `--notests` option should be passed to both `build` and `install` targets, otherwise waf will try to run them.

### Edit wscript

Many of the options are gathered in the file wscript. a good starting point when looking for additional options.

## Building the docs

If the following command line tools are found, the documentation will be built built:

> - doxygen to build the Doxygen documentation.
> - txt2man to build the Command line tools
> - sphinx to build this document

These tools are searched for in the current `PATH` environment variable. By default, the documentation is built only if the tools are found.

To disable the documentation, configure with `--disable-docs`. To build with the documentation, configure with `--enable-docs`.