Spin

Music Recommendation Engine

A content-based music recommender that surfaces sonically similar tracks using a K-Nearest Neighbors model trained on Spotify audio features. Takes a song as input and returns five recommendations based on audio feature similarity across a dataset of 114,000+ tracks. For songs outside the dataset, the system falls back to GPT-4o-mini, with results enriched via the Spotify API.

Built as a personal project to explore ML-based recommendation systems and full-stack development.

---

Demo

🔗 Live demo: spin-dmpk.onrender.com

Hosted on Render's free tier — may take ~30 seconds to wake up on first load.

1. Type a song name into the search bar (e.g. Blinding Lights or Blinding Lights - The Weeknd)
2. Select a track from the dropdown or press Enter
3. The CD spins while recommendations are generated
4. Click any track card to preview it via the Spotify embed player
5. Heart songs to save them to your picks list

---

Data

Source: Spotify Tracks Dataset (Kaggle, via maharshipandya)

Size: 114,000+ tracks after deduplication

Features used for similarity:

Feature	Description
danceability	How suitable a track is for dancing
energy	Perceptual measure of intensity and activity
valence	Musical positiveness (happy vs. sad)
tempo	Estimated beats per minute
acousticness	Confidence the track is acoustic
instrumentalness	Predicts whether a track contains no vocals
liveness	Detects presence of a live audience
loudness	Overall loudness in decibels
speechiness	Presence of spoken words in a track

Preprocessing:

• Dropped rows with missing track_name, artists, or album_name
• Deduplicated on (track_name, artists)
• Features normalized with StandardScaler before model fitting

---

Tech Stack

Layer	Technologies
Backend	Python, FastAPI
ML Model	scikit-learn (KNN), pandas, joblib
Music Metadata	Spotify Web API (Spotipy)
Fallback Recommendations	OpenAI GPT-4o-mini
Frontend	Plain HTML, CSS, JavaScript
Deployment	Render

---

How It Works

Model

The KNN model is trained on Spotify's audio feature vectors, including:

• danceability, energy, valence
• tempo, acousticness, instrumentalness
• loudness, speechiness, liveness

Features are normalized using StandardScaler before fitting. At inference time, the query song's feature vector is retrieved from the dataset and its 5 nearest neighbors are returned by cosine distance.

Recommendation Pipeline

1. Search — user queries are matched against the dataset by track name and optionally artist
2. KNN lookup — if found, the model returns the 5 most similar songs by audio feature distance
3. Spotify enrichment — album art, preview URLs, and track IDs are fetched via the Spotify API
4. ChatGPT fallback — if the track is not in the dataset, GPT-4o-mini suggests similar songs which are then enriched with Spotify metadata

---

Running Locally

1. Clone the repository

git clone https://github.com/rafiamb/spin.git
cd spin

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a .env file in the project root:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
OPENAI_API_KEY=your_openai_api_key

Spotify credentials can be obtained by registering an application at developer.spotify.com.

4. Start the server

uvicorn app:app --reload

The application will be available at http://localhost:8000.

---

Project Structure

spin/
├── app.py                  # FastAPI application and API routes
├── requirements.txt
├── static/
│   ├── index.html
│   ├── style.css
│   ├── app.js
│   └── CD.png
└── model/
    ├── knn_model.joblib    # trained KNN model
    ├── scaler.joblib       # fitted StandardScaler
    ├── songs.parquet       # song dataset (114k tracks)
    └── features.json       # feature column names

---

License

This project is licensed under the MIT License.