vibra

Overview

• vibra is a library and CLI tool for music recognition using the unofficial Shazam API.
• It analyzes audio files, generates fingerprints, and queries Shazam's database for song identification.
• Key features:
  • Fast and lightweight, optimized for various platforms, including embedded devices.
  • Cross-platform support: Linux, Windows, macOS, WebAssembly, and Python.
  • Flexible input processing: native support for WAV files, optional FFmpeg for other formats.
• Based on Shazam's algorithm:
  • An Industrial-Strength Audio Search Algorithm
  • How does Shazam work
• Inspired by SongRec, adapted to C++ 11.
• Target platforms:
  • Embedded devices (e.g., Raspberry Pi, Jetson Nano)
  • Desktop and server environments for high-performance recognition
  • WebAssembly for web-based use
  • Python applications through the ctypes-based Python package
  • Additional support for iOS, Android, and other languages through the public C ABI

Live Demo

• You can try the music recognition with the WebAssembly version of vibra here
• The source code for the demo is available at vibra-live-demo

Platform Compatibility and Build Status

Platform	Status	Workflows
Code Checks		ci-code
Linux AMD64		ci-linux-amd64
Linux ARM64		ci-linux-arm64
MacOS ARM64		ci-macos-arm64
Windows AMD64		ci-windows-amd64
WebAssembly		ci-webassembly
Python		ci-python

Building the WebAssembly Version

• Please refer to js/README.md for instructions on building and running the JavaScript/WebAssembly version of vibra.

Building the Python Package

• Please refer to python/README.md for instructions on building and using the Python package.

Building the Native Version

Prerequisites

• vibra requires CMake for its build process. Please install CMake before proceeding.
• The project is developed using the C++11 standard.
• vibra has the following dependencies:
  • CMake: A cross-platform build system generator.
  • libcurl (CLI tool only): A library for transferring data with URLs.
    • If you don't need CLI tool, libcurl is not required.
    • You can disable it by setting the -DLIBRARY_ONLY=ON option in the CMake command.
  • FFmpeg (Optional): Provides support for audio formats other than WAV (e.g., MP3, FLAC).
    • Install FFmpeg if you need to process audio files in formats other than WAV.

Install dependencies

• Ubuntu
  • sudo apt-get update
  • sudo apt-get install cmake libcurl4-openssl-dev
  • sudo apt-get install ffmpeg (Optional)
• Windows
  • Install CMake
  • Install vcpkg
  • Install dependencies using vcpkg:
    • vcpkg install curl:x64-windows
  • Add the vcpkg toolchain file to your CMake command (see Build section)
  • Install FFmpeg (Optional)
• macOS
  • Install Homebrew
  • brew install cmake curl
  • brew install ffmpeg (Optional)

Build

• Clone vibra repository

  • git clone https://github.com/bayernmuller/vibra.git

• Run the following commands to build vibra:

  • cd vibra
  • mkdir build && cd build
  • cmake ..
  • make
  • sudo make install (Optional)
    • Installs the libvibra static, shared libraries and the vibra command-line tool.

Usage

Use --help option to see the help message.

vibra {COMMAND} [OPTIONS]

Options:

  Commands:
      -F, --fingerprint                     Generate a fingerprint
      -R, --recognize                       Recognize a song
      -h, --help                            Display this help menu
  Sources:
      File sources:
          -f, --file                            File path
      Raw PCM sources:
          -s, --seconds                         Chunk seconds
          -r, --rate                            Sample rate
          -c, --channels                        Channels
          -b, --bits                            Bits per sample

Recognizing a song from a WAV file

vibra --recognize --file sample.wav > result.json

jq .track.title result.json
"Stairway To Heaven"
jq .track.subtitle result.json
"Led Zeppelin"
jq .track.share.href result.json
"https://www.shazam.com/track/5933917/stairway-to-heaven"

Recognizing a song from a microphone

• You can use sox or FFmpeg to capture raw PCM data from the microphone.
• sox

sox -d -t raw -b 24 -e signed-integer -r 44100 -c 1 - 2>/dev/null
| vibra --recognize --seconds 5 --rate 44100 --channels 1 --bits 24 > result.json

• FFmpeg

ffmpeg -f avfoundation -i ":2" -f s32le -ar 44100 -ac 1 - 2>/dev/null
| vibra --recognize --seconds 5 --rate 44100 --channels 1 --bits 32 > result.json
# - "avfoundation" can be replaced depending on your system.
# - Make sure to use the correct device index for your system.

• output

jq .track.title result.json
"Bound 2"
jq .track.subtitle result.json
"Kanye West"
jq .track.sections[1].text result.json
[
  "B-B-B-Bound to fall in love",
  "Bound to fall in love",
  "(Uh-huh, honey)",
  ...
]

Recognizing non-WAV files

• To decode non-WAV media files, FFmpeg must be installed on your system.
• Vibra will attempt to locate FFmpeg in your system's PATH environment variable. If you prefer, you can explicitly specify the FFmpeg path by setting the FFMPEG_PATH environment variable.

# Automatically find FFmpeg in PATH
vibra --recognize --file sample.mp3

# Specify the FFmpeg path
export FFMPEG_PATH=/opt/homebrew/bin/ffmpeg
vibra --recognize --file sample.mp3
# You can use your own FFmpeg which is optimized for your system.

• You can see the sample shazam result json file in here

FFI Bindings

• vibra provides FFI bindings, allowing other languages to leverage its music recognition functionality.
• After building vibra, the shared library libvibra.so will be located in the build directory.
• This shared library can be integrated into languages such as Python or Swift using FFI mechanisms.
• For detailed function signatures, please refer to the vibra header file vibra.h.

Performance comparison

lower is better

• I compared the performance of vibra with the SongRec rust and python version on the Raspberry Pi 4.
• vibra is about 2 times faster than the SongRec!

Contribution

Unit tests

• Unit tests are built with GoogleTest, fetched by CMake.
• Native CI builds release artifacts with -DBUILD_TESTING=OFF, then configures a separate test build with -DBUILD_TESTING=ON.
• Run the following commands to build and run unit tests:
  • cmake -B build-test -DCMAKE_BUILD_TYPE=Debug -DLIBRARY_ONLY=ON -DBUILD_TESTING=ON
  • cmake --build build-test --target vibra_unit_tests
  • ctest --test-dir build-test --output-on-failure

Code checks

• Code CI runs cpplint and clang-format.
• Run the following commands locally:
  • cpplint --recursive lib include tests/algorithm tests/audio tests/utils tests/public_api_test.cpp
  • find include lib tests -path tests/e2e -prune -o \( -name '*.h' -o -name '*.cpp' -o -name '*.cc' -o -name '*.c' \) -print0 | xargs -0 clang-format --dry-run --Werror

License

• vibra is licensed under the GPLv3 license. See LICENSE for more details.