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

# LinkPlay

> Controle alto-falantes LinkPlay (WiiM, Arylic, iEAST, Audio Pro) pelo Portal

# LinkPlay

Controla dispositivos baseados no módulo **LinkPlay** — a plataforma Wi-Fi de
áudio que equipa linhas como **WiiM Mini/Pro/Pro Plus**, **Arylic Up2Stream/A50**,
**iEAST**, **Audio Pro**, **DOSS**, **Medion** entre outras — via API HTTP local
(`/httpapi.asp?command=...`). Suporta play/pause/stop, próxima/anterior, volume,
mute, seleção de fonte (Wi-Fi, Bluetooth, Line In, Óptica, HDMI, USB DAC...) e
disparo de presets configurados no próprio aparelho.

## Pré-requisitos

* O alto-falante precisa estar **na mesma rede** do edge e com IP fixo (ou
  reserva DHCP).
* A integração roda em um **edge local**. Crie um em **Configurações → Edges**
  antes de adicionar.
* O LinkPlay precisa aceitar HTTP (porta 80) ou HTTPS (porta 443). A detecção é
  automática — o Portal tenta HTTP primeiro e cai para HTTPS se o aparelho só
  responde na porta segura (comum nos WiiM mais novos).

## Configurar

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

  <Step title="Informe o IP">
    Digite o IP local do dispositivo (ex: `192.168.0.60`). O Portal consulta o
    aparelho, detecta modelo, firmware, UUID e lista de fontes suportadas.
  </Step>

  <Step title="Pronto">
    Uma entidade `media_player.linkplay_<uuid>_media_player` é criada. A lista
    de fontes (`source_list`) é derivada do bitmask `plm_support` do próprio
    aparelho — você só vê as entradas que ele realmente aceita.
  </Step>
</Steps>

## Funcionalidades

* Play / Pause / Stop / Next / Previous track
* Volume (ajuste absoluto 0–100 e mute/unmute)
* Seek (`media_seek`) quando o stream expõe duração
* Trocar fonte: `Wifi`, `AirPlay`, `DLNA`, `Spotify`, `Tidal`, `Bluetooth`,
  `Line In`, `Optical`, `Coaxial`, `USB DAC`, `HDMI` (conforme o modelo)
* Tocar URL arbitrária (MP3, FLAC, HLS, DLNA) via `play_media`
* Disparar preset configurado no aparelho (1–10)
* Reboot do dispositivo e sincronização de hora (via `button.press`)
* Metadados de reprodução: título, artista, álbum, posição/duração, e arte da
  capa (apenas em WiiM, que expõe `getMetaInfo`)

## Reproduzir mídia (`media_player.play_media`)

O LinkPlay aceita URL direta — basta chamar:

```json theme={null}
{
  "media_content_type": "music",
  "media_content_id": "https://exemplo.com/track.mp3"
}
```

Formatos aceitos pelo módulo LinkPlay: MP3, FLAC, WAV, AAC, OGG, M4A, HLS
(`.m3u8`). Para rádios internet, passe a URL direta do stream (`http://...pls`
não funciona — resolva o PLS antes de enviar).

## Presets

Os presets 1–10 são configurados no próprio app LinkPlay / 4STREAM / WiiM Home
(dependendo do fabricante). Pelo Portal você aciona um preset com a ação
customizada `media_player.play_preset`:

```json theme={null}
{
  "preset_number": 3
}
```

Chama `MCUKeyShortClick:3` no aparelho, que começa a tocar o conteúdo salvo no
preset 3 (rádio, playlist Spotify, playlist local etc.).

## Multiroom

A API multiroom (grupo de leader + followers) está disponível no `python-linkplay`
que inspirou essa integração, mas **não** está exposta nesta versão. O suporte a
agrupamento (`join_players` / `unjoin_player`) depende de termos múltiplos
LinkPlay registrados simultaneamente no mesmo edge — e um painel dedicado no
dashboard para gerir os grupos. Fica para uma iteração futura.

## Dashboard

Use o card **Media Player** para exibir estado (tocando/pausado/parado), fonte
atual, metadata (título/artista/álbum/capa quando disponível) e controles
padrão. O botão **Reproduzir mídia** abre um modal para colar URL direta.

## Solução de problemas

* **"Não foi possível conectar ao LinkPlay em `<ip>`"** — IP errado, aparelho
  desligado da tomada, ou a rede do edge não enxerga a rede do dispositivo
  (VLANs separadas). O LinkPlay não responde a ICMP em alguns firmwares; teste
  com `curl http://<ip>/httpapi.asp?command=getStatusEx` para confirmar.
* **Nome do dispositivo veio como hexadecimal** — alguns firmwares antigos
  serializam `DeviceName` como hex ASCII. O Portal decodifica automaticamente
  quando reconhece o padrão; se um nome continuar hex, renomeie o aparelho pelo
  app oficial do fabricante.
* **`source_list` está vazia (só "Wifi")** — o aparelho não reportou
  `plm_support` (comum em sticks antigos). A fonte Wi-Fi/rede continua funcional
  mesmo sem a lista de entradas físicas.
* **Volume não aceita valores fracionados** — o LinkPlay só aceita inteiros
  0–100; o Portal arredonda `volume_level` para o inteiro mais próximo.
* **Arte da capa (`entity_picture`) não aparece** — apenas aparelhos **WiiM**
  expõem `getMetaInfo`. Outros fabricantes não disponibilizam a URL da capa via
  HTTP API.
* **Comando funciona mas o estado demora para atualizar** — o polling é de 5 s.
  Mudanças iniciadas por outro app (4STREAM, WiiM Home, remote físico) só
  refletem no Portal no próximo ciclo. Para comandos acionados pelo Portal
  (play/pause/volume) usamos atualização otimista — o estado no card muda
  imediatamente.


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