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.


Since the README get bigger and bigger this file MANUAL shall be used
to explain some things in detail. So its not really a manual, but an
extended README.

Topics:

- Using variables in the directory entry of a search timer
- The format of epgsearch.conf
- Description of the search process
- How do Search Timers work?
- Using createcats
- The sources of the 'Select directory' menu
- Language dependent commands for EPG
- Usage from other plugins or scripts

Using variables in the directory entry of a search timer
--------------------------------------------------------
If you are using extended EPG information, you can use variables as
part of a directory entry of a search timer. These variables always have
the form '%variable%'. The name of a variable corresponds with the
internal name of an extended EPG info, as specified in the file
epgsearchcats.conf. Example:

1|Category|Kategorie|Information,Kinder,Musik,Serie,Show,Spielfilm,Sport|3

The category with ID 1 has the internal name 'Category'. So you could
use it with '%Category%'. The names are not case sensitiv. Sample
directory entries could look like this:

My Movies~%Category%
Childrens Movies~%category%
%CATEGORY%~%genre%

There are also three other variables: %Title%, %Subtitle% and
%Channel%. If you don't use %Title%, the title is always automatically
appended to the directory entry, when a timer will be created. If you
set 'serial recording' to 'yes' in your search timer then also the
subtitle will be automatically appended. So the directory entry

%Category%~%Genre%~%Title%~%Subtitle%

is the same as 

%Category%~%Genre%
(with 'serial recording' set to 'yes').

The %Channel% variable gets replaced with the name of the channel.

Attention: Automatically appending title and subtitle will not be
done, if you use the variables %Title% or %Subtitle% in the directory
entry. This allows to form directory entries like this one:

%Category%~%Genre%~%Title%~%Episode%~%Subtitle%


The format of epgsearch.conf
----------------------------
This file stores the search entries. Format is as follows (delimiter
is ':'):

 1 - the search term
 2 - use time? 0/1
 3 - start time in HHMM 
 4 - stop time in HHMM 
 5 - use channel? 0 = no,  1 = Intervall, 2 = Channel group
 6 - if 'use channel' = 1 then channel id[|channel id] in vdr format,
     one entry or min/max entry separated with |, if 'use channel' = 2
     then the channel group name     
 7 - match case? 0/1 
 8 - search mode:
      0 - the whole term must appear as substring
      1 - all single terms (delimiters are blank,',', ';', '|' or '~') 
	  must exist as substrings.
      2 - at least one term (delimiters are blank, ',', ';', '|' or '~') 
          must exist as substring.
      3 - matches exactly
      4 - regular expression
 9 - use title? 0/1
10 - use subtitle? 0/1
11 - use description? 0/1
12 - use duration? 0/1
13 - min duration in minutes
14 - max duration in minutes
15 - use as search timer? 0/1
16 - use day of week? 0/1
17 - day of week (0 = monday, 1 = tuesday...)
18 - use series recording? 0/1
19 - directory for recording
20 - priority of recording
21 - lifetime of recording
22 - time margin for start in minutes
23 - time margin for stop in minutes
24 - use VPS? 0/1
25 - only announce event (dont create a timer)? 0/1
26 - use extended EPG info? 0/1
27 - extended EPG info values. This entry has the following format
     (delimiter is '|' for each category, '#' separates id and value):
     1 - the id of the extended EPG info category as specified in
         epgsearchcats.conf
     2 - the value of the extended EPG info category
         (a ':' will be tranlated to "!^colon^!", e.g. in "16:9")
     

A ':' in the search term or the directory entry will be translated in
a '|'. If a '|' exists in the search term, e.g. when using regular
expressions, it will be tranlated to "!^pipe^!" (I know it's ugly ;-))


Description of the search process
---------------------------------
First, for each broadcasting a search text divided by '~' is created,
depending on the settings of 'Use title', 'Use subtitle' and 'Use
description': 

title~subtitle~description

If "Match case" is not set, the search text and the search term are
transformed to lower case.
Now depending on the search mode, the search term will be looked up in
the search text:
- 'Phrase' matches, if the search term is found anywhere in the search
text.
- 'at least one word', 'all words': first the search term will be
splitted in single words. Delimiters are a blank and the characters
',' ';' '|' '~'. 
Then we check if at least one or all words appear in the search text.
- 'match exactly': matches if search term and search text are identical.
- 'regular expression': the search is done with a regular
expression. You don't need a leading and trailing '/' in your search
term. Two standards of regular expression are supported: extended
POSIX and Perl compatible regular expressions (PCRE) (see Installation
at the top).

If the search was successful until now, the other criterions (start
time, duration, week day) are checked.


How do Search Timers work?
--------------------------
With each update, the plugin searches for new matches of your search
timers. If a new match is found then a new timer is created. For
serial recordings, the subtitle is appended to the recording
directory. Many providers deliver the subtitle just 1-2 days before
the event. The plugin uses then a date/time string for the subtitle,
but replaces this one later if the subtitle is present.
Start and end times of a broadcasting often vary a little bit. To avoid
getting many different timers for the same event, the plugin
checks before adding a new timer, if there is one, that has start and
end times which only differ by a maximum of 10 minutes. If so, the
present timer is modified, else a new timer is created. If the timer
was set to inactive there will be no update. Also manually corrected
priority or lifetime will not be changed when updating.
If you have set 'Announce only (no timer)' to yes, no timer is
created. Instead you get an OSD message about the event. This message
is displayed at each scan, but only if there is no timer for the event.


Using createcats
----------------
This tool is deliverd with the plugin and should exist in the plugins
source directory after compilation. It helps you in creating your own
epgsearchcats.conf, if the samples don't fit your needs.

createcats takes your epg.data as argument and scans it for suitable
EPG infos. Such an info is a set of a category name and a coresponding
value at the beginning of a line (represented with '|') and has the
form '|category: value', e.g.

|Genre: Action

So simply call it with

createcats /path_to/epg.data

The output is a file epgsearchcats.conf, that should be copied to your
plugins config dir. Before using it, you should do some customizing,
since not all things in the file will be suitable to be used as
extended EPG info.

The full set of arguments is:

usage: createcats [OPTIONS] /path_to/epg.data

-m N, --minappearance=N    the minimum number a category has to appear
                           to be used
-v N, --maxvalues=N        values of a category are omitted if they exceed
                           this number
-l N, --maxlength=N        the maximum length of a text to be accepted
                           as a category value
-h, --help                 this help

Some notes:

-m N, --minappearance=N    
createcats counts how often a category is used in your current
epg.data. If this is less than N, then this category will not be part
of the resulting epgsearchcats.conf.

-v N, --maxvalues=N
if the number of values for a category is more than N then createcats
will not output a value list for this category. As a consequence in
epgsearch the menu item gets an edit item, that can be filled with
every text. Else, the item gets a selection item, that lets you select
from a list of values.

-l N, --maxlength=N
if the text length of a value is more than N, this value is not part
of the value list. 

Hint: Results are best, if your current EPG is as big as possible. So
update it, if you are using an external EPG provider, before calling
createcats. 

The sources of the 'Select directory' menu
------------------------------------------
This menu displays directories, that can be used for search timers or
ordinary timers. The items displayed are read from the following
sources: 
   * current recording directories
   * current timer directories
   * directories used in search timers
   * directories specified in epgsearchdirs.conf
The menu merges theses directories and displays only distinct
directories. With key 'yellow' one can change the depth of the
directories shown. If there are items, that contain category variables
like '%genre%', these entries are always shown before any other
directories. They are also not level dependent, but are always shown
with their full directory.
If this menu is called from the timer edit menu and an item is
selected that contains the variables "%title%" or "%subtitle" then the
'file' item of the timer gets cleared, since title or subtitle already
exist in the 'directory' item.

Language dependent commands for EPG
-----------------------------------
If you like to have a language dependent list of commands simply
translate your present epgsearchcmds.conf to your prefered OSD
language and store it with the filename epgsearchcmds-XXX.conf, where
XXX is the language code from i18n.c:

  { "eng,dos",
    "deu,ger",
    "slv",
    "ita",
    "dut,nla,nld",
    "por",
    "fra,fre",
    "nor",
    "fin,smi",
    "pol",
    "esl,spa",
    "ell,gre",
    "sve,swe",
    "rom,rum",
    "hun",
    "cat,cln",
    "rus",
    "hrv",
    "est",
    "dan",
  }

If there are more codes for one language (e.g. "deu,ger") choose
one of them. If there is no language dependent file, epgsearch loads
the file epgsearchcmds.conf. 

Usage from other plugins or scripts
------------------------------------
Searching the epg and other functionality can be used by other plugins
or scripts. There are two approaches:

1. Filebased (intended for use in scripts)
------------------------------------------
Therefore simply create the file '.epgsearchrc' in the plugins config
directory with the following lines in it:

Search=your search term
Searchmode=x //0=phrase, 1=and, 2=or, 3=regular expression
ChannelNr=x //add this line, to search on a specific channel
UseTitle=x //1(default) or 0
UseSubtitle=x //1(default) or 0
UseDescr=x //1(default) or 0

Then call EPGSearch via svdrpsend.pl (you must have assigned a key
to it), e.g.

svdrpsend.pl HITK green

At startup EPGSearch will look for this file and give you the
searchresults for your search, if it exists. After that the file is
removed.

A sample script recrep.sh, that searches for the repeats of a recording
exists in the scripts subdirectory of EPGSearch.

2. via Plugin-Interface (intended for use in plugins)
-----------------------------------------------------

A plugin can directly call two functions of epgsearch with only some
lines of source code:

- searching the epg for some criteria and display the result list
- extended timer edit menu

I have added a quick and dirty dummy plugin
(source/vdr-epgsearchclient-0.0.1.tgz), that demonstrates the usage.

Remark:
Using these services requires vdr-1.3.30 or higher or Udo Richters
backport to previous vdr versions (see the patches subdir)

