XMLTV Importer for SageTV : Installation and Configuration

Table of content

XMLTV

XMLTV is an Open Source project with a simple and effective principle. A utility (a grabber) extract television programs from a Web site and save these data in XML format. These XML data can then be used in a software that will display a program guide.

You can learn more about XMLTV here: http://membled.com/work/apps/xmltv
You can download XMLTV grabber here: http://sourceforge.net/project/showfiles.php?group_id=39046

Installation

Step 1: Install SageTV 4 (or newer) and run the SageTV Setup Wizard. Verify that SageTV can display Live TV fine at the end of the setup Wizard.

You don't need to configure completely your channels in SageTV as the Importer will replace your channels. However scanning for channels is recommended to know what channel numbers you will have to use in the Importer (for instance for Digital Tuners like ATSC, DVB-T / DVB-S tuners, SageTV create a .frq file that will contain channel numbers)

Step 2: Get XMLTV data by using a XMLTV grabber.

Step 3: Install our importer. If you don't have yet: download our XMLTV Importer.

Stop SageTV and launch the installation software and follow the instruction of the setup wizard. Then launch our importer, you should obtain the following welcome screen.

The welcome screen shows you what you should do in order from top to bottom:

Locate your XMLTV file(s) and eventually set up your grabber within the XMLTV Importer
Create channels lineups
Edit categories and ratings
Create rules for first run / re-run (you'll certainly not use this feature when setting up the Importer but instead after your first import to change the behavior of the Importer regarding first run / re-run)
Set up advanced options
Decide when the Importer should run automatically (feature available only to our donators)
Update your SageTV guide data

XMLTV File and Grabber

The very first step of guide data import is to locate the previously grabbed XMLTV file(s) you will use as your guide data source. You can add more than one XMLTV files in the Importer by clicking on the "Add a new XMLTV source" link.

Give a name to your XMLTV data source (this is for internal use only) and type the full path for your XMLTV file or use the "Browse..." button to search for it on your PC.

Warning: if your XMLTV file use the XMLTV DTD, don't forget to put the DTD file in the directory where your XMLTV file is located (download the XMLTV DTD version 1.27)

You can as well locate your XMLTV grabber so as the XMLTV Importer can run it before importing your XMLTV data. Click on the "Next >" button

Specify your time zone settings: that is the numbers of hours to add or subtract from the hours in your XMLTV file to have universal time. You can also specify if your zone use daylight saving time. The importer should have detected the right parameters for you already. To help you find the right settings, the wizard displays the air date of a show, adjust settings until the air date is right for the show, then click on the "Next >" button.

The Importer needs to know how to make the difference between two episodes of the same series, to do so three detection methods are proposed. The Importer should have selected the most appropriate method based on your XMLTV file.

If after importing your data, you see in the program guide that two episodes are the same when they should not, try to change the detection method (the safer is based on airing date).

The "shows without original air date are reruns" should be checked if you want that all shows without original air date in your XMLTV file be imported as re-runs. If you are not sure leave this checkbox unchecked, the Importer will try to figure out by itself if shows are first run or re-runs (if your XMLTV file doesn't contain any data about first run and re-run, then all your shows will be first run and progressively you'll begin to see some re-runs).

Channel Lineups

You have to organize your channels into lineups. Lineups are collection of channels to be assigned to a tuner within SageTV. You usually need to create as many lineups as you have video feeds (a tuner card can receive more than one feed, for example a tuner can receive TV on its coax input and S/Video input). To create a new lineup, click on the "Add a new lineup" link.

You will have to first describe your lineup. All these fields will help you or other users to find lineup on our online database:

give it a name (this will be displayed in SageTV)
choose your country
type or select your region (the region list is downloaded from the Internet, if you can't find your region, just type it). If the channel lineup does apply to all your country, leave the region blank.
select the type of TV reception used by this lineup (digital / analog / satellite / use a set top box etc..)
eventually select or type the name of the commercial provider for this lineup or the brand name for the reception type used.
if you are creating a lineup for a SageTV digital source and use SageTV native digital support (ATSC / DVB-T / S / C), you can specify to the Importer what frequencies file is used by SageTV for this lineup. This will allow the Importer to get the real channel lineup (with the right channel numbers). You can also download an updated frequencies file from our online database, it will replace your current one (restart SageTV for applying the changes)

Click on the "Next >" button to create the channels list. You have to add all the channels you are able to receive through the tuner card you'll use with this lineup. You can add channels one by one by using the "Add a channel" button or add channels from external sources.

If you click on the "Add channels" button, you'll be able to add channels from:

The online database: the XMLTV Importer will search channel lineups that match your lineup country / region / provider etc...
Your XMLTV files: the XMLTV Importer will show you all the channels from your XMLTV file
Another existing lineup (this is useful when lineups are receiving the same channels)
SageTV ATSC & DVB-T/S/C frequency files: the XMLTV Importer will show you all the channels you already scanned into SageTV (with the correct channel numbers)
DVBViewer Recorder: the XMLTV Importer will show you the channel lineups you created in DVBViewer Recorder.

For each channel in the list you'll have to provide:

The name of the channel
The call sign or short name of the channel (it will be displayed in SageTV)
The physical channel number, this is the number used to tune the channel through your capture card or recorder plug-in
The logicial channel number, this is the number that will be displayed in the program guide (if specified, otherwise the physical number is used)
The numbers of hours to add or subtract to each program schedule in the guide (if you want to make a "+1" channel for instance)
If the channel can broadcast HD shows or not (some XMLTV data carry a HD flag wether the channel is a HD channel or not)
The XMLTV channel containing the guide data

If you duplicate a channel to be present on multiple lineups and want to SageTV treats these channels as the same one (to see only one channel in the guide), all these duplicated channels must have the same ID.

Categories and Ratings

The TV Ratings Editor will list all ratings found in your XMLTV file. For SageTV to correctly recognize your ratings, you have to select the appropriate SageTV rating in the drop down list of the "SageTV rating" column. You can also add some details about the content of the program in the "Extended Rating" column, this feature is useful to fine tune ratings. For instance if a show is forbidden to young people it may be because of sexual content or some violence, and you may authorize sex but not violence... When you have mapped all your ratings to SageTV ratings, simply close the dialog by clicking on the "Update" button.

You can also edit the categories found in your XMLTV file. The purpose of the Category Editor is to reduce the numbers of categories. The Editor will already contains the recommended top level categories (Movie, Series, Sport, News etc...) you cannot delete them, but you can ignore them (except Movies and Series) and create some new top level categories.

When you edit a category you can specify:

The Name: this is the name that will be displayed in SageTV. You can use whatever name you want to for all the categories with a special note for the "Movie" categories. With current version of SageTV (6.0.19), you have to use the "Movie" string that SageTV is using ("Movie" for English, "Film" for French, etc...). If you use the wrong name, SageTV will drop the subcategory, so if you choose "Movies" and SageTV use English language; all movies will be imported as "Movie / Movies" (the main category becomes the subcategory). This behavior will be fixed in an upcoming SageTV release.
The keywords: you can type here many keywords separated by a comma, whenever the Importer found the corresponding keyword in one of your XMLTV categories, it will match it to the category.
The excluding keywords: those are the keywords (coma separated list), that will prevent a XMLTV category to be matched to the category your are editing when it match the preceding keywords list
If you want all shows belonging to this category to be recorded by SageTV, check the "shows of this category are generics (neither first run nor rerun)". By checking this option the Importer will not try to find an original air date for the show (if the show doesn't have an episode title) this way SageTV will be able to record all episodes. This is mostly useful for news shows when you know that all airings of such shows are somehow all first runs. If one of the show in this category should not follow this rule, you can always create a specific rule for this show: create an overriding rule for the show.
If you know that all the shows of this category are not the same on all channels, you can check the "shows of this category are not the same on all channels". By selecting this option, the Importer will create a unique series for a show on each channel this is only useful for news shows and it is not really recommended to use this option (this mainly avoid to have a "watched" status for shows on a channel because you have watched a show with the same title on another channel but even if the show title is the same, they are different shows).

After editing the keywords and excluding keywords list click on the "Test" button to view the result of the filter. This way you can tune your keywords filter easily.

You will notice that you cannot edit the keywords lists for the "Other" category. This is because this category is designed to receive all the XMLTV categories that don't match any of your categories. You can as well click on the "Test" button to view all the XMLTV categories that cannot be classified. This will help you to create the missing categories and adjust the keywords lists of your categories.

You can add / remove sub categories, this way you can create any number of levels. But don't forget that SageTV only understand a category and a sub category, so it is advisable that you limit your tree to two levels: main category and sub category. Also to be more efficient try to use the same sub category names for Movies and Series (and other main category if you can).

Note: After each Import, the Importer will log information that lists precisely the categories that couldn't be mapped to one of your categories. There are two events: one for categories that can't be matched to a top level categories and one for categories that can be matched to a top level category but can't be matched to a sub category.

First Run Rules

If the Importer cannot set apart some episodes from a series because of lack of details in the XMLTV file (for example all shows of a series are the same and you can only record one of them), you can create rules to override the default behavior of the Importer.

To create a new rule for a show, click on the "Add a new rule". Then in the search dialog box, type a keyword and click on the "Search" button. The Importer will search all your XMLTV files for the shows corresponding to the keyword you typed (this could take a few minutes), in the result list click on the show title and click on the "Next >" button to edit the rule for that show. You can choose between several options:

Select "This program is generic (neither first run nor rerun: all shows will be recorded)" to force the Importer to not handle a first run / rerun / repeat logic for this show. This is useful if the show doesn't have any episode title or description to tell apart each episodes. You'll mostly use this option for news shows.
Select "This program does have first run, you can specify when first run occurs" if you know that some first run exists for the show. Eventually if you also know when the first run are aired you can tell the Importer when those first runs should occurs (check on a week day and specify the schedule). If you give the first run schedule to the Importer you can also check the "shows not in the first run range will be repeats of these first runs" option. This will force the Importer to create repeats of the first run it will create. For example, if you have a show that is first aired every week on Monday and then get repeated on Tuesday and Friday and no other airing will take place in the week (for example a last week rerun), you can select this option. Otherwise don't check it and the Importer will use its usual algorithm to tell shows apart.
Select the "This program is not the same on all channels" if you know that this show is not the same on all your channels. That is even though the show title is the same like "Evening News", this show on channel A is not the same on channel B and a whole series should be created for each channel. It is generally not required to use this option at all.

Other Options

You can choose here some options to customize your guide data such as:

Put star rating in the program title (for movies only)
Put a "HD" label in the program title
Put a "VO" label in the program title for program in foreign languages
Put the episode numbers in the episode title (you can customize position of the episode numbers and prefix used)
Choose to be notified by e-mail when errors and warnings occurs during import. When you set up your SMTP Server, click on the "Test" button to send a test e-mail, if the Importer is able to send mail, a green check mark will be displayed next to the "Test" button.

Scheduled Update

If you have a donation for the XMLTV Importer you can schedule automated update of your guide data. Simply choose the time of the week you want the XMLTV Importer to run automatically. The XMLTV Importer will launch your grabber, and then import your data into SageTV.

If you want SageTV to load the guide data immediately after the import you'll have to use the SageTV Web Server plug-in. Simply type the Web Server plug-in URL, username and password (a green check mark is displayed next to the URL if the XMLTV Importer can log in successfully to the Web Server plug-in)

Note: If you don't have specified the grabber in our utility, you will have to schedule your XMLTV grabber to run automatically (before the task you schedule here for automating the program guide transformation for SageTV)

Updating guide data

To manually start the import, click on the "Start Import" button. During the import the progress bars will show you the state of the data transformation process. Our importer is currently converting your XMLTV files in three new XML files (or more if you have more than one lineup) that will be saved in the Importer settings folder ("C:\Documents and Settings\All Users\Application Data\LM Gestion\SageTV XMLTV Importer\GuideData").

Clicking on the "Cancel" button will stop the import, however clicking on the "Ok" button, or even closing the Importer GUI will not cancel the import.

When the XMLTV Importer has finished the update, your guide data are not yet in the SageTV program guide.

To load these new data into SageTV, you'll have to open SageTV and configure your tuners.

Choose the option to "Use US, Canada, or XMLTV Guide Data with this Source".

Then select the type of channels your receive, you can pick any of the options ("Local channels" is recommended because it's not very important and it will save you one step).

If the Importer setup was correct, you should see your XMLTV lineup, select the appropriate lineup for the current tuner, SageTV will begin to download your channels and program guide (quickly).

When guide data has been fully loaded in SageTV, SageTV will display your new channel lineup.

SageTV will also want you to scan for channels. It is not recommended to scan for channels. You should have already scanned channels prior to the Import and used this scan as a base to create the lineup in the XMLTV Importer with the correct channel numbers.

After that, SageTV will update his guide every 24 hour. It will use the XML files produced by the Importer to do so, this way the SageTV update is always fast. You'll just have to run the Importer each time you update your XMLTV file: either manually or automatically (with automatic execution of the Importer, you can as well download the XMLTV file).

If you have some problems, you can read the FAQ.