Eliprint Audio Fingerprinting is a powerful Python library designed for audio fingerprinting and music identification. It leverages advanced signal processing techniques to efficiently store and identify audio tracks based on their unique acoustic characteristics.
- Features
- Installation
- Usage
- Signal Processing Concepts
- Library Capabilities
- Contributing
- License
- Acknowledgements
- Single Song Addition: Add individual audio files with metadata.
- Batch Processing: Add multiple songs from a directory efficiently.
- Real-Time Identification: Identify unknown audio tracks with high accuracy.
- Customizable Parameters: Adjust settings for fingerprinting and identification to suit various applications.
You can install the library using pip:
pip install eliprintSet up the database to store your music fingerprints with customizable parameters:
from eliprint import setup_database
# Initialize the fingerprint database with customizable parameters
setup_database(
db_path="music_fingerprints.db",
hash_algorithm="constellation", # Options: "constellation", "wavelet", "mfcc_hash"
peak_neighborhood_size=20, # Controls peak density
min_peak_amplitude=10, # Minimum amplitude for peak detection
fan_value=15, # Number of point pairs per anchor point
min_hash_time_delta=0, # Minimum time between paired points
max_hash_time_delta=200 # Maximum time between paired points
)To add a single song to your database:
from eliprint import add_song
track = add_song(
"elias_melka_song.mp3",
metadata={"artist": "Elias Melka", "title": "Sample Track"},
fft_window_size=4096, # FFT window size for frequency resolution
hop_length=512, # Hop length between frames
frequency_bands=(20, 8000), # Min and max frequency to analyze
energy_threshold=0.75 # Minimum energy for considering a frame
)To add multiple songs from a directory:
from eliprint import batch_add_songs
tracks = batch_add_songs(
"music_collection/",
max_workers=4,
progress_callback=lambda current, total, path: print(f"Processing {current}/{total}"),
sample_rate=44100, # Target sample rate for processing
window_function="hamming", # Window function type
peak_pruning_algorithm="adaptive_threshold" # Algorithm for pruning peaks
)To identify an unknown song:
from eliprint import identify_song
result = identify_song(
"unknown_sample.wav",
confidence_threshold=0.65, # Minimum confidence for a match
time_stretch_range=(-5, 5), # Percentage range for time stretch invariance
match_algorithm="probabilistic", # Options: "probabilistic", "geometric", "hybrid"
noise_reduction=True # Apply noise reduction filter
)
if result:
print(f"Match found: {result.title} by {result.artist} with {result.confidence:.2%} confidence")
print(f"Match details: {result.time_offset}s offset, {result.score} hash matches")
else:
print("No match found")Eliprint Audio Fingerprinting utilizes several advanced signal processing techniques for robust audio fingerprinting. Below is a detailed mathematical explanation of these concepts.
The Fast Fourier Transform efficiently computes the Discrete Fourier Transform (DFT) of a signal, converting time-domain audio data into the frequency domain. For a discrete-time signal
The inverse DFT is given by:
The FFT reduces computational complexity from
A spectrogram provides a time-frequency representation of the signal through the Short-Time Fourier Transform (STFT). For a discrete signal
where
The power spectrogram in decibels is often used for visualization:
Peak detection identifies local maxima in the spectrogram that serve as robust reference points. A spectral peak at position
where
In practice, adaptive thresholding is often used, where a point is a peak if:
where
After peak detection, a constellation map
where
The constellation map is then filtered based on peak strength and density using a rank-order filter:
$$C_{filtered} = {(t_i, f_i) \in C \mid S[t_i, f_i] \geq \text{rank}k(S{N(t_i, f_i)})}$$
where
The fingerprint hashing process converts pairs of peaks from the constellation map into compact, robust hashes. For each anchor point
For each pair of anchor and target points, a hash
where
where
The complete fingerprint consists of the hash and the absolute time of the anchor point:
The matching process uses a combinatorial approach to identify a song. For each hash
For each match, the time offset
A histogram of time offsets for each song
The best matching song is the one with the highest peak in its histogram:
The confidence score can be calculated as:
Time-frequency analysis methods like the Gabor transform provide optimal time-frequency localization according to the Heisenberg uncertainty principle:
The Gabor transform is defined as:
where
This provides better localization in both time and frequency domains compared to the conventional STFT.
The Continuous Wavelet Transform (CWT) decomposes a signal using scaled and shifted versions of a wavelet function:
where
The Discrete Wavelet Transform (DWT) uses dyadic scales and positions:
Wavelet transforms provide multi-resolution analysis that adapts to the signal's local characteristics.
The cross-correlation between two signals
The normalized cross-correlation is:
This provides a measure of similarity between the signals at different time lags, which is useful for audio matching.
The Hamming window is commonly used to reduce spectral leakage in the FFT. It is defined as:
The Hamming window has a main lobe width of approximately
The application of a window function modifies the spectral estimate:
where
MFCCs capture the spectral envelope of the signal in a perceptually relevant way. The mel scale conversion is:
The MFCCs are computed as:
- Compute the power spectrum:
$P[k] = |X[k]|^2$ - Map to mel scale using a filterbank of
$M$ triangular filters:$S[m] = \sum_{k=0}^{N-1} P[k] H_m[k]$ - Take the logarithm:
$\log(S[m])$ - Apply the Discrete Cosine Transform (DCT):
MFCCs provide a compact representation of the spectral characteristics of audio signals.
The CQT provides a frequency analysis with logarithmically spaced frequency bins, which aligns with musical scales:
where
The CQT offers better frequency resolution at lower frequencies and better time resolution at higher frequencies, making it particularly suitable for music analysis.
DTW finds the optimal alignment between two time series by minimizing the cumulative distance:
where
The warping path
- Boundary conditions:
$w_1 = (1, 1)$ and$w_K = (n, m)$ - Monotonicity:
$i_{k-1} \leq i_k$ and$j_{k-1} \leq j_k$ - Continuity:
$i_k - i_{k-1} \leq 1$ and$j_k - j_{k-1} \leq 1$
DTW allows for comparison of audio fingerprints with different time scales, making it robust 8000 to tempo variations.
Eliprint Audio Fingerprinting implements these mathematical concepts with efficient algorithms to provide:
- Scalability: Efficiently manage large music collections with parallel processing and optimized data structures.
- Robustness: Identify songs even with background noise, time stretching, pitch shifting, or partial audio using advanced probabilistic models.
- Customizability: Modify algorithms and parameters for specific use cases, from low-latency live performances to high-accuracy archival applications.
The library employs a hierarchical matching approach:
- Coarse Matching: Fast hash lookup with time offset histogram analysis
- Fine Matching: Detailed verification of matched segments using DTW or cross-correlation
- Confidence Estimation: Statistical models to evaluate match quality based on hash density and consistency
| Operation | Formula | Implementation |
|---|---|---|
| STFT | X(Ο,f) = β«x(t)w(t-Ο)e^(-j2Οft)dt | SpectrogramTransformer |
| Peak Extraction | S(t,f) > ΞΌ + 3Ο | find_spectral_peaks() |
| Hash Generation | H = (f1βf2βΞt) mod 2Β³Β² | HashAlgebra.generate() |
| Matching Score | P(match) = 1 - β(1 - pα΅’) | ProbabilityModel.score() |
# Benchmark metrics
from eliprint.benchmarks import run_analysis
run_analysis(
dataset="gtzan_ethio_subset",
metrics=["precision", "recall", "throughput"],
conditions=["clean", "noisy(-10dB)", "clip(30%)"]
)Expected Output:
| Condition | Precision | Recall | Songs/Min |
|-------------|-----------|--------|-----------|
| Clean | 0.992 | 0.988 | 42 |
| Noisy | 0.963 | 0.951 | 38 |
| Clipped | 0.942 | 0.930 | 35 |
from eliprint import presets
# Ethio-music optimized
presets.apply_ethiopic_mode()
# Live performance settings
presets.set_live_config(
latency="ultra_low",
noise_reduction="aggressive"
)
# Academic research
presets.enable_research_mode(
export_spectrograms=True,
save_intermediate=True
)# Traditional instrument profiles
ELIA_MELKA_PROFILE = {
"tempo_range": (80, 160),
"signature_rhythms": ["3+2", "2+3"],
"scale_preferences": ["Pentatonic", "Tizita"]
}
ep = Eliprint(cultural_profile=ELIA_MELKA_PROFILE)For End Users:
pip install eliprintFor Developers:
git clone https://github.com/ethio-audio/eliprint
cd eliprint
pip install -e ".[dev,analysis]"@software{Eliprint,
author = {Ethio Audio Research},
title = {Bridging Traditional Music and Modern Signal Processing},
year = {2023},
url = {https://github.com/ethio-audio/eliprint}
}Contributions are welcome! Please open an issue or submit a pull request for any improvements or features you'd like to see.
This project is licensed under the MIT License - see the LICENSE file for details.
- Thanks to the open-source community for providing inspiration and tools to create this library.