EPG database

Tvheadend maintains an internal (in memory) EPG database for the purpose of providing a viewable programming schedule and scheduling recordings etc.

This document describes the basic structures (and connections) that make up the database.

On-disk format

The database is written out to disk on shutdown and loaded in on startup. This avoids having to wait for the various grabbers to re-populate it.

The details of the on-disk structure are not covered here (yet), though in essence its just a serialised representation of the in-memory format.

Should you wish to convert the binary format into a human readable format then you can use epgdump script provided in the source package:

./support/epgdump PATH_TO_DB

Note: in most cases PATH_TO_DB will be ~TVH_USER/.hts/epgdb.v2

Memory format

All objects have an id field that is internally generated within Tvheadend and is an auto-incrementing number that is global across all object types. This is generally the ID that is also used for referencing object within the HTSP API.

The tables below provide detailed information about each object.

  • The HTSP column indicates the name of the field in the HTSP event messages (see eventAdd)
  • The Grabber columns indicate which grabbers support the fields. Though it should be noted whether a specific field is actually filled in will depend on the upstream EPG source data.
  • Fields marked NA are either internally generated, represent linkages or are not in use within the object.
  • Some fields may be supported by the grabber protocols but simply not (yet) processed by TVH, in this case the fields are marked N.

Object URIs

The object unique references provided by the grabbers (URIs) are used to help differentiate between data that represents the same thing. This can be very useful for DVR operations where you need to be able to detect a set of broadcasts to record and eliminate duplicates content etc...

Not all grabbers provide such IDs, however for all EPG object (except broadcast and episode_number) they are required within TVH. Therefore if no URI is provided by the grabber TVH will generate one internally. This will have the format:

tvh://channel-CHANID/bcast-BCASTID/episode

Within the grabber types the presence of unique IDs will depend a lot on the upstream data source. For example EIT only has support for systems using CRIDs (e.g. Freesat or Freeview in the UK), XMLTV only has support for systems using dd_progid (Note: this will change in future as other systems exist).

Brand object - epg_brand_t

Brands can be seen as analogous to a TV Show.

Examples might include The Simpsons, 24, Eastenders, etc.

Grabbers
Field Type Description HTSP DVB EIT OpenTV XMLTV PyEPG
id uint32_t Internal ID brandId NA
uri char* Unique ID (from grabber) N N N Y
title lang_str_t* Brand name N N N Y
summary lang_str_t* Brand summary N N N Y
season_count uint16_t Total number of seasons N N N Y
image char* Brand image N N N Y
seasons epg_season_list_t Season list NA
episodes epg_episode_list_t Episode list NA

Note: At present the XMLTV standard does not allow for proper brand identification, however some custom extensions exist that will eventually be supported.

Season object - epg_season_t

A Season represents a single season of a TV Show.

Examples might include The Simpsons - Season 10, 24 - Season 2, etc.

Grabbers
Field Type Description HTSP DVB EIT OpenTV XMLTV PyEPG
id uint32_t Internal ID seasonId NA
uri char* Unique ID (from grabber) N N N Y
summary lang_str_t* Season summary N N N Y
number uint16_t The season number N N N Y
episode_count uint16_t Total number of episodes N N N Y
image char* Season image N N N Y
brand epg_brand_t Parent brand NA
episodes epg_episode_list_t Episode list NA

Note: At present the XMLTV standard does not allow for proper season identification, however some custom extensions exist that will eventually be supported.

Episode object - epg_episode_t

An episode represents the information that is shared between broadcasts of the same content.

Grabbers
Field Type Description HTSP DVB EIT OpenTV XMLTV PyEPG
id uint32_t Internal ID episodeId NA
uri char* Unique ID (from grabber) Y^1 N Y^2 Y
title lang_str_t* Title title Y Y Y Y
subtitle lang_str_t* Sub-title N N Y Y
summary lang_str_t* Summary summary^3 Y N Y Y
description lang_str_t* An extended description description^3 Y N Y Y
image char* URL of episode image image N N N Y
genre epg_genre_list_t Episode genre(s) contentType^4 Y Y Y Y
epnum epg_episode_num_t Episode numbering NA (see below)
is_bw uint8_t Is black and white Y N Y Y
star_rating uint8_t Star rating starRating N N Y N
age_rating uint8_t Age certificate ageRating Y N N N
first_aired time_t Original airdate firstAired N N N N
brand epg_brand_t* (Grand-)Parent brand N N N Y
season epg_season_t* Parent season N N N Y
broadcasts epg_broadcast_list_t Broadcast list Y Y Y Y
  • ^1 This is only provided by EIT systems supporting the CRID system.
  • ^2 This is only currently provided by XMLTV systems using the dd_progid namespace.
  • ^3 Summary/description will be replaced with the versions in the specific broadcast, if they differ.
  • ^4 contentType contains only the first genre in the case where multiple genres are stored.

Episode numbering object - epg_episode_num_t:

The episode number can contains both episode and season numbering. Season information is duplicated here to remove the requirement to create "dummy" season objects simply to support a season number.

Grabbers
Field Type Description HTSP DVB EIT OpenTV XMLTV PyEPG
s_num uint16_t Series number seasonNumber N N Y Y
s_cnt uint16_t Series count seasonCount N N Y Y
e_num uint16_t Episode number episodeNumber N N Y Y
e_cnt uint16_t Episode count episodeCount N N Y Y
p_num uint16_t Part number partNumber N N Y Y
p_cnt uint16_t Part count partCount N N Y Y
text char* Arbitary text description of episode num episodeOnscreen N N Y N

Broadcast object - epg_broadcast_t

This object contains the details of a specific airing (channel & time) of an episode.

Grabbers
Field Type Description HTSP DVB EIT OpenTV XML TV PyEPG
id uint32_t Internal ID eventId NA
uri char* Unique ID (from grabber) NA
dvb_eid uint16_t DVB Event ID Y N N N
start time_t Start time (UTC) start Y Y Y Y
stop time_t Stop time (UTC) stop Y Y Y Y
is_widescreen uint8_t Is widescreen Y N Y Y
is_hd uint8_t Is HD Y N Y Y
lines uint16_t Lines in image (quality) Y N Y N
aspect uint16_t Aspect ratio (*100) Y N Y N
is_deafsigned uint8_t In screen signing Y N Y N
is_subtitled uint8_t Teletext subtitles Y N Y N
is_audio_desc uint8_t Audio description Y N Y N
is_new uint8_t New series / film premiere N N Y Y
is_repeat uint8_t Repeat screening N N Y Y
summary lang_str_t* Summary summary^1 Y Y Y Y
description lang_str_t* An extended description description^1 Y Y Y Y
episode epg_episode_t* Link to tvheadend episode object NA
serieslink epg_serieslink_t* SeriesLink NA
channel struct channel* Channel being broadcast on channelId NA

^1 summary/description will override the versions in the episode object

SeriesLink object - epg_serieslink_t

This object represents a related set of broadcasts intended to be automatically recorded by a DVR.

Populated from
Field Type Description HTSP DVB EIT OpenTV XML TV PyEPG
id uint32_t Internal ID serieslinkId NA
uri char* Unique ID (from grabber) Y Y Y N
broadcasts epg_broadcast_list_t List of broadcasts NA