The playlist and guide have different jobs
A playlist entry normally contains a stream URL, display name and optional tvg-id. An XMLTV document defines channel records and programme records with start times, stop times, titles, descriptions and other schedule metadata. The player combines them at import time.
Channel identifiers connect the two datasets
The playlist tvg-id should equal the XMLTV channel id exactly. Matching only by display name is fragile because punctuation, localisation, HD suffixes and regional variants can differ.
#EXTINF:-1 tvg-id="example.news",Example News
https://stream.example.com/news.m3u8
<channel id="example.news">
<display-name>Example News</display-name>
</channel>Programme records build the schedule
Each programme references a channel identifier and carries a time range. Players convert those timestamps into the viewer’s local time and lay the records out in a grid. The guide does not make the stream seekable or enable catch-up by itself; those features require media and provider support.
Why an EPG appears empty or shifted
- Playlist tvg-id and XMLTV channel id do not match
- The XMLTV feed is stale, unavailable or malformed
- Programme timestamps use an unexpected or incorrectly interpreted offset
- The player cached an old guide and has not refreshed it
- Several regional channels share a similar name but different schedules
Maintain a stable guide integration
Choose one authoritative guide source for each channel set, preserve stable IDs and refresh on a predictable schedule. Validate the XML before distributing it, monitor how far into the future listings extend and keep guide access credentials separate from public playlist files.