Music Assistant

Integra o Music Assistant (MA) — o servidor de música multi-provedor open-source — ao Portal. Permite controlar os players cadastrados no MA, navegar e tocar a biblioteca (Spotify, Tidal, Apple Music, YouTube Music, playlists locais, rádios etc.), além de disparar anúncios TTS e agrupar players.

Pré-requisitos

Um servidor Music Assistant versão 2.4 ou superior rodando (add-on do Home Assistant, container Docker ou serviço avulso).
A URL do servidor acessível pelo edge do Portal (ex.: http://mass.local:8095). Para rodar com cloud edge, o servidor precisa estar exposto publicamente (DDNS, túnel, VPN).
Um Long-lived access token gerado no próprio MA.

Gerando o token

Abra a UI do Music Assistant.
Vá em Settings → Profile → Long-lived access tokens.
Clique em Create token, dê um nome (ex.: portal), e copie o token mostrado. Ele só aparece uma vez — guarde antes de fechar o modal.

Configurar no Portal

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Music Assistant.

Informe URL e token

Preencha a URL do servidor (ex.: http://mass.local:8095) e cole o long-lived token. O Portal valida a URL via GET /info e testa o token com players/all.

Players são descobertos automaticamente

Cada player exposto no MA (expose_to_ha === true) vira:

Um media_player.music_assistant_<nome> com controles completos.
Um button.music_assistant_<nome>_favorite que, quando pressionado, favorita a música tocando no momento (players/cmd/add_currently_playing_to_favorites).

Players criados/removidos depois são sincronizados a cada 5 segundos.

Funcionalidades

Play / Pause / Stop / Next / Previous / Seek
Volume absoluto (0–100%), mute/unmute, volume up/down
Power on/off (quando o player suporta power_control)
Troca de fonte (source_list reportada por cada player)
Shuffle e repeat em nível de queue
Clear playlist (media_player.clear_playlist)
Agrupamento multiroom: media_player.join + media_player.unjoin
Reproduzir mídia da biblioteca MA ou URI arbitrária
Anúncios TTS sem interromper a música (media_player.play_announcement)
Botão Favoritar (button.press em cada player)
Navegação e busca na biblioteca via painel “Procurar mídia”

Reproduzir mídia (`media_player.play_media`)

O MA aceita qualquer URI que seus providers conheçam. Formatos típicos:

{
  "media_content_type": "music",
  "media_content_id": "spotify://track/4iV5W9uYEdYUVa79Axb7Rh"
}

{
  "media_content_type": "music",
  "media_content_id": "library://playlist/42"
}

Também aceita URL direta de MP3/FLAC/HLS. Combine com enqueue (play, replace, next, add, replace_next) para controlar o comportamento da fila.

Navegar a biblioteca

O painel Procurar mídia mostra a hierarquia padrão do MA:

Playlists
Artistas
Álbuns
Músicas
Rádios
Podcasts
Audiobooks

Cada folder busca sob demanda (até 100 itens por página na primeira fase). A busca livre usa music/search com fallback cross-provider — digite o termo e, opcionalmente, filtre por tipo (track / álbum / artista / playlist / podcast).

Anúncios TTS

Service dedicado:

service: media_player.play_announcement
target:
  entity_id: media_player.music_assistant_sala
data:
  message: "https://seu-tts.example.com/audio.mp3"
  volume_level: 0.6
  use_pre_announce: true

O MA automaticamente abaixa o volume da música atual, toca o anúncio, e retoma a reprodução. Ótimo para campainha / interfone.

Multiroom

service: media_player.join
target:
  entity_id: media_player.music_assistant_sala
data:
  group_members:
    - media_player.music_assistant_cozinha
    - media_player.music_assistant_quarto

Para desagrupar, chame media_player.unjoin no player a ser separado.

O suporte a grouping só aparece em players com a feature SET_MEMBERS reportada pelo MA (ex.: Snapcast, Sonos, grupos nativos). Players que não suportam o recurso não exibem o botão de agrupar no card.

Solução de problemas

“MA: token inválido ou sem permissão (HTTP 401)” — token digitado errado ou revogado. Gere um novo em Settings → Profile → Long-lived access tokens e use o fluxo de Reautorizar no Portal.
“Não foi possível conectar ao Music Assistant em <url>” — URL errada, servidor desligado, ou firewall bloqueando a porta 8095. Teste com curl http://<host>:8095/info — deve retornar o JSON do servidor.
“Esta URL aponta para outra instância do Music Assistant” — você tentou reconfigurar o entry apontando para outro servidor (o Portal usa o server_id como identidade). Remova o entry e crie um novo se quiser trocar de servidor.
Player não aparece — provavelmente está com expose_to_ha: false no MA. Abra o player em Settings → Players no MA e marque “Expose player to Home Assistant / Portal”.
Mudanças externas demoram pra aparecer — polling de 5 s. Mudanças iniciadas pelo próprio Portal usam optimistic update, então o card reage na hora; apps externos (MA UI, Spotify Connect direto no player) só refletem no próximo ciclo.
Favoritar não funciona em player X — o comando add_currently_playing_to_favorites depende do provedor; nem todos (ex.: rádios públicas) suportam a ação. Veja os logs do servidor MA.

Limites conhecidos (fase 1)

Browse não expande dentro de artista/álbum/playlist — só mostra os itens raízes de cada categoria. Clique em “Play” funciona em todos.
Sem painel dedicado de queue avançada (reorder, remove item).
Options avançadas do player (NUMBER/SELECT/SWITCH/TEXT customizadas no MA) ainda não são expostas como entidades separadas — ficam disponíveis apenas via dashboard do próprio MA.

​Music Assistant

​Pré-requisitos

​Gerando o token

​Configurar no Portal

​Funcionalidades

​Reproduzir mídia (media_player.play_media)

​Navegar a biblioteca

​Anúncios TTS

​Multiroom

​Solução de problemas

​Limites conhecidos (fase 1)