"EPG not loading" é a queixa mais comum entre quem configura IPTV em Android TV, e quase todas as causas têm o mesmo aspeto do lado do utilizador: a lista de canais está bem, o vídeo toca, mas o guia está em branco. A boa notícia é que os modos de falha são poucos. São cerca de seis e dá para excluir a maior parte em poucos minutos.
Este guia percorre cada um pela ordem que vale a pena verificar. Se conseguires colar o teu URL XMLTV no validador de EPG antes de começar, saltas inteiramente os passos 2 a 4.
Os IDs de canal são comparados byte a byte: uma única letra maiúscula é o suficiente para deixar um canal com o guia em branco.
1. Confirma que tens mesmo um URL de EPG
A primeira coisa a verificar é se chegaste a configurar uma fonte de guia. Há fornecedores de IPTV que entregam a lista de canais (M3U) e o guia (XMLTV) como dois URLs separados, e uma boa parte dos utilizadores configura um e assume que o outro veio incluído.
Abre as definições de fontes do teu leitor e procura dois campos distintos. O URL M3U acaba em .m3u, .m3u8 ou contém type=m3u_plus. O URL XMLTV costuma acabar em .xml, .xml.gz ou conter xmltv.php. Se só um campo está preenchido, o problema é esse. A maioria dos fornecedores no estilo Xtream expõe o XMLTV no mesmo nome de servidor da playlist; o caminho é tipicamente /xmltv.php?username=…&password=… com as mesmas credenciais.
2. Confirma que o URL devolve mesmo XMLTV
Cola o URL num browser. Devias ver XML — texto a começar por <?xml ou <tv>, cheio de tags <channel> e <programme>. Se vês uma página HTML, o teu fornecedor redirecionou-te para um login ou um portal cativo, e o teu leitor está a receber a mesma resposta. A correção é do lado do fornecedor: o URL precisa de outras credenciais ou de um token novo.
Se vês XML mas é minúsculo — menos de uns kilobytes — o teu fornecedor devolveu um documento vazio. Também é problema deles; a maioria dos ficheiros XMLTV para uns milhares de canais tem entre 5 e 50 MB.
3. Verifica a estrutura do ficheiro
É aqui que o validador de EPG mostra ao que veio. Cola o URL no validador e olha para os quatro números no topo:
- Canais. Deve corresponder grosso modo ao número de canais da tua M3U. Se for um décimo, o ficheiro não é o guia completo do teu fornecedor.
- Programas. Devem ser muitos milhares. Um guia com menos de 100 programas no total não vai mostrar nada de útil.
- Cobertura das próximas 24h. O número mais importante. Se for zero, o teu guia está obsoleto — o ficheiro abre, mas todas as entradas lá dentro estão no passado. O leitor não tem nada para mostrar.
- Horas no total. Um EPG saudável cobre 24 a 168 horas para a frente a partir de agora. Menos de 24 quer dizer que o guia esgota hoje.
4. Olha para o painel de problemas
Se os números parecem bem mas o guia continua vazio, a lista de problemas do validador é o sítio seguinte a consultar. Três problemas são comuns em ficheiros reais:
Programas órfãos. Programas que referenciam IDs de canal que não estão declarados como <channel> no mesmo ficheiro. Leitores estritos (a maioria dos modernos em Android TV) deitam-nos fora na importação — o programa não tem canal a que se ligar, por isso desaparece. Se o teu fornecedor entrega umas centenas de órfãos, é normal e inofensivo. Se entrega dezenas de milhares, é por isso que tens secções enormes do guia em branco.
Canais duplicados. O mesmo channel id aparece em <channel> mais do que uma vez. A maioria dos parsers fica com a primeira declaração e descarta as outras em silêncio. Se a descartada tinha um display name diferente, o canal aparece no guia mas com a etiqueta errada.
Sem cobertura no momento. A verificação principal do validador: há algum canal a mostrar um programa agora mesmo? Se a resposta for zero, o guia vai aparecer inteiramente em branco em qualquer leitor que se preze, mesmo que o ficheiro XMLTV seja tecnicamente válido. Guia obsoleto. O fornecedor tem de o refrescar.
5. Verifica o emparelhamento dos IDs de canal
Esta apanha quase toda a gente. O valor de <channel id="…"> do XMLTV tem de bater certo, exatamente, com o tvg-id="…" na tua M3U. Sensível a maiúsculas, sem correspondência aproximada. Se a M3U diz tvg-id="bbc1" e o XMLTV diz <channel id="BBC1">, o leitor não tem forma de os ligar e o canal mostra uma célula de guia em branco.
Para verificar, abre a tua M3U num editor de texto e olha para qualquer valor tvg-id. Depois confirma o mesmo canal na tabela "Canais com mais programas" do validador. Os IDs devem ser byte a byte idênticos. Se não forem, tens três opções:
- Arranjar um ficheiro de mapeamento de tvg-id junto do teu fornecedor (alguns publicam-nos).
- Editar a M3U à mão para que os IDs coincidam com os do EPG.
- Mudar para um leitor que faça emparelhamento aproximado por display name. O Klipa faz — mas a maioria não.
6. Verifica o fuso horário
A especificação XMLTV usa timestamps YYYYMMDDHHMMSS +ZZZZ. Há fornecedores que retiram o offset, ficando timestamps nuas, sem fuso. Parsers estritos tratam-nas como UTC; parsers permissivos adivinham com base no locale do sistema; um e outro acertam por vezes mal, e o resultado é um guia desfasado em várias horas — os programas aparecem na faixa horária errada, ou os programas de ontem à noite aparecem como sendo de hoje.
Se as entradas do guia parecem corretas mas desfasadas, é quase de certeza esta a causa. A correção é feia: precisas de uma ferramenta que desloque todas as timestamps em N horas. Até lançarmos o ajustador de fuso horário do EPG como ferramenta, a alternativa é abrir uma queixa junto do teu fornecedor a pedir que inclua o offset no que ele emite.
Quando nada disto resolve
Se já verificaste os seis e o guia continua sem carregar, a falha está no próprio leitor. A maioria dos leitores IPTV modernos faz cache agressiva do EPG — por vezes durante horas depois de uma atualização. Limpa a cache do EPG à força, ou desinstala e reinstala a app para forçar uma importação limpa.
O Klipa não mantém EPG obsoleto em cache: por defeito volta a buscar a cada seis horas, e podes refrescar manualmente nas definições. Se queres um leitor que já trata destes seis modos de falha corretamente logo à partida, é este o argumento.