Spotify

Hermes は Spotify を直接操作できます。再生、キュー、検索、プレイリスト、保存済みのトラックやアルバム、再生履歴まで、Spotify 公式の Web API と PKCE OAuth を使って扱えます。トークンは ~/.hermes/auth.json に保存され、401 が返ったときは自動で更新されます。ログインは端末ごとに一度だけで済みます（リフレッシュトークンは 6 か月ほどで期限切れになるので、そのときは hermes auth spotify を実行し直してください）。

Hermes に組み込みの OAuth 連携（Google、GitHub Copilot、Codex）とは違い、Spotify では利用者一人ひとりが自分用の小さな開発者アプリを登録する必要があります。Spotify は、誰でも使える公開 OAuth アプリを第三者が配布することを認めていないためです。作業は 2 分ほどで、hermes auth spotify が手順を案内してくれます。

事前に必要なもの

• Spotify のアカウント。検索、プレイリスト、ライブラリ、履歴のツールは 無料プラン でも動きます。再生の操作（再生、一時停止、スキップ、シーク、音量、キューへの追加、再生機器の切り替え）には Premium が必要です。
• Hermes Agent がインストールされ、動いていること。
• 再生系のツールを使うなら、動作中の Spotify Connect 機器。Web API が操作する相手が要るので、スマートフォン、パソコン、Web プレーヤー、スピーカーのどれかで Spotify アプリを開いておきます。何も動いていないと「no active device」というメッセージ付きの 403 Forbidden が返ります。どれか一台で Spotify を開いてから、もう一度試してください。

設定

一度で済ませる: hermes tools または初回設定

いちばん速い道です。次を実行します。

hermes tools

🎵 Spotify までスクロールし、スペースキーでオンに切り替えて、s で保存します。同じ切り替えは初回の hermes setup / hermes setup tools の流れの中にもあります。Spotify は任意で有効にするものなので、そこで有効にしても hermes tools と同じ、プロバイダーに合わせた設定が走ります。

Hermes はそのまま OAuth の手順に入ります。Spotify アプリをまだ持っていない場合は、その場で作成手順を案内してくれます。終わったときには、ツール群の有効化と認証の両方が一度に済んでいます。

手順を分けて進めたい場合（あるいは後から認証をやり直す場合）は、次の 2 段階の流れを使ってください。

2 段階の流れ

1. ツール群を有効にする

hermes tools

🎵 Spotify をオンにして保存し、その場でウィザードが開いたら Ctrl+C で閉じます。ツール群は有効なままで、認証だけが後回しになります。

2. ログインウィザードを実行する

hermes auth spotify

7 つの Spotify ツールは、手順 1 を済ませて初めてエージェントのツール群に現れます。既定ではオフなので、使わない人が API 呼び出しのたびに余分なツール定義を送らずに済みます。

HERMES_SPOTIFY_CLIENT_ID が設定されていない場合、Hermes がアプリ登録をその場で案内します。

1. ブラウザーで https://developer.spotify.com/dashboard を開きます
2. Spotify の「Create app」フォームに貼り付ける値をそのまま表示します
3. 受け取った Client ID の入力を求めます
4. それを ~/.hermes/.env に保存し、次回からこの手順を飛ばせるようにします
5. そのまま OAuth の同意画面へ進みます

承認すると、トークンは ~/.hermes/auth.json の providers.spotify の下に書き込まれます。推論プロバイダーの設定は変わりません。Spotify の認証は、使っている LLM プロバイダーとは独立しています。

Spotify アプリを作る（ウィザードが尋ねる内容）

ダッシュボードが開いたら Create app をクリックし、次のように入力します。

規約に同意して Save をクリックします。次のページで Settings を開き、Client ID をコピーして Hermes の入力欄に貼り付けます。Hermes が必要とする値はこれだけです。PKCE ではクライアントシークレットを使いません。

SSH 越し・画面のない環境で実行する

SSH_CLIENT または SSH_TTY が設定されている場合、Hermes はウィザードでも OAuth の段階でもブラウザーの自動起動を行いません。Hermes が表示するダッシュボードの URL と認可 URL をコピーして、手元の端末のブラウザーで開けば、あとは同じように進められます。ローカルの HTTP 受け口はリモート側のホストのポート 43827 で動いたままです。手元のブラウザーからリモートのループバックへは、SSH のローカル転送なしには届きません。

ssh -N -L 43827:127.0.0.1:43827 user@remote-host

踏み台やバスティオン経由の構成、その他の落とし穴（mosh、tmux、ポートの衝突）については OAuth over SSH / Remote Hosts を参照してください。

確認する

hermes auth status spotify

トークンがあるかどうかと、アクセストークンの期限を表示します。更新は自動です。Spotify API の呼び出しが 401 を返すと、クライアントがリフレッシュトークンを交換して一度だけやり直します。リフレッシュトークンは Hermes を再起動しても残るので、Spotify のアカウント設定でアプリの許可を取り消したり、hermes auth logout spotify を実行したりしない限り、認証をやり直す必要はありません。

使ってみる

ログインすると、エージェントは 7 つの Spotify ツールを使えるようになります。話しかけるのはふだんの言葉で構いません。エージェントが適切なツールと操作を選びます。より良い動きのために、エージェントは定番の使い方（検索は一度にまとめて再生へつなぐ、get_state を先回りして呼ばない場面など）を教える補助スキルを読み込みます。

> play some miles davis
> what am I listening to
> add this track to my Late Night Jazz playlist
> skip to the next song
> make a new playlist called "Focus 2026" and add the last three songs I played
> which of my saved albums are by Radiohead
> search for acoustic covers of Blackbird
> transfer playback to my kitchen speaker

ツール早見表

再生状態を変えるツールはどれも、機器を指定する device_id を任意で受け取ります。省略した場合、Spotify は現在動いている機器を使います。

spotify_playback

再生の操作と状態の確認、それに最近の再生履歴の取得を行います。

spotify_devices

Home Assistant が管理するスピーカー

Home Assistant が管理しているスピーカーでも、そのスピーカー自身が Spotify Connect に対応していれば（たとえば Sonos、Echo、Nest など Connect 対応のスピーカー）、Spotify から見えている間は spotify_devices list に自動で現れます。この経路では Home Assistant と Spotify をつなぐ橋渡しは要りません。機器の振り分けは Spotify 自身が行います。

Hermes には「キッチンのスピーカーに Spotify を移して」のように、スピーカーの表示名で再生の移動を頼めます。スクリプトから呼ぶときは spotify_devices list で確認し、正確な device_id を spotify_devices transfer に渡してください。目当てのスピーカーが見当たらない場合は、Spotify アプリかそのスピーカーの Spotify 連携を一度開いて、Spotify に動作中の Connect 先として登録させます。

spotify_queue

spotify_search

カタログを検索します。query は必須です。任意で types（track / album / artist / playlist / show / episode の配列）、limit、offset、market を指定できます。

spotify_playlists

spotify_albums

spotify_library

保存済みの曲とアルバムをまとめて扱います。どちらを対象にするかは kind 引数で選びます。

必須の引数は kind = tracks または albums と、action です。

できることの対応表: 無料プランと Premium

読み取りだけのツールは無料プランでも動きます。再生やキューを変える操作には Premium が要ります。

時刻を決めて動かす: Spotify と cron

Spotify のツールはふつうの Hermes のツールなので、Hermes のセッションで動く cron ジョブから好きな時刻に再生を始められます。新しくコードを書く必要はありません。

朝の目覚ましプレイリスト

hermes cron add \
  --name "morning-commute" \
  "0 7 * * 1-5" \
  "Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."

平日の朝 7 時に起きることは次のとおりです。

1. cron が画面のない Hermes セッションを立ち上げます。
2. エージェントが指示を読み、spotify_devices list を呼んで名前から「kitchen speaker」を探し、spotify_devices transfer → spotify_playback set_volume → spotify_playback set_shuffle → spotify_search + spotify_playback play と続けます。
3. 目当てのスピーカーで音楽が鳴り始めます。かかるのはセッション 1 回と数回のツール呼び出しだけで、人の操作は要りません。

夜に静かにしていく

hermes cron add \
  --name "wind-down" \
  "30 22 * * *" \
  "Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."

落とし穴

• cron が動く時点で、動作中の機器が要ります。 Spotify のクライアント（スマートフォン、パソコン、Connect 対応スピーカー）がどれも動いていないと、再生系の操作は 403 no active device を返します。朝のプレイリストなら、スマートフォンではなく常に電源の入っている機器（Sonos、Echo、スマートスピーカー）を狙うのがこつです。
• 再生を変える操作には Premium が要ります。 再生、一時停止、スキップ、音量、機器の切り替えが該当します。読み取りだけの cron ジョブ（「最近再生した曲をメールで送って」など）は無料プランでも問題なく動きます。
• cron のエージェントは、有効にしているツール群をそのまま引き継ぎます。 cron のセッションから Spotify のツールを見せるには、hermes tools で Spotify を有効にしておく必要があります。
• cron ジョブは skip_memory=True で動きます。 そのため記憶の保存先には書き込みません。

cron の詳しい説明は Cron Jobs にあります。

ログアウトする

hermes auth logout spotify

~/.hermes/auth.json からトークンを削除します。アプリの設定も消したい場合は、~/.hermes/.env から HERMES_SPOTIFY_CLIENT_ID（設定していれば HERMES_SPOTIFY_REDIRECT_URI も）を削除するか、ウィザードをもう一度実行してください。

Spotify 側でアプリの許可を取り消すには、Apps connected to your account を開いて REMOVE ACCESS をクリックします。

困ったときは

403 Forbidden — Player command failed: No active device found — Spotify がどれか一台で動いている必要があります。スマートフォン、パソコン、Web プレーヤーで Spotify アプリを開き、何か 1 曲を数秒だけ再生して機器として登録させてから、もう一度試してください。いま見えている機器は spotify_devices list で確認できます。

403 Forbidden — Premium required — 無料プランのまま、再生を変える操作を使おうとしています。上の対応表を確認してください。

get_currently_playing で 204 No Content — どの機器でも何も再生されていない状態です。これは Spotify の正常な応答であってエラーではありません。Hermes は説明を添えた空の結果（is_playing: false）として返します。

INVALID_CLIENT: Invalid redirect URI — Spotify アプリ側の設定にあるリダイレクト URI と、Hermes が使っているものが食い違っています。既定は http://127.0.0.1:43827/spotify/callback です。これをアプリの許可済みリダイレクト URI に追加するか、登録した値を ~/.hermes/.env の HERMES_SPOTIFY_REDIRECT_URI に設定してください。

429 Too Many Requests — Spotify の呼び出し回数の上限です。Hermes は分かりやすいエラーを返すので、1 分ほど待ってからやり直してください。これが続くなら、スクリプトで短い間隔の繰り返しを回している可能性が高いです。Spotify の割り当ては 30 秒ほどで戻ります。

401 Unauthorized が繰り返し出る — リフレッシュトークンが無効になっています。たいていはアカウントからアプリを外したか、アプリそのものを削除した場合です。hermes auth spotify をもう一度実行してください。

ウィザードがブラウザーを開かない — SSH 越しの接続や、画面のないコンテナの中では、Hermes がそれを検知して自動起動を行いません。表示されたダッシュボードの URL をコピーして、手作業で開いてください。

応用: スコープを自分で指定する

既定では、Hermes は同梱するすべてのツールに必要なスコープを要求します。権限を絞りたい場合は上書きしてください。

hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"

スコープの一覧は Spotify Web API scopes にあります。ツールが必要とするより少ないスコープしか要求しなかった場合、そのツールの呼び出しは 403 で失敗します。

応用: Client ID とリダイレクト URI を自分で指定する

hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback

あるいは ~/.hermes/.env に書いて固定しておくこともできます。

HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

リダイレクト URI は Spotify アプリの設定で許可しておく必要があります。既定の値でほとんどの場合は足りるので、変えるのはポート 43827 がふさがっているときだけで構いません。

どこに何があるか