• Eigen: for linear algebra

• FFTW: for the FFT implementation

• libavcodec/libavformat/libavutil/libavresample (from the FFmpeg/LibAv project): for loading/saving any type of audio files

• libsamplerate: for resampling audio 

• TagLib: for reading audio metadata tags

• LibYAML: for YAML files input/output 

• Gaia: for using SVM classifier models 

• Chromaprint: for audio fingerprinting

• TensorFlow: for inference with TensorFlow deep learning models 

All dependencies are optional, and some functionality will be excluded when a dependency is not found.

Installing dependencies on Linux

We can install those dependencies on a Debian/Ubuntu system from official repositories using the command below:

sudo apt-get install build-essential libeigen3-dev libyaml-dev libfftw3-dev libavcodec-dev libavformat-dev libavutil-dev libavresample-dev libsamplerate0-dev libtag1-dev libchromaprint-dev

In order to use Python 3 bindings for the library, you might also need to install python3-dev, python3-numpy-dev (or python3-numpy on Ubuntu) and python3-yaml for YAML support in python:

sudo apt-get install python3-dev python3-numpy-dev python3-numpy python3-yaml python3-six

Note that, depending on the version of Essentia, different versions of libav* and libtag1-dev packages are required.

If you are willing to use Essentia with a TensorFlow wrapper in C++, install the TensorFlow shared library using a helper script inside our source code:

src/3rdparty/tensorflow/setup_from_libtensorflow.sh

Installing dependencies on macOS

Install Command Line Tools for Xcode. Even if you install Xcode from the app store you must configure command-line compilation by running:

xcode-select --install

Install Homebrew package manager.

Insert the Homebrew directory at the top of your PATH environment variable by adding the following line at the bottom of your ~/.profile file:

export PATH=/usr/local/bin:/usr/local/sbin:

Install prerequisites:

brew install pkg-config gcc readline sqlite gdbm freetype libpng

Install Essentia’s dependencies:

brew install eigen libyaml fftw ffmpeg libsamplerate libtag tensorflow

Install Python environment using Homebrew

brew install python --framework
pip install ipython numpy matplotlib pyyaml

Compiling Essentia

Once your dependencies are installed, you can proceed to compile Essentia. Download Essentia’s source code at Github. Due to different dependencies requirements, make sure to download the version compatible with your system:

• master branch is the most updated version of Essentia in development

• 2.1 beta5 is the current stable version recommended to install.

Go into its source code directory and start by configuring the build:

python3 waf configure --build-static --with-python --with-cpptests --with-examples --with-vamp

The following will give you the full list of options:

python3 waf --help

If you want to build with a custom toolchain, you can pass in the CC and CXX variables for using another compiler. For example, to build the library and examples with clang:

CC=clang CXX=clang++ python3 waf configure

To compile everything you’ve configured:

python3 waf

All built examples will be located in build/src/examples/ folder, as well as the Vamp plugin file libvamp_essentia.so.

To install the C++ library, Python bindings, extractors, and Vamp plugin :

python3 waf install

Python3 bindings

To build Essentia with Python 3 bindings, use the --with-python configuration flag.By default, the waf build script will auto-detect the site-packages (or dist-packages) directory to install Essentia’s Python package according to the Python binary used to execute it. Alternatively, you can set a specific Python binary using the --python=PYTHON configuration option.

Note that when installing Essentia to the default /usr/local prefix, on some Linux distributions this results in a wrong /usr/local/lib/python3/dist-packages/ package installation path (for example, Ubuntu, see here and here).

To avoid import errors on such systems, specify the correct path in waf configure using an --pythondir option or the PYTHONDIR environmental variable. For example, on Ubuntu 20.10 the correct path for the default Python 3.8 is /usr/local/lib/python3.8/dist-packages/.

Binding Essentia on Windows

The easiest way to build Essentia is by cross-compilation on Linux using MinGW. However the resulting library binaries are only compatible within C++ projects using MinGW compilers, and therefore they are not compatible with Visual Studio.

Binding Essentia on Android 

A lightweight version of Essentia can be cross-compiled for Android from Linux or macOS

Binding Essentia on iOS

A lightweight version of Essentia can be cross-compiled for iOS from macOS.