Osele1/sonic-clusters

SonicClusters — Music Clustering & Recommendation System

An interactive web application demonstrating unsupervised music clustering and content-based recommendation. Built with React 18, TypeScript, FastAPI, and scikit-learn, powered by a 12,000-song dataset combining the Million Song Dataset with modern Spotify tracks.

[image]

Features

1. Cluster Explorer

• —Musical Mood Labeling: Clusters are automatically named based on their audio profile (e.g., "Intense Upbeat Pop", "Mellow Slow Jazz") rather than just IDs.
• —2D/3D Visualization: Interactive scatter plots using UMAP dimensionality reduction for mathematically accurate spatial grouping.
• —Real Audio Features: View live Tempo, Loudness, Energy, and Danceability data directly from the dataset.
• —Switchable Algorithms: Compare K-Means, Hierarchical, and DBSCAN on the fly.

2. Recommendation System

• —Live Model Inference: Euclidean distance is calculated in real-time on the backend to find the most similar songs within a cluster.
• —Spotify Integration: Real album artwork, audio previews, and "Open in Spotify" links via the Web API.
• —Genre Badges: Modern Spotify tracks display their specific genre tags (e.g., synth-pop, latin).

3. Algorithm Comparison

• —Radar Charts: Compare algorithm performance across metrics like Silhouette and Davies-Bouldin.
• —Distribution Analysis: Pie charts showing how each algorithm partitions the 12,000-song space.
• —Metric Dashboard: Comprehensive table with sub-second performance scores.

Tech Stack

Frontend

• —React 18 — Component-based architecture
• —TypeScript — Enterprise-grade type safety
• —Tailwind CSS — Modern "Dark Neon" aesthetic with glassmorphism
• —Framer Motion — Smooth animations and layout transitions
• —Recharts — Dynamic metric visualizations

Backend

• —FastAPI — High-performance async REST API
• —scikit-learn — Machine learning pipeline (K-Means, Hierarchical, DBSCAN)
• —UMAP-learn — Dimensionality reduction for visualization
• —Pandas/NumPy — Large-scale vector operations
• —Spotify Web API — Dynamic metadata retrieval

Dataset

The application utilizes a unified 12,000-song dataset:

Unified Features: tempo, loudness, duration, danceability, energy, key, mode, time_signature, and genre.

Getting Started

Prerequisites

• —Node.js 18+
• —Python 3.9+
• —Spotify API Credentials (Optional, for album art)

Installation

1. 1.Clone & Install:

git clone https://github.com/Oseleadeoye/sonic-clusters-.git
cd sonic-clusters-
npm install
pip install -r backend/requirements.txt

1. 1.Configure Spotify (Optional): Add your credentials to backend/.env:

SPOTIFY_CLIENT_ID=your_id
SPOTIFY_CLIENT_SECRET=your_secret

1. 1.Run the App:

# Terminal 1: Backend
cd backend
python main.py

# Terminal 2: Frontend
npm run dev

API Documentation

• —GET /api/songs: Fetch unified dataset
• —GET /api/recommendations/{id}: Live similarity search
• —GET /api/labels/{algorithm}: Retrieve automated musical mood labels
• —GET /api/algorithms: Performance metrics and metadata
• —GET /api/health: System status and model integrity check

Team

• —Vik Dayal
• —Nathaniel Ola Ogunleye
• —Osele Adeoye
• —Huynh Hai Trieu Le

Built for DATA480 Project — Advanced Music Clustering