epgsearch - Searchtimer and replacement of the VDR program menu

       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 sensitive. Sample directory entries could look like this:

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

       There are also three other variables: %Title%, %Subtitle% and %chlng%.  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 %chlng% 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 one to form directory entries like this one:

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

       There are also the following search variables:

        %search.query% that will be replaced with the query of the search timer
        %search.series% that is '1', if the search has its 'Series recording' flag set, else '0'.

       See also "epgsearchuservars.conf(5)".

       The file epgsearchmenu.conf in your  epgsearch  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, Favorites) 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
        MenuFavorites=%chnr%:3|%time%:6|%timespan%:7|%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,  MenuFavorites  specify
       the menu 'What's on next', 'What's on at ...', 'Schedule', 'Search results' and 'Favorites' respectively.
       If you do not specify one entry, epgsearch uses its default menu look.

       'MenuSearchResults'  has something special: If you want to have different layouts for your search results
       depending on the search, you can use more then one menu template. Simply define e.g. an additional

        MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35

       This will produce an additional menu item "Result menu layout" in the edit menu of a search where you can
       choose between the default menu template and your own templates. In the example above you will  get  "Tip
       of  the  Day"  as  selection entry, since epgsearch simply cuts the leading "MenuSearchResults". When you
       display the search results the chosen template will be used instead of the default one.

       The following variables exist:

        %time%           - start time in format HH:MM
        %timeend%        - end time in format HH:MM
        %date%           - start date in format DD.MM.YY
        %datesh%         - start date in format DD.MM.
        %date_iso%       - start date in format YYYY-MM-DD.
        %year%           - year with century
        %month%          - month (1-12)
        %day%            - day (1-31)
        %week%           - week number of the year (Monday as the first day of the week) as a decimal number [01,53]
        %time_w%         - weekday name
        %time_d%         - start day in format TT
        %time_lng%       - start time in seconds since 1970-01-01 00:00
        %timespan%       - timespan from now to the beginning of an event, e.g. 'in 15m'
                           or the time an event is already running, e.g. '10m'.
        %length%         - length in seconds
        %title%          - title
        %subtitle%       - subtitle
        %summary%        - summary
        %htmlsummary%    - summary, where all CR are replaced with '<br />'
        %eventid%        - numeric event ID
        %liveeventid%    - encoded event ID as used in the frontend 'live'
        %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%'

        %<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 are also:

        %chnr%           - channel number
        %chsh%           - the short channel name
        %chlng%          - the 'normal' channel name
        %chdata%         - VDR's internal channel representation (e.g. 'S19.2E-1-1101-28106')
        %progr%          - graphical progress bar (not for menu 'Search results'),
                           requires VDRSymbols font
        %progrT2S%       - progress bar in text2skin style (not for menu 'Search results')

       some independent variables:

        %colon%          - the sign ':'
        %datenow%        - current date in format DD.MM.YY
        %dateshnow%      - current date in format DD.MM.
        %date_iso_now%   - current date in format YYYY-MM-DD
        %timenow%        - current time in format HH:MM
        %videodir%       - VDR video directory (e.g. /video)
        %plugconfdir%    - VDR plugin config directory (e.g. /etc/vdr/plugins)
        %epgsearchdir%   - epgsearch config directory (e.g. /etc/vdr/plugins/epgsearch)

       The variables are not case sensitive. You can also use variables for extended EPG categories  defined  in
       epgsearchcats.conf or use your own user defined variables defined in epgsearchuservars.conf

       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.  epgsearchmenu.conf  is not reloaded with every plugin call, since this is only useful when testing
       the conf file. To activate the permanent reload for testing your conf, pass the new start parameter  '-r'
       or '--reloadmenuconf' in your runvdr.

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

       To enable icons from the VDRSymbols font simply put the line

        WarEagleIcons=1

       to        epgsearchmenu.conf.        The        VDRSymbols        font        is       available       at
       http://andreas.vdr-developer.org/fonts/download.html

       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.

       See also "epgsearchmenu.con(5)".

       If  a  conflict  is  detected  within the periodic conflict background check you get an OSD message which
       informs you about it. Pressing 'Ok' you will get a menu that displays all  relevant  conflicts.  You  can
       manually call this menu in epgsearch in the menu 'Search/Actions'.

       Besides  the  relevant  conflicts  (relevance is controlled via the setup options of epgsearch) there may
       also be conflicts which are not classified as important. If so, you can  press  'Show  all'  to  get  the
       complete list. The menu title always displays the number of relevant conflicts and the total number.

       The list displays first the time when a conflict appears and then all timers that will fail here. A timer
       entry consists of the channel number and its name followed by the timer priority and the percentage value
       that shows how much of the timer will be recorded. Finally the timer's file entry is displayed.

       When  you  select  a  timer  entry  and  press  'Ok'  or  'Details' you get a new menu which displays all
       concurrent timers. This menu allows you to resolve the conflict by

        - searching a repeat for an event
        - disabling a timer
        - deleting a timer
        - changing the timers start- or stop-time or its priority
        - executing any other commands on this timer

       An entry of this menu consists of the sign '>' to indicate an active timer, the channel number, the start
       and stop time, the priority, the number of the device that will do the recording (or  'C'  for  conflict)
       and  the  timer's  file  entry.  Pressing  'Ok'  on  a timer entry will show you its event description if
       present.

       If one returns from this menu to the conflict overview menu there will be an automatic update to see if a
       conflict was really resolved. Some changes to a timer (like modifying start/stop or deleting a timer)  in
       the conflict details menu also cause an immediate return to the overview menu and produce an update.

       Note:  There's  a 'hidden' setup option epgsearch.ConflCheckCmd, that allows executing a command for each
       timer causing a conflict. You have to set this directly in VDRs setup.conf like this:

       epgsearch.ConflCheckCmd = system(your_script_handling_the_conflict.sh, any_arguments like %timer.file%)

       (Please have a look at 'Calling a system command' below for the possible arguments) One  could  use  this
       for  example  to forward a timer to another VDR machine in case of a conflict.  This command is evaluated
       for each timer causing a conflict whenever an automatic conflict  check  is  running.  When  calling  the
       conflict check via OSD the command is not evaluated.

       You  can  create  your  own  variables  to be used in any place that supports variables, like the default
       recording directory for manually created timers, the recording directory of a search  timer  or  in  your
       customized EPG menus.  Put them in the file epgsearchuservars.conf.

       Variables looks like %Variablename%.

       "Variablename"  can  be  consist  of  any  alphanumerical character. Space and special characters are not
       allowed.

       The variable names are case-insensitive.

       Examples for possible names:

        %Series% %DocuVar1% %ThemesSubtitleDate1%

   Assignment
        %Series%=New series~Thriller

       The variable %Series% will be assigned with the string "New series~Thriller".

       Assignments are always strings. Spaces stay spaces.

        %Path%=%Series%

       The variable %Path% gets the content of the variable %Series%.

       You can do nearly everything:

        %Path%=%Serie%~Lost

       The variable %Path% contains now the string "New series~Thriller~Lost".

   Controlstructures
       You can use simple "if then else" constructions.

       These constructions cannot contain strings, only variables.  Spaces are ignored.

        %Foo%=Other

        %Variable%=%Path% ? %Path% : %Foo%

       If %Path% is not empty, assign the content of %Path% to %Variable%, otherwise the content of %Foo%.

       "%Path% ?" means "not empty?". You can use other checks.

        %Variable%=%Path%!=5 ? %Path% : %Foo%

       "%Path%!=5 ?" means "is %Path% equal 5?"

       You can also compare variables.

        %Five%=5

        %Variable%=%Path%!=%Five% ? %Path% : %Foo%

       Other possible checks:

        ==   equal
        !=   not equal

   Callingasystemcommand
       You can call external commands. The returned string will be assigned to a variable

        %uservar%=system(scriptname[, parameters])

       Calls the script "scriptname" with the parameters defined in the optional list of 'parameters'. This  can
       be  an arbitrary expression containing other user variables, but not again a system call or a conditional
       expression.

       Sample:

        %myVar%=system(/usr/local/bin/myscript.sh, -t %title% -s %subtitle% -u %myOtherVar%)

       The script must return a string without line break!

       If the script returns nothing, an empty string will be assigned to the Variable %Result%.

   CallingaTCPservice
       You can call a TCP service with the following syntax:

        %uservar%=connect(<addr>, <port>, [<data>])

       This will connect to <addr> through the given port and pass the optional given data. <addr> can be an  IP
       address or the domain name of the TCP service. The result returned by the service must be terminated with
       a line feed.

   Getthelengthofanargument
       When  passing  any  values  to  the  connect or system command it can be helpful to have the length of an
       argument for simple parsing. This can be done with

        %uservar%=length(<any arguments>)

       Sample:

       %length_title%=length(%title%)

   Possiblevariables
       for a list of already builtin variables refer to the section "Customizing the EPG menus" Furthermore  you
       can use every variable defined in epgsearchcats.conf.

       See "epgsearchcats.conf(5)".

   EXAMPLES
        # Weekday, Date, Time
        %DateStr%=%time_w% %date% %time%

        # Themes or Subtitle or Date
        %ThemesSubtitleDate1%=%Subtitle% ? %Subtitle% : %DateStr%
        %ThemesSubtitleDate%=%Themes% ? %Themes% : %ThemesSubtitleDate1%

        # Calls this script to get a recording path
        %DocuScript%=system(doku.pl, -t %Title% -s %Subtitle% -e %Episode% -th %Themes% -c %Category% -g %Genre%)
        %Docu%=%DocuScript%

       If  you want to get email notifications about timers added/modified/removed by the search timer thread or
       about timer conflicts, first copy the script 'sendEmail.pl' to the place where your executables are (e.g.
       /usr/local/bin) and then configure your email account in the setup. Press 'Test' to check  if  it  works.
       There  should  be  something like 'Email successfully sent' at the end of the output.  The content of the
       mails is defined by the files

         - epgsearchupdmail.templ (for search timer update notifications)
         - epgsearchconflmail.templ (for timer conflict notifications)

       You can find sample files in the 'conf' directory. Copy them to  the  epgsearch  config  directory  (e.g.
       /etc/vdr/plugins/epgsearch).

   Customizingthenotificationsmails
       The  content  of the mails can be customized in many ways. You can use plain text or HTML (see the sample
       conf/epgsearchupdmail-html.templ). For an update mail you have to define the following sections:

         - "subject" to be used as mail subject
         - "mailbody" the body of the mail:
           put %update.newtimers% in the place where the list of new timers should
           appear. The same for %update.modtimers%, %update.deltimers% and
           %update.newevents% for the list of changed or deleted timers and event
           announcements.
         - "timer" the description of one timer and "event" with the description of
           one event. This section is used to display one timer within a timer list,
           e.g. in %update.newtimers%. The same for "event".

       All sections are optional, e.g. if you don't use event announcements you can drop "%update.newevents%" in
       the mailbody and the "event" section. But of course you should have at least a mailbody ;-) Each  section
       is enclosed in a pseudo XML tag.

       The following variables can be used in the section <mailbody>:

         - %update.newtimers%      - will be replaced with the list of new timers
                                     created with this update. The timers are
                                     displayed as defined in the section '<timer>'
         - %update.countnewtimers% - the number of new timers
         - %update.modtimers%      - same as %update.newtimers% but for modified
                                     timers.
         - %update.countmodtimers% - the number of modified timers
         - %update.deltimers%      - same as %update.newtimers% but for deleted
                                     timers. (Note: a deleted timer has eventually
                                     no event assigned to it. So all event variables
                                     within the timer section will be substituted to
                                     an empty string.)
         - %update.countdeltimers% - the number of deleted timers
         - %update.newevents%      - will be replaced with the list of events to
                                     announce. These events are the search result of
                                     search timers with the action "announce by mail".
                                     The events are displayed as defined in the section
                                     '<event>'
         - %update.countnewevents% - the number of new events
         - %colon%                 - the sign ':'
         - %datenow%               - current date in format TT.MM.YY
         - %dateshnow%             - current date in format TT.MM.
         - %timenow%               - current time in format HH:MM

       The following variables can be used in the section <timer>:

         - %timer.date%            - date of the timer
         - %timer.start%           - start time of the timer
         - %timer.stop%            - stop time of the timer
         - %timer.file%            - recording directory of the timer
         - %timer.chnr%            - channel number
         - %timer.chsh%            - short channel name
         - %timer.chlng%           - channel name
         - %timer.search%          - name of the search timer, that created the timer
         - %timer.searchid%        - id of the search timer, that created the timer
         - %timer.modreason%       - the reason for a timer modification in plain text
         - %timer.liveid%          - encoded timer ID as used in the frontend 'live'
         - any event variable (as in '10. Customizing the EPG menus')
         - any extended EPG variable as defined in epgsearchcats.conf
         - any user variable (as in '12. User defined variables')

       The following variables can be used in the section <event>:

         - any event variable (as in '10. Customizing the EPG menus')
         - %search%                - the name of the search timer that triggered
                                     this event
         - %searchid%              - the ID of the corresponding search timer
         - any extended EPG variable as defined in epgsearchcats.conf
         - any user variable (as in '12. User defined variables')

       For a conflict notification mail the following sections exist:

         - "subject" to be used as mail subject
         - "mailbody" the body of the mail. Put %conflict.conflicts% in the place
           where the list of conflict times should appear (Note: there can be more
           than one timer conflict at the same time!). A conflict time uses the
           section 'conflictsat' to display its content.
         - "conflictsat" the description of one time where one or more conflicts
           exists. Put %conflict.confltimers% in the place where the list of conflict
           timers should appear.
         - "confltimer" the description of one conflicting timer

       The following variables can be used in the section <mailbody>:

         - %conflict.count%        - complete number of timer conflicts
         - %conflict.conflicts%    - list of times with conflicting timers

       The following variables can be used in the section <conflictsat>:

         - %conflict.date%         - date of the conflict
         - %conflict.time%         - time of the conflict
         - %conflict.confltimers%  - list of conflicting timers for this time

       The  section  <conflicttimer>  can  use  the same variables as the section <timer> in an update mail (see
       above).

       epgsearch supports a configuration mechanism well-known in linux. The settings of the configuration files

         - epgsearchuservars.conf
         - epgsearchdirs.conf
         - epgsearchmenu.conf
         - epgsearchcats.conf

       can   also   be   given   in   a   file   with   arbitrary   name   in   the   subdirectory   conf.d   in
       <plugin-configuration-directory>/epgsearch.  This  allows  one  to  quickly test different setups only by
       exchanging files instead of editing them. The format of these files is

         [<section name>]
         <settings>
         ...

         [<section name>]
         <settings>
         ...

       where <section_name> is one of the following:

         - epgsearchuservars
         - epgsearchdirs
         - epgsearchmenu
         - epgsearchcats

       The <settings> format follows the one in the corresponding configuration file.  Comments beginning with #
       are allowed, also blank lines.  At startup epgsearch first reads its 'regular'  configuration  files  and
       then  the  conf.d  subdirectory.   It's  allowed  to  overwrite  variables already defined in other files
       (although this is signaled with a warning in epgsearch's log file.).

       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 field 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 = Interval, 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
              5 - fuzzy searching (specify tolerance in parameter 42, not available
                  for EPG categories)
        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/2 (with 2 one can specify time margins in
             parameter 48/49 where the search timer is active)
        17 - use day of week? 0/1
        18 - day of week (0 = Sunday, 1 = Monday...;
             -1 Sunday, -2 Monday, -4 Tuesday, ...; -7 Sun, Mon, Tue)
        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 translated 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=no/1=yes/2=yes-if present
        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)
        39 - pause if x recordings already exist
        40 - blacklist usage mode (0 none, 1 selection, 2 all)
        41 - selected blacklist IDs separated with '|'
        42 - fuzzy tolerance value for fuzzy searching
        43 - use this search in favorites menu (0 no, 1 yes)
        44 - number of the search menu template to use (only available if multiple
             search result templates are defined in epgsearchmenu.conf)
        45 - auto deletion mode (0 don't delete search timer, 1 delete after given
             count of recordings, 2 delete after given days after first recording)
        46 - count of recordings after which to delete the search timer
        47 - count of days after the first recording after which to delete the search
             timer
        48 - first day where the search timer is active (see parameter 16)
        49 - last day where the search timer is active (see parameter 16)
        50 - ignore missing EPG categories? 0/1
        51 - unmute sound if off when used as switch timer
        52 - the minimum required match in percent when descriptions are compared to avoid repeats (-> 33)

       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 translated to "!^pipe^!" (I know it's ugly
       ;-))

       See also "epgsearch.conf(5)".

       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 split 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 INSTALL).

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

       With each update, the plugin first sorts the search timers by timer priority (descending) and search term
       and  then  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 (or the events duration if this is less then 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.

       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 interval' 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

       there's 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

       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 F<epgsearchdirs.conf>,
            see C<epgsearchdirs.con(5)>
          * entries in VDR's folders.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.  This list can also be accessed via the SVDRP command 'LSRD'.

       If   you   like   to   have  a  language  dependent  list  of  commands  simply  translate  your  present
       epgsearchcmds.conf to your preferred 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.

       See also "epgsearchcmds.conf(5)".

       Searching the EPG and other functionality can be  used  by  other  plugins  or  scripts.  There  are  two
       approaches:

   8.1.File-based(intendedforuseinscripts)
       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 (you must have assigned a key to it), e.g.

        svdrpsend HITK green

       At startup Epgsearch will look for this file and give you the search  results  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.

   8.2.viaPlugin-Interface(intendedforuseinplugins)
       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.

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

        svdrpsend PLUG epgsearch LSTS

       the following commands are available:

   searchmanagement:
        * '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.
        * 'MODS ID ON|OFF' turns on/off the option 'Use as search timer'.
        * 'UPDD' to reload the file epgsearchdone.data, e.g. after an
          external tool has modified it.
        * 'SETS <ON|OFF>' to temporarily 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.
        * 'QRYS < ID(s) >' to get the results for a search with the given
          ID. Multiple IDs can also be passed and have to be separated with '|'.
          The results are formatted like this:

          search ID    : // the ID of the corresponding search timer
          event ID     : // VDR event ID
          title        : // event title, any ':' will be converted to '|'
          episode name : // event short text, any ':' will be converted to '|'
          event start  : // event start in seconds since 1970-01-01
          event stop   : // event stop in seconds since 1970-01-01
          channel      : // channel ID in VDR's internal representation (e.g. 'S19.2E-1-1101-28106')
          timer start  : // timer start in seconds since 1970-01-01 (only valid if timer flag is > 0)
          timer stop   : // timer stop in seconds since 1970-01-01 (only valid if timer flag is > 0)
          timer file   : // timer file (only valid if timer flag is > 0)
          timer flag   : // 0 = no timer needed, 1 = has timer, 2 timer planned for next update)
        * 'QRYS <settings>' to get the results for a search with the given search
          settings.
        * 'QRYF [hours]' to get the results for the favorites menu, see QRYS for
          result format. The optional parameter specifies the number of hours to
          evaluate and defaults to 24h.
        * 'MENU [PRG|NOW|SUM]' calls one of the main menus of epgsearch or the summary
          of the current event.
        * 'UPDT' reloads the search timers from epgsearch.conf

   channelgroupmanagement:
        * 'LSTC [channel group name]'
          list all channel groups or if given the one with name 'group name'
        * 'NEWC <channel group settings>'
          create a new channel group, format as in epgsearchchangrps.conf
        * 'EDIC <channel group settings>'
          modify an existing channel group, format as in epgsearchchangrps.conf
        * 'DELC <channel group name>'
          delete an existing channel group
        * 'RENC <old channel group name|new channel group name>'
          rename an existing channel group

   blacklistmanagement:
        * 'LSTB [ID]' to list all blacklists, or the one with the passed ID
          (format is the same as epgsearchblacklists.conf)
        * 'NEWB <settings>' to add a new blacklist
          REMARK: the value of element ID is ignored. epgsearch will always
          assign the next free ID
        * 'DELB <ID>' to delete the blacklist with ID
        * 'EDIB <settings>' to modify an existing blacklist

   searchtemplatemanagement:
        * 'LSTT [ID]' to list all search templates, or the one with the passed ID
          (format is the same as epgsearch.conf)
        * 'NEWT <settings>' to add a new search template
          REMARK: the value of element ID is ignored. epgsearch will always
          assign the next free ID
        * 'DELT <ID>' to delete the search template with ID
        * 'EDIT <settings>' to modify an existing search template
        * 'DEFT [ID]' returns the ID of the default search template. When passing an
          ID it activates the corresponding template as default.

   extendedEPGcategories:
        * 'LSTE [ID] to get the extended EPG categories defined in epgsearchcats.conf
          or the one with the given ID. (format is the same as epgsearchcats.conf)

   misc:
        * 'SETP [option]' returns the current value of the given setup option or a
          list of all options with their current values.
          The following options can be accessed:
           - ShowFavoritesMenu
           - UseSearchTimers

   timerconflicts:
        * 'LSCC [REL]' returns the current timer conflicts. With the option 'REL' only
          relevant conflicts are listed. The result list looks like this for example
          when we have 2 timer conflicts at one time:

          1190232780:152|30|50#152#45:45|10|50#152#45

          '1190232780' is the time of the conflict in seconds since 1970-01-01. It's
          followed by list of timers that have a conflict at this time:

          '152|30|50#152#45' is the description of the first conflicting timer. Here:

          '152' is VDR's timer id of this timer as returned from VDR's LSTT command
          '30' is the percentage of recording that would be done (0...100)
          '50#152#45' is the list of concurrent timers at this conflict

          '45|10|50#152#45' describes the next conflict

       Mike Constabel <epgsearch (at) constabel (dot) net>

        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.  The sources of the 'Select directory' menu
        7.  Language dependent commands for EPG
        8.  Usage from other plugins or scripts
        9.  SVDRP interface
        10. Customizing the EPG menus
        11. Working with the timer conflict menu
        12. User defined variables
        13. Email notifications
        14. The conf.d subdirectory

       Copyright (C) 2004-2010 Christian Wieninger

       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 2 of the License,  or
       (at your option) any later version.

       This  program  is  distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General  Public
       License for more details.

       You  should have received a copy of the GNU General Public License along with this program; if not, write
       to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,  MA  02110-1301  USA  Or,
       point your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html

       The author can be reached at cwieninger@gmx.de

       The project's page is at http://winni.vdr-developer.org/epgsearch

       The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

perl v5.40.0                                       2025-02-05                                       epgsearch(4)

       epgsearch - Searchtimer and replacement of the VDR program menu

       Since the README get bigger and bigger this man page shall be used to explain some things in detail. So
       it's not really a manual, but an extended README.

       Bug reports (german):

       <http://projects.vdr-developer.org/projects/plg-epgsearch>

       Mailing list:

       <http://www.vdr-developer.org/mailman/listinfo/epgsearch>

epgsearch(1),       "epgsearch.conf(5)",       "epgsearchuservars.con(5)",       "epgsearchdirs.conf(5)",
       "epgsearchmenu.conf(5)", "epgsearchcmds.conf(5)"