Spotify

Integração oficial do Portal com Spotify. Combina:

Media source: navegue por suas playlists, álbuns salvos, podcasts, músicas curtidas, top artistas, top faixas e ouvidas recentemente diretamente no painel Mídia.
Spotify Connect: envie a reprodução para qualquer dispositivo da sua conta (Echo, WiiM/LinkPlay, Sonos, Google Nest, celular, carro, desktop).
Busca unificada: faixas, álbuns, artistas, playlists, shows e episódios em um único campo.

A integração requer Spotify Premium. Contas Free podem fazer login para navegar o catálogo, mas qualquer ação de controle de reprodução vai falhar na API do Spotify. O config-flow já bloqueia contas Free com mensagem clara.

Pré-requisitos

Conta Spotify Premium ativa.
Pelo menos um dispositivo com Spotify Connect disponível quando quiser tocar algo — veja a seção Preparando seus dispositivos abaixo.
Administrador do Portal com as variáveis de ambiente SPOTIFY_CLIENT_ID e SPOTIFY_CLIENT_SECRET configuradas (app oficial do Spotify Developer registrado pelo Unisec).
Seu email de usuário Spotify precisa estar autorizado na app do Portal enquanto a Spotify não aprova a Quota Extension (ver seção “Autorização de usuários” abaixo).

Pré-requisitos administrativos da app Spotify Developer

Antes de qualquer usuário conseguir vincular, o administrador do Portal precisa garantir:

1. A conta Spotify dona da app precisa ser Premium

Desde 2024/2025, a Spotify exige que a conta Spotify que criou a app no Spotify Developer tenha assinatura Premium ativa — mesmo que a app seja usada só por terceiros. Se a conta não for Premium, aparece este banner no dashboard da app:

Your application is blocked from accessing the Web API since you do not have a Spotify Premium subscription.

Enquanto a conta estiver bloqueada, todas as tentativas de vinculação (de qualquer usuário) falham com HTTP 403, mesmo com credenciais corretas. Como resolver: torne a conta dona Premium em spotify.com/premium, ou crie uma nova app a partir de uma conta Premium existente e atualize SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET no deploy do Portal.

2. Autorização de usuários (Development Mode)

Enquanto a app estiver em Development Mode (status inicial de qualquer app no Spotify Developer, com limite de 25 usuários), cada usuário precisa ser cadastrado manualmente antes de conseguir vincular:

Acesse developer.spotify.com/dashboard com a conta dona.
Abra a app Portal.
Vá em Settings → aba User Management → Add New User.
Preencha com o nome e o email exato da conta Spotify do usuário.
Avise o usuário para refazer o fluxo de vinculação.

Para liberar sem allowlist (produção), submeta uma Quota Extension Request no dashboard da Spotify. A revisão deles leva ~2 a 6 semanas.

Diagnóstico do erro HTTP 403

Se um usuário vê a mensagem “Spotify recusou o acesso (HTTP 403)” durante a vinculação, isso significa que a Spotify bloqueou a chamada à Web API. Não dá para distinguir pelo erro em si qual das duas causas é — verifique nessa ordem:

Abra o dashboard da app e procure o banner “Your application is blocked” → se aparecer, é o pré-requisito 1 (conta dona precisa de Premium).
Se o banner não aparece, verifique em Settings → User Management se o email do usuário está cadastrado → se não estiver, é o pré-requisito 2 (allowlist).

Configurar

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Spotify.

Autorize no Spotify

Uma janela abrirá no site do Spotify pedindo autorização. Faça login e autorize o Portal a acessar sua biblioteca e controlar seus devices.

Pronto

O Portal detecta automaticamente seus dispositivos Spotify Connect ativos e cria uma media_player.spotify_<nome> para cada um. Novos devices são descobertos automaticamente conforme ficam online.

Preparando seus dispositivos

A integração Spotify do Portal é um “controle remoto glorificado”: o áudio nunca passa pelo Portal, cada dispositivo busca o stream direto do Spotify. Para isso cada caixa/TV/smart-speaker precisa estar logada na sua conta Spotify pelo app do próprio fabricante.

Dispositivo	Como vincular a conta Spotify
WiiM / LinkPlay	WiiM Home / 4Stream → Settings → Services → Spotify → Login
Echo (Alexa)	App Alexa → More → Settings → Music & Podcasts → Link New Service → Spotify
Google Nest / Cast	Google Home → Settings → Music → Add Service → Spotify
Sonos	App Sonos → Settings → Services & Voice → Add a Service → Spotify
Samsung TV / Tizen	App Spotify instalado na TV, logado
Celular Android/iOS	Basta ter o app Spotify oficial aberto
Desktop (Windows/Mac/Linux)	App Spotify oficial aberto
Portal (navegador)	Automático — veja seção “Portal como device Spotify” abaixo

Depois do pareamento, o device aparece automaticamente no Portal como media_player.spotify_<nome>. Devices em idle somem da lista do Spotify após alguns minutos — reaparecem assim que voltam a ficar ativos (ex.: tocar algo pelo app).

Como usar o painel de mídia

Abra o painel Mídia.
Selecione Spotify no índice de fontes.
Navegue por Playlists, Álbuns salvos, Músicas curtidas, Podcasts, Top Artistas, etc.
Escolha o device alvo no seletor no canto inferior direito — qualquer device Spotify Connect, ou o próprio Navegador web (veja seção abaixo).
Clique em qualquer playlist/álbum/faixa — ela começa a tocar no device escolhido.

Também é possível usar o campo Buscar no topo do painel para procurar faixas, álbuns, artistas, playlists, podcasts e episódios ao mesmo tempo.

Portal como device Spotify (Web Playback SDK)

Quando a aba do Portal está aberta, o navegador se registra automaticamente como um device Spotify Connect chamado “Portal (web)”. Isso significa que você pode:

Selecionar “Navegador web” no painel de mídia e tocar Spotify dentro da aba do Portal.
Ver o device “Portal (web)” aparecer no app oficial do Spotify, no celular, no Echo, etc. — e enviar música pra ele de qualquer lugar.
Migrar a reprodução entre o navegador e qualquer outro device (Echo, WiiM, celular) sem corte via o seletor de device do mini-player.

Requisitos técnicos:

Spotify Premium (SDK oficial não funciona com Free).
Navegador com suporte a EME/Widevine: Chrome, Edge, Opera, Brave (Firefox com DRM habilitado também funciona).
Interação prévia do usuário na página antes do primeiro play (política de autoplay dos navegadores).

Observações:

Reprodução pausa quando a aba vai para background sem áudio ativo — isso é limitação do próprio navegador.
Fechar a aba desconecta o device do Spotify. Reabrir reconecta automaticamente.
O SDK carrega sob demanda (lazy) — a primeira vez que você abrir o painel de mídia com Spotify configurado, pode levar 1-2s pra ficar pronto. O seletor de device mostra “Carregando Spotify…” nesse intervalo.

Entities criadas

Para cada dispositivo Spotify Connect da sua conta, a integração cria:

media_player.spotify_<nome> com os seguintes serviços:
- media_player.play / media_pause / media_stop
- media_player.media_next_track / media_previous_track
- media_player.media_seek (position_ms)
- media_player.volume_set (volume_level 0..1)
- media_player.shuffle_set (shuffle true/false)
- media_player.repeat_set (repeat off/track/context, aliases “one”/“all” aceitos)
- media_player.play_media — aceita media_content_id começando com spotify: (ex.: spotify:playlist:37i9..., spotify:track:4iV5...), além dos campos context_uri/uris quando chamado pelo painel de mídia.

A entity reflete o estado real da reprodução no device ativo: media_title, media_artist, media_album_name, media_duration, media_position, entity_picture (capa), shuffle, repeat, volume_level.

Convivência com outras integrações

É normal um device físico aparecer duas vezes no Portal — uma pela integração do fabricante (ex.: media_player.linkplay_wiim_sala) e outra pela integração Spotify (ex.: media_player.spotify_wiim_sala). No seletor de device do painel de mídia, as entities da Spotify ganham o sufixo ” (Spotify)” para facilitar a escolha.

Use a entity LinkPlay/Alexa/Cast para controles genéricos (volume do device, source change, stop total).
Use a entity Spotify para controle contextual via Spotify Connect (muda faixa, shuffle, repeat, tocar playlist específica da sua biblioteca).

Automações

Exemplo — ao chegar em casa, tocar uma playlist Spotify no amplificador:

trigger:
  platform: state
  entity_id: person.jadson
  to: "home"
action:
  service: media_player.play_media
  entity_id: media_player.spotify_sala
  data:
    media_content_id: spotify:playlist:37i9dQZF1DX4JAvHpjipBk
    media_content_type: audio/x-spotify

Para tocar uma faixa:

service: media_player.play_media
entity_id: media_player.spotify_quarto
data:
  media_content_id: spotify:track:4iV5W9uYEdYUVa79Axb7Rh
  media_content_type: audio/x-spotify

Limitações

Devices offline somem da lista até reativar. Isso é comportamento do próprio Spotify (não armazenamos o device como “sempre disponível”).
Rate limits da Spotify Web API aplicam. O Portal usa polling adaptativo (10s se tocando, 30s se idle, 5min se nenhum device ativo) para mitigar.
Revogação do token: se você revogar a autorização em spotify.com/account/apps, a integração para de funcionar e precisa ser reautenticada pelo painel.
Web Playback SDK no mobile browser: a Spotify oficialmente não suporta o SDK em Safari iOS / Chrome Android. Nesses navegadores o “Portal (web)” não aparece — use a aba do Portal em desktop, ou toque num device externo (Echo, WiiM, carro).

Solução de problemas

Sintoma	Causa provável	Solução
Painel diz “Spotify Connect exige conta Premium”	Conta Free	Faça upgrade em spotify.com/premium
Nenhum device aparece	Nenhum device logado na sua conta Spotify, ou todos em idle	Abra o Spotify no celular/desktop ou vincule um dispositivo no app do fabricante
Toca no app Spotify oficial mas não no Echo/WiiM	Device ainda não está logado na conta Spotify	Vincule a conta no app do fabricante (veja tabela acima)
Erro 401 persistente	Token revogado em spotify.com/account/apps	Faça reconfigure da integração para reautenticar
”Navegador web” fica em “Carregando Spotify…” indefinidamente	Script `sdk.scdn.co/spotify-player.js` bloqueado (adblock, firewall corporativo) ou DRM desabilitado	Libere o domínio e habilite “Protected content” no navegador
Reprodução no navegador para ao mudar de aba	Comportamento padrão do browser (background audio)	Mantenha a aba do Portal visível, ou use um device externo

Para quem tem Echo com Alexa: a reprodução via Spotify Connect (nossa integração Spotify) é mais consistente do que via media_player.play_media da integração Alexa Devices. Ambas funcionam, mas o Spotify Connect dá menos surpresa.

​Spotify

​Pré-requisitos

​Pré-requisitos administrativos da app Spotify Developer

​1. A conta Spotify dona da app precisa ser Premium

​2. Autorização de usuários (Development Mode)

​Diagnóstico do erro HTTP 403

​Configurar

​Preparando seus dispositivos

​Como usar o painel de mídia

​Portal como device Spotify (Web Playback SDK)

​Entities criadas

​Convivência com outras integrações

​Automações

​Limitações

​Solução de problemas

Spotify

Pré-requisitos

Pré-requisitos administrativos da app Spotify Developer

1. A conta Spotify dona da app precisa ser Premium

2. Autorização de usuários (Development Mode)

Diagnóstico do erro HTTP 403

Configurar

Preparando seus dispositivos

Como usar o painel de mídia

Portal como device Spotify (Web Playback SDK)

Entities criadas

Convivência com outras integrações

Automações

Limitações

Solução de problemas