How orms147/music-recommendation works
Project type and purpose
• This is a full-stack Python application for music recommendation.
• Purpose: fetch real metadata from Spotify, run two content-based filtering models (EnhancedContentRecommender and WeightedContentRecommender), and expose a web UI (Gradio) for side-by-side comparison of recommendations.
Main components
a. Presentation Layer (Frontend)
• Gradio interface (.gradio folder + code in main.py)
• Accepts user input (seed track names or IDs) and displays two ranked song lists.
b. Application Layer (Backend orchestrator)
• main.py: entry point that wires together configuration, data utilities, model training/inference, and UI callbacks.
• config/config.py: holds environment variables (Spotify credentials, thresholds, model hyperparameters).
c. Utility Modules
• utils/data_fetcher.py: interacts with Spotify Web API (via spotipy), handles rate-limiting, retries, genre fetching.
• utils/data_checker.py: validates completeness and quality of fetched metadata.
• utils/data_processor.py: transforms raw JSON into feature vectors (popularity, language flags, mood tiers, etc.).
d. Model Layer
• models/base_model.py: abstract interface for recommenders.
• models/content_model.py: shared content-based logic (cosine similarity, feature extraction).
• models/enhanced_content_model.py: implements fuzzy matching + multi-factor scoring + diversity penalty + popularity balancing.
• models/weighted_content_model.py: implements language-first weighting + mood hierarchy + cultural similarity.
e. Data Storage
• Local “data/” directory (raw & processed CSVs or pickles) – not committed but defined in README.
• .cache folder used by Gradio or spotipy for caching tokens/certificates.
f. External Services
• Spotify Web API (metadata only).
Relationships & data flow
1. User → Gradio UI
2. UI callback → main.py
3. main.py loads config → calls data_fetcher.fetch( seed_tracks ) → Spotify API
4. Raw metadata → data_checker.validate → data_processor.transform → DataFrame/feature matrix
5. Feature matrix → two model instances → produce ranked lists
6. Results → main.py → Gradio output panels
Architectural patterns & design principles
• Layered architecture: clear separation of UI, orchestration, utilities, models, and data.
• Strategy pattern for recommenders: interchangeable model classes inheriting from base_model.
• Single Responsibility: each module focuses on one concern (fetching, checking, processing, modeling).
• Dependency injection via config.py for credentials and hyperparameters.
Key technologies/frameworks
• Python 3.x
• spotipy (Spotify API wrapper)
• pandas, numpy (data processing)
• scikit-learn (similarity metrics, pipelines)
• difflib.SequenceMatcher (fuzzy search)
• Gradio (web UI)