Skip to main content

​
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

1

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Roku.
2

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

Pronto

Uma entidade media_player.roku_<serial>_media_player é criada. O MAC é capturado automaticamente para suportar Wake-on-LAN.

​
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

{
  "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

{
  "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

{
  "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: 
{
  "media_content_type": "music",
  "media_content_id": "https://exemplo.com/audio.mp3"
}
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.
Se você sabe o formato de deep-link de um app específico, passa direto como querystring no media_content_id: 
{
  "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: 
curl http://192.168.0.190:8060/query/apps
Retorna a lista XML com id, name e version de cada app instalado. IDs comuns:
AppID
Netflix12
YouTube837
Prime Video13
Disney+291097
Roku Media Player2213 ou 15985 (varia por modelo)
Apple TV551012
Pluto TV74519
Spotify22297

​
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 fica “off” mesmo com a TV ligada — algumas Roku TVs OEM (Hisense antigas) param o ECP em standby ativo. A integração faz polling de 30 s; o estado vai sincronizar no próximo ciclo.