This is part II of the tutorial on providing tv listings. I will assume that you have successfully completed part I. We shall use the same tools for this part.
While we did not use custom tv listings during part I, we will now manually create listings for one or more channels and upload them to a web server like we did in part I.
You do not need to know how to write computer programs to complete this part.
In part I, we already worked with SimplePDS.
In general, PrimaryDataServices (PDS) are small Java applications that collect tv listings.
PrimaryDataServices must be written (programmed) by the listings providers themselves in order to be able to automatically collect the listings.
Besides SimplePDS, which we used during part I, this tutorial comes with another PDS: ExcelODS (developed by Til Schneider).
We will now learn more about this PDS and configure it to suit or needs.
First of all, we open the file TvData.xls in OpenOffice or MS Excel.
The file already contains sample listings, so it will not be difficult to use.
We need one table for each channel. The Excel file contains two tables, allowing us to provide listings for two channels.
Depending on the number of channels we want to provide, we have to add new tables or delete one of the existing tables.
The rows that use bold fonts must be in the same position for each table.
We enter the channel ID into the second row of the channel's table:
| Channel ID | This name is used by TV-Browser to identify the channel. Once assigned, it should not be changed. Otherwise, TV-Browser would not recognize the channel and assume that it was newly generated. The ID consists of alphanumeric characters (i.e. letters and numbers, but no special characters). TV-Browser must be able to identify each channel by a unique name; this means that new channels must not use a channel ID that is already assigned to another channel. So please make sure not to re-use existing channel IDs. The channel IDs in the Excel file must match those in gruppe_channellist.txt in the config directory. |
|---|---|
| Country code | The country code identifies the country of origin for the channel. The format is specified in ISO 3166. Germany, for example, has a country code of de. |
In the table below the one containing channel ID and country code, we enter the listings for the channel. The format is very simple.
Date, start time and title of the program are mandatory fields, the rest can be filled in if enough information is available for the channel.
As soon as everything has been filled in, we save the file as TVData.xls in the workspace directory.
Now we can start a first test run. We start PDSRunner with the command
pdsrunner ExcelPDS
We already know PDSRunner from part I. This time, we run it using ExcelPDS.
If any errors occurred, the error messages can be found in the pdslog directory.
If PDSRunner completed successfully, the raw listings can be found in the raw directory as usual.
Now we need the two other tools: DataManager and MirrorUpdater. Before running them, however, we must configure them.
When configuring the two tools, we need to take into account the name of our channel group.
In all, we will create three new files in the prepared folder:
You have to replace GROUPIDwith the name you chose for your channel group. The contents of the first two files are equivalent to those of myfirstgroup.txt and myfirstgroup_mirrorlist.txt (see part I). GROUPID_channellist.txt will be needed for the MirrorUpdater; it will be described in detail below.
Now the configuration of the DataManager is complete, so let's run it:
datamanager [GROUPID]
The DataManager expects - as explained in part I - to receive the channel group name as its argument.
The only step that is still missing is running the MirrorUpdater. The configuration file for the MirrorUpdater is named MirrorUpdater.ini. We open this file and edit the line
groups=GROUPID
If you want to use several channel groups, separate them using :. For example, you might enter:
groups=groupid1:groupid2:groupid3
In most cases, one channel group will be sufficient.
Now we will create the file GROUPID_channellist.txt, which contains information about the channels:
The channel list follows a simple format: Each line contains information about a single channel.
The format of such a line is:
country;timezone;channel ID;channel name;copyright;channel url;icon url;channel category
Country, timezone, channel ID and channel name are mandatory. All other fields may be omitted. A sample file might look like this:
de;GMT+01:00;ard;ARD;(c) by DasErste/TV-Browser;http://www.ard.de;http://www.tvbrowser.org/icons/ard01.gif;3 de;GMT+01:00;rtl;RTL;;;;4 de;GMT+01:00;superrtl;SuperRTL de;MET;zdf;ZDF;(c) by ZDF/TV-Browser de;MET;vox;Vox;(c) by Vox;http://www.vox.de
It is important to create a line for each channel belonging to the channel group.
It is optional to add an URL pointing to the channel icon. If it is omitted, TV-Browser will not display an icon for that channel (however, the semicolon must be present even if no URL was entered).
TV-Browser will download the icon only once; if the URL was changed, TV-Browser will re-load the icon. This means that you must enter a new URL when a new icon for a channel is available. The icon must have the dimensions of 40x20 pixels.
The last entry within a line, channel category, defines the categories that a channel belongs to. TV-Browser 2 and newer allows to filter channels by category. The number representing the categories can be computed with a script on our website.
We are now ready to run MirrorUpdater:
mirrorupdater MirrorUpdater.ini
Done! The listings have been uploaded to the webserver. Now we can add the new channel group to TV-Browser. The URL depends on the channel group name:
http://mywebspace/tv-listings-test/GROUPID
Any questions? Something didn't work as it should have? Just ask in our forum and I will gladly help.
The listings on the webserver must be updated regularly. For each update, the tools mentioned above have to be run:
pdsrunner ExcelPDS datamanager [GROUPID] mirrorupdater mirrorupdater.ini
First of all, the updated listings must be entered into the Excel file, of course.
Important note: To avoid that TV-Browser loads listings from servers that contain outdated listings, the MirrorUpdater stores a file named lastupdate on each server.
TV-Browser will not use servers that have not been updated for more than five days. Hence, a listings provider has to update his servers at least every five days.
DataManager requires the files in the prepared folder to determine the changes that were made to the listings. For this reason, you must not remove files from the prepared folder.
If files were removed from the prepared folder, the listings would no longer be the same as those that the user has already downloaded. As a consequence, TV-Browser would not realize that the listings for that day and channel have changed and would never download the new listings.
| Back to part I | Overview | On to part III |