lastfm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Last.fm

Setup

设置

bash

export LASTFM_API_KEY="your_api_key_here"

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).

export LASTFM_API_SECRET="your_api_secret" export LASTFM_SESSION_KEY="your_session_key"


在 https://www.last.fm/api/account/create 获取 API key（免费，需要 Last.fm 账户）。

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

可通过

LASTFM_USERNAME

环境变量配置。未设置时默认使用

<username>

。

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"

音乐发现——“什么与 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

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

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

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"

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

undefined

bash

undefined

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>

undefined

undefined

Reference Files

参考文件

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

```
references/auth-flow.md
```
— 写入操作认证（scrobble、love、now-playing）的完整配置说明。在尝试写入操作前请先阅读此文件。

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

音乐发现流水线——“帮我找点新的喜欢内容”

The core flow for turning liked tracks into recommendations:

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

For each artist, find similar artists via Last.fm's collaborative filtering:
bash
```
lastfm-cli artist similar "<artist>" --limit 5 --json
```
For each track, find similar tracks for more granular recommendations:
bash
```
lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
```
Cross-reference against what they've already scrobbled (recent-tracks) to filter out already-heard material.
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.

将喜欢的曲目转化为推荐的核心流程：

从 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

通过 Last.fm 的协同过滤为每位艺人查找相似艺人：
bash
```
lastfm-cli artist similar "<artist>" --limit 5 --json
```
为每首曲目查找相似曲目，以获得更细粒度的推荐：
bash
```
lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
```
与已经 scrobble 的内容（recent-tracks）进行交叉核对，过滤掉已经听过的内容。
与用户自己的收藏库（通过 Radarr/Sonarr/jellyfin 或 Spotify library）进行核对，区分收藏库中已有的内容和真正的新发现。

Using with --json for Machine Processing

使用 --json 进行机器处理

bash

undefined

bash

undefined

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}'

undefined

lastfm-cli tag top-tracks "electronic" --limit 10 --json | jq '.tracks.track[] | {name, artist: .artist.name, listeners}'

undefined

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
```
.

每次请求都需要 API key。 key 免费——请在 Last.fm API 账户页面获取。
速率限制约为持续每秒 5 个请求。 API 文档要求“保持合理”；如果持续在每秒内发起多个请求，账户可能会被暂停。请在循环中添加短暂延迟。
User-Agent header 很重要。 CLI 会发送
```
lastfm-cli/1.0 (hermes-agent)
```
。Last.fm 文档明确要求提供可识别的 User-Agent。
默认响应格式是 XML。 CLI 会请求
```
format=json
```
。如果不指定，响应将以 XML 格式返回。
艺人名称可能拼写错误。 在艺人相关命令中使用
```
--autocorrect
```
flag，让 Last.fm 自动纠正拼写错误。
写入操作需要完成认证设置。 scrobble、love 和 now-playing 需要完整的认证流程（token → session key）。只读端点不需要。
协同过滤图并不是社交关系。
```
artist.getSimilar
```
返回的是基于汇总收听模式的算法相似度，而不是人工策划的推荐。
scrobble 的时间戳采用 UNIX epoch seconds。 如果未提供，则使用当前时间。
recent-tracks 上的
--from
和
--to
接受 ISO 8601 日期字符串，例如
```
2026-05-27
```
。
周期值：
```
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

用户询问“某人最近在听什么？”
用户希望发现音乐：“帮我找一些与……相似的艺人。”
用户需要收听统计：按周期查询热门艺人、曲目和专辑
用户需要了解地域音乐趋势：“某个国家什么最流行？”
用户希望通过标签探索音乐类型
用户希望以编程方式 scrobble 或标记为 love 的曲目
任何有关音乐元数据、艺人信息或专辑曲目列表的问题

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`

脚本	用途	调用方式
`scripts/lastfm-cli`	此 skill 驱动的 CLI 工具：只读查询（user info/recent-tracks/top-artists/top-tracks/loved-tracks/friends/weekly-charts）、音乐发现（ `artist similar` 、 `track similar` ）、榜单和地域榜单、搜索、标签，以及在会话认证后执行 `scrobble` 、 `now-playing` 和 `love` 。对于上述所有 Last.fm 数据问题，运行此脚本；完整命令列表请参阅核心命令。	`scripts/lastfm-cli user top-artists <username> --period 7day --limit 10`
`scripts/test-lastfm.sh`	Shell 测试套件，无需网络调用即可覆盖 CLI 的参数处理和输出格式。修改 `scripts/lastfm-cli` 后或审计其行为变更时运行；CI 会通过 `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.

需将免费的 Last.fm API key 导出为
```
LASTFM_API_KEY
```
（在 https://www.last.fm/api/account/create 创建）；缺少该 key 时，每个请求都会失败。
仅写入操作需要将
```
LASTFM_API_SECRET
```
与通过一次性认证流程获得的 session key 一同导出，session key 使用
```
LASTFM_SESSION_KEY
```
表示。
PATH 中需要存在 Python 3——如果无法直接执行捆绑的工具，请使用
```
python3 scripts/lastfm-cli ...
```
；SKILL.md 中的示例假设
```
lastfm-cli
```
可在 PATH 中解析。
可选：使用
```
LASTFM_USERNAME
```
设置用户查询的默认用户；使用
```
jq
```
管道处理
```
--json
```
输出以执行结构化处理。

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.

只读端点仅需 API key；scrobble、now-playing 和 love 需要完整的 token → session-key 认证流程，否则会失败。
持续调用速率超过约每秒 5 个请求可能导致账户被暂停——请在循环中添加短暂延迟。
相似度端点使用基于汇总收听模式的算法协同过滤，并非社交关系或人工策划的推荐。
周期值固定为
```
overall
```
、
```
7day
```
、
```
1month
```
、
```
3month
```
、
```
6month
```
和
```
12month
```
；仅 recent-tracks 支持通过
```
--from
```
和
```
--to
```
查询任意日期范围。
如果不使用
```
--autocorrect
```
，拼错的艺人名称会返回空结果或错误结果。

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.

不要将此 skill 用于音乐播放控制（本地播放器、流媒体播放队列）、非 Last.fm 目录数据（MusicBrainz、Spotify 元数据），也不要将其作为歌词来源——该 API 仅覆盖收听历史、元数据、榜单、标签、相似度和 scrobbling。