Soundings

Soundings is a static listening atlas that reads my last.fm scrobble history and turns it into favourites, patterns, records, discoveries, and a searchable library. The name is a Moby-Dick reference: sailors take soundings to measure the depth of the water beneath the ship, and this project takes soundings of my listening history. A scheduled GitHub Action pulls scrobbles from the last.fm API, stores them as a gzipped JSONL archive, and generates the statistics, catalogue, and artwork metadata consumed by the page. The browser never calls last.fm.

The deployed page lives at https://tiagojct.eu/soundings/.

Setup

To run your own copy:

1. Fork this repository.
2. Get a last.fm API key at https://www.last.fm/api/account/create.
3. In the fork, open Settings, Secrets and variables, Actions. Add a repository secret named LASTFM_API_KEY with the API key as its value.
4. Switch to the Variables tab in the same place and add a repository variable named LASTFM_USER with your last.fm username. If you skip this, the workflow falls back to tiagojct.
5. Under Settings, Pages, set the source to the main branch and the /docs folder.
6. Trigger the "Update soundings data" workflow once from the Actions tab. The first run pulls the full history and may take a few minutes.

After that, the workflow runs daily at 03:00 UTC (about 04:00 in Lisbon during summer time) and commits any new data to main.

Local development

Requires Python 3.11.

cp .env.example .env
# Paste your LASTFM_API_KEY into .env
python3.11 -m venv .venv
.venv/bin/pip install -r scripts/requirements.txt
.venv/bin/python scripts/fetch.py
.venv/bin/python scripts/aggregate.py
.venv/bin/python scripts/enrich.py
cp data/{stats,images,catalog}.json docs/
.venv/bin/python -m http.server --directory docs 8000

Open http://127.0.0.1:8000/ to view the page. Re-run the pipeline whenever you want to refresh, then re-copy the generated JSON files into docs/.

Discovery caveat

The discovery section counts an artist as new in the month they first appear in the last.fm archive. That is not always when I first heard them. Anyone I was already listening to before my scrobbling history begins shows up as new in the earliest month, and an artist I had not played for years before re-discovering them will only ever look "new" once.

License

MIT.