TSDuck v3.38-3738
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::EITGenerator Class Reference

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

#include <tsEITGenerator.h>

Inheritance diagram for ts::EITGenerator:
Collaboration diagram for ts::EITGenerator:

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 (const 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 (const 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 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:

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]duckTSDuck execution context. The reference is kept inside this object.
[in]pidThe PID containing EIT's to insert.
[in]optionsEIT generation options.
[in]profileThe 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]pidThe 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]optionsEIT 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]profileThe 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_idActual 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]bitrateMaximum bitrate of the EIT PID.
See also
setTransportStreamBitRate()

◆ setCurrentTime()

void ts::EITGenerator::setCurrentTime ( const 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_utcCurrent 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 ( const 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]bitrateCurrent 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]pktA 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]serviceService id triplet for all events in the binary data.
[in]dataAddress 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]sizeSize 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]sectionA section object. Non-EIT sections are ignored.
[in]get_actual_tsIf 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]sectionsA vector of sections. Non-EIT sections are ignored.
Returns
True in case of success, false on error.
Parameters
[in]get_actual_tsIf 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]sectionsA section file object. Non-EIT sections are ignored.
[in]get_actual_tsIf 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]sectionsA 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]sectionsA 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]levelSeverity level at which the state is dumped.

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