Spotify

O Hermes controla o Spotify diretamente — reprodução, fila, busca, playlists, faixas/álbuns salvos e histórico de audição — usando a Web API oficial do Spotify com OAuth PKCE. Os tokens ficam em ~/.hermes/auth.json e são renovados automaticamente em caso de 401; você faz login uma única vez por máquina (os refresh tokens expiram em cerca de 6 meses; quando isso acontecer, rode hermes auth spotify de novo).

Diferente das integrações OAuth embutidas no Hermes (Google, GitHub Copilot, Codex), o Spotify exige que cada usuário registre o próprio app de desenvolvedor. O Spotify não permite que terceiros distribuam um app OAuth público que qualquer um possa usar. Leva uns dois minutos e o hermes auth spotify conduz você pelo processo.

Pré-requisitos

• Uma conta Spotify. A conta Free funciona para as ferramentas de busca, playlist, biblioteca e atividade. A Premium é necessária para controlar a reprodução (tocar, pausar, pular, avançar, volume, adicionar à fila, transferir).
• Hermes Agent instalado e rodando.
• Para as ferramentas de reprodução: um dispositivo Spotify Connect ativo — o app do Spotify precisa estar aberto em pelo menos um dispositivo (celular, computador, web player, caixa de som) para a Web API ter o que controlar. Se nada estiver ativo, você recebe um 403 Forbidden com a mensagem "no active device"; abra o Spotify em qualquer dispositivo e tente de novo.

Configuração

Caminho direto: hermes tools ou configuração inicial

O jeito mais rápido. Rode:

hermes tools

Vá até 🎵 Spotify, aperte espaço para ligar e depois s para salvar. O mesmo interruptor aparece durante o fluxo inicial de hermes setup / hermes setup tools. O Spotify continua opcional, então ligá-lo ali roda a mesma configuração ciente do provedor que o hermes tools.

O Hermes leva você direto para o fluxo OAuth — se você ainda não tem um app do Spotify, ele conduz a criação ali mesmo. Ao terminar, o conjunto de ferramentas fica habilitado E autenticado de uma vez só.

Se preferir fazer as etapas separadamente (ou estiver reautenticando depois), use o fluxo em dois passos abaixo.

Fluxo em dois passos

1. Habilite o conjunto de ferramentas

hermes tools

Ligue o 🎵 Spotify, salve e, quando o assistente abrir, feche-o (Ctrl+C). O conjunto de ferramentas continua ligado; só a autenticação fica para depois.

2. Rode o assistente de login

hermes auth spotify

As 7 ferramentas do Spotify só aparecem no conjunto de ferramentas do agente depois do passo 1 — elas vêm desligadas por padrão para que quem não quiser não carregue schemas extras em toda chamada de API.

Se não houver HERMES_SPOTIFY_CLIENT_ID definido, o Hermes conduz o registro do app ali mesmo:

1. Abre https://developer.spotify.com/dashboard no seu navegador
2. Imprime os valores exatos para colar no formulário "Create app" do Spotify
3. Pede o Client ID que você recebeu
4. Salva o valor em ~/.hermes/.env para as próximas execuções pularem esta etapa
5. Segue direto para o fluxo de consentimento OAuth

Depois que você aprova, os tokens são gravados em providers.spotify no ~/.hermes/auth.json. O provedor de inferência ativo NÃO é alterado — a autenticação do Spotify é independente do seu provedor de LLM.

Criando o app do Spotify (o que o assistente pede)

Quando o dashboard abrir, clique em Create app e preencha:

Campo	Valor
App name	qualquer coisa (ex.: hermes-agent)
App description	qualquer coisa (ex.: integração pessoal com o Hermes)
Website	deixe em branco
Redirect URI	http://127.0.0.1:43827/spotify/callback
Which API/SDKs?	marque Web API

Aceite os termos e clique em Save. Na página seguinte, clique em Settings → copie o Client ID e cole no prompt do Hermes. Esse é o único valor de que o Hermes precisa — o PKCE não usa client secret.

Rodando por SSH / em ambiente sem interface gráfica

Se SSH_CLIENT ou SSH_TTY estiver definido, o Hermes não abre o navegador automaticamente nem no assistente nem na etapa OAuth. Copie a URL do dashboard e a URL de autorização que o Hermes imprime, abra-as em um navegador na sua máquina local e siga normalmente — o listener HTTP local continua rodando na máquina remota, na porta 43827. O navegador do seu notebook não alcança o loopback remoto sem um encaminhamento local por SSH:

ssh -N -L 43827:127.0.0.1:43827 usuario@maquina-remota

Para cenários com jump box / bastion e outras pegadinhas (mosh, tmux, conflito de porta), veja OAuth por SSH / hosts remotos.

Verificação

hermes auth status spotify

Mostra se há tokens salvos e quando o access token expira. A renovação é automática: quando qualquer chamada à API do Spotify retorna 401, o cliente troca o refresh token e tenta de novo uma vez. Os refresh tokens sobrevivem a reinícios do Hermes, então você só reautentica se revogar o app nas configurações da sua conta Spotify ou rodar hermes auth logout spotify.

Usando

Depois do login, o agente passa a ter acesso a 7 ferramentas do Spotify. Você fala com o agente naturalmente — ele escolhe a ferramenta e a ação certas. Para o melhor comportamento, o agente carrega uma skill complementar que ensina os padrões canônicos de uso (buscar uma vez e tocar, quando não vale fazer um get_state preventivo etc.).

> toca um miles davis aí
> o que estou ouvindo
> adiciona esta faixa à minha playlist Late Night Jazz
> pula para a próxima música
> cria uma playlist chamada "Foco 2026" e adiciona as três últimas músicas que toquei
> quais dos meus álbuns salvos são do Radiohead
> procura covers acústicos de Blackbird
> transfere a reprodução para a caixa de som da cozinha

Referência de ferramentas

Todas as ações que alteram a reprodução aceitam um device_id opcional para mirar um dispositivo específico. Se você omitir, o Spotify usa o dispositivo ativo no momento.

spotify_playback

Controla e inspeciona a reprodução, além de buscar o histórico recente.

Ação	Para que serve	Premium?
get_state	Estado completo da reprodução (faixa, dispositivo, progresso, shuffle/repeat)	Não
get_currently_playing	Só a faixa atual (volta vazio em 204 — veja abaixo)	Não
play	Inicia/retoma a reprodução. Opcionais: context_uri, uris, offset, position_ms	Sim
pause	Pausa a reprodução	Sim
next / previous	Pula de faixa	Sim
seek	Salta para position_ms	Sim
set_repeat	state = track / context / off	Sim
set_shuffle	state = true / false	Sim
set_volume	volume_percent = 0-100	Sim
recently_played	Últimas faixas tocadas. Opcionais limit, before, after (Unix ms)	Não

spotify_devices

Ação	Para que serve
list	Todo dispositivo Spotify Connect visível para a sua conta
transfer	Move a reprodução para device_id. O opcional play: true já inicia a reprodução ao transferir

Caixas de som gerenciadas pelo Home Assistant

Se o Home Assistant gerencia caixas de som que já suportam Spotify Connect (por exemplo Sonos, Echo, Nest ou outras compatíveis com Connect), elas aparecem no spotify_devices list automaticamente sempre que o Spotify as enxerga. O Hermes não precisa de uma ponte Home Assistant ↔ Spotify para esse caminho — o Spotify cuida do roteamento de dispositivo nativamente.

Peça ao Hermes para transferir a reprodução pelo nome de exibição da caixa de som (por exemplo, "transfere o Spotify para a caixa da cozinha"), ou chame spotify_devices list e passe o device_id exato para spotify_devices transfer quando estiver automatizando. Se a caixa de som não aparecer, abra o app do Spotify ou a integração Spotify da caixa uma vez para o Spotify registrá-la como alvo Connect ativo.

spotify_queue

Ação	Para que serve	Premium?
get	Faixas atualmente na fila	Não
add	Acrescenta uri à fila	Sim

spotify_search

Busca no catálogo. query é obrigatório. Opcionais: types (lista de track / album / artist / playlist / show / episode), limit, offset, market.

spotify_playlists

Ação	Para que serve	Argumentos obrigatórios
list	Playlists do usuário	—
get	Uma playlist + faixas	playlist_id
create	Nova playlist	name (+ opcionais description, public, collaborative)
add_items	Adiciona faixas	playlist_id, uris (opcional position)
remove_items	Remove faixas	playlist_id, uris (+ opcional snapshot_id)
update_details	Renomeia / edita	playlist_id + qualquer um de name, description, public, collaborative

spotify_albums

Ação	Para que serve	Argumentos obrigatórios
get	Metadados do álbum	album_id
tracks	Lista de faixas do álbum	album_id

spotify_library

Acesso unificado às faixas e aos álbuns salvos. Escolha a coleção com o argumento kind.

Ação	Para que serve
list	Listagem paginada da biblioteca
save	Adiciona ids / uris à biblioteca
remove	Remove ids / uris da biblioteca

Obrigatórios: kind = tracks ou albums, mais action.

Matriz de recursos: Free vs Premium

As ferramentas somente de leitura funcionam em contas Free. Tudo que altera a reprodução ou a fila exige Premium.

Funciona no Free	Exige Premium
spotify_search (tudo)	spotify_playback — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume
spotify_playback — get_state, get_currently_playing, recently_played	spotify_queue — add
spotify_devices — list	spotify_devices — transfer
spotify_queue — get
spotify_playlists (tudo)
spotify_albums (tudo)
spotify_library (tudo)

Agendamento: Spotify + cron

Como as ferramentas do Spotify são ferramentas comuns do Hermes, um job de cron rodando em uma sessão do Hermes pode disparar a reprodução em qualquer horário. Não precisa de código novo.

Playlist para acordar

hermes cron add \
  --name "trajeto-da-manha" \
  "0 7 * * 1-5" \
  "Transfira a reprodução para a caixa de som da cozinha e comece a playlist 'Morning Commute'. Volume em 40. Shuffle ligado."

O que acontece às 7h de todo dia útil:

1. O cron sobe uma sessão headless do Hermes.
2. O agente lê o prompt, chama spotify_devices list para achar a "caixa de som da cozinha" pelo nome, depois spotify_devices transfer → spotify_playback set_volume → spotify_playback set_shuffle → spotify_search + spotify_playback play.
3. A música começa na caixa de som escolhida. Custo total: uma sessão, algumas chamadas de ferramenta, nenhuma intervenção humana.

Desacelerar à noite

hermes cron add \
  --name "fim-de-dia" \
  "30 22 * * *" \
  "Pause o Spotify. Depois coloque o volume em 20 para ficar baixo quando eu ligar de novo amanhã."

Pegadinhas

• Precisa existir um dispositivo ativo na hora em que o cron dispara. Se nenhum cliente Spotify estiver rodando (celular/computador/caixa Connect), as ações de reprodução retornam 403 no active device. Para playlists matinais, o truque é mirar um dispositivo que fica sempre ligado (Sonos, Echo, uma caixa inteligente) em vez do seu celular.
• Premium é obrigatório para qualquer coisa que altere a reprodução — tocar, pausar, pular, volume, transferir. Jobs de cron somente de leitura (agendar "me mande por e-mail as faixas que ouvi") funcionam bem no Free.
• O agente do cron herda os seus conjuntos de ferramentas ativos. O Spotify precisa estar habilitado no hermes tools para a sessão do cron enxergar as ferramentas do Spotify.
• Jobs de cron rodam com skip_memory=True, então não escrevem no seu armazenamento de memória.

Referência completa do cron: Jobs de cron.

Sair da conta

hermes auth logout spotify

Remove os tokens de ~/.hermes/auth.json. Para limpar também a configuração do app, apague HERMES_SPOTIFY_CLIENT_ID (e HERMES_SPOTIFY_REDIRECT_URI, se você tiver definido) do ~/.hermes/.env, ou rode o assistente de novo.

Para revogar o app do lado do Spotify, acesse Apps conectados à sua conta e clique em REMOVE ACCESS.

Solução de problemas

403 Forbidden — Player command failed: No active device found — Você precisa do Spotify rodando em pelo menos um dispositivo. Abra o app do Spotify no celular, no computador ou no web player, toque qualquer faixa por um segundo para registrá-lo e tente de novo. O spotify_devices list mostra o que está visível no momento.

403 Forbidden — Premium required — Você está em uma conta Free tentando usar uma ação que altera a reprodução. Veja a matriz de recursos acima.

204 No Content em get_currently_playing — nada está tocando em nenhum dispositivo. Essa é a resposta normal do Spotify, não um erro; o Hermes a apresenta como um resultado vazio explicativo (is_playing: false).

INVALID_CLIENT: Invalid redirect URI — a redirect URI nas configurações do seu app do Spotify não bate com a que o Hermes usa. O padrão é http://127.0.0.1:43827/spotify/callback. Ou adicione essa URI às redirect URIs permitidas do seu app, ou defina HERMES_SPOTIFY_REDIRECT_URI no ~/.hermes/.env com o valor que você registrou.

429 Too Many Requests — limite de requisições do Spotify. O Hermes devolve um erro amigável; espere um minuto e tente de novo. Se persistir, provavelmente você está rodando um laço apertado em um script — a cota do Spotify se recompõe mais ou menos a cada 30 segundos.

401 Unauthorized voltando sempre — seu refresh token foi revogado (normalmente porque você removeu o app da sua conta ou o app foi apagado). Rode hermes auth spotify de novo.

O assistente não abre o navegador — se você está por SSH ou em um contêiner sem display, o Hermes detecta isso e não abre nada automaticamente. Copie a URL do dashboard que ele imprime e abra manualmente.

Avançado: escopos personalizados

Por padrão, o Hermes pede os escopos necessários para todas as ferramentas distribuídas. Sobrescreva se quiser restringir o acesso:

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

Referência de escopos: escopos da Web API do Spotify. Se você pedir menos escopos do que uma ferramenta precisa, as chamadas dela vão falhar com 403.

Avançado: client ID / redirect URI personalizados

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

Ou defina os valores em definitivo no ~/.hermes/.env:

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

A redirect URI precisa estar na lista de permissões das configurações do seu app do Spotify. O padrão serve para quase todo mundo — só mude se a porta 43827 estiver ocupada.

Onde cada coisa fica

Arquivo	Conteúdo
~/.hermes/auth.json → providers.spotify	access token, refresh token, validade, escopo, redirect URI
~/.hermes/.env	HERMES_SPOTIFY_CLIENT_ID, opcionalmente HERMES_SPOTIFY_REDIRECT_URI
App do Spotify	seu, em developer.spotify.com/dashboard; contém o Client ID e a lista de redirect URIs permitidas

---