"L'EPG non si carica" è in assoluto la lamentela più comune tra chi configura l'IPTV su Android TV, e quasi tutte le cause sembrano identiche dal punto di vista dell'utente: la lista canali va bene, il video viene riprodotto, ma la guida è vuota. La buona notizia è che i tipi di errore sono limitati. Ce ne sono circa sei e puoi escluderne la maggior parte in un paio di minuti.

Questa guida li esamina uno per uno, nell'ordine in cui vale la pena controllarli. Se prima di iniziare puoi incollare il tuo URL XMLTV nel validatore EPG, salterai completamente i passaggi 2–4.

Due pannelli affiancati — un frammento M3U con tvg-id="bbc1" e un frammento XMLTV in cui l'ID del canale oscilla tra "BBC1" e "bbc1". Un connettore tra di loro passa da una croce rossa a un segno di spunta verde quando gli ID corrispondono o meno.

Gli ID dei canali vengono confrontati byte per byte: una singola lettera maiuscola è sufficiente per lasciare un canale con una guida vuota.

1. Controlla di avere effettivamente un URL EPG

La prima cosa da verificare è se hai configurato una fonte per la guida. Alcuni provider IPTV forniscono la lista canali (M3U) e la guida (XMLTV) come due URL separati, e un buon numero di utenti ne configura uno dando per scontato che l'altro sia incluso.

Apri le impostazioni delle sorgenti del tuo player e cerca due campi distinti. L'URL M3U finisce in .m3u, .m3u8 o contiene type=m3u_plus. L'URL XMLTV di solito finisce in .xml, .xml.gz o contiene xmltv.php. Se è compilato solo un campo, questo è il tuo problema. La maggior parte dei provider in stile Xtream espone l'XMLTV sullo stesso hostname della playlist; il percorso è in genere /xmltv.php?username=…&password=… con le stesse credenziali.

2. Conferma che l'URL restituisca effettivamente XMLTV

Incolla l'URL in un browser. Dovresti vedere dell'XML — testo che inizia con <?xml o <tv> e pieno di tag <channel> e <programme>. Se invece vedi una pagina HTML, il tuo provider ti ha reindirizzato a un login o a un captive portal, e il tuo player riceve la stessa risposta. La soluzione spetta al provider: l'URL necessita di credenziali diverse o di un token aggiornato.

Se vedi dell'XML ma è piccolissimo — meno di qualche KB — il tuo provider ha restituito un documento vuoto. Anche questo è un problema suo; la maggior parte dei file XMLTV per qualche migliaio di canali va dai 5 ai 50 MB.

3. Controlla la struttura del file

Questo è il momento in cui il validatore EPG si rende utile. Incolla l'URL nel validatore e guarda i quattro numeri in alto:

  • Channels (Canali). Dovrebbero corrispondere all'incirca al numero di canali nel tuo M3U. Se è un decimo di quelli, il file non è la guida completa del tuo provider.
  • Programmes (Programmi). Dovrebbero essere molte migliaia. Una guida con meno di 100 programmi in totale non mostrerà nulla di utile.
  • Covering next 24h (Copertura per le prossime 24 ore). Il numero più importante in assoluto. Se è zero, la tua guida è obsoleta — il file viene elaborato, ma ogni suo elemento è nel passato. Il player non ha nulla da visualizzare.
  • Hours total (Ore totali). Un EPG in salute copre tra le 24 e le 168 ore future rispetto ad ora. Meno di 24 significa che la guida si esaurirà oggi.

4. Controlla il pannello dei problemi

Se i numeri sembrano corretti ma la guida è ancora vuota, la lista dei problemi del validatore è il prossimo posto in cui guardare. Tre problemi sono comuni negli output dei provider reali:

Programmi orfani (Orphan programmes). I programmi fanno riferimento a ID di canale che non sono dichiarati come <channel> nello stesso file. I player più rigidi (la maggior parte di quelli moderni per Android TV) li scartano in fase di importazione — il programma non ha un canale a cui collegarsi, perciò scompare. Se il tuo provider invia qualche centinaio di orfani, è normale e innocuo. Se ne invia decine di migliaia, ecco perché enormi sezioni della tua guida sono vuote.

Canali duplicati (Duplicate channels). Lo stesso ID del canale appare in <channel> più di una volta. La maggior parte dei parser mantiene la prima dichiarazione e scarta silenziosamente il resto. Se quello scartato aveva un nome visualizzato diverso, il canale apparirà nella guida ma con l'etichetta sbagliata.

Nessuna copertura "in riproduzione ora" (No now-playing coverage). Il controllo principale del validatore: c'è qualche canale che sta trasmettendo un programma in questo momento? Se la risposta è zero, la guida apparirà completamente vuota in qualsiasi player ben progettato, anche se il file XMLTV è tecnicamente valido. Guida obsoleta. Il provider deve aggiornarla.

5. Verifica la corrispondenza dell'ID del canale

Questo inganna quasi tutti. Il valore <channel id="…"> dell'XMLTV deve corrispondere esattamente al tvg-id="…" nel tuo M3U. Sensibile alle maiuscole/minuscole, nessuna corrispondenza approssimativa. Se il tuo M3U dice tvg-id="bbc1" e il tuo XMLTV dice <channel id="BBC1">, il player non ha modo di collegarli, e il canale mostra la cella della guida vuota.

Per controllare, apri il tuo M3U in un editor di testo e guarda qualsiasi valore tvg-id. Quindi controlla lo stesso canale nella tabella "Canali principali" del validatore. Gli ID dovrebbero essere identici byte per byte. Se non lo sono, hai tre opzioni:

  1. Trovare un file di mappatura dei tvg-id del tuo provider (alcuni li pubblicano).
  2. Modificare manualmente il tuo M3U per far corrispondere gli ID dell'EPG.
  3. Passare a un player che esegua una corrispondenza approssimativa in base al nome visualizzato. Klipa lo fa — ma la maggior parte non lo fa.

6. Controlla il fuso orario

Le specifiche XMLTV usano timestamp YYYYMMDDHHMMSS +ZZZZ. Alcuni provider rimuovono l'offset, lasciando timestamp nudi e senza fuso orario. I parser rigidi li trattano come UTC; i parser indulgenti tirano a indovinare in base alla lingua di sistema; entrambi a volte sbagliano, e il risultato è una guida sfasata di diverse ore — i programmi compaiono nella fascia oraria sbagliata, o i programmi della scorsa notte si presentano come odierni.

Se le voci della tua guida sembrano corrette ma sfasate, quasi certamente è questa la causa. La soluzione è brutta: hai bisogno di uno strumento che sposti ogni timestamp di N ore. Finché non rilasceremo il variatore di fuso orario per EPG come strumento, l'alternativa è segnalare il problema al tuo provider chiedendogli di includere l'offset nel suo output.

Quando tutto il resto fallisce

Se hai controllato tutti e sei i punti e la guida continua a non caricarsi, il problema risiede nel player stesso. La maggior parte dei moderni player IPTV memorizza l'EPG nella cache in modo aggressivo — a volte per ore dopo un aggiornamento. Forza la cancellazione della cache dell'EPG o disinstalla e reinstalla l'app per forzare un'importazione pulita.

Klipa non memorizza in cache un EPG obsoleto: per impostazione predefinita esegue un nuovo recupero ogni sei ore, e puoi aggiornare manualmente dalle impostazioni. Se vuoi un player che gestisca già correttamente queste sei modalità di guasto senza dover fare nulla, questa è la soluzione.