> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify

> Media source + Spotify Connect para controlar qualquer device compatível.

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

<Warning>
  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.
</Warning>

## Pré-requisitos

1. Conta Spotify Premium ativa.
2. Pelo menos um dispositivo com Spotify Connect disponível quando quiser tocar algo — veja a seção **Preparando seus dispositivos** abaixo.
3. 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).
4. **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](https://www.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:

1. Acesse [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) com a conta dona.
2. Abra a app **Portal**.
3. Vá em **Settings** → aba **User Management** → **Add New User**.
4. Preencha com o nome e o **email exato** da conta Spotify do usuário.
5. 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:

1. Abra o dashboard da app e procure o banner "Your application is blocked" → se aparecer, é o pré-requisito 1 (conta dona precisa de Premium).
2. 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

<Steps>
  <Step title="Adicione a integração">
    Vá em **Configurações → Integrações → Adicionar → Spotify**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

1. Abra o painel **Mídia**.
2. Selecione **Spotify** no índice de fontes.
3. Navegue por **Playlists**, **Álbuns salvos**, **Músicas curtidas**, **Podcasts**, **Top Artistas**, etc.
4. **Escolha o device alvo** no seletor no canto inferior direito — qualquer device Spotify Connect, **ou o próprio Navegador web** (veja seção abaixo).
5. 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:

```yaml theme={null}
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:

```yaml theme={null}
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](https://www.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 |

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.