MusicAnalyser/README.md

Music Analyser

A personal analytics dashboard for your music listening habits, powered by Python, FastAPI, React, and Google Gemini AI.

Project Structure

• backend/: FastAPI backend for data ingestion and API.
  • app/ingest.py: Background worker that polls Spotify and enriches data via ReccoBeats.
  • app/services/: Logic for Spotify, ReccoBeats, and Gemini APIs.
  • app/models.py: Database schema (Tracks, PlayHistory).
• frontend/: React + Vite frontend for visualizing the dashboard.
• docker-compose.yml: For easy deployment.

Features

• Continuous Ingestion: Polls Spotify every 60 seconds to record your listening history.
• Data Enrichment: Automatically fetches Genres (via Spotify) and Audio Features (Energy, BPM, Mood via ReccoBeats).
• Dashboard: A responsive UI to view your history and stats.
• AI Ready: Database schema and environment prepared for Gemini AI integration.

Hosting Guide (Docker)

This application is designed to run via Docker Compose.

1. Prerequisites

• Docker & Docker Compose installed.
• Spotify Developer Credentials (Client ID & Secret).
• Spotify Refresh Token (Run backend/scripts/get_refresh_token.py locally to generate this).
• Google Gemini API Key.

2. Deployment

1. Clone the repository.

2. Create a .env file in the root directory (or use environment variables directly):

   SPOTIFY_CLIENT_ID="your_client_id"
   SPOTIFY_CLIENT_SECRET="your_client_secret"
   SPOTIFY_REFRESH_TOKEN="your_refresh_token"
   GEMINI_API_KEY="your_gemini_key"
   

3. Run with Docker Compose:

   docker-compose up -d --build
   

   This will:

   • Build and start the Backend (port 8000).
   • Build and start the Frontend (port 8991).
   • Create a Persistent Volume at /opt/mySpotify (mapped to the container's database) to ensure no data loss during updates.

4. Access the Dashboard: Open your browser to http://localhost:8991 (or your server IP).

3. Data Persistence & Updates

• Data: All data is stored in music.db inside the container, which is mounted to /opt/mySpotify/music.db on your host machine.
• Migrations: The project uses Alembic for database migrations. When you update the container image in the future, the backend will automatically apply any schema changes without deleting your data.

4. Pulling from Registry (Alternative)

If you prefer to pull the pre-built image instead of building locally:

docker pull ghcr.io/bnair123/musicanalyser:latest

(Note: You still need to mount the volume and pass environment variables as shown in docker-compose.yml).

Local Development

1. Backend:

   cd backend
   pip install -r requirements.txt
   python run_worker.py  # Starts ingestion
   uvicorn app.main:app --reload  # Starts API
   

2. Frontend:

   cd frontend
   npm install
   npm run dev