# 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**: 
  - **Genres & Images** (via Spotify)
  - **Audio Features** (Energy, BPM, Mood via ReccoBeats)
  - **Lyrics & Metadata** (via Genius)
- **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**.
- **Genius API Token** (Optional, for lyrics).

### 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.

```bash
SPOTIFY_CLIENT_ID="your_client_id"
SPOTIFY_CLIENT_SECRET="your_client_secret"
SPOTIFY_REFRESH_TOKEN="your_refresh_token"
GEMINI_API_KEY="your_gemini_key"
GENIUS_ACCESS_TOKEN="your_genius_token"
```

### 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:
    ```bash
    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:
    ```bash
    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**:
    ```bash
    cd backend
    pip install -r requirements.txt
    python run_worker.py  # Starts ingestion
    uvicorn app.main:app --reload  # Starts API
    ```

2.  **Frontend**:
    ```bash
    cd frontend
    npm install
    npm run dev
    ```
    Access at `http://localhost:5173`.