C Python CMake

README.md

Bliss music analyzer v1.0.0

Bliss music library is a C library used to compute distance between songs. It is especially used in leleleplayer. It is can be useful for creating « intelligent » playlists, for instance. See below for a technical description of the project.

Usage

  • Use bl_cosine_similarity_file() to compute the cosine similarity of two songs: Graph from -1 to 1, 1 = close songs, -1 = opposite songs
  • Use bl_distance_file() to compute the euclidian distance between two songs. If the distance is < 5, the songs are really similar; between 5 and 10, they are quite similar, between 10 and 15 means quite opposite, and > 15 « total opposites ».
  • Combine both functions to obtain a better result - for example, a good condition to find similar songs would be « if cosine_distance >= 0.90 AND distance <= 5 then... » .
  • Python bindings are also available. See the wiki to use learn how to use them.

Dependencies

  • libavformat
  • libavutil
  • libavcodec
  • libswresample (or libavresample, if libswresample isn't present)

If you are running Ubuntu (e.g. 14.04), you should apt-get install libavutil-dev libavformat-dev libavcodec-dev libavresample-dev.

If you are running Arch Linux, pacman -S ffmpeg should be enough.

For the Python bindings

  • python-cffi
  • python-setuptools

Installation

Linux users

  • clone repository on github
$ git clone https://github.com/Polochon-street/bliss.git
  • go to bliss root directory
$ cd bliss
  • Create and enter the build directory
$ mkdir build && cd build
  • Generate the Makefile
$ cmake .. -DCMAKE_BUILD_TYPE=Release
  • Compile the library
$ make
  • Install the library
(root) make install
  • (optional) Install the python bindings
(root) cd python && python setup.py install

Usage examples

  • See examples/analyze.c and examples/distance.c
  • Compile any project using bliss with
$ gcc -o example example.c -lbliss $(pkg-config --cflags libavutil libavformat libavcodec)
  • Examples for python bindings are in python/test

Unittests

This library comes with some unittests. To build them, just run

$ make test

in the build/ folder. Unittests source files can be found in the tests/ folder.

How does the analysis process work?

For every song analyzed, libbliss returns a struct song which contains, among other things, four floats, each rating an aspect of the song:

  • The tempo rating follows this paper until part II. A), in order to obtain a downsampled envelope of the whole song. The song's BPM are then estimated by counting the number of peaks and dividing by the length of the song.
    The period of each dominant beat can then be deduced from the frequencies, hinting at the song's tempo. Warning: the tempo is not equal to the force of the song. As an example , a heavy metal track can have no steady beat at all, giving a very low tempo score while being very loud.

  • The amplitude rating reprents the physical « force » of the song, that is, how much the speaker's membrane will move in order to create the sound.
    It is obtained by applying a magic formula with magic coefficients to a histogram of the values of all the song's samples

  • The frequency rating is a ratio between high and low frequencies: a song with a lot of high-pitched sounds tends to wake humans up far more easily.
    This rating is obtained by performing a DFT over the sample array, and splitting the resulting array in 4 frequency bands: low, mid-low, mid, mid-high, and high. Using the value in dB for each band, the final formula corresponds to freq_result = high + mid-high + mid - (low + mid-low)

  • The attack rating is just a sum of the intensity of all the attacks divided by the song's length.
    As you have already guessed, a song with a lot of attacks also tends to wake humans up very quickly.

Python bindings

Please refer to the README.md file in python/ folder.