Che aspetto ha davvero un file XMLTV EPG (Con esempi)

Il modo più veloce per smettere di essere confuso dalle guide dei programmi è aprirne una e leggerla. XMLTV è semplice XML — prolisso, ma non complicato — e dieci minuti con un esempio reale ti faranno risparmiare ore di supposizioni sul motivo per cui la tua guida è vuota.

Questo articolo mostra un file reale, lo decodifica tag per tag, e poi utilizza questa comprensione per spiegare il singolo errore di guida più comune.

La cornice onesta: Tuneline è un lettore multimediale per contenuti che tu fornisci. Visualizza una guida da una fonte di programmazione che tu fornisci. Viene fornito senza guida e senza contenuti.

La struttura in una frase

Un file XMLTV contiene esattamente due tipi di cose: elementi <channel> che dichiarano cosa esiste, e elementi <programme> che indicano cosa va in onda e quando.

Ecco tutto. Tutto il resto è dettaglio.

Un esempio minimo e completo

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="example-grabber">

  <channel id="example.news.us">
    <display-name>Example News</display-name>
    <icon src="http://logos.example/news.png" />
  </channel>

  <programme start="20260806180000 +0000"
             stop="20260806190000 +0000"
             channel="example.news.us">
    <title lang="en">Evening Report</title>
    <desc lang="en">The day's headlines and analysis.</desc>
    <category lang="en">News</category>
  </programme>

</tv>

Questa è una guida valida e completa che descrive una fonte e un'ora di programmazione. Un file reale ha le stesse due forme ripetute migliaia di volte.

Decodificato tag per tag

Il formato del timestamp cattura tutti

start="20260806180000 +0000"

Leggi come YYYYMMDDHHMMSS seguito da un offset UTC. Quindi è il 6 agosto 2026, 18:00:00 UTC.

L'offset è la parte importante. Se un file lo omette, o ne dichiara uno che non corrisponde alla realtà, la tua guida si carica perfettamente e mostra tutto all'ora sbagliata. Questo è un problema completamente diverso da una guida vuota, ed è risolto nelle impostazioni del tuo fuso orario, non cambiando fonti. (Correzione orari sbagliati.)

Il join: perché la tua guida è vuota anche se il file si è caricato

Ecco la cosa che vale la pena capire, perché spiega la maggior parte dei reclami sulla guida.

La tua playlist e la tua guida sono due file separati che devono essere abbinati. L'abbinamento avviene su un ID.

Nella M3U:

#EXTINF:-1 tvg-id="example.news.us" tvg-logo="…",Example News
http://example.com/news.m3u8

Nella XMLTV:

<channel id="example.news.us">

tvg-id deve essere uguale a channel id. Esattamente — incluso maiuscole e punteggiatura.

Quando corrispongono, la voce mostra la sua programmazione. Quando non corrispondono, ottieni una voce con una guida vuota, e il file non è mai stato colpevole. (Il lato M3U di questo.)

Questo è il motivo per cui "Ho aggiunto una guida e non è successo nulla" di solito non è colpa della playlist né della guida. È che nessuno li ha fatti concordare sugli identificatori. Una guida che copre una regione diversa dalla tua playlist caricherà migliaia di programmi che non corrispondono a nessuna delle tue voci.

Come ispezionare una fonte di guida prima di fidarsi di essa

Prima di incolpare il tuo lettore, guarda il file.

1. È compresso? Molte fonti spediscono .xml.gz. È normale — la maggior parte dei lettori lo gestisce. Se lo stai ispezionando a mano, decomprimi prima.

2. Contiene effettivamente le tue fonti? Cerca nel file uno dei tuoi valori tvg-id. Se non c'è, quella guida non copre la tua lista, e nessuna impostazione cambierà questo.

curl -s "https://example.com/guide.xml.gz" | gunzip | grep -c "<channel "
curl -s "https://example.com/guide.xml.gz" | gunzip | grep "example.news.us"

Il primo ti dice quante fonti dichiara. Il secondo ti dice se la tua è una di loro.

3. Copre un intervallo di tempo utile? Controlla i valori start più vecchi e più recenti. Alcune guide gratuite hanno solo 24 ore; alcuni hanno due settimane. Una guida terminata ieri sembra identica a una rotta.

4. Quanto è grande? Le guide nazionali complete raggiungono decine o centinaia di megabyte senza compressione. È normale, ed è il motivo per cui il primo caricamento può richiedere minuti su un TV box. (Fonti XMLTV gratuite.)

Malformazioni comuni

I file di guida nel mondo reale si rompono in modi prevedibili:

• Una pagina di errore HTML salvata come .xml. Aprilo. Se la prima riga è <!DOCTYPE html>, il download ha avuto esito negativo e ha salvato l'errore.
• Ampersand non sfuggiti. Un semplice & invece di & in un titolo è XML non valido e può interrompere l'intera analisi. Un titolo errato, nessuna guida affatto.
• Voci <channel id> duplicate. Due dichiarazioni dello stesso ID; il comportamento dipende dal lettore.
• Programmi senza canale corrispondente. Voci di programmazione il cui attributo channel non corrisponde a nessun <channel id> dichiarato. Vengono eliminati silenziosamente.
• Tempi stop mancanti. Alcuni grabber li omettono e si aspettano che l'inizio del programma successivo implichi la fine. Alcuni lettori non lo deducono, lasciando vuoti.

Posso scriverne o modificarne uno da solo?

Sì. È XML, quindi qualsiasi editor di testo funziona, e per una piccola configurazione curata è totalmente pratico.

Modifiche utili:

• Cambia un <channel id> per abbinare il tvg-id che la tua playlist usa già — spesso più facile che modificare centinaia di righe di playlist.
• Riducilo. Elimina elementi <channel> e <programme> che non ti servono. Un file più piccolo si carica molto più velocemente su dispositivi limitati.
• Correggi l'offset se ogni volta è uniformemente sbagliato.

Due regole: salva come UTF-8, e mantienilo ben formato — un & non sfuggito può costarti l'intera guida.

Domande frequenti

Che aspetto ha un file EPG?

XML semplice con due tipi di elemento: <channel> che dichiarano ogni fonte, e <programme> che forniscono un'ora di inizio, ora di fine e titolo per ogni elemento programmato.

Qual è il formato di XMLTV?

XML, tipicamente servito come .xml o .xml.gz compresso con gzip. I timestamp sono YYYYMMDDHHMMSS più un offset UTC.

Perché la mia guida si carica ma non mostra nulla?

Quasi sempre perché i valori tvg-id della tua playlist non corrispondono ai valori <channel id> della guida. Il file si è caricato bene; non c'era nulla a cui unirlo.

Come faccio a verificare se una guida copre le mie fonti?

Scaricalo, decomprimi se necessario, e cerca una delle tue stringhe tvg-id. Se non è nel file, quella guida non descrive la tua lista.

Perché il mio file di guida è così grande?

Una guida nazionale con due settimane di programmazione per centinaia di fonti è genuinamente decine o centinaia di megabyte. È previsto, ed è il motivo per cui il primo caricamento è lento.

Posso modificare un file XMLTV?

Sì, in qualsiasi editor di testo. Salva come UTF-8 e mantieni il XML ben formato — un singolo & non sfuggito può rompere l'intera analisi.

Il risultato finale

• XMLTV contiene esattamente due cose: dichiarazioni <channel> e voci <programme>.
• I timestamp sono YYYYMMDDHHMMSS + offset UTC — un offset sbagliato significa dati giusti, orari sbagliati.
• La guida si unisce alla tua playlist su tvg-id = channel id, esattamente. La mancata corrispondenza è la causa principale di una guida vuota.
• Ispeziona prima di incolpare: decomprimi, grep il tuo ID, controlla l'intervallo di date.
• Un singolo & non sfuggito può invalidare un intero file di guida.

Hai una playlist e un URL della guida? Scarica Tuneline — aggiungi entrambi e la griglia si riempie. Gratuito e senza pubblicità.

— Shamir