scrobbles

Fetch, export, and visualize Last.fm listening data — plus create Spotify playlists from your top albums.

Setup

Prerequisites

• Python 3.12+
• uv (recommended) or pip

Install

pip install scrobbles
# or
uv add scrobbles

From source

git clone https://github.com/saforem2/scrobbles.git
cd lastfm
uv sync

Environment Variables

Last.fm

Get API credentials at https://www.last.fm/api/account.

export LASTFM_API_KEY="..."
export LASTFM_API_SECRET="..."
export LASTFM_USERNAME="..."
export LASTFM_PASSWORD="..."

Spotify (optional — only needed for playlist creation)

1. Create an app at https://developer.spotify.com/dashboard
2. Add http://127.0.0.1:8888/callback as a Redirect URI in your app settings
3. Export your credentials:

export SPOTIFY_CLIENT_ID="..."       # or SPOTIPY_CLIENT_ID
export SPOTIFY_CLIENT_SECRET="..."   # or SPOTIPY_CLIENT_SECRET
export SPOTIPY_REDIRECT_URI="http://127.0.0.1:8888/callback"

Either SPOTIFY_* or SPOTIPY_* naming works — the library maps them automatically.

Usage

CLI

# Via entry point (after install)
scrobbles top-albums overall --limit 25
scrobbles top-albums 2024
scrobbles dashboard

# Via main.py (development)
uv run python main.py top-albums overall --limit 25
uv run python main.py top-albums 2024
uv run python main.py top-albums last_month

# Export top albums to JSON
uv run python main.py dump-albums 2024 --limit 100

# Generate the HTML dashboard from existing JSON files
uv run python main.py dashboard

# Create Spotify playlists from all top100-YYYY.json files
uv run python main.py spotify-playlists --dry-run
uv run python main.py spotify-playlists --skip 2020 2021

Python API

import scrobbles

# Recent tracks & now playing
scrobbles.get_recent_tracks("username", 10)
print(scrobbles.get_now_playing("username"))

# Top albums — predefined periods
scrobbles.print_top_albums("username", period="7day", limit=20)

# Top albums — arbitrary date ranges
scrobbles.print_top_albums("username", period="2024")       # full year
scrobbles.print_top_albums("username", period="2024-06")    # single month
scrobbles.print_top_albums("username", period="last_week")

# Export to JSON
scrobbles.dump_top_albums("username", period="2024", limit=100)

# Generate interactive HTML dashboard
from scrobbles.albums import build_dashboard
build_dashboard()  # reads data/albums/top100-*.json → data/albums/index.html

# Spotify: create a playlist from any album list
from scrobbles.spotify import create_playlist_from_albums
albums = [{"artist": "Radiohead", "album": "OK Computer", "plays": 50}]
create_playlist_from_albums(albums, "My Playlist", dry_run=True)

# Spotify: bulk-create yearly playlists
from scrobbles.spotify import create_all_playlists
create_all_playlists(dry_run=True)

Supported Period Strings

Project Structure

lastfm/
├── src/scrobbles/
│   ├── __init__.py      # Network setup, track utils, re-exports
│   ├── albums.py        # Top albums: fetch, format, export, dashboard
│   ├── cli.py           # CLI entry point
│   └── spotify.py       # Spotify playlist creation
├── data/albums/         # Generated JSON + HTML dashboard
│   ├── top100-YYYY.json
│   └── index.html
├── main.py              # Thin shim (calls scrobbles.cli:main)
├── pyproject.toml
└── README.md

Publishing

# Bump version
uv version --bump patch

# Build
uv build

# Publish to PyPI
uv publish