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			NA
season	epg_season_t*	Parent season			NA
broadcasts	epg_broadcast_list_t	Broadcast list			NA

• ^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