Overview.
=========

The 4 modules in this directory are designed to allow vdr timer 
programming via the http://tvtv.de web EPG (Electronic Program Guide).

Once you have these modules properly configured and installed, 
you should be able to simply click on the things you want vdr 
to record in the http://tvtv.de web EPG and be done with it. 
Everything else can be handled automatically.
Note that this allows you to program your vdr from anywhere in
the world, as long as you have access to the internet from there!



Module description.
===================

The http://tvtv.de web EPG creates a so-called "merkliste"
("a list of items to remember") containing all the broadcasts
you selected.

1.  The perl script "get_merkliste.pl" transfers this "merkliste"
    from the http://tvtv.de web site to a local file "merkliste.html".

2.  The C++ program "epg2timers" converts this HTML file into vdr's
    timers.conf format.
    
3.  The perl script "loadvdr.pl" pumps these new timer entries
    into a running vdr using telnet and the SVDRP protocol.
    (alternatively, the timers.conf file could be written directly
     when vdr is not running)

4.  The shell script "update_timers" implements the overall 
    control of the entire process.
    It retrieves the latest merkliste from http://tvtv.de,
    converts it to timers.conf format and sends the timer entries 
    to vdr.
    
    

Configuration.
==============

get_merkliste.pl requires configuration of the "files_to_fetch"
variable preset. 
Log in to your http://tvtv.de account and click on the "Bookmark setzen"
item in the "System" submenu of the "Mein Programm" side bar menu.
This will open a window with a URL in the location field that ends
with an ID value. Replace the xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
in the "files_to_fetch" variable preset with your ID value.
If you are using an HTTP proxy, uncomment the line containing
the $ua->proxy call and put your proxy details in.

epg2timers.cxx allows various items to be configured, but it
should work out of the box. See "tvtv.de channel names" below.

update_timers must know where to find the get_merkliste.pl
perl script and the compiled epg2timers binary. Both must be
in a directory pointed to by the TOOLDIR variable.
update_timers also must know where to find vdr's current 
channels.conf file. Put that into the CHANPATH.

Depending on the price of your internet access, you may want to
run update_timers more or less frequently. It may also be a good
idea to run it at times where it is unlikely to interfere with 
your current use of vdr. Configure a crontab entry according to
these personal preferences. Here is the entry I once used:
1       2       *       *       *       /home/cko/bin/update_timers
It runs update_timers only once a night at 02:01 a.m.

As of November 17th, 2000, http://tvtv.de provides a new format
which gives you finer control about what is displayed in the
merkliste. Not all combinations of settings will yield a merkliste.html
file that epg2timers can parse. The following settings are recommended:

Format:     Lang
Ansicht:    Alle
Bilder:     on
Timeline:   on
Kontrollen: on


Installation.
=============
Create your TOOLDIR directory if it does not already exist.
Copy get_merkliste.pl and loadvdr.pl into it, compile epg2timers.cxx 
with the command:
    g++ epg2timers.cxx -o epg2timers
and move the epg2timers binary into the TOOLDIR directory.
If you use the english version of tvtv.de (http://www.tvtv.co.uk),
compile epg2timers.cxx with the command:
    g++ epg2timers.cxx -Denglish -o epg2timers

The get_merkliste.pl script requires certain packages to run.
Besides of course perl, install perl-libwww-perl (at least
that's the name on SuSE 7.2, it may have a different name in
your distribution).

If you have problems with SVDRP and loadvdr.pl, you may want to
try out the update_timers.old script, which replaces the timers.conf
file directly and kills vdr (assuming that it will be restarted
by the runvdr script) to make vdr reload the timers.conf file.

As a third alternative (and that is the one I use), I (mis-)use
vdr's automatic shutdown feature to run epg2timers BETWEEN vdr
runs. So vdr shuts down automatically whenever it has been idle 
for a while and there are no recordings scheduled for the 
near future. My runvdr script basically runs epg2timers then
and restarts vdr. This way, conflicts between updated timer
entries and running recordings are safely prevented. Also, the
DVB driver is reloaded often, which can sometimes be beneficial.
My personal runvdr script is included as an example. 
It is most likely that you cannot use it as it is without 
modifications. 
Do not try to use it unless you understand everything it does!



tvtv.de channel names.
======================
tvtv.de has two naming schemes for the channel names: 
text channel names and channel icon file names.
Unfortunately, as of November 17th, 2000, the text
channel names in the merkliste HTML file are difficult to
assign to the rest of the timer entry data, so epg2timers
has been converted to use the channel icon file names.
The variable "channel_map" in epg2timers.cxx maps
such names into PNRs (aka Service IDs).
Consider the map supplied an example. ;-)
It is not complete.
If you fix any of the entries, please send me a patch.
If epg2timers gets a "merkliste" channel name from tvtv.de that
it cannot find in it's channel map, it issues the error message
  Error - channel '<name>' not recognized.
This is the point where you should fix your channel map 
and send me a patch.

For my own humble purposes, the table works well as it is.
Of course, your channels.conf must contain the matching
PNRs, so the last field in each channels.conf line must be 
identical with the pnr number in the corresponding channel 
map entry.
While the first field in each channels.conf line and the 
tvtv_name string in the corresponding channel map entry
have roughly the same meaning, you can freely choose the
contents of the channels.conf field, while the channel
map entry spelling must match the tvtv.de spelling exactly
(including upper/lower case).
Here is an example: The north-german regional station "N3"
has a service ID or PNR of 28224. A vdr channels.conf entry
for it could look like this:
   N3:12110:H:0:27500:2401:2402:2404:0:28224
tvtv.de currently calls this channel "NDR Fernsehen".
So the channel map entry MUST be:
   {"NDR Fernsehen", 28224}
While you are free to use the same name in your channels.conf,
the channel map entry must look exactly as shown above.
In other words, this:
   NDR Fernsehen:12110:H:0:27500:2401:2402:2404:0:28224
and this:
   NDR fernsehen:12110:H:0:27500:2401:2402:2404:0:28224
and this:
   NDR-TV:12110:H:0:27500:2401:2402:2404:0:28224
and this:
   N3-TV:12110:H:0:27500:2401:2402:2404:0:28224
is OK in channels.conf, but this:
   NDR Fernsehen:12110:H:0:27500:2401:2402:2404:0:0
is not and anything other than the exact values shown
above in the channel map entry is not. For example, this:
   {"NDR fernsehen", 28224}
will not work regardless of the contents of your channels.conf 
entry and will give you the error message
  Error - channel 'NDR Fernsehen' not recognized.
as soon as you put something for NDR Fernsehen into your merkliste.

Please note that epg2timers only recognizes the NEW channels.conf
format (VDR >= 0.71). Some tools on the web still produce the
old channels.conf format. Note that you can use VDR to convert
from the old to the new format. Simply make any change to any
channel entry via the OSD. VDR will then rewrite your entire
channels.conf file and will always use the new format when doing so.



To Do.
======
It would be nice to download the pictures provided along with the
summaries by tvtv.de and display them in VDR.
Alessio Sangalli is planning to create a VDR patch that allows
pictures to be displayed in the background of a summary text.
As soon as this patch is avaliable, epg2timers should be extended
to create a shell script with wget commands that download the
pictures and to insert the path to each picture in a predefined
form into the summary text.


If you have a bright idea about something that should be enhanced,
please let me know. Time permitting, I might implement it.
Of course, this is open source, so you are more than welcome to
supply patches.
Supplying a patch is of course also the method that makes it most
likely that your enhancement idea gets implemented. ;-)



Changes.
========
0.8   23-Mar-2002   Update channel map.
                    Optionally use vdr EPISODE macro in file name.
0.9   28-Mar-2002   Remove mapping of most special characters 
                    when converting the title to a file name.
                    Add handling of "quot" HTML keyword.
0.9.1 27-Apr-2002   Implement additional safeguards against 
                    accidental deletion of timer entries.
                    Only transmit new timers to vdr if they are
                    different from the ones successfully transmitted
                    last time.
                    Fix Krimi&Co channel map entry.
0.9.2  4-May-2002   Update channel map.
0.9.3  29-Jun-2002  Implement new configuration option "max_time_processed"
                    that limits the time into the future for which timer
                    entries are created.
                    Issue an error message when a channels.conf line is not 
                    recognized.
                    Update various maps.
0.9.4  11-Aug-2002  Update channel map.
                    Update README file.
                    Include runvdr example.
0.9.5  17-Nov-2002  Convert epg2timers to new tvtv.de merkliste format.
0.9.6  17-Nov-2002  Use channel icon file names to determine the channel as the 
                    text channel name itself is no longer part of the entry group.
0.9.7   2-Jan-2003  Update channel map.
                    Prevent abort when a channel is not recognized.
                    Insert optional english month names into epg2timers.cxx 
                    for http://www.tvtv.co.uk.
                    Support gaps in channels.conf channel numbering
                    as introduced in vdr 1.1.14.
0.9.8   23-Mar-2003 Update channel map.
                    Evaluate the "pisubtitle-box" table cell and add the
                    info found there to the summary text.
0.9.9   07-Sep-2003 Change epg2timers to create vdr 1.1 timers.conf format.
                    Update channel map.
1.3.6   13-Apr-2004 Change epg2timers to create vdr 1.3.6 timers.conf format.
                    Update channel map.
                    Change version numberb to match corresponding VDR version number.

Authors.
========
Carsten Koch:    epg2timers.cxx, update_timers,  this README file.
                                     
Axel Gruber and 
Rolf Hakenes:    get_merkliste.pl

Peter Ahlert:    loadvdr.pl


Credits.
========
I am grateful (in chronological order) to 

* Klaus Schmidinger for his excellent vdr program and for
  keeping an open mind in all directions.
  
* Suse (my wife, not the Linux distributor ;-) for encouraging me to 
  write epg2timers in June 2000 and for her constant patience and support.
  
* Andreas Steinhauser for periodically criticizing the epg2timers 
  "manual mode" until I came up with the idea to fully automatize it
  and for contributing ideas.
 
* Axel Gruber for reminding me half a year later, for pushing
  the idea to fully automatize it until it got implemented, for 
  asking for new features all the time and for contributing ideas.

* Axel Gruber and Rolf Hakenes for contributing the get_merkliste.pl
  perl script.
  
* Peter Ahlert for contributing the loadvdr.pl perl script.

* Matthias Weingart for contributing additional channel_map entries.

* Rainer Janson for updated channel map entries.

* Christian Rienecker for suggesting that mapping of most special
  characters is no longer necessary when converting the title to 
  a file name.
  
* Emil Naepflein for suggesting control improvements,
  for updated channel map entries and for loadvdr patches.
  
* Andreas Kool for pointing out that characters passed into 
  read_summary should be unsigned.
  
* Heiko Raff for an additional channel map entry.
  
* Helmut Auer for additional channel map entries and a bug fix.

* Andy "fruit" for making epg2timers work with the UK version of tvtv.

* Christan Rienecker for contributing the code that deals with
  gaps in channels.conf channel numbering.
  
* Thomas Bueschgens for updated channel map entries.
  
* Uwe Weissbach for updated channel map entries and
  for suggesting to evaluate the "pisubtitle-box" table cell.
  
* Rolf Hillen for updated channel map entries.

(If I forgot somebody, it was not intentional. Please remind me)


Carsten, April 2004.
