Introduction
EchoStats is a self-hosted Spotify analytics platform that connects to your Spotify account, automatically syncs your listening history, and delivers 40+ pages of beautiful dashboards, charts, and insights about your music taste. Think of it as Spotify Wrapped — but year-round, running entirely on your own server.
Who is EchoStats for?
- Self-hosters who want full control over their data and infrastructure
- Privacy-conscious Spotify users who don’t want analytics data sent to third parties
- Music data enthusiasts who want deeper insights than Spotify provides natively
- Developers looking for a modern full-stack reference project (FastAPI + Next.js + MongoDB)
Key Features
🎛️ Analytics & Visualization
- 40+ Dashboard Pages — Stats, charts, heatmaps, radar charts, listening calendars, mood analysis, and more
- Listening Analytics — Top tracks, artists, genres, and albums with time-range filters (week / month / year / all-time)
- Music DNA — Audio feature radar showing danceability, energy, valence, acousticness, tempo, and more
- Artist Map — Explore connections between favorite artists with play-share distribution
- Taste Profile — Deep analysis of your listening patterns and preferences
- Year in Review — Spotify Wrapped-style annual summary generated from your data
🔄 Sync & Data
- Auto Sync — Background worker syncs your Spotify data every 15 minutes via ARQ cron
- Data Import — Import your full Spotify extended streaming history (JSON from privacy data export)
- Sync Job Tracking — View step-by-step sync progress with detailed API call history
- API Logs Dashboard — Monitor all Spotify API calls with status distribution and latency stats
🎵 Playback & Discovery
- Spotify Playback Control — Play, pause, skip, view queue, and switch devices from the dashboard
- Recommendations — Discover new music based on your listening patterns
- Browse — New releases, featured playlists, and categories from Spotify
🎨 Customization & UX
- 6 Themes + 8 Accent Colors — Dark, Light, Dim, Ocean, Midnight, Forest + custom color picker
- PWA — Install on any device (mobile and desktop), works offline
- Single-User Auto-Login — Auto-authenticates when only one user exists (ideal for self-hosting)
- Update Notifications — Dashboard banner when a new version is available on GitHub
🏠 Deployment
- Docker Compose — One-command deployment with all services included
- Helm Chart — Kubernetes deployment via OCI registry with full configurability
- Version Indicator — Deployed version shown in sidebar and API health endpoint
How It Works
- Authenticate — Connect your Spotify account via OAuth
- Sync — EchoStats automatically syncs your listening data every 15 minutes
- Explore — Browse 40+ dashboard pages of analytics, charts, and insights
- Import — Optionally import your full Spotify history from privacy data exports
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16 / React 19 / TypeScript | SSR dashboard with 42 pages |
| Styling | Tailwind CSS 4 / Framer Motion | 6 themes + spring animations |
| Charts | Recharts | Interactive data visualizations |
| Backend | Python 3.12 / FastAPI | REST API with 30+ endpoints |
| Database | MongoDB 7 / Beanie ODM | Document storage for analytics |
| Cache / Queue | Redis 7 / ARQ | Background sync + task queue |
| Container | Docker / Helm | Kubernetes-ready deployment |
| CI/CD | GitHub Actions | Automated testing + GHCR publishing |
Architecture Overview
EchoStats follows a modern microservices architecture with clear separation between the frontend, backend API, background workers, and data stores.
┌─────────────────────┐ ┌──────────────────────┐│ Next.js 16 (Web) │────▶│ FastAPI (API) ││ React 19 / TS │ │ Python 3.12 ││ Tailwind / Motion │ │ 38 REST endpoints ││ Port 3000 │ │ Port 8000 │└─────────────────────┘ └──────┬───────┬────────┘ │ │ ┌──────▼──┐ ┌─▼──────────┐ │ MongoDB │ │ Redis │ │ 7.x │ │ 7.x │ │ Beanie │ │ Cache+Queue │ └─────────┘ └──────┬──────┘ │ ┌──────▼──────┐ │ ARQ Worker │ │ Cron every │ │ 15 minutes │ └─────────────┘Data Flow
- Spotify OAuth → User authenticates with their Spotify account
- Initial Sync → The API triggers the first full data sync on login
- Background Worker → ARQ cron syncs recently played tracks every 15 minutes and refreshes analytics every 6 hours
- API Layer → FastAPI serves 38 endpoints covering auth, analytics, history, playlists, playback, and sync management
- Frontend → Next.js renders 40+ pages with interactive Recharts visualizations, Framer Motion animations, and responsive layouts
Key Design Decisions
- Self-hosted first — All data stays on your infrastructure. No third-party analytics or telemetry.
- Single-user optimized — Auto-login when one user exists, no registration flow needed.
- PWA-native — Installable on mobile and desktop with service worker caching for offline access.
- Encrypted tokens — Spotify API tokens are encrypted at rest using your
ENCRYPTION_KEY.
Environment Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| Docker | 24.x | Latest |
| Docker Compose | v2.x | Latest |
| RAM | 1 GB | 2 GB |
| Disk | 1 GB | 5 GB |
| Spotify Account | Free or Premium | Premium (for playback controls) |
You also need a Spotify Developer Application with a Client ID and Client Secret.
Quick Links
- Installation — Get EchoStats running in under 5 minutes with Docker Compose
- Configuration — Environment variables, Spotify app setup, and deployment options
- Dashboard Guide — Navigate the dashboard, keyboard shortcuts, and responsive layouts
- Analytics Guide — Understand the 40+ analytics pages and visualizations
- Importing History — Import your full Spotify extended streaming history
- API Authentication — JWT session cookies, OAuth flow, and dev login
- Troubleshooting — Solutions to common deployment and runtime issues
- FAQ — Answers to frequently asked questions
Getting Started
Head to the Installation guide to get EchoStats running in under 5 minutes.