Hibiki

A Shazam-style music identification system using audio fingerprinting and spectral peak hashing.

Overview

Hibiki is a Go implementation of the Shazam audio fingerprinting algorithm based on the paper "An Industrial Strength Audio Search Algorithm" by Avery Li-Chun Wang (2003).

It works by:

1. Converting audio to a spectrogram using FFT
2. Extracting spectral peaks (constellation map)
3. Generating 32-bit combinatorial hashes from anchor-target pairs
4. Matching query hashes against a database using diagonal alignment

Requirements

• Go 1.25+
• SQLite3
• FFmpeg (for generating test audio)

Installation

git clone https://github.com/KiranRajeev-KV/hibiki.git
cd hibiki
go build -o hibiki ./cmd

Usage

# Add audio files (WAV or MP3) to database
./hibiki -add music/

# Find a matching song
./hibiki -find query.wav

# Find with verbose output (shows duration, hashes, time)
./hibiki -find query.mp3 -v

# List indexed songs
./hibiki -list

# Show database statistics
./hibiki -stats

# Delete a song
./hibiki -delete 1

# Custom database path
./hibiki -add music/ -db mydb.db

Configuration

All tunable parameters are in internal/config/config.go. See CONFIG.md for detailed explanations of each parameter and how to tune them.

Parameter	Default	Description
SampleRate	8000	Hz (after downsampling)
FFTSize	2048	FFT window size
WindowOverlap	0.5	Overlap ratio
PeakThreshold	15	Max peaks per frame
MinAmplitude	0.01	Noise floor cutoff
TargetZoneFrames	250	~1-3 seconds ahead
MinHashMatches	100000	Required for positive match
DiagonalWidth	10	Time coherence window

Project Structure

hibiki/
├── cmd/main.go              # Entry point
├── internal/
│   ├── config/config.go    # Tunable parameters
│   ├── audio/reader.go     # Audio loading (WAV/MP3)
│   ├── audio/preprocess.go # Low-pass filter + downsampling
│   ├── dsp/                # Signal processing
│   │   ├── fft.go
│   │   ├── spectrogram.go
│   │   └── window.go
│   ├── fingerprint/         # Core algorithm
│   │   ├── peaks.go
│   │   ├── hash.go
│   │   └── fingerprint.go
│   ├── db/store.go         # SQLite operations
│   └── match/matcher.go    # Recognition
├── testdata/               # Test audio files
│   ├── generate.sh        # Script to generate test data
│   ├── songs/             # Seed songs
│   └── queries/           # Query samples for testing
└── go.mod

Testing

# Generate test audio data
./testdata/generate.sh

# Run all tests
go test ./...

# Run tests with verbose output
go test ./... -v

# Run specific test
go test ./internal/dsp/... -v
go test ./internal/fingerprint/... -v
go test ./internal/db/... -v

License

MIT