Tourmaline
tourmaline Teal.fm scrobble analyser
Back to home

About Tourmaline

Privacy & data

No tracking No sign-in to browse No persistent server storage

Tourmaline analyses your listening history from your Teal.fm scrobbles. All fetching, analysis, and enrichment runs server-side. The server resolves your identity, fetches scrobbles from your PDS, computes the profile, and enriches top artists — then sends the results to your browser for display. No data is persisted between visits; the in-memory session cache is lost when the serverless function cold-starts.

The network requests made are:

  • Slingshot (slingshot.microcosm.blue) — resolves your AT Protocol handle to a DID and PDS URL. This is a standard identity lookup. No personally identifiable data beyond your handle is sent.
  • Your PDS — reads fm.teal.alpha.feed.play records from your Personal Data Server. Reading is unauthenticated. If you choose to share your personality profile to Bluesky, Tourmaline will use OAuth to publish the post and will also create a usage record in your repository via the click.croft.toolkit.use lexicon. This record contains the total number of scrobbles analysed and a timestamp.
  • MusicBrainz — enriches top artists with genre and tag data. Rate-limited to 1 request per second.
  • Last.fm — supplements artist data with listener counts, play counts, and images. Rate-limited to 5 requests per second.
  • Deezer — provides artist images as a fallback when Last.fm has none.
  • Bluesky CDN — loads your avatar from cdn.bsky.app.

Scrobbles are held in an in-memory session on the server for the duration of the analysis. This session expires after 10 minutes of inactivity and is never written to disk. No persistent database is used.

How it works

  1. 1
    Resolve identity

    Your handle or DID is resolved to a PDS URL via Slingshot.

  2. 2
    Fetch scrobbles

    fm.teal.alpha.feed.play records are fetched page by page from your PDS. Fetched in batches to stay within serverless function time limits.

  3. 3
    Analyse

    Scrobbles are aggregated into top artists, tracks, albums, daily counts, genre profiles, mood mapping, era preference, diversity scoring, and obscurity indexing. All date range presets are computed at once so switching is instant.

  4. 4
    Enrich

    Top artists are enriched with genre data from MusicBrainz, listener counts from Last.fm, and images from Deezer. This runs in batches on the server after the base profile is already computed.

What's analysed

  • Top artists, tracks, and albums
  • Genre profile (MusicBrainz + Last.fm tags)
  • Mood mapping (energetic, melancholic, etc.)
  • Listening timeline (365-day heatmap)
  • Era preference (decade distribution)
  • Diversity score (0–100)
  • Obscurity index (0–100)
  • Listener personality archetype

Not analysed: Private/hidden scrobbles. Only fm.teal.alpha.feed.play records visible on your PDS are read.

Licence

Tourmaline is free software released under the GNU Affero General Public License v3.0 (AGPL-3.0-only).

In short: you are free to use, modify, and redistribute this software, but any modified version you run as a network service must also be released under the same licence with its source code made available.

The full licence text is included in the repository.

Credits

Created by

Ewan Croft Author & maintainer
GitHub Support Website

Contributors

Contributions via GitHub are always welcome. The full contributor list is maintained there.

Dependencies