🎵 Audio Fingerprinting Engine

Audio fingerprinting engine built in Python and PostgreSQL.

This project identifies songs by converting audio into compact acoustic fingerprints through a pipeline consisting of STFT preprocessing, spectral peak detection, constellation mapping, combinatorial hash generation, and temporal coherence matching. The engine supports both file-based and live microphone recognition while visualizing every stage of the fingerprinting process.

---

---

About This Implementation

This repository is an independent, open-source implementation inspired by the algorithmic principles presented in Avery Li-Chun Wang's 2003 paper, An Industrial-Strength Audio Search Algorithm. It recreates the published DSP pipeline—including constellation mapping, combinatorial hashing, and temporal histogram alignment—using a modern Python and PostgreSQL stack for educational exploration and analysis.

This project is not affiliated with Shazam and is not a reproduction of its proprietary implementation. The commercial service incorporates proprietary optimizations, distributed infrastructure, and production engineering that are not publicly documented and are therefore beyond the scope of this repository. Instead, this repository serves as a transparent reference implementation for studying audio fingerprinting algorithms and digital signal processing techniques.

📚 Table of Contents

• Technical Highlights
• Tech Stack
• Audio Fingerprinting Pipeline
• Desktop Application
• Setup & Installation
• Usage
• Project Structure
• Database Architecture
• License

🚀 Technical Highlights

• ⚡ Decoupled DSP & Database Pipeline: Stateless processing modules operate on NumPy arrays and standard Python data structures, making the engine straightforward to integrate into FastAPI, gRPC, or other backend services.
• 🎹 Live System Audio Capture: Captures system audio through WASAPI loopback for real-time song identification without requiring external microphones.
• 🔑 64-bit Acoustic Fingerprinting: Generates compact combinatorial hashes from constellation-map peak pairs, enabling robust and efficient song identification using integer-based database lookups.
• 🗄️ PostgreSQL Fingerprint Database: Designed to efficiently store and query millions of 64-bit acoustic fingerprints using indexed BIGINT lookups and optimized batch operations.
• 📈 Two-Stage Temporal Matching: Combines fingerprint vote counting with temporal offset histogram alignment to verify candidate matches and reject random hash collisions.
• 🛡️ False Positive Rejection: Uses SNR-based confidence scoring together with an ambiguity filter that rejects matches when the runner-up score falls within a configurable ratio threshold.
• 📊 Dynamic Pipeline Visualizer: Incorporates a six-panel diagnostic visualization including the waveform, spectrogram, constellation map, vote tally, clip localization, and temporal offset histogram for every identification.

🛠️ Tech Stack

⚙️ Audio Fingerprinting Pipeline

The identification engine follows a multi-stage DSP pipeline:

End-to-end visualization of the fingerprinting pipeline, showing the major processing stages used during song identification.

🔗 See METHODOLOGY.md for a complete explanation of every stage—including the underlying mathematics, DSP concepts, implementation details, and individual visualizations

🖥️ Desktop Application

The project includes a modern desktop application built with CustomTkinter for indexing songs, identifying music from audio files or live system audio, and visualizing every stage of the fingerprinting pipeline.

Features

• Real-Time Recognition: Identify songs from uploaded audio files or live system audio.
• Responsive Interface: Background threading keeps the UI responsive during fingerprint generation and database queries.
• Pipeline Visualization: Inspect waveform, spectrogram, constellation map, timeline localization, vote distribution, and offset histograms for every match.
• Embedded Analysis: Matplotlib figures are rendered directly inside the application for interactive inspection.
• Live Database Metrics: Displays indexed song and fingerprint counts retrieved from PostgreSQL.

📦 Setup & Installation

1. Clone the Repository

git clone https://github.com/rhthm/audio-fingerprint-engine.git
cd audio-fingerprint-engine

2. Prerequisites

Ensure the following software is installed before continuing:

• Python 3.10+

• Docker Desktop (recommended)

  or

• PostgreSQL 14+ (only for manual setup)

Download links:

• Docker Desktop
• PostgreSQL

3. Set Up a Python Virtual Environment

# Create a virtual environment
python -m venv venv

# Activate the virtual environment

# Linux / macOS
source venv/bin/activate

# Windows (Command Prompt)
venv\Scripts\activate

# Install project dependencies
pip install -r requirements.txt

4. Initialize the Database

🐳 Docker (Recommended)

docker compose up -d

This will automatically:

• Start PostgreSQL
• Create the audio_fingerprint_db database
• Initialize the schema from database/schema.sql
• Persist your database using a Docker volume

💻 Manual PostgreSQL Setup

Click to expand setup instructions

Ensure the PostgreSQL server is installed and running before executing the commands below.

# Create the database
psql -U postgres -c "CREATE DATABASE audio_fingerprint_db;"

# Initialize the schema
psql -U postgres -d audio_fingerprint_db -f database/schema.sql

Configure Environment Variables

Create a .env file in the project root (refer to .env.template):

DB_HOST=localhost
DB_PORT=5432
DB_NAME=audio_fingerprint_db
DB_USER=postgres
DB_PASSWORD=your_secure_password

🏃 Usage

1. Indexing Your Music Library

Drop your reference music files (.mp3, .wav, .flac, .ogg, .m4a) into data/songs/ (or any other folder of your choice). If your audio files do not already contain embedded metadata, name them using the format Artist - Title.mp3.

Note: Embedded metadata (ID3/Vorbis/MP4 tags) always takes priority. When metadata is unavailable, the engine automatically extracts the artist and title from filenames following the format Artist - Title.ext. Files without embedded metadata or this naming convention are still indexed, but will appear using the filename and Unknown Artist.

Run the ingestion pipeline:

python scripts/ingest.py --folder data/songs

Tip: The --folder argument can point to any directory containing your audio library.

To rebuild the fingerprint database from scratch, use the --reset flag:

python scripts/ingest.py --folder data/songs/ --reset

2. Launching the App

python ui/app.py

3. Command-line Recognition

For users who prefer a terminal workflow, the engine supports both saved audio file identification and live recognition directly from microphone or system audio:

Identify saved audio clips

python scripts/recognize.py --file path/to/clip.mp3

Real-time Recognition via Microphone/System Audio

To view available input devices:

python scripts/recognize.py --list-devices

Start live recognition:

python scripts/recognize.py --duration 8

📁 Project Structure

audio-fingerprint-engine/
├── assets/
│   ├── demo.gif
│   ├── icon.png
│   ├── ui.png
│   ├── pipeline.png
│   ├── waveform.png
│   ├── spectrogram.png
│   ├── constellation.png
│   ├── hash_histogram.png
│   └── offset_histogram.png
│
├── data/
│   ├── samples/
│   │   └── .gitkeep
│   └── songs/
│       └── .gitkeep
│
├── database/
│   ├── db.py
│   └── schema.sql
│
├── engine/
│   ├── preprocessor.py
│   ├── constellation_map.py
│   ├── fingerprint.py
│   ├── fingerprint_encoding.py
│   └── matcher.py
│
├── scripts/
│   ├── ingest.py
│   └── recognize.py
│
├── ui/
│   ├── app.py
│   └── config.py
│
├── visualization/
│   ├── plots.py
│   └── config.py
│
├── .dockerignore
├── .env.template
├── .gitignore
├── docker-compose.yml
├── LICENSE
├── README.md
├── METHODOLOGY.md
├── DATABASE.md
└── requirements.txt

🗄️ Database Architecture

The engine stores and queries over 2.36 million acoustic fingerprints using a highly optimized single-node PostgreSQL instance.

• Dataset Scale: Stores 2,361,758 fingerprints across 74 indexed tracks using compact 64-bit (BIGINT) acoustic hashes.
• Covering Index: Uses (hash_val, song_id) INCLUDE (frame_offset) to execute lookups as Index Only Scans, eliminating heap access.
• Measured Performance: Completes a realistic 700-hash fingerprint lookup in 2.322 ms, verified using EXPLAIN (ANALYZE, BUFFERS).
• Stable Query Plans: Uses PostgreSQL array binding (= ANY(%s)) so the SQL statement remains constant regardless of batch size.
• Atomic Data Ingestion: Relies on INSERT ... ON CONFLICT together with PostgreSQL transaction metadata (xmax) to perform race-condition-safe upserts in a single database round trip.

🔗 See DATABASE.md for the complete database architecture, schema design, indexing strategy, benchmark results, execution plans, and query implementation details.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Built by rhthm.