Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Watches your currently playing Spotify track. This is on a per-user basis since it uses the Spotify Web API, so you don't need to run it on all your machines if you don't want the redundancy.

This watcher is currently in a early stage of development, please submit PRs if you find bugs!


Step 0: Create Spotify Web API token

Go to Spotify Developer Dashboard and create a new application.

In the app settings, add http://localhost:8088 in the Redirect URIs section.

Step 1: Install package (using poetry)

Requirements: Requires that you have poetry installed.

First install the package and its dependencies:

poetry install

First run (generates empty config that you need to fill out):

poetry run aw-watcher-spotify

Step 1: Install package (without poetry, using only pip)

Install the requirements:

pip install .

First run (generates empty config that you need to fill out):

python aw-watcher-spotify/

Step 2: Enter credentials

If this is the first time you run it on your machine, it will give you an error, this is normal. Just fill in the config file (the directory is referenced in the error).

Run the script again and... You're done! Try playing a song on Spotify on any of your devices and it should start logging (provided they are not in offline mode).


Even without using this watcher, you can get a full export of the last year of listening history by requesting an export directly from Spotify here:

The export contains, among other things:

  • Streaming history for the past year
  • Playlists
  • Search queries
  • A list of items saved in your library
  • User data
  • Inferences

(thanks @oreHGA for the tip!)