Programme guide (EPG)

What it does

A guest who presses the guide button expects to see what is on now, what is on next and what is on tonight. Without programme information, the television shows an empty grid, and that is conspicuous in a way most headend faults are not.

Castmux fills it from XMLTV, the common interchange format for guide data. You add one or more XMLTV sources and match each channel to its entry in the guide. From then on, the appliance keeps the guide data up to date and sends it to the televisions as DVB Event Information Tables (EIT), the same way a broadcaster does. A set-top box needs no configuration to show it.

Everything is set up on the EPG page of the web interface.

Adding a guide source

A source is the URL of an XMLTV file, as published by a guide provider. Compressed guides (.gz) are accepted as they are.

When a source is added, Castmux fetches it and reads its channel list: each channel’s guide identifier (for example rtl.de) and its display name. It does not store the programmes yet. An XMLTV file can be hundreds of megabytes, and programmes for channels nobody has mapped are not worth the storage.

A source can be renamed, pointed at a new URL, or deleted. Deleting a source removes its stored guide data. Channels mapped to it keep their guide identifier until you clear it, so a replacement source that uses the same identifiers picks up where the old one left off.

Mapping channels

Each channel is matched to a guide identifier from the imported lists. The EPG page offers the identifiers as you type. The mapping is saved on the channel itself, as epg_id in the configuration file, so it is backed up and restored with the rest of the channel’s settings.

A channel without a mapping carries no guide data. Mapping is per channel, so a site can map the channels that have guide data and leave the others alone.

Keeping the guide current

Every source is re-fetched once an hour. On each sync, programmes are stored only for guide identifiers that at least one channel is mapped to. Everything else in the file is read and discarded without touching the disk. Finished programmes are pruned, so the store holds only what is on now and what is still to come.

Sync now on a source fetches it straight away and reports the real result, which is the button to use after adding a source or changing a mapping. It can take a few minutes on a large guide.

Guide data is stored in a small database file, epg.db, next to the configuration file.

What the televisions receive

For each mapped channel, the appliance writes the current and upcoming programmes as EIT and adds them to the channel’s transport stream. This covers both the now-and-next information and the schedule further ahead. It works on the multicast output, and on DVB-C: a channel carried in a multiplex keeps its EIT, renumbered to its service in that multiplex.

The details worth knowing:

• Guide times come from the appliance’s clock. Keep the appliance’s time right, for example with NTP. A wrong system clock shows the wrong programme as “now” on every television.
• Updates reach running channels without a restart. The EIT is re-read as the guide data changes, so an hourly sync is on screen within seconds and no channel is interrupted.
• A newly mapped channel starts carrying EIT on its next start. Map the channel, run Sync now, then restart the channel: switch it off and on again, or call POST /api/channels/{id}/restart.
• A mapped channel with no programmes shows a labelled gap. If the guide has nothing for a channel yet, or has stopped listing it, the television shows “No information available” in four-hour blocks instead of an empty guide, and the channel keeps playing.
• Accented characters need the right character set. By default, guide text is encoded in the DVB default character set, which some receivers mis-decode, typically as broken umlauts. Set the EPG character set in Settings (epg_charset under global.dvb) to what the site’s receivers expect. ISO-8859-15 is right for Western Europe, and a modern receiver fleet can use UTF-8.

EIT is sent on pass-through channels only

The guide is added to channels on the pass-through engine, which is the default. A channel on the remux engine, for example an RTMP source or an HLS origin with fMP4 segments, can still be mapped and shows now-and-next in the web interface, but its televisions receive no guide. Guide data on remux-engine channels is on the roadmap.

In the web interface

Each mapped channel’s card on the Channels page shows what is on now and what is next, so you can check a mapping without a television to hand. A channel that is mapped but has nothing on at the moment shows that, and it is not a fault: guides have gaps.

The EPG page lists each source with the time of its last fetch and whether it succeeded, which is the first place to look when the guide on the televisions stops advancing.