Frequently Asked Questions

General

What is Harmony?

Harmony is an open-source music analytics platform that ingests your Spotify listening data and presents rich insights via an elegant web interface.

Is it free?

Yes. Harmony is licensed under GPL-3.0 and free for personal and commercial use. Self-hosting costs (server, database) are your responsibility.

Which browsers are supported?

All latest versions of Chrome, Firefox, Safari, and Edge are supported.

Can I use Harmony if I don't have a Spotify Premium account?

Yes. Harmony works seamlessly with both Spotify Free and Premium accounts, there are no feature restrictions based on your subscription.

Usage

Why are some charts empty?

Currently, a background cron job runs at the beginning of each week and back-fills data for two of the headline charts. The remaining visualisations rely on either:

1. Package uploads - make sure you have imported your latest listening archive via the Package Upload page.
2. Sufficient history - some stats require several weeks of data before trends appear.

If your charts are still blank after a week and you have uploaded the package, open an issue.

How often is my data updated?

Harmony automatically refreshes data from the Spotify Web API every hour for the Top Artists, Top Tracks, and Recently Played sections. For richer metrics—such as long-term rankings and historical charts—you can upload your Spotify data package once per day.

How do I share my profile securely?

Use the Share Link feature. Links contain signed, time-limited JWTs. You can revoke links at any time from Settings → Sharing.

Data & Privacy

What scopes does Harmony request from Spotify?

See Spotify Account Permissions for the full list and rationale.

Where is my data stored?

Your listening history live inside a secure, central PostgreSQL database managed by Harmony. No third-party analytics services receive your data, the only external system involved is the database itself.

Troubleshooting Cheat-Sheet