How nikh7l/shazam works
Main Components
• Frontend (React + Vite SPA)
• Backend (Flask REST API + WebSockets)
• Core Fingerprinting Engine (Python library: shazam_core)
• Database (SQLite via db_handler)
• Background Task Runner (Python concurrent.futures)
• External Services (Spotify API, YouTube API/DL)
Relationships & Data Flows
a. User Interaction
• Browser captures audio (MediaRecorder API) → React UI “Listen” component
• React sends audio blob via HTTP POST or WebSocket → Backend /match endpoint or WS route
b. Matching Flow
• Flask routes (backend/routes/songs.py, websockets.py) receive audio →
• Pass audio to Fingerprinting Service (services/song_ingester.py for ingestion, or match service) →
• Fingerprinting Engine (shazam_core modules: spectrogram.py → peak_finding.py → fingerprinting.py → combinatorial hashes) →
• Query SQLite via db_handler to find best match →
• Return match data (song metadata + YouTube link) → React displays results
c. Ingestion Flow (Admin Panel → Background Task)
• React Admin form hits /ingest endpoint →
• Backend song_ingester.py enqueues job into concurrent.futures thread pool →
• Worker downloads track(s) (Spotipy, yt-dlp) →
• Processes through Fingerprinting Engine →
• Stores fingerprint hashes and metadata into SQLite via db_handler →
• Reports ingestion status via WS or REST status endpoint
Architectural Patterns & Principles
• Layered Responsibility:
• Presentation Layer (React)
• API Layer (Flask routes + WS)
• Service Layer (services/ orchestrates flows)
• Core Library Layer (shazam_core for pure audio logic)
• Persistence Layer (database/db_handler, migrations)
• Separation of Concerns: audio I/O, business logic, data access, external API interactions are all modular.
• Asynchronous Background Processing: use of thread pool for nonblocking ingestion tasks.
• External Integration Adapters: api_clients/spotify_client.py, youtube_client.py.
Call Out Key Technologies
• Frontend: React, Vite, Fetch API, WebSocket, react-youtube
• Backend: Python 3, Flask, Waitress (prod WSGI), pydub, numpy, scipy
• DB: SQLite, raw SQL + migrations
• Audio Fingerprinting: custom spectrogram/peak hash algorithm
• External APIs: Spotipy, yt-dlp
• Use arrowheads to denote request/response directions.
Detail Without Clutter
• Clearly identifies every major piece of the system
• Shows how data flows end‐to‐end (from mic to match result)
• Highlights both real‐time matching and background ingestion processes
• Distinguishes between internal modules, infrastructure, and third‐party services