> ## 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.
# Music Assistant
> Controle o servidor Music Assistant pelo Portal — players, filas, biblioteca e streaming
# Music Assistant
Integra o **[Music Assistant](https://music-assistant.io/)** (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
1. Abra a UI do Music Assistant.
2. Vá em **Settings → Profile → Long-lived access tokens**.
3. 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
Vá em **Configurações → Integrações → Adicionar → Music Assistant**.
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`.
Cada player exposto no MA (`expose_to_ha === true`) vira:
* Um `media_player.music_assistant_` com controles completos.
* Um `button.music_assistant__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:
```json theme={null}
{
"media_content_type": "music",
"media_content_id": "spotify://track/4iV5W9uYEdYUVa79Axb7Rh"
}
```
```json theme={null}
{
"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:
```yaml theme={null}
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
```yaml theme={null}
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 errada,
servidor desligado, ou firewall bloqueando a porta 8095. Teste com
`curl http://: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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.