lastfm

Last.fm

セットアップ

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"

https://www.last.fm/api/account/create で API キーを取得します（無料ですが、Last.fm アカウントが必要です）。

基本的なコマンド

ユーザーへの問い合わせ — 「今、何を聴いていますか？」

LASTFM_USERNAME 環境変数で設定できます。設定されていない場合は、<username> がデフォルトになります。

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

音楽の発見 — 「X に似た音楽は？」

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

チャート — 「何が人気ですか？」

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

検索 — 「あれを探して」

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

書き込み操作（セッション認証が必要です）

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

認証フロー（初回のみ設定）

# 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>

リファレンスファイル

• references/auth-flow.md — 書き込み操作の認証（scrobble、love、now-playing）を設定するための詳細な手順です。書き込み操作を行う前にお読みください。

音楽発見のパイプライン — 「気に入りそうな新しい音楽を見つけて」

お気に入りのトラックからおすすめを見つける基本的な流れです。

1. Last.fm からユーザーのトップアーティスト／トラックを取得します。

   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. Last.fm の協調フィルタリングを使って、各アーティストに似たアーティストを探します。

   lastfm-cli artist similar "<artist>" --limit 5 --json
   

3. より詳細なおすすめを得るため、各トラックに似たトラックを探します。

   lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
   

4. 最近 scrobble したトラックと照合し、すでに聴いた曲を除外します。

5. ユーザー自身のコレクション（Radarr／Sonarr／jellyfin または Spotify のライブラリ経由）と照合し、すでにライブラリにある曲と、実際に新たに発見した曲を確認します。

--json を使った機械処理

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

既知の注意点

• すべてのリクエストで API キーが必要です。 キーは無料です。Last.fm API のアカウントページから取得してください。
• 継続的なレート制限は約 5 リクエスト／秒です。 API ドキュメントには「節度を持って利用する」と記載されています。毎秒数回の呼び出しを継続すると、アカウントが停止される可能性があります。ループ内では短い待機時間を設けてください。
• User-Agent ヘッダーは重要です。 CLI は lastfm-cli/1.0 (hermes-agent) を送信します。Last.fm のドキュメントでは、識別可能な User-Agent を明示的に求めています。
• デフォルトのレスポンス形式は XML です。 CLI は format=json をリクエストします。これがない場合、レスポンスは XML で返されます。
• アーティスト名のスペルが間違っていることがあります。 Last.fm に誤字を修正させるには、アーティスト関連のコマンドで --autocorrect フラグを使用してください。
• 書き込み操作には認証設定が必要です。 scrobble、love、now-playing には完全な認証フロー（トークン → セッションキー）が必要です。読み取り専用のエンドポイントには必要ありません。
• 協調フィルタリングのグラフはソーシャルなものではありません。 artist.getSimilar が返すのは、ユーザー全体のリスニング傾向に基づくアルゴリズム上の類似度であり、人が選んだおすすめではありません。
• scrobble のタイムスタンプは UNIX エポック秒です。省略すると現在時刻が使用されます。
• recent-tracks の --from と --to には、ISO 8601 形式の日付文字列（例：2026-05-27）を指定できます。
• 期間の値：overall、7day、1month、3month、6month、12month。

このツールを使う場面

• ユーザーから「最近、[人名] は何を聴いている？」と尋ねられたとき
• 音楽を探したいとき：「〜に似たアーティストを見つけて」
• リスニング統計（期間別のトップアーティスト、トラック、アルバム）を知りたいとき
• 地域の音楽トレンドを知りたいとき：「[国名] では何が人気？」
• タグを使ってジャンルを探したいとき
• プログラムからトラックを scrobble または love したいとき
• 音楽のメタデータ、アーティスト情報、アルバムのトラックリストについて質問されたとき

利用可能なスクリプト

スクリプト	用途	実行方法
scripts/lastfm-cli	このスキルが使用する CLI ツールです。読み取り専用のクエリ（ユーザー情報／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	ネットワークに接続せず、CLI の引数処理と出力形式を検証するシェルテストスイートです。scripts/lastfm-cli を変更した後、または動作の変更を監査する際に実行してください。CI では scripts/check-skill-tests.py を使って実行されます。	bash scripts/test-lastfm.sh

前提条件

• 無料の Last.fm API キーを LASTFM_API_KEY としてエクスポートします（https://www.last.fm/api/account/create で作成できます）。キーがないと、すべてのリクエストが失敗します。
• 書き込み操作の場合のみ：LASTFM_API_SECRET と、references/auth-flow.md に記載されている一度限りの認証フローで取得したセッションキーを LASTFM_SESSION_KEY としてエクスポートします。
• PATH 上に Python 3 が必要です。バンドルされたツールを直接実行できない場合は、python3 scripts/lastfm-cli ... を実行します。SKILL.md の例では、lastfm-cli が PATH 上で解決されることを前提としています。
• 任意：ユーザーに関するクエリのデフォルトユーザーを設定するには LASTFM_USERNAME を使用します。構造化処理のために --json の出力をパイプで渡す場合は jq を使用します。

制限事項

• 読み取り専用のエンドポイントには API キーだけが必要です。スカrobble、再生中、love の各機能には、トークンからセッションキーを取得する認証フロー全体が必要で、認証情報がない場合は失敗します。
• 継続的に約 5 req/sec を超える頻度で呼び出すと、アカウントが停止されるおそれがあります。ループ内では短い遅延を入れてください。
• 類似性エンドポイントは、集計されたリスニングパターンに基づくアルゴリズムによる協調フィルタリングを使用しており、ソーシャル機能や人手で選曲されたおすすめではありません。
• 期間の値は overall、7day、1month、3month、6month、12month に固定されています。任意の日付範囲を指定できるのは、recent-tracks で --from／--to を使用する場合のみです。
• アーティスト名のスペルを間違えると、--autocorrect を使用しない限り、結果が空になったり誤ったりします。

使用しない場合

音楽の再生操作（ローカルプレーヤー、ストリーミングキュー）、Last.fm 以外のカタログデータ（MusicBrainz、Spotify のメタデータ）、または歌詞の取得には、このスキルを使用しないでください。この API が扱うのは、リスニング履歴、メタデータ、チャート、タグ、類似性、スカrobble のみです。