4mepgsearch24m(4)                Epgsearch Version 2.4.4               4mepgsearch24m(4)

1mNAME0m
       epgsearch - Searchtimer and replacement of the VDR program menu

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

1mCONTENT0m
        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

1m1. Using variables in the directory entry of a search timer0m
       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)".

1m2. The format of epgsearch.conf0m
       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
       1m':'22m:

         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 format: hhmm
        15 - max duration format: hhmm
        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)
              3 = announce via OSD and switch (no timer)
              4 = announce via mail
        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 - ID 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 (-> 16)
        49 - last day where the search timer is active (-> 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)
        53 - HEX representation of the content descriptors, each descriptor ID
             is represented with 2 chars
        54 - compare date when testing for a repeat?
             (0=no, 1=same day, 2=same week, 3=same month)

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

1m3. Description of the search process0m
       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 4mINSTALL24m).

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

1m4. How do Search Timers work?0m
       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.

1m5. How to trigger a search timer update?0m
       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

1m6. The sources of the 'Select directory' menu0m
       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'.

1m7. Language dependent commands for EPG0m
       If  you  like  to  have  a  language  dependent list of commands simply
       translate  your  present  4mepgsearchcmds.conf24m  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
       4mepgsearchcmds.conf24m.

       See also "epgsearchcmds.conf(5)".

1m8. Usage from other plugins or scripts0m
       Searching  the EPG and other functionality can be used by other plugins
       or scripts. There are two approaches:

   1m8.1. File-based (intended for use in scripts)0m
       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 4mrecrep.sh24m, that searches for the repeats of a recording
       exists in the scripts subdirectory of Epgsearch.

   1m8.2. via Plugin-Interface (intended for use in plugins)0m
       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.

1m9. SVDRP interface0m
       epgsearch implements a  SVDRP  interface,  that  can  be  accessed  for
       example like this

        svdrpsend PLUG epgsearch LSTS

       the following commands are available:

   1msearch management:0m
        * '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
          REMARK: An empty value (::) is ignored but
          search,directory,contentlist are cleared if not replaced with a new value
        * '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

   1mchannel group management:0m
        * '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

   1mblacklist management:0m
        * '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

   1msearch template management:0m
        * '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.

   1mextended EPG categories:0m
        * '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)

   1mmisc:0m
        * '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

   1mtimer conflicts:0m
        * '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

1m10. Customizing the EPG menus0m
       The  file 4mepgsearchmenu.conf24m 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 4mepgsearchcats.conf24m or use  your  own
       user defined variables defined in 4mepgsearchuservars.conf0m

       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 4mepgsearchmenu.conf24m 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   4mepgsearchmenu.conf24m.   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)".

1m11. Working with the timer conflict menu0m
       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.

1m12. User defined variables0m
       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 4mepgsearchuservars.conf24m.

       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%

   1mAssignment0m
        %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".

   1mControl structures0m
       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

   1mCalling a system command0m
       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 1mwithout 22mline break!

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

   1mCalling a TCP service0m
       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.

   1mGet the length of an argument0m
       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%)

   1mPossible variables0m
       for   a  list  of  already  builtin  variables  refer  to  the  section
       "Customizing the EPG menus" Furthermore  you  can  use  every  variable
       defined in 4mepgsearchcats.conf24m.

       See "epgsearchcats.conf(5)".

   1mEXAMPLES0m
        # 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%

1m13. Email notification0m
       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).

   1mCustomizing the notifications mails0m
       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).

1m14. The conf.d subdirectory0m
       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.).

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

1mAUTHOR (man pages)0m
       Mike Constabel <epgsearch (at) constabel (dot) net>

1mREPORT BUGS0m
       Bug reports (german):

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

       Mailing list:

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

1mCOPYRIGHT and LICENSE0m
       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.1                      2025-10-30                      4mepgsearch24m(4)
