🎵 Spotify Track Recommendation System

A production-grade music recommendation engine built on the Spotify Tracks Dataset from Kaggle, featuring multiple recommendation strategies and a full evaluation framework.

---

📁 Project Structure

spotify-tracks-dataset/
├── configs/
│   └── config.yaml              # All settings in one place
├── data/
│   ├── raw/
│   │   └── spotify_tracks.csv   # Kaggle dataset (place here)
│   └── processed/               # Auto-generated after training
├── models/                      # Saved recommender model
├── notebooks/                   # Jupyter exploration notebooks
├── outputs/                     # EDA plots, evaluation charts, CSV exports
├── src/
│   ├── data_info.py             # EDA & visualizations
│   ├── load_data.py             # Preprocessing pipeline
│   ├── recommender.py           # Core recommendation engine
│   └── evaluate.py              # Evaluation metrics & reports
└── main.py                      # CLI entry point

---

🚀 Setup

Using UV (recommended)

uv sync
uv run python main.py --help

Or with pip

pip install -r requirement.txt
python main.py --help

---

🗂️ Dataset Setup

1. Download from Kaggle: https://www.kaggle.com/datasets/maharshipandya/-spotify-tracks-dataset
2. Place the CSV at: data/raw/spotify_tracks.csv

---

🎯 Usage

1. Exploratory Data Analysis

python main.py --mode eda

Generates plots in outputs/:

• Genre distribution
• Audio feature histograms
• Correlation heatmap
• Popularity analysis
• Top artists

---

2. Train the Recommender

python main.py --mode train

• Cleans and preprocesses data
• Engineers new features (vibe_index, mood_index, etc.)
• Fits KNN + KMeans models
• Saves model to models/recommender.pkl

---

3. Get Recommendations

Content-based (default — cosine similarity):

python main.py --mode recommend --track "Blinding Lights" --n 10

KNN-based (faster for large datasets):

python main.py --mode recommend --track "Shape of You" --n 10 --method knn

Cluster-based (same musical neighborhood):

python main.py --mode recommend --track "Levitating" --n 10 --method cluster

Same genre only:

python main.py --mode recommend --track "Blinding Lights" --n 10 --same_genre

Exclude same artist (more diverse):

python main.py --mode recommend --track "Blinding Lights" --n 10 --exclude_artist

Save results to CSV:

python main.py --mode recommend --track "Blinding Lights" --n 10 --save_output

---

4. Mood-Based Recommendations

python main.py --mode mood --mood happy --n 10
python main.py --mode mood --mood energetic --n 15
python main.py --mode mood --mood calm --genre "acoustic" --n 10

Available moods: happy, sad, energetic, calm, party, focus, romantic, aggressive

---

5. Generate a Playlist from Multiple Seeds

python main.py --mode playlist --seeds "Blinding Lights,Shape of You,Levitating" --n_per_seed 5
python main.py --mode playlist --seeds "Bohemian Rhapsody,Hotel California" --n_per_seed 8 --save_output

---

6. Evaluate Recommendation Quality

# Single track evaluation
python main.py --mode evaluate --track "Blinding Lights"

# Batch evaluation across multiple tracks
python main.py --mode evaluate --batch "Blinding Lights,Shape of You,Levitating,Stay"

Metrics reported:

• Intra-list similarity — diversity of recommendations
• Genre coverage — genre entropy
• Popularity stats — mainstream vs niche balance
• Serendipity score — unexpectedness
• Feature drift — how far recs stray from seed

---

7. Search for Tracks

python main.py --mode search --query "blinding"

---

8. Get Track Info + System Info

python main.py --mode info --track "Blinding Lights"

---

🧠 How It Works

Feature Engineering

Beyond raw Spotify audio features, we compute:

Feature	Formula	Meaning
vibe_index	(energy + danceability) / 2	Overall vibe
mood_index	valence × energy	Emotional energy
acoustic_electric	acousticness − energy	Acoustic spectrum
tempo_bucket	bucketed tempo	Tempo category
popularity_tier	bucketed popularity	Mainstream level

Recommendation Strategies

Method	Description	Best For
Content-Based	Cosine similarity on scaled audio features	Default
KNN	sklearn NearestNeighbors (brute, cosine)	Speed on large data
Cluster	Same KMeans cluster + cosine ranking	Musical neighborhood
Mood-Based	Feature range filters + popularity sort	Discovery
Playlist	Multi-seed aggregation + deduplication	Session planning

Re-ranking

All methods support optional popularity boost — a weighted blend of similarity score and track popularity to surface well-known similar tracks.

---

📊 Config (configs/config.yaml)

Key settings you can tune:

recommendation:
  default_n_recommendations: 10
  popularity_boost: true
  popularity_weight: 0.15   # 0 = pure similarity, 1 = pure popularity

model:
  knn:
    n_neighbors: 20
  clustering:
    n_clusters: 20

preprocessing:
  scaler: "minmax"          # or "standard"

---

📈 Sample Evaluation Output

============================================================
  EVALUATION REPORT: 'Blinding Lights' (content)
============================================================
  Recommendations     : 10
  Intra-list Similarity: 0.9241 (lower = more diverse)
  Serendipity Score    : 0.3120

  Genre Coverage:
    Unique Genres  : 3
    Genre Entropy  : 1.5849

  Popularity Stats:
    Mean  : 71.4
    Mainstream (≥60): 80.0%

  Feature Drift from Seed:
    Mean Similarity: 0.9241
    Mean Distance  : 0.0759
============================================================

---

🏆 Next Steps / Extensions

• Collaborative filtering (user-track matrix)
• Transformer-based track embeddings
• FastAPI / Streamlit web interface
• Spotify API integration (live track lookup)
• User session personalization