Generate and insert EIT sections based on an EPG content. More...

#include <tsEITGenerator.h>

Inheritance diagram for ts::EITGenerator:

[legend]

Collaboration diagram for ts::EITGenerator:

[legend]

Public Member Functions
	EITGenerator (DuckContext &duck, PID pid=PID_EIT, EITOptions options=EITOptions::GEN_ALL\|EITOptions::LOAD_INPUT, const EITRepetitionProfile &profile=EITRepetitionProfile::SatelliteCable)
	Constructor.

void	dumpInternalState (int level) const
	Dump the internal state of the EIT generator on the DuckContext Report object.

Time	getCurrentTime ()
	Get the current time in the stream processing.

uint16_t	getTransportStreamId ()
	Get the "actual" transport stream id for generated EIT's.

bool	loadEvents (const Section &section, bool get_actual_ts=false)
	Load EPG data from an EIT section.

bool	loadEvents (const SectionFile &sections, bool get_actual_ts=false)
	Load EPG data from all EIT sections in a section file.

bool	loadEvents (const SectionPtrVector &sections, bool get_actual_ts=false)
	Load EPG data from a vector of EIT sections.

bool	loadEvents (const ServiceIdTriplet &service, const uint8_t *data, size_t size)
	Load EPG data from binary events descriptions.

void	processPacket (TSPacket &pkt)
	Process one packet from the stream.

void	reset ()
	Reset the EIT generator to default state.

void	reset (PID pid)
	Reset the EIT generator to default state.

void	saveEITs (SectionFile &sections)
	Save all current EIT sections in a section file.

void	saveEITs (SectionPtrVector &sections)
	Save all current EIT sections.

void	setCurrentTime (Time current_utc)
	Set the current time in the stream processing.

void	setMaxBitRate (const BitRate &bitrate)
	Set the maximum bitrate of the EIT PID.

void	setOptions (EITOptions options)
	Set new EIT generation options.

void	setProfile (const EITRepetitionProfile &profile)
	Set a new EIT repetition profile.

void	setTransportStreamBitRate (BitRate bitrate)
	Set the current bitrate of the transport stream.

void	setTransportStreamId (uint16_t ts_id)
	Define the "actual" transport stream id for generated EIT's.

Detailed Description

Generate and insert EIT sections based on an EPG content.

To generate EIT sections, an instance of EITGenerator needs:

The identity of the actual TS. Set using EITGenerator::setTransportStreamId() or using EITGenerator::processPacket() after a PAT is found.
The current UTC time. Set using EITGenerator::setCurrentTime() or using EITGenerator::processPacket() after a TDT or TOT is found.
Events in the EPG database. Loaded using EITGenerator::loadEvents() or using EITGenerator::processPacket() from incoming EIT's (if EITOption::INPUT is selected in the generation options).

The current time is automatically updated packet after packet, based on the last UTC time, the number of packets since then and the transport stream bitrate (shall be set using EITGenerator::setTransportStreamBitRate()).

Generated EIT section can be saved in a SectionFile object (see EITGenerator::saveEITs()) or inserted in the transport stream using EITGenerator::processPacket(). In the latter case, input null packets and EIT packets are replaced with packets for the generated EIT's (or null packets when necessary).

EIT packet insertion is performed depending on cycle time of the various EIT sections (see EITGenerator::setProfile()). The maximum EIT bandwidth can be limited using EITGenerator::setMaxBitRate().

EPG database

The EPG database is entirely in memory. It is initially empty and emptied using EITGenerator::reset(). Events are loaded in EPG using EITGenerator::loadEvents() (various flavours exist).

The EPG can be saved in a SectionFile object using EITGenerator::saveEITs(). This object can later be saved in binary or XML format. It can be reloaded later in another instance of EITGenerator.

The EPG content is filled with generic EIT sections, either in binary or XML form. The structure of these EIT sections, p/f or schedule, the number and order of events, do not matter. The events are individually extracted and will be stored and sorted independently. These events will be used to fill the generated EIT sections. In short, EIT section is just a convenient storage format for EPG events.

Events can also be individually loaded, outside EIT sections but using the same binary format as in EIT, from field event_id to end of descriptor list.

Principle of operation

The EITGenerator object is continuously invoked for all packets in a TS. Packets from the EIT PID or the stuffing PID are replaced by EIT packets, when necessary.

It is important that the application passes all packets from the TS, not only the packets that the application wishes to replace. This is required so that the EITGenerator object can evaluate the bitrate and repetition rate of the generated EIT sections.

EIT sections from the input EIT PID can also be used to populate the EPG database if the option EITOption::INPUT is set. This is a convenient way to generate EIT p/f in addition to (or in replacement to) an input stream of EIT schedule.

Basic EIT generation rules

Using a bit-mask of EITOption, the EITGenerator object can selectively generate any combination of EIT p/f (present/following) and/or EIT schedule, EIT actual and/or EIT other.
We call "subtable" the collection of sections with same table id and same table id extension (the service id in the case of an EIT). This is a general MPEG/DVB definition.
The EIT syntax and semantics are specified in ETSI EN 300 468, section 5.2.4. The usage guidelines are specified in ETSI TS 101 211, section 4.1.4.
An EIT p/f, when present, must have two sections. The present event is in section 0. The next event is in section 1. If there is no event, the EIT section must be present but empty (no event).
EIT schedule are structured as follow:
- The structure is based on a "reference midnight", typically the current day at 00:00:00.
- The total duration of an EPG is 64 days maximum, over 16 subtables per service.
- Each subtable covers a duration of 4 days. The first subtable starts at the reference midnight.
- Each subtable (4 days) is divided in 32 "segments" of 3 hours.
- A segment spans over 8 sections (sections 0-7, 8-15, 16-23, 24-31, etc.)
- In each subtable, all segments from 0 to the last used one shall be present. Unused segments after the last used one are optional.
- In each segment, all sections from 0 to the last non-empty one shall be present. Unused segments after the last used one are optional. Empty segment shall be represented with one empty section. The last section in each segment is set in the EIT field segment_last_section_number.
- The last EIT schedule table id is set in the field last_table_id in all EIT sections.
- As a consequence, an EIT schedule is not a complete table in MPEG terms since some sections are intentionally missing.
EIT schedule are divided into two periods with potentially distinct repetition rates:
- The "prime" period extends over the next few days. The repetition rate of those EIT's is typically longer than EIT present/following but still reasonably fast. The duration in days of the prime period depends on the type of network.
- The "later" period includes all events after the prime period. The repetition rate of those EIT's is typically longer that in the prime period.

Implementation notes

The number and content of the EIT sections depend on the EPG data and the time.

The public methods which may trigger EIT sections modifications are:

loadEvents() : new events in the EPG.
setCurrentTime() : obsoletes events, creates / removes segments.
processPacket() : increase time, load events from input EIT's.
setOptions() : may change the types of EIT to generate.
setTransportStreamId() : toggles EIT actual or some EIT other.
setProfile() : change the repetition rates, ignored, used only when a section is requeued.

The EIT regeneration takes time, so we need to limit the operations.

Changing the options, the transport stream id and the repetition profile is not supposed to happen more than once and the processing time is not important.
Setting the time to a completely new reference is not frequent either.
Setting the time to a small increment is extremely frequent (each packet in fact). Impact:
- Update EIT p/f on some services.
- Remove a segment and associated EIT schedule sections when crossing a 3-hour segment. We do not remove obsolete events in EIT schedule sections inside the current segment unless the segment is forced to be regenerated.
- Midnight effect: When crossing 00:00:00, all EIT schedule sections must change. Affected fields: table_id, section_number, last_section_number, segment_last_section_number, last_table_id. These are only a few fields to patch "in place" (and recompute the CRC).
Loading events is usually performed in batch (load files) or the same events are loaded again and again (input EIT sections). We use the following method:
- Existing events with same content are silently ignored.
- When a new event is loaded, the "regenerate" flag is set 1) globally, 2) on the service and 3) on the 3-hour segment.
- When an EIT section needs to be injected, we check the global "regenerate" flag. When set, all services and segments are inspected and regenerated when necessary. All "regenerate" flags are then cleared.

See also: ETSI EN 300 468, 5.2.4; ETSI TS 101 211, 4.1.4

Constructor & Destructor Documentation

◆ EITGenerator()

ts::EITGenerator::EITGenerator	(	DuckContext &	duck,
		PID	pid = `PID_EIT`,
		EITOptions	options = `EITOptions::GEN_ALL\|EITOptions::LOAD_INPUT`,
		const EITRepetitionProfile &	profile = `EITRepetitionProfile::SatelliteCable`
	)

explicit

Constructor.

Parameters

[in,out]	duck	TSDuck execution context. The reference is kept inside this object.
[in]	pid	The PID containing EIT's to insert.
[in]	options	EIT generation options.
[in]	profile	The EIT repetition profile.

Member Function Documentation

◆ reset() [1/2]

void ts::EITGenerator::reset ( )

inline

Reset the EIT generator to default state.

The EPG content is deleted. The TS id and current time are forgotten.

◆ reset() [2/2]

void ts::EITGenerator::reset ( PID pid )

Reset the EIT generator to default state.

The EPG content is deleted. The TS id and current time are forgotten.

Parameters

[in] pid The PID containing EIT's to insert.

◆ setOptions()

void ts::EITGenerator::setOptions ( EITOptions options )

Set new EIT generation options.

If EIT generation is already started, existing EIT's are not affected.

Parameters

[in] options EIT generation options.

◆ setProfile()

void ts::EITGenerator::setProfile ( const EITRepetitionProfile & profile )

inline

Set a new EIT repetition profile.

The new parameters may be taken into account at the end of the current cycles only.

Parameters

[in] profile The EIT repetition profile.

◆ setTransportStreamId()

void ts::EITGenerator::setTransportStreamId ( uint16_t ts_id )

Define the "actual" transport stream id for generated EIT's.

When this method is called, all events for the specified TS are stored in "EIT actual". All other events are stored in "EIT other". By default, when no explicit TS id is set, the first PAT or EIT actual which is seen by processPacket() defines the actual TS id.

Parameters

[in] ts_id Actual transport stream id.

◆ getTransportStreamId()

uint16_t ts::EITGenerator::getTransportStreamId ( )

inline

Get the "actual" transport stream id for generated EIT's.

Returns: Actual transport stream id or 0xFFFF if unset.

◆ setMaxBitRate()

void ts::EITGenerator::setMaxBitRate ( const BitRate & bitrate )

inline

Set the maximum bitrate of the EIT PID.

If set to zero (the default), EIT's are injected according to their cycle time, within the limits of the input PID and the stuffing. The PID bitrate limitation is effective only if the transport stream bitrate is specified.

Parameters

[in] bitrate Maximum bitrate of the EIT PID.

See also: setTransportStreamBitRate()

◆ setCurrentTime()

void ts::EITGenerator::setCurrentTime ( Time current_utc )

Set the current time in the stream processing.

By default, the current time is synchronized on each input TDT or TOT. Calling this method is useful only when there is no TDT/TOT or to set a time reference before the first TDT or TOT.

Parameters

[in] current_utc Current UTC time in the context of the stream.

◆ getCurrentTime()

Time ts::EITGenerator::getCurrentTime ( )

Get the current time in the stream processing.

The current time starts from the last reference clock (TDT, TOT or setCurrentTime()) and is maintained from the declared bitrate and number of processed packets. If there is no declared bitrate, the last reference time is returned.

Returns: Current UTC time in the context of the stream or Time::Epoch if the current time is not set.

◆ setTransportStreamBitRate()

void ts::EITGenerator::setTransportStreamBitRate ( BitRate bitrate )

inline

Set the current bitrate of the transport stream.

The bitrate is used to update the current time, packet after packet, from the last reference clock (TDT, TOT or setCurrentTime()).

Parameters

[in] bitrate Current transport stream bitrate in bits per second.

See also: setCurrentTime()

◆ processPacket()

void ts::EITGenerator::processPacket ( TSPacket & pkt )

Process one packet from the stream.

Parameters

[in,out] pkt A TS packet from the stream. If the packet belongs to the EIT PID or the null PID, it may be updated with new content.

◆ loadEvents() [1/4]

bool ts::EITGenerator::loadEvents	(	const ServiceIdTriplet &	service,
		const uint8_t *	data,
		size_t	size
	)

Load EPG data from binary events descriptions.

If the current clock is defined, events which are older (already terminated) are ignored. If the clock is not yet defined, all events are stored and obsolete events will be discarded when the clock is defined for the first time.

Parameters

[in]	service	Service id triplet for all events in the binary data.
[in]	data	Address of binary events data. Each event is described using the same format as in an EIT section, from the event_id field to the end of the descriptor list. Several events can be concatenated. All events are individually extracted.
[in]	size	Size in bytes of the event binary data.

Returns: True in case of success, false on error.

See also: ETSI EN 300 468; setCurrentTime()

◆ loadEvents() [2/4]

bool ts::EITGenerator::loadEvents	(	const Section &	section,
		bool	get_actual_ts = `false`
	)

Load EPG data from an EIT section.

Parameters

[in]	section	A section object. Non-EIT sections are ignored.
[in]	get_actual_ts	If true and the actual transport stream id is not yet defined and the section is an EIT actual, set the actual TS.

Returns: True in case of success, false on error.

◆ loadEvents() [3/4]

bool ts::EITGenerator::loadEvents	(	const SectionPtrVector &	sections,
		bool	get_actual_ts = `false`
	)

Load EPG data from a vector of EIT sections.

Parameters

[in] sections A vector of sections. Non-EIT sections are ignored.

Returns: True in case of success, false on error.

Parameters

[in] get_actual_ts If true and the actual transport stream id is not yet defined use the first EIT actual section to set the actual TS.

See also: loadEvents(const Section&)

◆ loadEvents() [4/4]

bool ts::EITGenerator::loadEvents	(	const SectionFile &	sections,
		bool	get_actual_ts = `false`
	)

inline

Load EPG data from all EIT sections in a section file.

Parameters

[in]	sections	A section file object. Non-EIT sections are ignored.
[in]	get_actual_ts	If true and the actual transport stream id is not yet defined use the first EIT actual section to set the actual TS.

Returns: True in case of success, false on error.

See also: loadEvents(const Section&)

◆ saveEITs() [1/2]

void ts::EITGenerator::saveEITs ( SectionPtrVector & sections )

Save all current EIT sections.

If the current time is not set, the oldest event time in the EPG database is used. An EIT sections are regenerated when necessary. EIT p/f are saved first. Then EIT schedule.

Parameters

[in,out] sections A vector of safe pointers to sections into which all current EIT sections are saved.

◆ saveEITs() [2/2]

void ts::EITGenerator::saveEITs ( SectionFile & sections )

Save all current EIT sections in a section file.

If the current time is not set, the oldest event time in the EPG database is used. An EIT sections are regenerated when necessary. EIT p/f are saved first. Then EIT schedule.

Parameters

[in,out] sections A section file object into which all current EIT sections are saved.

◆ dumpInternalState()

void ts::EITGenerator::dumpInternalState ( int level ) const

Dump the internal state of the EIT generator on the DuckContext Report object.

Parameters

[in] level Severity level at which the state is dumped.

The documentation for this class was generated from the following file:

tsEITGenerator.h

Public Member Functions

Detailed Description

EPG database

Principle of operation

Basic EIT generation rules

Implementation notes

Constructor & Destructor Documentation

◆ EITGenerator()

Member Function Documentation

◆ reset() [1/2]

◆ reset() [2/2]

◆ setOptions()

◆ setProfile()

◆ setTransportStreamId()

◆ getTransportStreamId()

◆ setMaxBitRate()

◆ setCurrentTime()

◆ getCurrentTime()

◆ setTransportStreamBitRate()

◆ processPacket()

◆ loadEvents() [1/4]

◆ loadEvents() [2/4]

◆ loadEvents() [3/4]

◆ loadEvents() [4/4]

◆ saveEITs() [1/2]

◆ saveEITs() [2/2]

◆ dumpInternalState()