EPG for IPTV: XMLTV, DVB EIT, Mapping & Timing | Callaba

An IPTV electronic programme guide is a metadata pipeline beside the video pipeline. It maps stable channel identities to scheduled programmes, normalizes time zones, publishes updates before viewers need them and reconciles late changes. A healthy stream can have a broken EPG, and a perfect schedule does not prove that the channel plays.

Keep schedule data and media health independent

Choose XMLTV or DVB EIT for the actual delivery system

XMLTV is an exchange format commonly used by IPTV applications. Its DTD defines a required id on each channel; each programme requires start and channel, while stop is optional. Titles are required, while descriptions, categories, icons, episode numbers, ratings and other fields can be added.

DVB transport streams use Service Information. ETSI EN 300 468 V1.19.1 defines the Event Information Table: optional present/following and schedule tables identify events by service, time and descriptors on PID 0x0012, with their presence signalled in the Service Description Table. XMLTV and EIT solve related guide problems but are not interchangeable payloads. Select one canonical internal model, then build explicit import or output adapters.

Design stable channel mapping before importing programmes

Give every channel one durable internal ID. Map each supplier's channel ID, Callaba player identity, display name, logo and regional variant to that record. Reject an ambiguous match instead of choosing the first familiar name. A rename should change a label, not break months of schedules.

Version the mapping and retain who changed it. Before activating a feed, calculate unmapped source channels, duplicate targets and guide channels without active media. Set a release threshold: for example, no high-priority channel may be unmapped, and every visible channel must have a verified player URL.

Normalize timestamps at ingestion

XMLTV permits timestamps with an explicit offset and assumes UTC when no zone is present. Preserve the supplier value for audit, parse it under a declared rule and store the normalized instant in UTC. Convert to viewer-local time only at presentation. A server's local time zone must never silently reinterpret the feed.

Test daylight-saving transitions, half-hour offsets, events crossing midnight and a schedule delivered before an announced clock change. Flag an impossible interval, a stop before start and a duration outside the channel's expected range. When stop is omitted, define whether the next programme start closes the interval; do not invent a fixed duration without marking it inferred.

Validate gaps, overlaps and duplicate events

For each channel, sort programmes by normalized start time. Measure gaps, overlaps, duplicate source IDs, identical title/start pairs and rapid changes to the same slot. Some overlaps are legitimate, but they still need a rule: select one source of truth, display both as linked events, or quarantine the conflict.

Give every imported revision an ingestion timestamp and feed identity. That allows an operator to answer whether the guide is wrong because the supplier changed a programme, the import was stale or the mapping pointed to another channel.

Publish enough history and future schedule

Define a guide window rather than loading an unbounded archive into every response. Viewer interfaces usually need now/next immediately and a bounded future schedule. Catch-up or recording workflows may also need past events, but their retention and rights policies are separate.

Include generated_at, source freshness and per-channel coverage in the guide API. Cache programme responses, but keep the cache lifetime shorter than the update promise. Purge or version cache keys when an urgent schedule correction arrives.

Reconcile late changes without losing event identity

Live events move. Match updates using the strongest supplier identifier available, then channel and scheduled time as controlled fallbacks. Keep a stable internal event ID when only title, description, start or duration changes. Otherwise viewer reminders, recordings and analytics can split one event into several unrelated records.

Define what happens when a feed retracts an event. A replacement should not briefly leave the channel empty, and an old cached response must not restore the retracted version. Apply each feed revision transactionally, then verify channel coverage before making it current.

Monitor guide quality as data quality

Useful metrics include feed age, import duration, parse failures, mapped-channel percentage, schedule coverage hours, gaps, overlaps, duplicate events and guide API latency. Alert on the service tier: a movie channel may require days of coverage, while an event channel may be intentionally empty outside a booking.

Correlate guide and media without merging their health states. Show “schedule unavailable” when metadata is stale and “channel unavailable” when playback fails. A fabricated programme title is worse than an honest unavailable state.

Run an EPG acceptance test before launch

1. Validate syntax. Reject malformed XMLTV or invalid EIT sections before changing the active schedule.
2. Audit mapping. Resolve every visible channel to one stable internal identity and one tested player.
3. Normalize time. Test explicit offsets, UTC defaults and daylight-saving boundaries.
4. Measure coverage. Check now/next and the required future window for each service tier.
5. Exercise revisions. Move, replace and retract an event while preserving the intended identity.
6. Separate failures. Simulate a stale schedule with healthy video and a dead channel with current metadata.