Music Analyser

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

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 (Ant Design) to view your history, stats, and "Vibes".
• AI Ready: Database schema and environment prepared for Gemini AI integration.

Hosting Guide

You can run this application using Docker Compose. You have two options: using the pre-built image from GitHub Container Registry or building from source.

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. Configuration (.env)

Create a .env file in the root directory (same level as docker-compose.yml). This file is used by Docker Compose to populate environment variables.

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

Option A: Build from Source (Recommended for Dev/Modifications)

Use this if you want to modify the code or ensure you are running the exact local version.

1. Clone the repository.
2. Ensure your .env file is set up.
3. Run:

   docker-compose up -d --build
   

Option B: Use Pre-built Image

Use this if you just want to run the app without building locally.

1. Open docker-compose.yml.
2. Ensure the backend service uses the image: ghcr.io/bnair123/musicanalyser:latest.
   • Note: If you want to force usage of the image and ignore local build context, you can comment out build: context: ./backend in the yaml, though Compose usually prefers build context if present.
3. Ensure your .env file is set up.
4. Run:

   docker pull ghcr.io/bnair123/musicanalyser:latest
   docker-compose up -d
   

4. Access the Dashboard

Open your browser to: http://localhost:8991

5. Data Persistence

• Database: Stored in a named volume or host path mapped to /app/music.db.
• Migrations: The backend uses Alembic. Schema changes are applied automatically on startup.

Local Development (Non-Docker)

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
   

   Access at http://localhost:5173.