Private Spotify listening analytics

Problem

Spotify’s extended history contains years of detailed listening events, but the raw JSON is difficult to explore and includes fields that should not be exposed to third-party analytics services. The project turns a local export into an understandable listening profile while keeping files, derived metrics, and dashboards on the user’s machine.

Approach

The pipeline separates loading, cleaning, analysis, visualization, reporting, and dashboard generation into reusable modules. It reconstructs listening sessions, aggregates behavior across time and content, measures replay, completion, skipping, concentration, and exploration, and generates both serious metrics and lightweight personal awards. Users can run the CLI on a folder or upload exports to a local FastAPI application.

Technical implementation

Pandas normalizes multiple export files and removes usernames, IP addresses, and user-agent fields from cleaned output by default. Configurable time zones and inactivity gaps make temporal and session metrics reproducible. Matplotlib creates static charts, while a generated HTML dashboard provides sorting, pagination, date-range search, an offline country map, report previews, and links to detailed CSV tables. Each web run is isolated under a unique local directory and requires no Spotify API or external network call.

streams = load_history(input_path)
cleaned = clean_streams(streams, timezone="Europe/Paris")
sessions = assign_sessions(cleaned, gap_minutes=30)
tables = analyze_listening(cleaned, sessions)
build_dashboard(tables, output_dir)