streamd

A CLI toolkit for exploring and analyzing your Spotify listening data. Bring your own Spotify data export, and streamd enriches it with metadata from the Spotify API to surface insights about your listening habits.

Architecture overview — how the codebase is structured, rate limiting strategy, and how to add new subcommands.

Commands

albums

Ranks every album you've listened to since a cutoff date by how many unique songs you played from it. Cross-references your streaming history with Spotify's API to map tracks to albums, then aggregates the results.

Albums found: 142

Rank | Unique songs | Total plays | Album — Album artist
------------------------------------------------------------------------------------------
   1 |          14  |         87  | In Rainbows — Radiohead
   2 |          12  |         63  | Blonde — Frank Ocean
   3 |          11  |         45  | Igor — Tyler, The Creator

More commands are planned — streamd is designed to be extended with new subcommands that build on top of your Spotify export and the API. See the architecture doc for how subcommands work.

Install

Requires Python 3.10+.

# Recommended — installs in an isolated environment
pipx install spotify-streamd

# Or with pip
pip install spotify-streamd

To install from source:

git clone https://github.com/prabhask5/spotify-streamd.git
cd spotify-streamd
pip install -e .

Setup

1. Configure credentials

streamd setup

This walks you through creating a Spotify developer app and saves your credentials to ~/.streamd/.env. You only need to do this once. The setup command gives you the exact steps — create an app at the Spotify developer dashboard, copy the Client ID and Secret, paste them in.

Your app will be in development mode, which has a rate limit based on a rolling 30-second window. This is fine for personal use — streamd's caching means you only hit the API once per unique track, ever.

2. Get your Spotify data export

Spotify requires you to request your data through their website:

1. Go to spotify.com/account/privacy
2. Scroll to Download your data
3. Request your Extended streaming history (the basic "Account data" package works too, but has less history)
4. Wait for the email (usually takes a few days)
5. Download and unzip the archive — you'll get a folder with StreamingHistory_music_*.json files

3. Run

streamd albums ~/path/to/spotify-export

Usage

# Basic — rank albums from plays since Jan 1, 2026
streamd albums ~/path/to/spotify-export

# Custom cutoff date
streamd albums ~/path/to/spotify-export --since 2025-06-01

# Adjust minimum play duration (default: 20s) and output file
streamd albums ~/path/to/spotify-export --min-ms 30000 --output results.txt

# Verbose mode — see API calls, cache hits, rate limiter activity
streamd -v albums ~/path/to/spotify-export

# Custom log file location
streamd --log-file ./debug.log albums ~/path/to/spotify-export

Options

Flag	Description	Default
-v, --verbose	Print debug log lines to stderr	off
--log-file PATH	Log file location	~/.streamd/run.log

albums subcommand

Argument	Description	Default
folder	Path to unzipped Spotify export folder	(required)
--since DATE	Only count plays after this date (YYYY-MM-DD)	2026-01-01
--min-ms MS	Ignore plays shorter than this (milliseconds)	20000
--output FILE	Output file path	albums_since_output.txt

Rate limits and caching

Spotify's API rate limit is a rolling 30-second window. In development mode (the only option for personal apps), the limit is relatively low — you'll hit 429s if you blast too many requests at once.

streamd handles this automatically:

• Caching: Every track-to-album lookup is cached in ~/.streamd/cache/track_albums.json. Once a track is looked up, it never needs to be fetched again. After the cache is populated, runs are instant with zero API calls.
• Partial saves: If you get rate-limited mid-run, all progress so far is saved. The next run picks up where it left off.
• Adaptive rate limiting: Starts conservative (2 req/s, 1 concurrent request) and ramps up. On any 429 response, it backs off automatically and respects the Retry-After header.

A first run with a large export (2,000–5,000 unique tracks) may take a couple of runs to fully populate the cache, depending on how aggressively Spotify throttles you. After that, it's free.

Advanced tuning

These optional environment variables can be set to tweak API behavior:

SPOTIFY_WORKERS=2 SPOTIFY_RPS=1 streamd albums ~/path/to/export

Variable	Description	Default
SPOTIFY_WORKERS	Max concurrent API requests	4
SPOTIFY_RPS	Initial requests/sec (adapts automatically)	2
SPOTIFY_MAX_RETRY_AFTER	Abort if Retry-After exceeds this (seconds)	3600

File locations

Path	Purpose
~/.streamd/.env	Spotify API credentials (created by streamd setup)
~/.streamd/cache/track_albums.json	Track-to-album lookup cache
~/.streamd/run.log	Debug log (last run)

License

MIT