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

# Roku

> Controle Roku TVs e dispositivos de streaming pelo Portal

# Roku

Controla **Roku TVs** (Hisense, TCL, AOC etc. com Roku OS), sticks e set-top boxes
Roku pela API externa de controle (ECP — *External Control Protocol*) na porta
`8060`. Suporta ligar/desligar, controle de mídia, troca de fonte, lançamento de
apps e reprodução de mídia por deep-link.

## Pré-requisitos

* O Roku precisa estar **ligado** (ou em standby acordável via Wake-on-LAN) e na
  mesma rede do edge.
* O ECP precisa estar **liberado** no Roku: vá em **Configurações → Sistema →
  Configurações avançadas do sistema → Controle por aplicativos móveis → Acesso à
  rede** e selecione **"Padrão"** (não "Permissivo").
* A integração precisa rodar em um **edge local**. Crie um em **Configurações →
  Edges** antes de adicionar.

## Configurar

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

  <Step title="Informe o IP">
    Digite o IP local do Roku (ex: `192.168.0.190`). O nome amigável é opcional —
    se vazio, é puxado do nome configurado no próprio aparelho.
  </Step>

  <Step title="Pronto">
    Uma entidade `media_player.roku_<serial>_media_player` é criada. O MAC é
    capturado automaticamente para suportar Wake-on-LAN.
  </Step>
</Steps>

## Funcionalidades

* Liga/desliga (com Wake-on-LAN quando em standby profundo)
* Play / Pause / Stop / Next / Previous track
* Volume up/down/mute (sem `set_volume` — Roku é controle remoto, não tem ajuste
  absoluto via ECP)
* Channel up/down (em Roku TVs com sintonizador)
* Trocar de fonte (HDMI 1-4, AV, Tuner) ou lançar app instalado por nome
* Reproduzir mídia por URL via Roku Media Player
* Reproduzir vídeo do YouTube por deep-link
* Lançar qualquer app instalado por ID

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

A ação aceita combinações de `media_content_type` e `media_content_id`. O comportamento
muda conforme o tipo:

### Lançar um app por ID

```json theme={null}
{
  "media_content_type": "app",
  "media_content_id": "12"
}
```

Abre o app cujo id é `12` (Netflix). Use `GET http://<roku-ip>:8060/query/apps`
no terminal para listar todos os apps instalados e seus IDs.

### Vídeo do YouTube

```json theme={null}
{
  "media_content_type": "url",
  "media_content_id": "https://youtu.be/dQw4w9WgXcQ"
}
```

O Portal detecta URLs do YouTube (`youtu.be`, `youtube.com/watch?v=`, `youtube.com/embed/`),
extrai o ID do vídeo e abre o app YouTube direto no conteúdo. Funciona tanto na
versão `Roku Channel Store` quanto em RAS / OEMs (a deep-link do YouTube não tem
a restrição que afeta o Roku Media Player — veja a próxima seção).

### URL arbitrária (MP4, HLS, etc.) via Roku Media Player

```json theme={null}
{
  "media_content_type": "url",
  "media_content_id": "https://exemplo.com/video.mp4"
}
```

O Portal procura o **Roku Media Player** instalado (por nome — funciona com
`Roku Media Player`, `Media Player`, `Play on Roku`) e o lança com parâmetros
`u`, `t=v`, `videoFormat=<mp4|hls|dash|mkv|...>` e `videoName=<arquivo>`. O
formato é inferido da extensão da URL.

Áudio:

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

<Warning>
  **Limitação conhecida em Roku TVs OEM (AOC, alguns TCL, alguns Hisense):** a
  versão do Roku Media Player que vem de fábrica em algumas TVs OEM **ignora os
  parâmetros de URL** — abre o app mas não inicia a reprodução. O ECP responde
  `200 OK`, mas o canal mostra a tela inicial dele em vez de tocar o stream.
  Não é bug do Portal nem do Home Assistant: é decisão do firmware OEM.

  Workarounds:

  * **DLNA** — exponha o vídeo via DLNA na rede local (MiniDLNA, Plex, Universal
    Media Server). O RMP OEM aceita DLNA mesmo quando bloqueia URL direta.
  * **App específico com deep-link** — YouTube, Pluto TV, Tubi, etc. continuam
    funcionando pelo `media_content_type: "app"` ou pela detecção automática (para
    YouTube).
  * **Sideload** — em modo desenvolvedor, instalar um canal customizado que aceite
    URLs. Fora do escopo da integração.
</Warning>

### Deep-link arbitrário (avançado)

Se você sabe o formato de deep-link de um app específico, passa direto como
querystring no `media_content_id`:

```json theme={null}
{
  "media_content_type": "movie",
  "media_content_id": "12?contentID=<netflix-title-id>"
}
```

O Portal trata isso como `POST /launch/<appId>?contentID=...&mediaType=movie&...`.

## Encontrando IDs de app

No terminal de qualquer máquina na mesma rede:

```bash theme={null}
curl http://192.168.0.190:8060/query/apps
```

Retorna a lista XML com `id`, `name` e `version` de cada app instalado. IDs comuns:

| App               | ID                                   |
| ----------------- | ------------------------------------ |
| Netflix           | `12`                                 |
| YouTube           | `837`                                |
| Prime Video       | `13`                                 |
| Disney+           | `291097`                             |
| Roku Media Player | `2213` ou `15985` (varia por modelo) |
| Apple TV          | `551012`                             |
| Pluto TV          | `74519`                              |
| Spotify           | `22297`                              |

## Dashboard

Use o card **Media Player** para exibir o estado (ligado/desligado, app atual,
arte da capa quando disponível) e os controles padrão. O botão "Reproduzir mídia"
abre um modal para colar URL/ID — usável tanto para YouTube quanto para Roku
Media Player.

## Solução de problemas

* **`403 Forbidden` ao chamar qualquer ação** — o ECP está em modo restrito.
  Em **Configurações → Sistema → Configurações avançadas do sistema → Controle
  por aplicativos móveis → Acesso à rede**, troque para **"Padrão"** (a opção
  "Permissivo" só bloqueia comandos sensíveis e também serve).
* **`/launch/<app>` retorna 200, mas o vídeo não toca** — Roku Media Player OEM
  bloqueado (veja o aviso acima). Confirme abrindo o app móvel da Roku no
  celular: se "Tocar no Roku" também não funcionar, o RMP do seu modelo tem a
  restrição. Use DLNA ou outro app.
* **`media_content_id (app id) is required`** — você passou `media_content_type:
  "app"` mas `media_content_id` vazio. Coloque o id numérico do app (`12`, `837`
  etc.).
* **"Não foi possível conectar ao dispositivo Roku"** — o Roku está em standby
  profundo (ECP desligado). Se o MAC foi capturado, ligar via `media_player.turn_on`
  envia Wake-on-LAN; se não, ligue manualmente uma vez e o ECP volta a responder.
* **Estado de energia (ligada/desligada)** — o Roku não tem um endpoint
  dedicado de power state; a integração usa o campo `power-mode` de
  `/query/device-info` (`PowerOn` = ligada; `Ready`/`Headless`/`DisplayOff` =
  standby) e, quando o aparelho recusa a conexão (standby profundo, ECP
  desligado), assume desligada. O polling é de 30 s, então uma mudança leva até
  um ciclo para refletir no portal.
* **Estado fica "off" mesmo com a TV ligada** — Rokus muito antigos que não
  expõem `power-mode` são tratados como ligados enquanto o ECP responder; se o
  modelo para o ECP em standby ativo, o estado só sincroniza no próximo ciclo
  de polling (30 s).