audiolocate

This document was AI-translated from the Traditional Chinese original.

An audio fingerprint matching engine based on the algorithm proposed in Wang (2003) "An Industrial-Strength Audio Search Algorithm." Given a short audio sample and a long reference audio, it determines whether the sample appears in the reference audio and returns the precise time offset.

Features

• Spectral Peak Constellation Fingerprinting — Generates hashes via STFT spectral local peak pairing for efficient matching
• Noise Resilience — Correctly identifies matches even under 3 dB SNR conditions
• Fast Localization in Long Audio — Chunked streaming with early-exit mechanism stops on hit, no need to scan the entire reference audio, significantly reducing matching time for long audio
• Streaming Processing — Supports chunked streaming matching for large audio files with controllable memory usage
• Parallel Decoding — Audio decoding and fingerprint computation run concurrently for improved throughput
• Multi-Format Support — Supports common audio formats such as MP3, AAC, and WAV via PyAV
• Multiple Input Sources — Accepts file paths, URLs, and file-like objects

Installation

pip install audiolocate

Or install from source:

git clone https://github.com/JoeYang1412/audiolocate.git
cd audiolocate
pip install .

Quick Start

Basic Matching

from audiolocate import AudioFingerprint

fp = AudioFingerprint()
result = fp.find_match("reference.wav", "sample.wav")

if result["found"]:
    print(f"Match found at {result['time_seconds']:.2f} seconds")
else:
    print("No match found")

Streaming Matching (for Large Files)

from audiolocate import StreamMatcher

matcher = StreamMatcher()
result = matcher.find_match_from_sources(
    "long_audio.wav",
    "short_sample.wav",
    chunk_seconds=300,   # Process 300 seconds per chunk
    early_exit=True,     # Stop immediately after finding a match
    verbose=True         # Show processing progress
)

if result["found"]:
    print(f"Match found at {result['time_seconds']:.2f} seconds")
    print(f"Processed {result['chunks_processed']} chunks")

In practice, locating a 10-second sample within a 4-hour reference audio: when the match point is near the beginning, early-exit hits on the first batch of chunks in approximately 10 seconds; when the match point is at the very end and all chunks must be scanned, it completes in approximately 45 seconds (including network I/O, decoding, and fingerprint computation).

Custom Parameters

fp = AudioFingerprint(
    sr=16000,                # Sample rate (default: 8000)
    n_fft=2048,              # FFT window size (default: 1024)
    peaks_per_second=50,     # Number of peaks per second (default: 30)
    significance_factor=2.5  # Statistical significance threshold factor (default: 3.0)
)

Classes and Methods

AudioFingerprint

Core fingerprint matching class.

StreamMatcher

Inherits from AudioFingerprint, providing streaming processing capabilities.

MatchResult

Match result (NamedTuple).

Key Parameters

Algorithm Overview

1. STFT — Convert audio into a time-frequency spectrogram
2. Peak Detection — Extract constellation using local maximum filter with block density control
3. Hash Generation — Encode peak pairs as 32-bit hashes (frequency pair + time difference)
4. Offset Histogram — Count hash hits for each time offset between sample and reference
5. Adaptive Thresholding — Three-layer determination combining minimum threshold, statistical significance, and prominence

References

Wang, A. (2003). An Industrial-Strength Audio Search Algorithm. In Proceedings of the 4th International Conference on Music Information Retrieval (ISMIR).

License

See the license file in the project root directory.