EPG Import Format

Download as PDF

The SmartTUBE SDP supports two EPG import formats:

XMLTV
XMLTV is a popular modern standard for describing TV listings. One file contains EPG for all channels. You can find a description and example of this format on the official XMLTV Wiki.
SmartLabs EPG XML
Simplified XML format developed by SmartLabs. One file contains EPG for one channel. All subsequent chapters of this section describe this format. You can use this for XML validation.

Regardless of your choice only HTTP(S) is supported as the EPG delivery protocol.

Program Identification

The TV programs are identified and matched by <id> field. Programs with unknown IDs are treated as new. The action which will be performed to the TV show is specified by the following logic:

If the <status> field have the following values:
- delete — the TV show will be unpublished. It is enough to specify only <id>, <status> and <channel_id> for this action (in this case, the other fields will be ignored, and no changes will be made to these fields);
- update — the TV show attributes will be updated with metadata from the import file.

If the <status> field is not specified or have another value:
- if the TV show does not exist — a new TV show with metadata from the import file will be created;
- if the TV show exists and <change_date> is equal to its previous value — no actions will be performed (the TV show will be ignored).
- if the TV show exists and <change_date> is not equal to its previous value — TV show attributes will be updated with the specified data, including saving current <change_date> value.

Genres, Categories and Countries Identification

The content Genres, Categories and Countries are determined by the <dictionaries> section, as shown below (see “Example of SmartLabs EPG XML Format”). Once imported, they are stored in the corresponding dictionaries of the SmartTUBE SDP.
Multilanguage values are supported.
If the <event> section contains unknown Genres, Categories or Countries, the SmartTUBE SDP creates them anyway. In such cases they are created only for the default language (determined by the default-profile-language parameter in the SmartTUBE SDP configuration file system.conf).

Image Identification

The identification of image type (<image> tag) is performed as follows:

By the header Content-Type: image/jpeg or Content-Type: image/png;
If the header was not recognized, by the file extension in the URL (e.g. http://image.storage/imagename.png);
If the file extension was not recognized, the error is logged.

Failure Notifications

In order to control the EPG import process result, you can configure email alerts in the SmartTUBE Admin Console > Administration > Email Alerts. You can also find useful information in the smarttube service log.

You can also call the import externally and get back results of such process the following way:

$ curl –H “Content-Type: application/json” -X POST –d ‘{“method”: “epgimport#doheapimport”, “params”: {“epg-import.url”: “http://epg_source_host_ip:port/epg.xml”}, “id”: 1 }’ http://smarttube_sdp_ip:port/sdpapibd

// Return Example

{
“result”: {
“ok”:681, // Number of successfuly imported events
“errors”:0 // Number of events with errors
},
“id”:1
}

Recommendations for Optimizing EPG Import

To reduce the load on the server and speed up the EPG data processing, we recommend you to make the daily import affect only 2-3 days, and re-import all programs and create new ones only once a week.
To ensure that EPG is displayed correctly in the SmartTUBE apps and that nPVR services work correctly, it is recommended to maintain a database of program IDs and, before importing, only check whether programs have been removed from the EPG. This way you can <update> all programs every time, and <delete> only if it is really necessary.
The | and * characters should be avoided in the import file, since they can be used as internal string separators. As a result, imported strings may not be displayed on end-user devices. We recommend replacing the separators as follows:
* -> “
| -> /

Maximum Field Length

Please see the table below for the maximum field lengths in the SmartLabs EPG XML format:

Name of Field	Default Max Length, symbols
title	300
details/subtitle	300
details/description	4000
dictionaries/genres/genre/id	300
dictionaries/genres/genre/name	300
dictionaries/categories/category/id	300
dictionaries/categories/category/name	300
dictionaries/countries/country/id	300
dictionaries/countries/country/name	300
details/genre	300
details/category	300
details/country	300
details/team/member/name	300
details/team/member/role	300

Example of SmartLabs EPG XML Format

<?xml version=“1.0” encoding=“UTF-8”?>
<schedule>
<!– Values in several languages for the Name field of Content genres (<genres>), Content categories (<categories>) and Countries (<countries>) dictionaries. Specify in the id attribute the external ID of dictionary element (e.g. of the genre), in the lang_id attribute – the language ID–>
<dictionaries>
<genres>
<genre id=“Melodrama”>
<name lang_id=“131”>Мелодрама</name>
<name lang_id=“111”>Melodrama</name>
</genre>
<genre id=“Comedy”>
<name lang_id=“131”>Комедия</name>
<name lang_id=“111”>Comedy</name>
</genre>
</genres>
<categories>
<category id=“New”>
<name lang_id=“131”>Новинки</name>
<name lang_id=“111”>New</name>
</category>
<category id=“Classic”>
<name lang_id=“131”>Классика</name>
<name lang_id=“111”>Classic</name>
</category>
</categories>
<countries>
<country id=“Slovenia”>
<name lang_id=“131”>Словения</name>
<name lang_id=“111”>Slovenia</name>
</country>
<country id=“USA”>
<name lang_id=“131”>США</name>
<name lang_id=“111”>USA</name>
</country>
</countries>
</dictionaries>
<!– Information about the TV program–>
<event>
<!– Unique ID of the TV program. Two <event> elements with the same ID are not allowed –>
<id>10001</id>
<!– Action –>
<status>update</status>
<!– The date and time the TV program was created or last edited (UTC). This value is stored as an internal SDP field. When you re-import a TV program with the same <id>, the new <change_date> value is compared to the previous one. Depending on the result of the comparison, the action described above is performed. –>
<change_date>20.12.2016 13:00:00</change_date>
<!– Date and time, when the TV program starts (UTC). To display the EPG grid correctly in the SmartTUBE app, please avoid duplicating the start and finish times of events. –>
<start>21.12.2016 14:30:00</start>
<!– Date and time, when the TV program finishes (UTC). To display the EPG grid correctly in the SmartTUBE app, the finish date of the TV program must be equal to the start of the next TV program on this channel (i.e, it is necessary to avoid overlaps and holes in the program guide.) –>
<finish>21.12.2016 15:00:00</finish>
<!– Flag indicating that the episode is being aired for the first time (not a repeat). Possible values: 1 or 0. The tag is optional. If not set, it is assumed to be “0”. –>
<first_showing>1</first_showing>
<!– Original air date (first broadcast (UTC), not repeat) –>
<original_air_date>21.12.2016 09:00:00</original_air_date>
<!– External ID of the channel –>
<channel_id>1</channel_id>
<!– Not used –>
<recomended>0</recomended>
<!– Flag to prohibit the TSTV service for the program: 0 – disallow; 1 – allow.
If the current program has recordable=0, it can only be viewed in Live mode, with rewind disabled.
If the previous program has recordable=1 and the user rewinds to the current program using the “Right” button on the remote, the progress bar will automatically rewind to the Live moment when program switching. This flag does not impact the nPVR service and is ignored for test service accounts. –>
<recordable>0</recordable>
<!– Flag to prohibit the Pause Live service for the program: 0 — disallow, 1 — allow. This flag does not impact the nPVR service and is ignored for test service accounts. –>
<pausable>1</pausable>
<!– TV program name. The attribute lang_id is a language ID. If it is not set, then the default lang_id value is used.–>
<title lang_id=“131”>Безумцы</title>
<title>Mad Men</title>
<details>
<!– Original title of a movie, TV show, episode, etc. –>
<title_original>Holby City</title_original>
<!– Episode name for the series (in several languages if needed, see lang_id description above) –>
<subtitle lang_id=“131”>Листья чая</subtitle>
<subtitle>Tea Leaves</subtitle>
<!– Description (in several languages if needed, see lang_id description above) –>
<description lang_id=“131”>Пегги проводит собеседование с неприятным молодым копирайтером…</description>
<description>Peggy interviews an obnoxious young copywriter for a job, the firm tries to get…</description>
<!– TV program genre, comma-separated lists are supported (list of comma-separated “external ids”) –>
<genre>Drama,Adventure</genre>
<!– Category, comma-separated lists are supported (list of comma-separated “external ids”) –>
<category>New,New_Series</category>
<!– Production сompany (not used) –>
<company>Lionsgate Television</company>
<!– Country, comma-separated lists are supported (list of comma-separated “external ids”) –>
<country>Slovenia,USA</country>
<!– Year –>
<year>2007</year>
<!–
Age rating.
Can take the following values:
0+ – no restrictions
6+ – the content is allowed for the 6-year-old children and older
12+ – the content is allowed for the 12-year-old children and older
16+ – the content is allowed for the 16-year-old children and older
18+ – not allowed for people under 18 years old
If omitted, the channel’s age rating is applied.
–>
<age_restriction>16+</age_restriction>
<!– Program poster. Absolute URL to the image (size not less than 350×200 pixels; proportions-insensitive, since SmartTUBE resizes images according to the SmartTUBE app requests). If missing or omitted, apps use an image from the program genre. If also missing, the image from the channel subject is used. If it is also missing, the placeholder is used.–>
<image>http://xmltv.tv-company.com/loadimage.php?id=3201776&width=400&height=300</image>
<!– URL of the additional logo overlaid on top of the stream –>
<logo_for_stream>http://xmltv.tv-company.com/some-image.png</logo_for_stream>
<!– X coordinate of the upper-left corner of the logo. Specified in pixels from the upper-left corner of the video image. This URL must be accessible to SmartMEDIA Recorder performing the logo overlay. –>
<logo_for_stream_x>155</logo_for_stream_x>
<!– Y coordinate of the upper-left corner of the logo. Specified in pixels from the upper-left corner of the video image. –>
<logo_for_stream_y>255</logo_for_stream_y>
<!– Cast and crew –>
<team>
<!– First personality –>
<member>
<!– Full name of the personality –>
<name>Phil Abraham</name>
<!– Role in the production. Possible values: actor, director, screenplay, operator, composer, producer, host, designer, montage –>
<role>director</role>
</member>
<!– Second personality –>
<member>
<name>Tony Smith</name>
<role>composer</role>
</member>
<!– Third personality –>
<member>
<name>Elisabeth Moss</name>
<role>actor</role>
</member>
<!– Others –>
</team>
<!– Identifier of a series for recording all its episodes. Must be unique over the channels. –>
<series_id>x123y456</series_id>
<!– Season and episode numbers of a program. Comma-separated enumeration of season/episode numbers is not supported. –>
<season_number>1</season_number>
<episode_number>10</episode_number>
<!– External price category ID of the PPV TV program –>
<ppv_ext_id>DSX4869D</ppv_ext_id>
<!– Device types that cannot watch this program as an nPVR –>
<npvr_unsupported_device_type>IPHONE</npvr_unsupported_device_type>
<npvr_unsupported_device_type>IPAD</npvr_unsupported_device_type>
<!– Flag to record the program to the Catch-up Content Library, i.e. accessible via content rails on the Home screen of SmartTUBE Apps: 1 — enabled; 0 — dissabled. –>
<public_npvr>0</public_npvr>
<!– Flag to blackout (overlap) the program with the <black_out_image> image: 1 – blackout the program, 0 (or omitted) – do not blackout –>
<black_out>0</black_out>
<!– URL of the image to blackout (overlap) the program –>
<black_out_image>http://some-image.png</black_out_image>
</details>
<!– More images (screenshots); absolute URLs to the images (size not less than 350×200 pixels; if bigger, consider the proportions) –>
<gallery>
<image>http://img.xprsdata.com/images/ac_series_1762__SLF3995.png</image>
<image>http://img.xprsdata.com/images/ac_series_1762__SLF3996.png</image>
</gallery>
</event>
<!–Information on the next TV program –>
<event>
<id>10002</id>
<status>update</status>
<change_date>20.12.2016 13:00:00</change_date>
<start>21.12.2016 15:00:00</start>
<finish>21.12.2016 15:30:00</finish>
<first_showing>1</first_showing>
<original_air_date>07.07.2016 09:00:00</original_air_date>
<channel_id>1</channel_id>
<recomended>0</recomended>
<recordable>0</recordable>
<pausable>1</pausable>
<title lang_id=“131”>Кот по имени Мурзик</title>
<title>The cat named Murzik</title>
<details>
<subtitle lang_id=“131”>Новые приключения</subtitle>
<subtitle>New Adventures</subtitle>
<description lang_id=“131”>Кот Мурзик отправляется на поиски новых приключений</description>
<description>Murzik the cat goes in search of new adventures</description>
<genre>Comedy,Cartoon</genre>
<category>New,New_Cartoons</category>
<company>Lionsgate Television</company>
<country>Slovenia,USA</country>
<year>2017</year>
<age_restriction>0+</age_restriction>
<image>http://xmltv.tv-company.com/loadimage.php?id=3201778&width=400&height=300</image>
<logo_for_stream>http://xmltv.tv-company.com/some-image2.png</logo_for_stream>
<logo_for_stream_x>155</logo_for_stream_x>
<logo_for_stream_y>255</logo_for_stream_y>
<team>
<member>
<name>Phil Abraham</name>
<role>director</role>
</member>
<member>
<name>Tony Smith</name>
<role>composer</role>
</member>
<member>
<name>Elisabeth Moss</name>
<role>actor</role>
</member>
</team>
<series_id>x123y457</series_id>
<season_number>2</season_number>
<episode_number>1</episode_number>
<ppv_ext_id>DSX4868D</ppv_ext_id>
<npvr_unsupported_device_type>IPHONE</npvr_unsupported_device_type>
<npvr_unsupported_device_type>IPAD</npvr_unsupported_device_type>
<public_npvr>1</public_npvr>
</details>
<gallery>
<image>http://img.xprsdata.com/images/ac_series_1762__SLF3997.png</image>
<image>http://img.xprsdata.com/images/ac_series_1762__SLF3998.png</image>
</gallery>
</event>
</schedule>

Change Log

SmartTUBE 8.4

Support for the <public_npvr> tag added for the SmartLabs EPG XML format added

SmartTUBE 7.10

Support for the <title_original> tag added for the SmartLabs EPG XML format added