vibra

Overview

• vibra is a C++ library and command-line tool for music recognition using the unofficial Shazam API.
• It analyzes audio files, generates fingerprints, and queries the Shazam database to identify songs.
• Key features:
  • Fast and lightweight: Optimized for various platforms, including embedded devices.
  • Cross-platform: Supports Linux, Windows, macOS, and WebAssembly.
  • Flexible input: Processes WAV files natively, with optional FFmpeg support for other formats.
• Based on Shazam's algorithm:
  • An Industrial-Strength Audio Search Algorithm - The original research paper.
  • How does Shazam work - A detailed explanation of the algorithm.
• Implementation inspired by SongRec, adapted to C++ 11.
• Target platforms:
  • Embedded devices (e.g., Raspberry Pi, Jetson Nano)
  • Desktop and server environments for high-performance audio recognition
  • WebAssembly for web-based music recognition

Platform Compatibility and Build Status

Platform	Architecture	Build Status
WebAssembly	-
Linux	x86_64, ARM64
Windows	x86_64	✅
macOS	x86_64, ARM64	✅
Raspberry Pi	ARMv8-A, ARMv6	✅

Building the WebAssembly Version

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

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: A library for making HTTP requests to the Shazam API.
  • libfftw3: A library for computing Fast Fourier Transforms.
  • 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 libfftw3-dev
  • sudo apt-get install ffmpeg (Optional)
• Windows
  • Install CMake
  • Install vcpkg
  • Install dependencies using vcpkg:
    • vcpkg install curl:x64-windows fftw3:x64-windows
  • Add the vcpkg toolchain file to your CMake command (see Build section)
  • Install FFmpeg (Optional)
• macOS
  • Install Homebrew
  • brew install cmake curl fftw
  • brew install ffmpeg (Optional)

Build

• Clone repository recursively to include submodules.

  • git clone --recursive 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 out.mp3

# Specify the FFmpeg path
export FFMPEG_PATH=/opt/homebrew/bin/ffmpeg
vibra --recognize --file out.mp3

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

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!

Demo Video

• Real time music tracker and lighting solution "Mooding", which uses vibra.
• Click to view!

License

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