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 it's not really a manual, but an
extended README.

Topics:

1.  Using variables in the directory entry of a search timer
2.  The format of epgsearch.conf
3.  Description of the search process
4.  How do Search Timers work?
5.  How to trigger a search timer update?
6.  Using createcats
7.  The sources of the 'Select directory' menu
8.  Language dependent commands for EPG
9.  Usage from other plugins or scripts
10. Commandline options
11. SVDRP interface
12. Customizing the EPG menus

1. 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 (samples can be found in subdirectory '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%


2. The format of epgsearch.conf
-------------------------------
Due to some new features there was a change in the format. The format
is now signed with a comment in the first line. The current format is
(delimiter is ':'):

 1 - unique search timer id
 2 - the search term
 3 - use time? 0/1
 4 - start time in HHMM 
 5 - stop time in HHMM 
 6 - use channel? 0 = no,  1 = Intervall, 2 = Channel group, 3 = FTA only
 7 - 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     
 8 - match case? 0/1 
 9 - 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
10 - use title? 0/1
11 - use subtitle? 0/1
12 - use description? 0/1
13 - use duration? 0/1
14 - min duration in minutes
15 - max duration in minutes
16 - use as search timer? 0/1
17 - use day of week? 0/1
18 - day of week (0 = monday, 1 = tuesday...)
19 - use series recording? 0/1
20 - directory for recording
21 - priority of recording
22 - lifetime of recording
23 - time margin for start in minutes
24 - time margin for stop in minutes
25 - use VPS? 0/1
26 - action:
      0 = create a timer
      1 = announce only via OSD (no timer)
      2 = switch only (no timer)
27 - use extended EPG info? 0/1
28 - 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")
29 - avoid repeats? 0/1
30 - allowed repeats
31 - compare title when testing for a repeat? 0/1     
32 - compare subtitle when testing for a repeat? 0/1     
33 - compare description when testing for a repeat? 0/1     
34 - compare extended EPG info when testing for a repeat?
     This entry is a bit field of the category ids.
35 - accepts repeats only within x days
36 - delete a recording automatically after x days
37 - but keep this number of recordings anyway
38 - minutes before switch (if action = 2)

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 ;-))


3. 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.


4. 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.

5. How to trigger a search timer update?
----------------------------------------
the update of search timers runs in its own thread. There are several
ways to trigger it:
- automatically: after VDR starts there is always an update (after a
  few seconds). After this, the setup option 'Update intervall' tells
  epgsearch when the next update should be done repeatedly (in minutes).
- manually extern: the thread observes the file '.epgsearchupdate' in the
  plugins config directory. When you

  touch /path_to_file/.epgsearchupdate

  this will also trigger an update. So this is a simple solution to
  make an update e.g. by a script.
- manually intern: calling actions or pressing '3' in the menu of
  searches asks also for an update
- from other plugins: theres a service
  'Epgsearch-updatesearchtimers-v1.0' that can be used with the service
  interface of VDR from other plugins with the option to inform via
  osd when the update has finished

6. 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 in directory 'conf' 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. 

7. 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.

8. 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. 

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

9.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.

9.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)


10. Commandline options
-----------------------

  -f file,  --svdrpsendcmd=file  

the path to svdrpsend.pl for external SVDRP communication (default is
internal communication, so this is usually not needed anymore)

  -c path,  --config=path

to specify a specific config dir for all epgsearch config files

  -l file,  --logfile=file

to specify a specific logfile for epgsearch (default logfile is
epgsearch.log in the plugins config directory)

  -v n,  --verbose=n       

verbose level for logfile. Value 0 means no logging. Other values
are 1 (general messages), 2 (detailed messages), 3 (planned for extra
detailled info for debugging purposes)

11. SVDRP interface
-------------------
epgsearch implements a SVDRP interface, that can be accessed for
example like this

svdrpsend.pl PLUG epgsearch LSTS

the following commands are available:

* 'LSTS [ID]' to list all searches, or the one with the passed ID
  (format is the same as epgsearch.conf)
* 'NEWS <settings>' to add a new search
  REMARK: the value of element ID is ignored. epgsearch will always
  assign the next free ID
* 'DELS <ID>' to delete the search with ID
* 'EDIS <settings>' to modify an existing search
* 'UPDS [OSD]' to update the search timers. Passing the optional keyword
  'OSD' pops up an OSD message after the update has finished.
* 'UPDD' to reload the file epgsearchdone.data, e.g. after an
  external tool has modified it.
* 'SETS <ON|OFF>' to activate or cancel the search timer background
  thread. 
* 'FIND <settings>' for searching the EPG
  input is the same as with 'NEWS'. output is a list of found events formatted
  as 'NEWT' lines. So they can be immediately used to create a new timer for
  an event.

12. Customizing the EPG menus
-----------------------------
the file epgsearchmenu.conf in your plugins config directory is used to store
the entries for customizing the EPG menus. You specify the look of each menu
(What's on now, What's on next, What's on at ..., Schedule, Search results)
with a separate line. Here's a sample: 

MenuWhatsOnNow=%chnr%:3|%progrt2s%:5| %time% %t_status%:8|%category%:6| %title% ~ %subtitle%:35
MenuWhatsOnNext=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
MenuWhatsOnElse=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
MenuSchedule=%time% %t_status%:8|%genre%:14| %title% ~ %subtitle%:35
MenuSearchResults=%chnr%:3|%datesh% %time% %t_status%:14|%genre%:8| %title%%colon% %subtitle%:35

E.g. the entry 'MenuWhatsOnNow' tells epgsearch how you would like to build a
line for the menu 'What's on now'. This would create a menu line starting with
the channel number, followed by a progress bar in text2skin style, a space of
one char, the start time, the timer status, the EPG category (like "movie")
and finally the title and subtitle.

The values for MenuWhatsOnNext, MenuWhatsOnElse, MenuSchedule,
MenuSearchResults specify the menu 'What's on next', 'What's on at ...',
'Schedule' and 'Search results' respectively. If you do not specify one entry,
epgsearch uses it's default menu look. 

The following variables exist:

%time%           - start time in format HH:MM
%date%           - start date in format TT.MM.YY
%datesh%         - start date in format TT.MM.
%time_w%         - weekday name
%time_d%         - start day in format TT
%title%          - title
%subtitle%       - subtitle
%t_status%       - timer status ('T', 't', 'R')
%v_status%       - VPS status
%r_status%       - running status
%status%         - complete status, the same as
                   '%t_status%%v_status%%r_status%'
%colon%          - the sign ':'
%<epg-category>% - a value from the extended EPG categories, specified in
                   epgsearchcats.conf, like %genre% or %category%

for the 'Whats on...' and 'Search results' menu there is also:

%chnr%           - channel number
%chsh%           - the short channel name (>=vdr-1.3.15)
%chlng%          - the 'normal' channel name
%progr%          - graphical progress bar (not for menu 'Search results')
%progrT2S%       - progress bar in text2skin style (not for menu 'Search results')

the variables are not case sensitive. 

An entry consists of up to 6 tables separated with '|'. The last entry of
each table should declare the table width in chars, separated with ':'.

If you use a separator like '~', '-' or '#' to separate items like title or
subtitle, e.g. %title% ~ %subtitle%, and the subtitle is empty, then epgsearch
will try to fix this automatically to avoid a trailing separator.

You should vary the tab width values to fit your needs, since the look often
depends on the selected skin. You can modify the file epgsearchmenu.conf while
VDR is running, since epgsearch reloads it at every menu call.

Theres a sample epgsearchmenu.conf in the subdirectory "conf". For a quick try
copy it to your plugins config directory (e.g. /etc/vdr/plugins).

To enable icons from WarEagleIcon-Patch simply put the line

WarEagleIcons=1

to epgsearchmenu.conf.

NOTE: As long as there is a file epgsearchmenu.conf with an entry for a special
menu, all setup settings regarding the look of this menu are ignored.

 





