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.
• The fingerprints vibra generates are compatible with Apple's official ShazamKit: generate the signature anywhere (server, embedded device, browser) and match it through the official ShazamKit SDK on any platform ShazamKit supports (iOS, macOS, Android). See Using vibra with the official ShazamKit.
• 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 lives in this repository under 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

Using vibra with the official ShazamKit

• vibra reproduces Shazam's signature format, so a fingerprint produced by vibra can be passed to the official ShazamKit SDK as a signature and matched through the public API instead of the unofficial web API.
• This enables a split architecture: a device without ShazamKit support (Linux server, embedded board, WebAssembly) generates the fingerprint, and a ShazamKit-capable app (iOS, macOS, Android) performs the match through the public API.
• Verified: a signature produced by vibra --fingerprint was loaded by ShazamKit without any conversion and matched successfully against the Shazam catalog (title, artist, ISRC and Shazam ID returned).
• Keep the signature between 3 and 12 seconds — the Shazam catalog rejects longer signatures. File input is capped at 12 seconds automatically; when fingerprinting raw PCM, pass --seconds 12 or shorter.

# 1. Generate the signature (a data URI) on any platform
vibra --fingerprint --file sample.wav
# data:audio/vnd.shazam.sig;base64,gJhwuB...

// 2. Match it with the official ShazamKit (Swift shown; the Android SDK works the same way)
import ShazamKit

let uri = "data:audio/vnd.shazam.sig;base64,gJhwuB..."   // from vibra
let base64 = uri.components(separatedBy: "base64,").last!
let signature = try SHSignature(dataRepresentation: Data(base64Encoded: base64)!)

let session = SHSession()
session.delegate = self
session.match(signature)

// SHSessionDelegate
func session(_ session: SHSession, didFind match: SHMatch) {
    let item = match.mediaItems.first
    print(item?.title, item?.artist, item?.isrc, item?.shazamID)
}
func session(_ session: SHSession, didNotFindMatchFor signature: SHSignature, error: Error?) {
    print("no match", error ?? "")
}

• The same data: URI is available through the C API (vibra_get_uri_from_fingerprint()), the Python package and the WebAssembly build.

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.