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

Written by:                  Christian Wieninger <cwieninger@gmx.de>

Project's home page:          http://www.cwieninger.de.vu

Latest version available at: http://www.cwieninger.de.vu

See the file COPYING for license information.


Overview
--------
EPG-Search can be used as a replacement for the default schedules
menu entry. It looks like the standard schedules menu, but adds some
additional functions:

- Commands for EPG entries with 5 built-in commands like 'show repeats',
  'create search'. One can add own commands for other needs, like adding a
  VDRAdmin auto-timer.

- Add up to 4 user-defined times to 'now' and 'next'

- Searching the EPG: Create reusable queries, which can also be used
  as 'search timers'.

- Search timers: Search for broadcasts in the background and add a
  timer if one matches (similar to VDRAdmin's auto-timers) or simply
  make an announcement about it via OSD

- Avoid double recordings of the same event
  * timer preview
  * recognition of broken recordings
  * fuzzy event comparision

- Progress bar in 'What's on now' and 'What's on next'

- Shift the time displayed by keypress, e.g. 'What's on now' + 30 minutes

- Start menu can be setup between 'Schedule' or 'What's on now'

- background check for timer conflicts (requires a recent timeline plugin)

- detailed epg menu (summary) allows jumping to the next/previous
  event

- support for extended EPG info for search timers

- extension of the timer edit menu with a directory item, user
  defined weekday selection and a subtitle completion.

Works only for vdr-1.3.x (x>=7). Tested on 1.3.10 to 1.3.47.
Parts of the sources are based on the repeating-EPG patch 
from Gerhard Steiner, who gave me the permission to use them 
(thanks for his work!).

Contents
--------

1.    Installation
2.    Description
2.1     Menu commands
2.2     Menu search
2.2.1     Menu edit search
2.2.2     Menu search results
2.3     Extended 'now' and 'next'
2.4     Menu setup
3.    Search timers
3.1     'Avoid repeats' - internals
3.2     How do we compare two events?
3.3     How and when do we compare?
4.    Usage from other plugins or scripts
5.    Using extended EPG info
6.    Replacing the standard schedule menu


1. Installation
---------------
Theres nothing special about it. Install it like any other standard
plugin (unpack, soft link, make plugins). There's only one thing, if
you like to use Perl compatible regular expression for the search:
simply edit the plugins Makefile and uncomment #HAVE_PCREPOSIX=1 to
HAVE_PCREPOSIX=1 or append HAVE_PCREPOSIX=1 to your 'make plugins'
call. (you will need pcreposix installed, comes with libpcre from
www.pcre.org, but it's already part of most distributions 
HINT: if all compiles well, but after starting VDR you get:

ERROR: /usr/lib/libpcreposix.so.0: undefined symbol: pcre_free).

update libpcre from www.pcre.org and recompile the plugin.


2. Description
--------------
At first glance EPG-Search looks like the schedules menu entry of vdr.
By pressing the key '0', one can toggle the bottom colour keys to access
additional functions (the default assignment of the colour keys can be
adjusted by setup):

2.1 Menu commands
-----------------
This menu displays commands that can be executed on the current
item. There are 5 built-in commands:

- Repeats: Searches for repeats

- Record

- Switch

- Create search
  Switches to search menu and adds a new search with the name of the current
  item (to avoid editing the name manually)

- Search in recordings:
  Search the recordings for a broadcast with the same name

You can add your own commands to this menu by editing the file
epgsearchcmds.conf in the plugins config directory. There's a sample
conf file with some sample commands (see directory 'scripts', taken
from vdr-wiki.de, thanks to the authors).

The format of the file is the same as vdr's commands.conf or
reccmds.conf. When a command is executed the following parameters
are passed to it:

$1: the title of the EPG entry
$2: the start time of the EPG entry as time_t value (like in the 
    shutdown script)
$3: the end time
$4: the channel number of the EPG entry
$5: the long channel name of the EPG entry
$6: the subtitle of the EPG entry, "" if not present 

To execute a command from the main menu you can also press its
associated number without opening the commands menu.

2.2 Menu search
---------------
Here you can add, edit, delete and execute your own queries on the
EPG. The usage and behaviour of this menu is similar to VDR's timer
menu. 

2.2.1 Menu edit search
----------------------
Most things in this menu are quite clear, so only some notes on:

- Search term
  The term to search for. If you like to search for more words, separate
  them by blanks. Leaving this empty (combined with search mode
  'Phrase') will match anything. This is useful, if you search e.g. for
  anything that starts between some times on a specific channel.
  With 'blue' you can also select a template for the new search. If
  one of the templates is set to default, new searches will
  automatically get the settings of the default template.
- Search mode:
  'Phrase' searches for the expression within the EPG. 'All words'
  requires, that each word of the expression occurs in the EPG item.
  'at least one word' requires, that only one word occurs in the EPG item.
  'Match exactly' requires, that your search term matches exactly the
  found title, subtitle or description.
  With 'Regular expression' you can setup a regular expression as
  search term. You don't need a leading and trailing '/' in the
  expression. By default these are POSIX extended regular expressions.
  If you like to have Perl compatible regular expression, simply edit
  the plugins Makefile and uncomment #HAVE_PCREPOSIX=1 to
  HAVE_PCREPOSIX=1 (you will need pcreposix installed, comes with
  libpcre from www.pcre.org, but it's already part of most distributions).
  See also MANUAL 'Description of the search process'.

- Use extended EPG info
  (only availabe if configured, see below 'Using extended EPG info)

- Use channel: 
  Search only for events in the given channels intervall, channel
  groups or FTA channels only.
  Channel groups (e.g. sport channels or PayTv channels) can be
  managed with a submenu called with 'blue'.
  ATTENTION: After changing the channels order please check the
  settings of your search timers!

- Use day of week
  Besides the weekdays you can also set up a user-defined selection,
  e.g. search only on Monday and Friday.

- Use blacklists
  You can select one or more or all blacklists here. If any search result
  is also contained in one of the selected blacklists it will be skipped.

- Use as Search Timer
  If set to yes, the plugin will do a background scan of the EPG in
  certain intervals and add a timer, if there is a match. (You have to
  activate the 'search timers' in the setup.)

- Action
  Default action is creating a timer for the search results. But you can
  also choose to simply announce the found event via OSD or to switch
  to the event one minute before it starts.

- Serial recording
  If set to yes, the recordings will be stored in a folder with the name
  of the broadcasting and the recordings itself will have the name of
  the episode. (If there is no episode name, the date and time of the
  recording will be used.)

- Directory
  Here you can assign a directory, where the recording should be stored,
  e.g. 'SciFi'. Use the key 'blue' to select directory entries already
  used in other search entries or given by entries in the file
  epgsearchdirs.conf (simply place your directories here one at each line
  without the leading video directory, also see MANUAL).
  If your provider delivers extended EPG infos you can also use
  variables like "%Genre%" or "%Category%" in your directory
  entry. These are replaced with the current EPG info, when a timer is
  created. (see also the MANUAL 'Using variables in the directory
  entry of a search timer')

- Delete recordings after ... days
  Some recordings should only be kept for a few days, like news. With
  this feature you can tell epgsearch to delete them automatically
  after ... days

- Pause when ... recordings exist
  If the given numbers of recordings currenty exists, then epgsearch
  will not create further timers. After deleting one or more
  recordings it will go on generating new timers. 

- Avoid repeats
  If you dont want to record repeats, this feature tries to check if
  an event was already recorded/programmed and skips it. Please refer
  to the section 'Avoid repeats - internals' below before using it. 

- Allowed repeats
  If you like to accept a certain amount of repeats you can give here
  their number

- Only repeats within ... days
  Give here the number of days a repeat has to follow its first
  broadcast. 0 is equal to no restriction

- Compare title
  When comparing to events then specify here if the title should be
  compared 

- Compare subtitle
  When comparing to events then specify here if the subtitle should be
  compared. If there is no subtitle than this event is always
  different to an event with/without a subtitle

- Compare description
  When comparing to events then specify here if the description should
  be compared. 
  For comparision all parts of the description, that look like a
  category value, are removed first. The remaining text will be
  compared. If this is similar at 90% (regarding the
  Levinshtein-Distance algorithm) then it will be accepted as equal

- Compare categories
  With the button 'setup' you can also specify which categories should
  be compared. As with subtitles an event is different if it has no
  according category value

- Priority, lifetime, margins for start and stop
  Each search timer can have its own settings for these parameters.
  Defaults can be adjusted in the plugins setup.

- VPS
  If set to yes, VPS is used (only, if activated in VDR's setup menu and
  if the broadcasting has VPS information)

(To toggle the flag 'Use as search timer' without editing the search
entry you can use the key '0') 

2.2.2 Menu search results
-------------------------
This menu displays the search results. A 'T' lets you know, that there
is already a timer for the event. A 't' means that there's only a
partial timer for it, as in standard schedules menu.

2.3 Extended 'now' and 'next'
-----------------------------
By setup, one can add up to 4 additional times to extend the green
button, e.g. 'afternoon', 'prime time', 'late night'. Times, that are
already passed, are skipped (you will not get 'afternoon' at evening).
In these menus you can shift the currently displayed time by pressing
FastRew or FastFwd to move back and forward in time. If you don't have
these keys on your remote, you can access this function by pressing
'0' to toggle the green and yellow button to '<<' and '>>'. This toggling
can be adjusted by setup.

You can display a progress bar in 'now' and 'next'. When using text2skin you
should use the setup option "text2skin" in the setup option "Show progress in
'Now'"/Show progress in 'Next'" (the setting 'graphical' may also work with
text2skin, but this depends on the selected skin).

2.4 Menu setup
--------------
- Hide main menu entry
  This hides the main menu entry 'search'. Attention: when the plugin is
  assigned to key 'green' then hiding the plugin will give you VDR's
  standard schedule menu (see below to avoid this)

- Main menu entry
  If not hidden, the name of main menu entry can be set here. Default is
  'Program guide'. Note: If you set it to something different from the default
  then the main menu entry is no longer dependent on the OSD language. Setting
  it back to default or empty restores this behaviour again.

- Start menu
  Select the starting menu 'Schedules' or 'Now'

- Red key
  Select if you like to have Standard ('Record') or 'Commands' as
  assignment for key 'red'

- Blue key
  select if you like to have Standard ('Switch') or 'Search' as
  assignment for key 'blue'

- Show progress in 'Now'
  In the menu 'what's on now' you can display a progress bar, that
  displays the progress of the current item. When using text2skin you
  should use the setup option "text2skin" (the setting 'graphical' may also
  work with text2skin, but this depends on the selected skin).

- Show channel numbers:
  Select this if you like to have a leading channel number before each
  item in the EPG menus

- Show channel separators:
  display channel group separators between channel in the menus
  'Overview now',...

- Show day separators:
  display a day seperator between events on different days in the
  schedule menu.

- Show channels without EPG:
  display channels without EPG to allow switching or create a timer

- 'One press' timer creation:
  If set to 'yes' a timer is immediately created when pressing 'Record' as
  introduced in vdr-1.3.38, else the timer edit menu is displayed

- Channel groups: 
  Here you can setup channel groups (e.g. Sport channels, PayTV
  channels) that can be used as criterion in  searches. The same can
  be done in the search edit menu.

- Time interval for FR/FF [min]:
  In the menus 'now', 'next', 'user def 1', ... you can shift the
  displayed time by pressing FastRew, FastFwd on your remote control.
  Adjust the amount of minutes to jump here.

- Toggle Green/Yellow:
  If you don't have FastRew, FastFwd on your remote control, set this to
  yes. When pressing '0' in the menus, this toggles the assignment of
  the colour keys and assigns e.g. '<<' and '>>' to 'green' and 'yellow'

- Use user time 1..4
  Add up to 4 user-defined times besides 'now' and 'next'.

- Description:
  Name of the user-defined time, e.g. 'Afternoon', 'Prime time', 'Late
  night'

- Time:
  The associated time of the user-defined time.

- Use VDR's timer edit menu:
  When programming a standard timer epgsearch uses an extended menu,
  that also supports a directory item, user defined weekday selection
  and subtitle completion. If you are using a patched version of VDR,
  that also has an extended timer edit menu and like to use this menu
  rather than epgsearch's then set this option to 'Yes'.

- Default recording dir:
  This entry will be used in standard timer programming as default
  directory. You can also use EPG category variables (e.g. 'My
  Movies~%Category%~%Genre%'). When the timer edit menu is launched
  epgsearch tries to replace all variables with the values found in
  the description of the event. If not all variables could be replaced
  then the directory item is left blank.

- Add episode to manual timers:
  When manually adding a timer epgsearch can automatically add the
  episode name to the timer file resulting in a subfolder for the
  later recording, that is named with the episode name. Choose here how
  this should be done. 'smart' tries to recognize if this makes
  sense. Therefore it checks the lenght of the event and skips the
  subtitle if the event has more than 80min.
 
- Use search timers:
  If yes, the plugin makes a background scan of the EPG and adds timers
  if it finds matching entries. This applies only to searches that are
  marked with 'use as search timer'.

- Update interval:
  the update interval of the background scan for search timers in
  minutes

- SVDRP port:
  if you are using a SVDRP port other than 2001 then enter this here
  to get the search timers working.

- Check timer conflicts:
  check for conflicting timers after each background scan. If
  conflicts are found a message is displayed. This function requires
  a recent timeline plugin running.

- Default Priority:
  Default priority of generated timers.

- Default Lifetime:
  Default lifetime of generated timers.

- Margin at start/stop:
  Default margins of generated timers.

3. Search timers
----------------
This is quite the same as VDRAdmin's auto-timers, but needs no external
software. When you create a search, you can give it an option to use
it as search timer. Now the plugin scans EPG entries in certain update
intervals (->setup) in the background and creates timers if there
are matching entries. If you don't like to get a new timer, but only
want to be informed about the event set 'Announce only (no timer)' to
yes. 
Since these search timers are quite useful for serials, you can set
the  option 'serial recording' in a search, which creates timers
whose recordings are stored in a folder with the serials name and
whose entries are named with the episode name. If there is no episode
name, the plugin names the recording with a date/time string.

To use search timers, you also have to activate them in the plugins setup.
Also edit the SVDRP port, if you are not using the default 2001.

If you want to trigger a background scan manually simply

touch /etc/vdr/plugins/.epgsearchupdate

This can also be part of your shutdown script. (Add here a sleep
afterwards to give the plugin the time to finish the scan.)

For more info about searchtimers please refer to the MANUAL, 
'Description of the search process' and 'How do Search Timers work?' 

3.1 'Avoid repeats' - internals
-------------------------------
This section explains the feature 'Avoid repeats' for a search timer.
Sometimes one cannot avoid double recordings of an event only by
setting the corresponding search criterions.
Therefore the feature 'avoid repeats' tries to check before creating a
timer, if the same event was already recorded in the past or if there
is a timer that records the same event. If so, there will be no new
timer for the event.

3.2 How do we compare two events?
---------------------------------
To check if two events are the same there are many possible settings
for a search timer. You can choose the title, subtitle, description or
extended EPG categories within the description of an event to be
compared with the elements of another event.
This comparision is always done case-sensitive and for the whole
term. But the description of an event makes an expection of this. 
First all text within the description will be truncated that looks
like an extended category entry, e.g. 'Rating: tip'. An extended
category entry is a line of text beginning with max. 40 signs,
followed by ':' and ending with max. 60 further signs.
The reason for this cutting is that some categories like the rating of
an event are not part of the descpription of the repeat of the same
event. 
The remaining text will now be compared by length. If the difference
is bigger then 90%, then we rate the description of the two events as
different. If not, we apply the Levinsthein-Distance-Algorithmus (LD),
which makes a fuzzy text comparision. We accept the description of the
events as equal, if LD returns a match of more then 90%.
Since LD is quite runtime intensive (O(mn)), you should not choose
'compare description' as the only comparision criterion, but combine
it always with other criterions.

3.3 How and when do we compare?
-------------------------------
As already mentioned each search timer update checks search timers
with this feature for recordings in the past or an already existing
timer for the same event.
To remember past recordings epgsearch stores their info in the file
epgsearchdone.data. You can have a look at the contents of this file
calling 'show recordings done' in the 'actions' of the searches menu. 
This file only stores info about recordings that are complete,
i.e. that started and stopped just in time. So a broken recording will
not be stored in this file and epgsearch will automatically try to
record the next repeat, if there is any.

How to use it?
--------------
As you see, the whole feature depends on the quality of the EPG.
After creating such a search timer, you should first check if it does
what is intended. Therefore the menu of search results has an
additional mode for the key 'blue' named 'Timer preview'. Here you can
see, what timers the next update would create. Existing timers are
labeled with 'T', future timers with 'P'. 
Hint: If the programming results in a conflict simply disable the
conflicting timer in the timers menu. The next search timer update,
will try to program a different timer for the same event, if it exists.

When it works not correctly :-)
-------------------------------
To get a better control of the programming or not-programming of the
timers when using this feature a logfile was introduced. When starting
epgsearch with the command line option '-v n' where n is the log level
than you get additional info in the file epgsearch.log. Available log
levels are 0 (no logging) to 3 (extended logging). See also the manual
for the command line options.

4. Usage from other plugins or scripts
--------------------------------------
(moved to MANUAL)

5. Using extended EPG info
--------------------------
Some EPG providers deliver additional EPG information like the type of
event, the video and audio format, cast,...
Using tvm2vdr or epg4vdr you can import this into vdr.
To use this information with search timers one has to configure it
with the file epgsearchcats.conf in your plugins config directory. The
format of the file is as follows:

ID|category name|name in menu|values separated by ','(option)|searchmode(option)

- 'ID' should be a unique positive integer
   (changing the id later on will force you to reedit your search timers!)
- 'category name' is the name as delivered by the EPG provider, e.g. 'Genre'
- 'name in menu' is the name displayed in epgsearch.
- 'values' is an optional list of possible values
  if you omit the list, the entry turns to an edit field in epgsearch,
  else it's an list of items to select from.
- 'searchmode' specifies the search mode:
  0 - the whole term must appear as substring
  1 - all single terms (delimiters are ',', ';', '|' or '~') 
      must exist as substrings. This is the default search mode.
  2 - at least one term (delimiters are ',', ';', '|' or '~') 
      must exist as substring.
  3 - matches exactly
  4 - regular expression

Sample files for epgsearchcats.conf are delivered with the plugin in the
directory 'conf'.
Simply copy the one that fits for you to your plugins config dir with
filename epgsearchcats.conf and then have a look to the search timers
edit menu (after a restart of VDR).
Since setting up a new epgsearchcats.conf is a lot of work, I've added
a small tool 'createcats', that makes the biggest part of the job. It
should have been compiled with the plugin and exists in the sources
directory. Simply call it with:

createcats /path_to_your/epg.data

This tool now scans your current EPG information and tries to extract
the extended EPG info resulting in a new epgsearchcats.conf. Please
edit this file now, since it will contain also things not suitable.
After that copy it to your plugins config directory.
(More about createcats in the MANUAL 'Using createcats')

(Internals: epgsearch scans the summary of an event for the category
name followed by ': ' for all categories that have a corresponding
value set in the search timer. The search is case sensitive regarding
the category name as also the value.)

6. Replacing the standard schedule menu
---------------------------------------
To use this plugin as a replacement for the default green key, simply 
put the line

Green	@epgsearch

in your keymacros.conf. If you don't like to get another plugin entry
in your main menu, first hide it by setup. Then you could use my
launcher-plugin and put the line 

Green @launcher x 

in your keymacros.conf, where x is the position of the EPGsearch
plugin within launchers menu listing.

Attention: Hiding the plugin without using the launcher plugin or
other patches that enable calling hidden plugins will show the standard
schedules menu when you press the green key. This is not needed
anymore after VDR >= 1.3.32.

Another approach is using a patch to vdr that replaces vdr's standard
schedule menu with epgsearch (vdr-replace-schedulemenu.diff.gz in the
patches subdir, thanks to the author Uwe/egal@vdrportal). When using
this patch the entry should look like

Gree Schedule

This patch is already included in some patch collections, like the
Bigpatch. 



Have fun!

Christian Wieninger
