This is a "plugin" for the Video Disk Recorder (VDR).

Project's homepage:          https://github.com/FireFlyVDR/vdr-plugin-xmltv4vdr
Latest version available at: https://github.com/FireFlyVDR/vdr-plugin-xmltv4vdr/files

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
See the file COPYING for more information.


Description:
------------
This plugin for the Linux Video Disk Recorder VDR imports EPG data from
external sources in XMLTV format and enhances the DVB EPG with that including
links to pictures. Beginning with version 0.4.5 it is also possible to add
EPG events to the DVB EPG (if the external EPG exceeds the DVB EPG) or to use
only the external EPG.
The file(s) in XMLTV format must be provided by one (or more) additional
grabber. These grabber scripts are not part of this plugin and need to be
executable by "/bin/sh -c <name of epg source>" so it should be in the path of
the user executing VDR. If the XMLTV files are fetched in a difffernt way, an
executable dummy script with this name is required.
The elements to be imported can be configured selectivly by channel and type
of event (movies, series, movies & series or all).
Additionally the episode info from www.eplists.de is optionally integrated.

Please be aware that depending on the data quality of the EPG not in every
situation a match for a DVB event can be found in the external events.

Requirements:
-------------
VDR 2.4.5+
libsqlite3
libxml2

Installation and Configuration:
-------------------------------
- compile plugin (or install from your distribution) as usual
- configure the locations of several files in <VDR-config-path>/conf.d/50-xmltv4vdr.conf
- choose at least one EPG grabber and execute for each grabber:
  - get the additional grabber executable from its source location
  - put the executable and the configuration file in /var/lib/epgsources
  - start VDR and go to the plugin settings of xmltv4vdr
  - for each EPG source enable it in the sub-menu and set parameters as required
  - for each provided channel of the EPG source you want to import into VDR enter the sub-menu and:
      1. choose a source
      2. select all VDR channels to map to
      3. select the usage of external EPG: enrich DVB, append to DVB or use only external EPG
      4. select the flags which info should be available to VDR
         For convenience the flags can be copied with the blue button (or deleted
         with the yellow button) to all other configured source channels


Episode Lists
-------------
The plugin supports optionally integrating the episodes info from www.eplists.de.
It uses a local SQLite DB for faster queries and the database is updated before
fetching the EPG info from external sources. The update con be configured either to
fetch the episodes info directly from the server (internet connection required)
or it reads them from a local directory with episode files.
Please be aware that the UTF-8 format is mandatory for the episode files.

To enable the usage of episodes info provide a database filename with --episodesdb
and configure either of the two fetch methods:
- For fetching the episodes info directly via internet configure the episode server
(e.g. --episodesserver=www.eplists.de, optionally the Port with --episodesport=PORT)
- If no episode server is provided it defaults to use an episode folder at
"<Plugin-ResourceDir>/episodes". To use a different location use the
parameter --episodes=DIR.

To use a local directory for the updates download the files regularly
via cron, e.g.:
   05 01 * * * vdr /usr/bin/svdrpsend-ng.pl -d www.eplists.de -p 2006 -c -o /srv/vdr/episodes TGET newer than $(($(date '+\%s')-$(stat -c %Y \"$(ls -t1 /srv/vdr/episodes/*|head -n 1)\")+3600)) seconds >/var/log/eplists 2>&1
and define in xmltv4xml.conf the location of the local episode DB (e.g. --episodesdb=/srv/vdr/episodes).

The series and episode info is also written in XML format into the AUX field of the events. It
can be read by any other plugin. or e.g. svdrpsend LSTE <channel No> at <timestamp> :
#> svdrpsend LSTE 1 at 1721585700
.....
215-@ <xmltv4vdr><season>53</season><episode>16</episode><episodeOverall>1199</episodeOverall></xmltv4vdr>
....

EPG images
----------
Dowloaded EPG images are expected in <EPGsources-Dir>/<epg-source>-img. If a
matching event is found they are soft-linked to the cache dir (default:
<Plugin-CacheDir>/epgimages) in the format <channeld-ID>-<Event-ID>_<Number>.jpg
where number begins with 0. Skin plugins can acces them with this schema to show
them in EPG events.

To have the images also available in recordings they need to be copied by a
recording hook script into the recording folder e.g. with the script provided
here:
https://www.vdr-portal.de/forum/index.php?thread/128217-0-6-fehler-in-usr-share-vdr-recording-hooks-r60copy-epgimage/&postID=1262719#post1262719


Config files
============
/etc/vdr/conf.d/50-xmltv4vdr.conf
---------------------------------
contains all parameters the plugin supports:
[xmltv4vdr]
#  -d FILE,  --epgdatabase=FILE     write the EPG database into the given FILE
#                                   default: <Plugin-CacheDir>/xmltv4vdr_EPG.db

#  -i DIR,   --images=DIR           location where links to EPG images are stored
#                                   default: <Plugin-CacheDir>/epgimages

#  -s DIR,   --epgsources=DIR       location where EPG Sources are stored
#                                   default: /var/lib/epgsources

#  -E DIR,   --episodesdb=DIR       use the given filename for the SQLite Episodes DB
#                                   ** mandatory for using episodes information **
#                                   suggested: <Plugin-CacheDir>/xmltv4vdr_episodes.db
#                                   default: none

#  -e DIR,   --episodes=DIR         location of episode files (UTF-8 format only!)
#                                   default is <Plugin-ResourceDir>/episodes

#  -h DIR,   --episodesserver=HOST  servername of episodes server, e.g. www.eplists.de
#                                   default: none

#  -p DIR,   --episodesport=PORT    port of episodes server
#                                   default: 2006

#  -l FILE,  --logfile=FILE         write trace logs into the given FILE
#                                   default: no trace log written

/etc/vdr/plugins/xmltv4vdr/xmltv4vdr.conf
-----------------------------------------
contains general settings, channel mappings with flags and source specific settings
It can be modified with the plugins setup menu and is not intended to be edited.

/var/lib/epgsources/*
---------------------
for each EPG source:
   - a folder for EPG images (if any) named <epg-source>-img
   - for xmltv info provided via file interface the xmltv file named <epg-source>.xmltv
   - a configuation file named <epg-source> with the following structure:
     line 1:  mode;00:00;P;I
         where mode is file or pipe
               00:00 start time (unused)
               P  1=pin required, else 0
               I  1=provides pictures, else 0
     line 2:  number of days EPG is provided by source
     line 3 to end:  names of provided channels

Example:
file;00:00;0;1
7
ard.de
ard-alpha.de
zdf.de
zdfinfo.de
zdfneo.de
