In part I of the tutorial we will use fictitious tv listings that the TV-Browser web site generates. The tools I have mentioned are responsible for processing these listings and uploading them to a webserver. After that, TV-Browser can access the listings on the server.
After having worked through part I, you should understand the basics on how tv listings are processed and you will be able to set up a working environment for the TV-Browser tools.
To keep the tutorial simple and concise, I will only explain the things that are crucial for understanding the process.
At the end of part I we will add a new channel group to TV-Browser. This group will contain three channels with fictitious listings that reside on the web space.
Throughout the tutorial we will need the dos box, terminal, console or whatever it may be called on your system.
So, fist of all we open a terminal window and change to the directory workspace. This will be the directory we will work in (I will explain the meaning of the other directories later).
In the directory you can see several shell scripts, each of them available in two versions - one for windows and the other for the *nix bash. Each script corresponds to a TV-Browser tool: PDSRunner, DataManager and MirrorUpdater. Those scripts will save us a lot of typing.
The first tool that we need is the PDSRunner. PDSRunner reads tv listings and converts them to a special format in order to facilitate further processing.
We start PDSRunner with the command
pdsrunner
We see the following output:
usage: PDSRunner [-raw directory] [-log directory] pds ...
What does that mean?
The task of PDSRunner is collecting the tv listings. The tool does this by calling external "modules" (Java classes) that provide the listings.
We (the developers) call these modules PrimaryDataServices, or PDS in short. The only time that a listings provider must do programming work is during development of such a PDS.
In this part of the tutorial we will skip this step. Instead, we will use the PDS that is delivered along with the tutorial.
We need to tell the PDSRunner what PDS it shall use. This is how we do it:
pdsrunner SimplePDS
SimplePDS is, as its name implies, a very simple PDS. It downloads tv listings from a web site and passes them to the PDSRunner. Both channel and listings are purely fictitious and are there only to demonstrate how the process works. The PDS resides in the java directory.
After PDSRunner has completed we see that a new directory named raw has been created in the workspace directory. The new directory contains one file for each combination of day and channel. The files themselves contain the raw listings data.
The tv listings originate from the TV-Browser web site and were generated by an automatic process on the web server.
SimplePDS has extracted these listings from the web site.
PDSRunner has started SimplePDS and has converted the tv listings returned by SimplePDS to the format that the other tools understand. PDSRunner has then stored the converted listings to the raw directory.
The original listings can be viewed here.
Because the raw listings are stored in a binary format that is compressed we cannot easily open them and see their contents. Luckily there is another tool that makes the listings readable for humans :-)
The command
dayprogramfiletranslator raw
creates text files corresponding to the binary files in the raw directory and stores them in the directory raw/txt. We can open and inspect these files to see whether everything is still all right.
You do not really need to use DayProgramFileTranslator to provide tv listings. It is just a tool to display listings in the binary format.
As they are, the files cannot yet be used in TV-Browser. The reason is that TV-Browser requires additional information, such as:
To help TV-Browser find the information on the web server DataManager creates some additional files-
First of all, we need to set up DataManager.
To do this, we change to the directory config.
It contains 3 files:
Each of them can be opened and edited in any text editor.
Let's start with the file myfirstgroup.txt: It contains the name and description of our group. By default, entries for several other languages are added. You can edit the strings following the '=' sign as you wish.
myfirstgroup is the name of our group. This name is defined in SimplePDS and should not concern us further. In part II we will learn how to customize this name.
myfirstgroup_channellist.txt contains a list of the channels that you will provide (more precisely, the channels belonging to the group myfirstgroup). We need not edit this file because it already contains appropriate test data.
myfirstgroup_mirrorlist.txt must be changed, however: It contains a list of those servers that will carry our channel group. For most purposes, one entry will suffice. If you want provide the listings on several mirrors you need to add all of the to the file. For a start, we will use just one entry.
The file myfirstgroup_mirrorlist might, for example, contain something like:
http://www.tvbrowser.org/tv-daten-test/
In this case, the directory tv-daten-test must exist on the web server.
It is important to create a separate subdirectory on the webspace for the tv listings. This is much tidier and, since the tools will create a file named index.html, it will not mess up your web page :-).
Now is a good time to create the subdirectory where the tv listings will be stored.
After having edited and saved the two files we can start DataManager:
datamanager myfirstgroup
DataManager must know for which channel group to process the raw listings. If you provide multiple channel groups you may process all of them at once by listing all group identifiers separated by blanks.
Once DataManager is done the directory prepared holds many new files. These are the files we will upload to the webspace later on. To save bandwidth all the files have been compressed.
What exactly has DataManager done?
DataManager has read all the files in the raw directory and created a new version of each file in the prepared directory. If a previous version of a file (identified by channel and date) already existed in the prepared directory the DataManager has created a file containing the changes to the most recent version. DataManager will re-use the information in the prepared directory each time it is run.
NO FILES MAY BE DELETED FROM THE PREPARED FOLDER. 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.
immen die Daten nicht mehr mit denen zusammen, die der Benutzer bereits heruntergeladen hat. Folglich lädt TV-Browser keine Programmänderungen mehr für den entsprechenden Tag und Sender.
Now we are ready for step 3.
The third and last tool called MirrorUpdater will upload the listings files to the webspace. First, though, we have to configure MirrorUpdater; for this purpose, we open the file mirrorupdater.ini in a text editor and make the necessary changes. I have already edited the .ini file such that you need to add only the login information for the ftp server. url denotes the ftp server and path stands for the folder to which the listings will be copied (this folder must already exist; MirrorUpdater will not create it). In addition, MirrorUpdater requires a user name and password to access the webspace by ftp. You need not change the other lines; nonetheless, I will describe their meaning below:
dataSource.type=file |
The files are read from the local file system. |
dataSource.dir=prepared |
We use the listings files in the prepared folder. DataManager has created these files for us in step 2. |
dataTarget.type=ftp |
We upload the files to an ftp server. |
groups=myfirstgroup |
We are interested in the channel group myfirstgroup. |
mirror.weight=-1 |
If we had multiple mirrors for the listings, we could set the weight of the mirror here. In this example with one server, however, we don't need a weight. |
Now we run MirrorUpdater with the command
mirrorupdater mirrorupdater.ini
MirrorUpdater receives as its argument the configuration file we just edited. When MirrorUpdater has finished uploading the files, you should be able to download the listings with your TV-Browser client.
If MirrorUpdater completed without an error message, we look at the server to make sure the listings have really been uploaded.
For example, I would visit the url http://www.tvbrowser.org/tv-daten-test/. The web browser should show a website. Additionally, I can see the channel group file at http://www.tvbrowser.org/tv-daten-test/myfirstgroup_info.
The websites used in the example do not exist. Change the urls accordingly.
Finally, we start TV-Browser and add the channel group:
Settings --> TVDataServices --> TVBrowser --> Channel groups.
Click "Add" and enter the url pointing to your channel group.
For example, if the listings are stored at http://members.meinprovider.de/myhome/tvdata, we enter http://members.meinprovider.de/myhome/tvdata/myfirstgroup.
If everything worked, we can update the channel list to see our new channels in the TV-Browser client!
Any questions? Something didn't work as it should have? Just ask in our forum and I will gladly help.
| Overview | On to part II |