RITHMA

Music recommendation system based on emotion analysis using AI.

Features

• Sentiment Analysis: Detects emotions in text using Hugging Face models
• Smart Recommendations: Suggests Spotify music based on your mood
• Modern Interface: Frontend built with React + TypeScript + Vite

Prerequisites

• Python 3.8+
• Node.js 16+
• Spotify Developer Account
• Hugging Face Token

Credentials Setup

1. Spotify API

1. Go to Spotify Developer Dashboard
2. Create an application
3. Copy your Client ID and Client Secret

2. Hugging Face API

1. Go to Hugging Face Settings
2. Generate a new access token

3. Environment Variables

Create a .env file in the backend/ folder:

cd backend
cp .env.example .env

Edit the .env file with your real credentials:

SPOTIFY_CLIENT_ID=your_real_client_id
SPOTIFY_CLIENT_SECRET=your_real_client_secret
HF_API_TOKEN=your_real_hf_token

⚠️ IMPORTANT: NEVER upload the .env file to Git. It's already included in .gitignore.

Installation

Backend (Python)

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run server
uvicorn src.main:app --reload

The backend will be available at: http://localhost:8000

Frontend (React)

cd frontend

# Install dependencies
npm install

# Run in development mode
npm run dev

The frontend will be available at: http://localhost:5173

📊 Machine Learning Model

The emotion detection system is powered by a K-Means clustering analysis of 14,306 songs from the FMA dataset. The complete development process is documented in:

• Notebook: notebooks/Rithma_song_rec_sys_ml_train.ipynb
• Documentation: notebooks/README.md

Key Findings:

• 7 distinct sonic clusters identified using K-Means
• Emotion-to-audio-feature mapping created
• Dynamic rules system for Spotify API recommendations

Want to understand how it all works? Read the LEARN.md guide!

Security

This project follows security best practices:

• Credentials in environment variables (.env)
• .env included in .gitignore
• .env.example as template without sensitive data
• CORS configured for specific origins
• No secrets exposed in code

BEFORE PUSHING TO GITHUB

1. Verify that .env is NOT in Git:

   git status
   # You should NOT see .env in the list

2. If you accidentally uploaded credentials:

   • Regenerate ALL credentials immediately
   • Use git filter-branch or BFG Repo-Cleaner to clean the history

Usage

1. Start the backend
2. Start the frontend
3. Write how you feel (e.g., "I'm feeling very happy today")
4. Receive a personalized music recommendation

Contributing

Contributions are welcome. Please:

1. Fork the project
2. Create a branch for your feature (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is open source and available under the MIT License.

⚠️ Disclaimer

This project uses third-party APIs (Spotify and Hugging Face). Make sure to comply with their terms of service.