Spotify History

Script to parse and display full Spotify listening history.

1. Install pyenv and poetry

2. Install package

    pyenv install $(cat .python-version)
    poetry install
   

1. Go to https://www.spotify.com/us/account/privacy/
2. Scroll down to Request Extended History and follow the steps to request your data.
3. Within a day (usually) Spotify will email a link to download a ZIP archive containing JSON files of your listening history.
4. Download and extract the ZIP file and copy its JSON files into the data/ directory at the project root.

Once you have downloaded your Spotify history, run poetry run spotify-history to generate the following tables:

• Top Songs table: shows song title, artist, total plays, and total listening time (minutes).
• Top Artists table: shows artist name, total plays, and total listening time (minutes).
• Top Albums table: shows album name, artist, total plays, and total listening time (minutes).
• Yearly summary table: a compact table showing total plays and total listening time per year.

You can also optionally generate cumulative or rolling plots to the plots/ directory to view listening history over time.

Run poetry run spotify-history --help to view all available flags, arguments, and filters. Major options:

• --top-songs, --top-artists, --top-albums: control how many items are shown in the corresponding table (and plots). All four tables are still produced; these flags only change the number of rows shown for each type. All tables and plots will default to top 10 items.
• --sort-by: (plays or minutes): determines the primary metric used to select and order top items and controls whether plots show cumulative plays or cumulative minutes. Default is number of plays.
• --artist and --year: filter the source plays to include only the provided artist or year (both filters can be combined).
• --plot-cumulative: when present, saves PNG cumulative plots into the plots/ subdirectory. These plots show the cumulative listening history over time for each top K item in each category (songs, artists, albums).
• --plot-rolling: when present, saves PNG rolling plots into the plots/ subdirectory. These plots show the rolling window averages over time for each top K item in each category.
• --rolling-window: change the rolling window average. Defaults to 30 days. Higher numbers will smooth out noise (good for longer timeframes) while smaller numbers will show more details (good for shorter timeframes)

• Show listening history for a specific artist and year and create cumulative plot:

poetry run spotify-history --artist "Radiohead" --year 2023 --plot-cumulative

• Show top 20 artists sorted by total listening minutes and create rolling plots:

poetry run spotify-history --top-artists 20 --sort-by minutes --plot-rolling --rolling-window 90

If there are any artists that you don't want included in the accumulated results, add the artist name to the IGNORED_ARTISTS list at the top of cli.py.