mirror of https://github.com/bnair123/MusicAnalyser.git synced 2026-02-25 11:46:07 +00:00

Files

bnair123 887e78bf47 Add skip tracking, compressed heatmap, listening log, docs, tests, and OpenAI support

Major changes:
- Add skip tracking: poll currently-playing every 15s, detect skips (<30s listened)
- Add listening-log and sessions API endpoints
- Fix ReccoBeats client to extract spotify_id from href response
- Compress heatmap from 24 hours to 6 x 4-hour blocks
- Add OpenAI support in narrative service (use max_completion_tokens for new models)
- Add ListeningLog component with timeline and list views
- Update all frontend components to use real data (album art, play counts)
- Add docker-compose external network (dockernet) support
- Add comprehensive documentation (API, DATA_MODEL, ARCHITECTURE, FRONTEND)
- Add unit tests for ingest and API endpoints

2025-12-30 00:15:01 +04:00

2.4 KiB

Raw Blame History

Architecture Overview

MusicAnalyser is a full-stack personal analytics platform designed to collect, store, and analyze music listening habits using the Spotify API and Google Gemini AI.

System Components

1. Backend (FastAPI)

API Layer: Handles requests from the frontend, manages the database, and triggers analysis.
Database: SQLite used for local storage of listening history, track metadata, and AI snapshots.
ORM: SQLAlchemy manages the data models and relationships.
Services:
- SpotifyClient: Handles OAuth2 flow and API requests.
- StatsService: Computes complex metrics (heatmaps, sessions, top tracks, hipster scores).
- NarrativeService: Interfaces with Google Gemini to generate text-based insights.
- IngestService: Manages the logic of fetching and deduplicating Spotify "recently played" data.

2. Background Worker

A standalone Python script (run_worker.py) that polls the Spotify API every 60 seconds.
Ensures a continuous record of listening history even when the dashboard is not open.

3. Frontend (React)

Framework: Vite + React.
Styling: Tailwind CSS for a modern, dark-themed dashboard.
Visualizations: Recharts for radar and heatmaps; Framer Motion for animations.
State: Managed via standard React hooks (useState, useEffect) and local storage for caching.

4. External Integrations

Spotify API: Primary data source for tracks, artists, and listening history.
ReccoBeats API: Used for fetching audio features (BPM, Energy, Mood) for tracks.
Genius API: Used for fetching song lyrics to provide deep content analysis.
Google Gemini: Large Language Model used to "roast" the user's taste and generate personas.

Data Flow

Ingestion: Background Worker → Spotify API → Database (PlayHistory).
Enrichment: Ingest Logic → ReccoBeats/Genius/Spotify → Database (Track/Artist).
Analysis: Frontend → Backend API → StatsService → NarrativeService (Gemini) → Database (Snapshot).
Visualization: Frontend ← Backend API ← Database (Snapshot/Log).

Deployment

Containerization: Both Backend and Frontend are containerized using Docker.
Docker Compose: Orchestrates the backend (including worker) and frontend (Nginx proxy) services.
CI/CD: GitHub Actions builds multi-arch images (amd64/arm64) and pushes to GHCR.

2.4 KiB Raw Blame History