Metadata-Version: 2.4
Name: spotify-streamd
Version: 1.0.0
Summary: CLI toolkit for exploring and analyzing your Spotify listening data
Project-URL: Homepage, https://github.com/prabhask5/streamd
Project-URL: Repository, https://github.com/prabhask5/streamd
Project-URL: Issues, https://github.com/prabhask5/streamd/issues
Author: prabhask5
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: requests
Description-Content-Type: text/markdown

# 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](ARCHITECTURE.md) — 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](ARCHITECTURE.md#adding-a-new-subcommand) for how subcommands work.

## Install

Requires Python 3.10+.

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

# Or with pip
pip install spotify-streamd
```

To install from source:

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

## Setup

### 1. Configure credentials

```bash
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](https://www.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

```bash
streamd albums ~/path/to/spotify-export
```

## Usage

```bash
# 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:

```bash
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](LICENSE)
