lastfm git:20260826.ff1dab9A

Immutable. This exact content is served forever at /api/v1/blob/0e36a3d22eeb364f.

---
name: lastfm
description: 'Interact with the Last.fm music data API: lookup user listening history,
  get artist/album/track metadata, discover similar music via collaborative filtering,
  explore global and per-country charts, search by artist/album/track, manage tags,
  and scrobble listening events. Use when the user asks about music data, listening
  statistics, music recommendations, similar artists, charts, or wants to scrobble
  or love tracks.'
license: MIT
compatibility: Requires a Last.fm API key in the LASTFM_API_KEY env var. For write
  operations (scrobble, love, now-playing), also needs LASTFM_API_SECRET and LASTFM_SESSION_KEY.
  The `lastfm-cli` CLI tool must be on PATH.
metadata:
  tags: music, lastfm, scrobbling, api-client, music-discovery
  source: https://www.last.fm/api
---

# Last.fm

## Setup

```bash
export LASTFM_API_KEY="your_api_key_here"
# For write operations only:
export LASTFM_API_SECRET="your_api_secret"
export LASTFM_SESSION_KEY="your_session_key"
```

Get an API key at https://www.last.fm/api/account/create (free, requires a Last.fm account).

## Essential Commands

### User queries — "what am I listening to"

Configurable via `LASTFM_USERNAME` env var. Defaults to `<username>` if unset.

```bash
lastfm-cli user info <username>                      # Profile + stats
lastfm-cli user recent-tracks <username> --limit 10   # Recent listening
lastfm-cli user top-artists <username> --period 7day  # Weekly top artists
lastfm-cli user top-tracks <username> --period overall # All-time faves
lastfm-cli user loved-tracks <username>               # Loved tracks
lastfm-cli user friends <username>                    # Social graph
lastfm-cli user weekly-charts <username>              # Available chart periods
```

### Music Discovery — "what's similar to X"

```bash
lastfm-cli artist similar <artist> --limit 10         # Taste graph neighbors
lastfm-cli artist info <artist>                       # Bio, stats, tags
lastfm-cli artist top-tracks <artist>                 # Their most popular
lastfm-cli track similar <artist> "<track>"           # Track-level similarity
lastfm-cli album info <artist> "<album>"              # Tracklist, metadata
lastfm-cli tag top-artists <tag>                      # Genre browsing
```

### Charts — "what's popular"

```bash
lastfm-cli chart top-artists --limit 20               # Global
lastfm-cli geo top-artists "Japan" --limit 20         # Per-country
lastfm-cli geo top-tracks "Germany" --limit 20
lastfm-cli tag top-tracks "electronic" --limit 15     # By genre tag
```

### Search — "find that thing"

```bash
lastfm-cli artist search "Radiohead"                  # Find by name
lastfm-cli album search "OK Computer"                 # Find albums
lastfm-cli track search "Karma Police"                # Find tracks
```

### Write operations (require session auth)

```bash
lastfm-cli track scrobble "Artist" "Song" --album "Album"
lastfm-cli track now-playing "Artist" "Song"
lastfm-cli track love "Artist" "Song"
```

### Auth flow (one-time setup)

```bash
# 1. Get a token
lastfm-cli auth get-token

# 2. User visits: https://www.last.fm/api/auth/?api_key=KEY&token=TOKEN

# 3. Exchange for session key
lastfm-cli auth get-session <token>
# → Set export LASTFM_SESSION_KEY=<key>
```

## Reference Files

- `references/auth-flow.md` — Full walkthrough for setting up write operation auth (scrobble, love, now-playing). Read this before attempting write operations.

## Music Discovery Pipeline — "find me new stuff I'll like"

The core flow for turning liked tracks into recommendations:

1. **Get user's top artists/tracks** from Last.fm:
   ```bash
   lastfm-cli user top-artists <username> --period 1month --limit 5 --json
   lastfm-cli user top-tracks <username> --period 1month --limit 10 --json
   lastfm-cli user loved-tracks <username> --json
   ```

2. **For each artist, find similar artists** via Last.fm's collaborative filtering:
   ```bash
   lastfm-cli artist similar "<artist>" --limit 5 --json
   ```

3. **For each track, find similar tracks** for more granular recommendations:
   ```bash
   lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
   ```

4. **Cross-reference** against what they've already scrobbled (recent-tracks) to filter out already-heard material.

5. **Check against the user's own collection** (via Radarr/Sonarr/jellyfin or Spotify library) to see what's already in the library vs genuinely new discovery.

## Using with --json for Machine Processing

```bash
# Pipe to jq for structured queries
lastfm-cli artist similar "Radiohead" --limit 5 --json | jq '.similarartists.artist[] | {name, match}'

# Get a user's all-time top artists with playcounts
lastfm-cli user top-artists <username> --period overall --limit 3 --json | jq '.topartists.artist[] | {name, playcount}'

# Find most popular tracks by a genre
lastfm-cli tag top-tracks "electronic" --limit 10 --json | jq '.tracks.track[] | {name, artist: .artist.name, listeners}'
```

## Known Gotchas

- **API key required for EVERY request.** The key is free — get one at the Last.fm API account page.
- **Rate limit is ~5 req/sec sustained.** The API docs say "be reasonable" — if you're making several calls per second continuously, your account may be suspended. Add small delays in loops.
- **User-Agent header matters.** The CLI sends `lastfm-cli/1.0 (hermes-agent)`. Last.fm's docs explicitly ask for an identifiable User-Agent.
- **XML is the default response format.** The CLI requests `format=json`. Without it, responses come back as XML.
- **Artist names can be misspelled.** Use `--autocorrect` flag on artist commands to let Last.fm correct misspellings.
- **Write operations need auth setup.** scrobble, love, and now-playing require a full auth flow (token → session key). Read-only endpoints don't.
- **The collaborative filtering graph is NOT social.** `artist.getSimilar` returns algorithmic similarity based on aggregate listening patterns, not human-curated recommendations.
- **Timestamps for scrobbles** are UNIX epoch seconds. If omitted, uses current time.
- **`--from` and `--to` on recent-tracks** accept ISO 8601 date strings (e.g., `2026-05-27`).
- **Period values**: `overall`, `7day`, `1month`, `3month`, `6month`, `12month`.

## When to Reach for This Tool

- User asks "what's [person] listening to lately?"
- User wants music discovery: "find me artists similar to..."
- User wants listening statistics: top artists, tracks, albums by period
- User wants geographic music trends: "what's popular in [country]"
- User wants genre exploration via tags
- User wants to scrobble or love tracks programmatically
- Any question about music metadata, artist info, album tracklists

## Available Scripts

| Script | Purpose | Invocation |
|---|---|---|
| `scripts/lastfm-cli` | The CLI tool this skill drives: read-only queries (user info/recent-tracks/top-artists/top-tracks/loved-tracks/friends/weekly-charts), discovery (`artist similar`, `track similar`), charts and geo charts, search, tags, and — with session auth — `scrobble`, `now-playing`, and `love`. Run it for every Last.fm data question above; see Essential Commands for the full command surface. | `scripts/lastfm-cli user top-artists <username> --period 7day --limit 10` |
| `scripts/test-lastfm.sh` | Shell test suite covering the CLI's argument handling and output formatting without network calls. Run it after modifying `scripts/lastfm-cli` or when auditing a change to its behavior; CI runs it via `scripts/check-skill-tests.py`. | `bash scripts/test-lastfm.sh` |

## Prerequisites

- A free Last.fm API key exported as `LASTFM_API_KEY` (create one at https://www.last.fm/api/account/create); every request fails without it.
- For write operations only: `LASTFM_API_SECRET` plus a session key from the one-time auth flow in `references/auth-flow.md`, exported as `LASTFM_SESSION_KEY`.
- Python 3 on PATH — invoke the bundled tool as `python3 scripts/lastfm-cli ...` if it is not executable directly; the SKILL.md examples assume `lastfm-cli` resolves on PATH.
- Optional: `LASTFM_USERNAME` to set the default user for user queries; `jq` when piping `--json` output for structured processing.

## Limitations

- Read-only endpoints need only the API key; scrobble, now-playing, and love require the full token → session-key auth flow and will fail without it.
- Sustained call rates above ~5 req/sec risk account suspension — add small delays in loops.
- Similarity endpoints are algorithmic collaborative filtering over aggregate listening patterns, not social or human-curated recommendations.
- Period values are fixed to `overall`, `7day`, `1month`, `3month`, `6month`, and `12month`; arbitrary date ranges are only available via `--from`/`--to` on recent-tracks.
- Misspelled artist names return empty or wrong results unless `--autocorrect` is used.

## When not to use

Do not use this skill for music playback control (local players, streaming queues), for non-Last.fm catalog data (MusicBrainz, Spotify metadata), or as a lyrics source — the API covers listening history, metadata, charts, tags, similarity, and scrobbling only.