Se o guia de canais do seu IPTV mostra os programas certos, mas nos horários errados — cada programa com uma ou duas horas de diferença em relação a quando realmente vai ao ar —, você está enfrentando um dos bugs de XMLTV mais comuns e persistentes que existem. A correção geralmente é uma alteração de uma linha na URL. Descobrir para que lado ajustar leva cerca de cinco minutos.

Este guia explica onde o bug realmente reside, como descobrir o ajuste necessário e como aplicá-lo. O EPG timezone shifter (ajustador de fuso horário EPG) neste site faz o ajuste real; este artigo explica como usá-lo corretamente.

Two timelines: the wall-clock row marks BBC News at 18:00; the EPG row shows the same programme at 16:00, then animates a +2-hour shift to align with wall-clock.

Mesmo programa, dois relógios: o EPG fica duas horas atrás do horário real (wall-clock) até o ajustador realinhá-lo.

Por que ocorrem bugs de fuso horário no XMLTV

XMLTV é um formato com 25 anos de idade. Todo programa tem um atributo start e um stop que se parecem com isto:

<programme start="20260507180000 +0000" stop="20260507190000 +0000" channel="bbc1">

Os 14 dígitos são o horário real; o +0000 final é o fuso horário (offset) em que esse horário real se encontra. Assim, 20260507180000 +0000 significa "18:00 UTC em 7 de maio de 2026". O player lê ambos, converte para o seu fuso horário local e exibe "20:00" se você estiver no horário CET.

Isso funciona se o arquivo XMLTV for internamente consistente. Mas o XMLTV é gerado por uma longa cadeia de programas:

  1. O sistema de listagem da emissora original, em seu fuso horário local.
  2. Um agregador regional que talvez converta para uma zona regional.
  3. O raspador (scraper) do provedor de IPTV, que provavelmente o arredonda novamente.
  4. O exportador XMLTV do seu provedor, que coloca um +0000 no final, independentemente de os dígitos estarem realmente em UTC.

Qualquer um desses passos pode introduzir um erro de fuso horário, e o formato não fornece um checksum de validação. O arquivo de saída parece bem formatado. O player não consegue detectar que os dígitos dentro não correspondem ao fuso declarado. O resultado é um guia que está seguramente errado em um número inteiro de horas.

Uma segunda classe de bug é quando o arquivo XMLTV omite totalmente o fuso:

<programme start="20260507180000" stop="20260507190000" channel="bbc1">

Sem o fuso, o player tem que adivinhar. A maioria dos players assume "os dígitos estão no seu horário local"; alguns assumem UTC. Se o provedor quis dizer UTC e seu player assume local, todo programa estará errado pelo valor do seu fuso local.

Em ambos os casos, os dados subjacentes estão corretos — os números só precisam ser somados ou subtraídos para cair no lugar certo.

Descobrindo de qual ajuste você precisa

A correção é "adicionar N horas a cada registro de tempo no arquivo XMLTV". Para escolher N:

Passo 1: Escolha um único canal onde você sabe o que está passando agora

Abra o player. Encontre um canal que esteja exibindo conteúdo ao vivo e que você saiba exatamente o que é — o jornal local às 18:00, o BBC News no início da hora, horário nobre em um canal principal. O ponto é ter uma âncora conhecida: "este canal está exibindo X agora mesmo, neste exato horário real no meu relógio".

Passo 2: Olhe o que o EPG diz

Olhe para a entrada "passando agora" (now playing) do mesmo canal em seu player. Anote o horário de início que ele afirma. Se disser que o programa começou às 16:00, mas na verdade começou às 18:00, o EPG está duas horas atrasado — você precisa adicionar 2 a cada registro de tempo.

Se o EPG mostrar que o programa "começa em duas horas", mas ele já está no ar, o EPG está duas horas adiantado — você precisa subtrair 2.

Passo 3: Confirme o mesmo ajuste em vários canais

Escolha um segundo e terceiro canal e verifique se o ajuste é consistente. Se o canal A estiver errado em +2 e o canal B em -3, você não tem um problema de fuso horário; você tem dados inconsistentes por canal e um ajuste fixo não consertará ambos. (A inconsistência entre vários canais é rara e geralmente significa que o provedor uniu feeds de várias fontes sem harmonizar os fusos horários — a única correção aí é pedir ao provedor que limpe seus dados).

Em mais de 95% dos casos, o ajuste é consistente em todos os canais e o valor é um de: ±1, ±2, ±3, às vezes ±5 ou ±8 para usuários em fusos horários distantes de onde o feed de origem do provedor se origina.

Aplicando o ajuste

Uma vez que você saiba o ajuste, a ferramenta shifter lhe dá uma nova URL que entrega o XMLTV do seu provedor com cada registro de tempo deslocado exatamente por esse valor. Substitua a URL do EPG do seu player pela nova e os horários do guia se alinharão.

Dois pontos práticos:

  • O shifter é um proxy, não um uso único. Seu player atualizará o EPG a cada poucas horas. Cada atualização busca novamente o XMLTV do seu provedor por meio do shifter e reaplica o ajuste. Não há cache do nosso lado; os dados oficiais da origem continuam prevalecendo, apenas com os horários alterados.
  • Suas credenciais vão na URL. A maioria dos provedores de IPTV fornece XMLTV em uma URL como http://server/xmltv.php?username=...&password=.... O shifter lê essas credenciais apenas no momento da requisição para buscar a origem — ele não as registra, não faz cache, não as indexa. A string de consulta também é removida antes que nossos logs de acesso sejam gravados.

O que o shifter não conserta

Alguns problemas vizinhos parecem bugs de fuso horário, mas não são:

Programas perdem e ganham sincronia

Se o EPG está às vezes certo e às vezes não, você não está diante de um problema de fuso horário. Possibilidades:

  • Os dados do provedor estão desatualizados. Entradas de programas mais antigas são atualizadas em um ritmo lento; as mais recentes vêm de um feed mais novo. Os dois feeds podem estar em fusos horários diferentes, misturados no mesmo XMLTV. Difícil consertar sem a cooperação do provedor.
  • Horário de Verão (DST). Se o seu fuso horário local observa o horário de verão, mas o XMLTV do provedor não (ou vice-versa), a diferença muda em uma hora duas vezes por ano. Um ajuste fixo só funciona para a metade do ano em que você calibra.

Para problemas de DST especificamente, você pode manter duas URLs ajustadas — uma para cada metade do ano — e alternar a fonte de EPG do player duas vezes por ano. É irritante, mas funciona.

O guia está vazio, não errado

"Sem informação" / guia em branco é um problema diferente. Veja como consertar EPG não carregando — a causa aí geralmente é incompatibilidade de tvg-id entre a playlist e o XMLTV, não o fuso horário.

Canais específicos estão errados, mas a maioria está certa

Se todo o resto está certo e apenas um ou dois canais estão errados, os dados de origem desses canais estão errados no provedor. O ajuste fixo quebrará os canais certos para consertar os errados. Peça ao provedor para consertar os dados, ou aceite que os horários desses canais específicos serão aproximações.

Por que não detectamos o ajuste automaticamente

O shifter recebe o ajuste como um parâmetro explícito em vez de tentar adivinhar. Poderíamos, em teoria, buscar o arquivo, comparar os horários de início dos programas com o "agora" e adivinhar. Nós não o fazemos porque:

  • A "resposta certa" depende de em qual canal você se baseia. Canais diferentes podem discordar.
  • Um palpite automático errado é pior do que perguntar. Se nós silenciosamente ajustarmos pelo valor errado, você terá um guia que está consistentemente errado por um valor diferente, e você perderá tempo depurando.
  • O usuário tem o contexto. Ele sabe que "o jornal da BBC One às 18:00 está sendo exibido como 16:00 no guia". A ferramenta pode aplicar esse conhecimento com um clique; derivá-lo da observação da rede não é confiável.

Após a correção

Verifique com mais uma passagem pelo Passo 1 acima: canal conhecido, programa atual, verifique o tempo de reprodução atual do player. Agora ele deve corresponder ao relógio real. Se corresponder, a correção é permanente — seu player continuará atualizando pela URL do shifter e o ajuste permanecerá aplicado.

Se algo mais ainda estiver errado (canais que não mudaram, IDs incompatíveis, lacunas na cobertura), esses são problemas separados e usar o Validador EPG é o próximo passo. O validador analisa um arquivo XMLTV e relata problemas estruturais independentes do tempo — útil quando você quer saber "o arquivo em si está bem formatado" em vez de "os horários estão certos".

Para todo o resto do lado do IPTV, o Xtream credentials checker e o M3U playlist tester cobrem as extremidades da playlist e credenciais. Junto com o EPG timezone shifter, essas quatro ferramentas lidam com a maior parte da resolução de problemas que as pessoas acabam fazendo no escuro em fóruns.