music-repeat-listen-predictor

Predicting Repeat Listens: A Music Recommendation System

Binary classification project that predicts whether a user will replay a song within 30 days, then uses that model to rank personalized song recommendations.

Problem

For each (user, song) interaction, predict:

• 1 → user replays the song within 30 days
• 0 → user does not replay it

Project Structure

music-recsys/
├── data/
│   ├── raw/            # raw listening logs (csv/json) go here
│   └── processed/      # cleaned + feature-engineered data
├── model/              # saved trained model (.pkl / .joblib)
├── notebooks/
│   └── notebook.ipynb  # full EDA -> model -> evaluation walkthrough
├── src/
│   ├── make_sample_data.py   # generates a synthetic dataset for testing
│   ├── data_prep.py          # cleaning + label generation
│   ├── features.py           # feature engineering
│   ├── train.py               # train baseline + tuned model
│   ├── evaluate.py            # metrics: F1, ROC-AUC, Precision@K
│   ├── recommend.py           # top-N recommendation generator
│   └── inference.py           # load model, score new interactions
├── requirements.txt
└── README.md

Pipeline

1. Data Collection — load raw listening logs
2. Data Cleaning — handle missing values, duplicates, invalid timestamps
3. Feature Engineering — recency, frequency, avg gap between plays, time-of-day, genre encoding
4. Label Generation — "replay within 30 days" target
5. Train/Test Split — time-based (no leakage)
6. Modeling — Logistic Regression baseline → Random Forest / XGBoost
7. Evaluation — F1, ROC-AUC, Precision@K
8. Recommendation Layer — rank untried/older songs per user
9. Packaging — save model, write inference script
10. Deployment — GitHub (code) + Hugging Face (model/demo)

Quickstart

pip install -r requirements.txt

# 1. Generate a synthetic sample dataset (swap for a real dataset later,
#    e.g. Spotify Million Playlist Dataset, Last.fm, or a Kaggle dataset)
python src/make_sample_data.py

# 2. Clean data + generate labels
python src/data_prep.py

# 3. Engineer features
python src/features.py

# 4. Train model
python src/train.py

# 5. Evaluate
python src/evaluate.py

# 6. Generate top-N recommendations for a user
python src/recommend.py --user_id U001 --top_n 5

Using a Real Dataset

Replace the file at data/raw/listening_history.csv with your real dataset. Required columns:

• user_id, song_id, timestamp
• optional: genre, tempo, danceability (song-level features)

The rest of the pipeline (data_prep.py onward) works unchanged as long as these columns are present.

Results

Fill in after training: Accuracy / Precision / Recall / F1 / ROC-AUC / Precision@K

Tech Stack

Python, pandas, numpy, scikit-learn, xgboost, matplotlib/seaborn, joblib, Google Colab, GitHub, Hugging Face Hub (+ optional Gradio demo).

Publishing to GitHub

This folder is already a git repo with an initial commit. To push it:

# 1. Create a new empty repo on github.com (no README/license, so it stays empty)
# 2. Then:
cd music-recsys
git remote add origin https://github.com/<your-username>/music-recsys.git
git branch -M main
git push -u origin main

Publishing to Hugging Face

The huggingface/ folder is a ready-to-upload model repo (model card + optional Gradio demo).

pip install huggingface_hub
huggingface-cli login

# Create the model repo and upload model files
huggingface-cli repo create music-repeat-listen-predictor --type model
cp model/model.joblib model/feature_columns.json huggingface/
cd huggingface
git init -q
huggingface-cli upload <your-username>/music-repeat-listen-predictor . .

To also deploy the interactive demo, create a Space (type: space, SDK: gradio), and upload app.py + requirements.txt from huggingface/ along with the model files — the Space will auto-launch app.py.