Here is an example how to compile standard_mfcc.cpp example on Linux linking with a system-wide installation of Essentia (done by ./waf install) and all its dependencies. Modify to your needs.
g++ -pipe -Wall -O2 -fPIC -I/usr/local/include/essentia/ -I/usr/local/include/essentia/scheduler/ -I/usr/local/include/essentia/streaming/ -I/usr/local/include/essentia/utils -I/usr/include/taglib -I/usr/local/include/gaia2 -I/usr/include/qt4 -I/usr/include/qt4/QtCore -D__STDC_CONSTANT_MACROS standard_mfcc.cpp -o standard_mfcc -L/usr/local/lib -lessentia -lfftw3 -lyaml -lavcodec -lavformat -lavutil -lsamplerate -ltag -lfftw3f -lQtCore -lgaia2
Alternatively, if you want to create and build your own examples, the easiest way is to add them to src/examples folder, modify src/examples/wscript file accordingly and use ./waf configure --with-examples; ./waf to build them.
You can build your application using XCode (OSX) following these steps.
Here you can find portable 32-bit static builds of the Essentia C++ library and its dependencies for OSX (thanks to Cárthach from GiantSteps) as well as templates for JUCE/VST and openFrameworks:
https://github.com/GiantSteps/Essentia-Libraries
To create static build of the library and executable example extractors:
Prepare static build of Libav 0.8.16:
git clone git://git.libav.org/libav.git
cd libav
git checkout tags/v0.8.16
./configure --disable-doc --disable-ffmpeg --disable-avconv --disable-avplay --disable-avprobe --disable-avserver --disable-avdevice --disable-swscale --disable-avfilter --disable-network --disable-indevs --disable-outdevs
make
sudo make install
Prepare static build of Taglib 1.9.1:
wget http://taglib.github.io/releases/taglib-1.9.1.tar.gz
tar xf taglib-1.9.1.tar.gz
cd taglib-1.9.1
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_RELEASE_TYPE=Release -DENABLE_STATIC=ON
make
sudo make install
Make sure you did not have libtag1-dev package installed via apt-get (if so, uninstall it).
Build Essentia:
./waf configure --with-static-examples
./waf
sudo ./waf install
The static executables will be in the build/src/examples folder.
Install mingw gcc/g++
sudo apt-get install gcc-mingw32
Build dependencies
cd packaging/win32_3rdparty
build_libav_nomuxers.sh
build_taglib.sh
build_fftw3.sh
build_libsamplerate.sh
build_yaml.sh
cd ../../
Build Essentia
./waf configure --with-examples --cross-compile-mingw32
./waf
A lightweight version of Essentia can be compiled using the --cross-compile-android flag. It requires reducing the dependencies to a bare minimum using KissFFT library for FFT. Specify the installation prefix with --prefix flag. Update the PATH variable to point to where you have your Android Standalone Toolchain.
export PATH=~/Dev/android/toolchain/bin:$PATH;
./waf configure --cross-compile-android --lightweight= --fft=KISS --prefix=/Users/carthach/Dev/android/modules/essentia
./waf
./waf install
Use the instructions below to compile Essentia with FFTW3 support only. The rest of dependencies have not been tested, but they should work as well.
Install Emscripten following the instructions on their website. If you downloaded the SDK manually, make sure to activate the Emscripten environment by executing emsdk_env.sh.
./path/to/emsdk_env.sh
Alternatively, you can install from Ubuntu/Debian repository (the environment will be activated by default).
sudo apt-get install emscripten
Get the latest FFTW3 source code, and prepare it for compilation and installation as an Emscripten system library and build it.
tar xf fftw-3.3.4.tar.gz
cd fftw-3.3.4
# Spawn a subshell to be able to use $EMSCRIPTEN in the command's args
emconfigure sh -c './configure --prefix=$EMSCRIPTEN/system/local/ CFLAGS="-Oz" --disable-fortran --enable-single'
emmake make
emmake make install
Finally, compile Essentia for Emscripten.
cd path/to/essentia
emconfigure sh -c './waf configure --prefix=$EMSCRIPTEN/system/local/ --lightweight=fftw --emscripten'
emmake ./waf
emmake ./waf install
Essentia is now built. If you want to build applications with Essentia and Emscripten, be sure to read their tutorial. Use the emcc compiler, preferably the -Oz option for size optimization, and include the static libraries for Essentia and FFTW as you would with source files. An example would be:
# Make sure your script can access the variable $EMSCRIPTEN
# (available to child processes of emconfigure and emmake)
LIB_DIR=$EMSCRIPTEN/system/local/lib
emcc -Oz -c application.cpp application.bc
emcc -Oz application.bc ${LIB_DIR}/libessentia.a ${LIB_DIR}/libfftw3f.a -o out.js
In the case you want to assure correct working of Essentia, do the tests.
The most important test is the basetest, it should never fail:
./build/basetest
Run all python tests:
./waf run_python_tests
Run all tests except specific ones:
python test/src/unittest/all_tests.py -audioloader_streaming
Run a specific test
python test/src/unittest/all_tests.py audioloader_streaming
The most obvious answer is: by reading its code. However, it is also possible to generate such a list automatically.
Running the python script src/examples/python/show_algo_dependencies.py will output a list of all intermediate Algorithms created within each Algorithm in Essentia. It utilizes the logging framework and watches for messages generated by AlgorithmFactory at the moment of running create() method for each internal algorithm.
Note, that you cannot be sure this list of dependencies is 100% correct as the script simply instantiates each algorithm to test for its dependencies, but does not run the compute stage. It is up to developers conscience to keep instantiations in a correct place, and if an Algorithm is being created on the compute stage, it will be unnoticed.
The amount of algorithms counting streaming and standard mode separately:
python src/examples/python/show_algo_dependencies.py > /tmp/all.txt
cat /tmp/all.txt | grep -- "---------- " | wc -l
The amount of algorithms counting both modes as one algorithm:
python src/examples/python/show_algo_dependencies.py > /tmp/all.txt
cat /tmp/all.txt | grep -- "---------- " | cut -c 12- | sed s/"streaming : "// | sed s/"standard : "// | sed s/" ----------"// | sort -u | wc -l
In order to run classification in Essentia you need to prepare a classifier model in Gaia and run GaiaTransform algorithm configured to use this model. The example of using high-level models can be seen in the code of streaming_music_extractor. Here we discuss the steps to be followed to train classifier models that can be used with this extractor.
- Compute music descriptors using
streaming_music_extractorfor all audio files. - Install Gaia with python bindings.
- Prepare json groundtruth and filelist files (see examples).
- Groundtruth file maps identifiers for audio files (they can be paths to audio files or whatever id strings you want to use) to class labels.
- Filelist file maps these identifiers to the actual paths to the descriptor files for each audio track.
- Currently Gaia does not support loading descriptors in json format, as a workaround you can configure the extractor output to yaml format in Step 1, or run
json_to_sig.pyconversion script. - Run
train_model.pyscript in Gaia (here) with these groundtruth and filelist files. The script will create the classifier model file. - The model file can now be used by a GaiaTransform algorithm inside
streaming_music_extractor.
Note that using a specific classifier model implies that you are expected to give a pool with the same descriptor layout as the one used in training as an input to GaiaTransform Algorithm.
Since version 2.1, build scripts can be configured to ignore 3rdparty dependencies required by Essentia in order to create a striped-down version of the library. Use ./waf configure command with the --lightweight flag to provide the list of 3rdparty dependencies to be included. For example, the command below will configure to build Essentia avoiding all dependencies except fftw:
./waf configure --lightweight=fftw
Avoid all dependencies including fftw and build with KissFFT instead (BSD, included in Essentia therefore no external linking needed, cross-platform):
./waf configure --lightweight= --fft=KISS
Avoid all dependencies and build with Accelerate FFT (native on OSX/iOS):
./waf configure --lightweight= --fft=ACCELERATE
It is also possible to specify algorithms to be ignored using the --ignore-algos flag, although you need to take care that the ignored algorithm are not required by any of the algorithms and examples that will be compiled.
Note, that Essentia includes in its code the Spline library (LGPLv3) which is used by Spline and CubicSpline algorithms and is built by default. To ignore this library, use the following flag in ./waf configure command:
--ignore-algos=Spline,CubicSpline
For more details on the build flags, run:
./waf --help
You can use Essentia's streaming mode in real time feeding input audio frames to a network of algorithms via RingBufferInput. The output of the network can be consumed in real time using RingBufferOutput.
As an example, see the code of essentiaRT~.
You can also use Essentia's standard mode for real-time computations.
Not all algorithms available in the library are suited for real-time analysis due to their computational complexity. Some complex algorithms, such as BeatTrackerDegara, BeatTrackerMultiFeatures, and PredominantMelody, require large segments of audio in order to function properly.
Note that you do not need any copying algorithm to multiplex an output to several inputs. You can just assign it and it will work.