How kither12/shezem-rs works
Project’s Purpose and Overview
• Shezem-rs is designed to index audio files and quickly search for similar audio based on a fingerprinting algorithm inspired by Shazam.
• The tool is a CLI application with two main commands: “index” (to process and save fingerprints) and “search” (to find matches against a saved fingerprint database).
Main Components
a. CLI Interface and Command Handling:
• Main module (src/main.rs): Acts as the entry point which parses CLI arguments and routes commands (“index” and “search”).
• Lib module (src/lib.rs): Likely exports the core functionality for reuse in both commands.
b. Audio Processing Pipeline (Indexing):
• Preprocessing: Convert audio from stereo to mono, downsample by filtering frequencies (using IIR low-pass filter), and prepare the audio for further processing.
• Spectrogram Generation (src/spectrogram.rs): Apply the Short-Time Fourier Transform (STFT) with a Hamming window, determine the time-frequency representation, and identify peaks.
• Fingerprinting (src/fingerprint.rs and src/sample.rs): Group significant peaks into fingerprint hashes by using adjacent peak groups (anchor-based addressing using adjacent peaks).
c. Database Management:
• Database module (src/db.rs): Handles creation and storage of the fingerprint index (e.g., writing to a “.db/db.db3” file). This module will be used in both the indexing and searching phases.
d. Utility Functions:
• Utils (src/utils.rs): Contains lower-level utilities that support common tasks across the audio processing pipeline.
Relationships and Data Flow
• CLI (src/main.rs) receives commands and directs the flow.
• For “index”:
• Audio Input → Preprocessing → Spectrogram Generation → Fingerprinting → Database Storage (via src/db.rs)
• For “search”:
• Query Audio Input → Same processing pipeline (preprocessing, spectrogram, fingerprint extraction) → Compare with stored fingerprints from the DB → Use temporal coherence and ranking logic to sort and return top matches.
Architectural Patterns and Design Principles
• Modular monolithic design: All components are part of a single executable, but the responsibilities are segmented into dedicated modules.
• Separation of concerns: Clearly separate audio signal processing (preprocessing, spectrogram, fingerprinting) from persistence (database handling) and command parsing (CLI).
• Reusability: Core libraries in src/lib.rs integrate shared functionality between commands.