epgsearch(1)                 EPGSearch Version 2.4.6                epgsearch(1)

NAME
     EPGSearch  –  search  timers and replacement of the VDR's default schedules
     menu

OVERVIEW
     EPGSearch can be used as a replacement for the default schedules  menu.  It
     looks rather the same, but adds some additional functions:

     • The  main menu can be configured to replace the VDR's default schedule by
       an extended program guide.

     • The program guide allows switching  between  the  next  and  the  current
       events.

     • In  addition to displaying current and next events, the program guide al‐
       lows viewing the events for up to four user-defined  times,  as  well  as
       configurable favorites.

     • Shifting  the  time displayed in the program guide by key press (e.g., by
       30 minutes).

     • Progress bar in the program guide for current and next events.

     • Built-in commands allow, amongst others, looking for repeats of events or
       create search timers for them. Own commands can be added as well, for ex‐
       ample, to set up VDRAdmin auto-timers.

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

     • Search  timer:  Background search for matching events and creation of re‐
       spective timers (similar to VDRAdmin's auto-timers) or just  notification
       via OSD.

     • Support  of  content  descriptors and extended EPG information for search
       timers.

     • Avoiding multiple recordings of the same event:

       – timer preview
       – recognition of broken recordings
       – fuzzy event comparison
     • Extension of the timer-edit menu with a directory item,  flexible  selec‐
       tion of weekdays, and subtitle ("episode name") completion.

     • Background check for timer conflicts in combination with a timer-conflict
       manager.

     • Notification of detected timer conflicts via OSD messages.

     • Detailed information of timer conflicts and suuport for resolving them.

     • E-mail notifications about search-timer updates and timer conflicts.

     Parts  of  the  sources  are  based on the Repeating-EPG patch from Gerhard
     Steiner, who authorized their use. Thanks for his work!

OPTIONS
     −f file,  −−svdrpsendcmd=file
         The path to svdrpsend for external  SVDRP  communication.  As  internal
         communication  will  be used by default, this option is usually not re‐
         quired.

     −c path,  −−config=path
         Specifies a specific directory for all  EPGSearch  configuration  files
         (defaults to <plugins configuration directory>/epgsearch).

     −l file,  −−logfile=file
         Specifies  a  specific  log  file  for  EPGSearch.  Default log file is
         epgsearch.log in the EPGSearch configuration directory.

     -v n,  −−verbose=n
         Verbose level for the log file. Value 0 means no logging. Other  values
         are  1 (general messages), 2 (detailed messages), 3 (for debugging pur‐
         poses).

     −r,  −−reloadmenuconf
         Reload epgsearchmenu.conf with each plugin call within the  OSD.   This
         can be useful when testing customized menu layouts.

     −m file,  −−mailcmd=file
         External  command  to  be  used  for  e-mail delivery. The default uses
         sendEmail.pl. When using a different command or script, make sure  that
         it has the same parameter interface as sendEmail.pl.

CONTENT
     1. Description
        1.1 Menu 'Commands'
        1.2 Menu 'Search'
            1.2.1 Menu 'Edit search'
            1.2.2 Menu 'Search results'
        1.3 Extended 'Now' and 'Next'
        1.4 Menu 'Setup'
            1.4.1 General
            1.4.2 EPG menus
            1.4.3 User-defined EPG times
            1.4.4 Timer programming
            1.4.5 Search and search timers
            1.4.6 Timer conflict checking
            1.4.7 E-mail notification
     2. Search timers
        2.1 Avoiding repeats in detail
        2.2 How do we compare two events?
        2.3 How and when do we compare?
            2.3.1 How to use it?
            2.3.3 If it does not work correctly
     3. Usage from other plugins or scripts
     4. Using extended EPG info
     5. Replacing the standard schedule menu
     6. Add-ons

1. Description
     At  first glance, EPGSearch looks like the schedules menu entry of the VDR.
     Pressing the key 0 toggles the bottom color keys for  accessing  additional
     functions  (the  default  assignment  of  the color keys can be adjusted by
     setup).

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

     Repeats
         Searches for events with same title.

     Record
         Creates a timer for recording the event.

     Switch
         Switches to the channel broadcasting the event.

     Create search
         Switches to the search menu, adding a new search with the name  of  the
         current event (to avoid entering the name manually).

     Search in recordings
         Search the recordings for an event with the same name.

     Mark as 'already recorded'?
         Adds  the  selected  event to the file epgsearchdone.data and instructs
         EPGSearch to avoid recording this event if the related search timer  is
         set  to 'avoid repeats'. An already created timer will be automatically
         removed with the next search-timer update.

     Add/Remove to/from switch list?
         Controls the switch list. If an event is in the switch list,  EPGSearch
         will  announce  it  and  switch  to  the  event  before it starts. Call
         'Search' » 'Actions' » 'Switch list' for accessing  the  entire  switch
         list.

     Create blacklist
         A blacklist is used to ignore events when using search timers. A search
         timer can be set up to ignore events from arbitrary blacklists.

     You   can  add  your  own  commands  to  this  menu  by  editing  the  file
     epgsearchcmds.conf in the EPGSearch configuration directory. There's a sam‐
     ple configuration file with some exemplary commands (see directory scripts,
     taken from 'vdr-wiki.de' – thanks to the authors).

     The format of the file is the same as VDR's commands.conf or  reccmds.conf;
     also see epgsearchcmds.conf(5).

     When a command is executed, the following parameters are provided:

     $1  Title of the EPG entry.

     $2  Start  time  of  the  EPG  entry in Epoch encoding (i.e., seconds since
         1970-01-01 00:00 UTC), like in the shutdown script.

     $3  Stop time of the EPG entry  in  Epoch  encoding  (i.e.,  seconds  since
         1970-01-01 00:00 UTC).

     $4  Channel number of the EPG entry.

     $5  Long channel name of the EPG entry.

     $6  Subtitle of the EPG entry, or an empty string if not present.

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

   1.2 Menu 'Search'
     This menu allows adding, editing, deleting and executing own queries on the
     EPG. The usage and behavior is like the VDR's timer menu.

     1.2.1 Menu 'Edit search'

     Most things in this menu are quite clear. Thus, only some notes on selected
     elements:

     Search term
         The term to search for. If you like to search for several words,  sepa‐
         rate  them  by  blanks.  Leaving  this empty (combined with search mode
         'phrase'), will match anything.  This  is,  for  example,  useful  when
         searching  for  all  EPG  entries that start within a span of time on a
         specific channel.

         Using key 'blue', you can also select a template for the new search. If
         one of the templates is set to default, new searches will automatically
         get the settings of the default template.

         Note: Fuzzy searching is limited to 32 characters!

     Search mode
         A search can be performed in several flavors:

         Phrase
             Searches for the expression within the EPG.

         All words
             Requires that each word of the expression occurs in the EPG item.

         At least one word
             Requires that at least one word of the expression occurs in the EPG
             item.

         Match exactly
             Requires that the search term exactly matches the found title, sub‐
             title or description. This is particularly helpful  for  short  ti‐
             tles, like "ALF".

         Regular expression
             A  regular  expression serves as search term. Enclosing '/' charac‐
             ters are not required.

             If the plugin's Makefile has automatic  configuration  enabled  (no
             '#'  before  'AUTOCONFIG = 1'), Perl-compatible regular expressions
             (PCRE) will be used by default; this requires libpcre  or  libpcre2
             being installed.  Alternatively, POSIX-extended regular expressions
             featuring  approximate  matching  will  be employed, which requires
             libtre on your machine.

             Without automatic  configuration,  simply  edit  the  Makefile  and
             change  '#REGEXLIB  = pcre2' to 'REGEXLIB = pcre2', adapt the regu‐
             lar-expression library to the one desired, and recompile  the  plu‐
             gin. The required library must possibly be installed beforehand us‐
             ing the machine's packet manager.

         Fuzzy
             Compares  the search term based upon the Levenshtein-Distance algo‐
             rithm.  The value of 'Tolerance' determines how much  deviation  is
             acceptable.

         See also "Description of the search process" in epgsearch(4).

     Use content descriptors
         Some   providers  deliver  content  descriptors  in  their  EPGs,  like
         'movie/drama', 'sports', and so  forth.  Such  descriptors,  which  are
         available  since  VDR 1.7.11, can be included in a search. Multiple se‐
         lection is possible, for which the matching scheme is configurable  per
         search.

         All selected descriptors must match by default (AND operator). However,
         you can choose that just one matching descriptor will be sufficient (OR
         operator).   As  similar  content descriptors are arranged into groups,
         you can alternatively define that one match per used group will be suf‐
         ficient (OR operator within a group, AND operator across groups).

         Furthermore, special characteristics of events (like original language,
         black & white) are hosted in a distinct group that deviates  from  this
         similarity  scheme.  You can specifically define for this group whether
         all selected descriptors must match (defaults to AND operator) or  just
         one of them (OR operator).

     Use extended EPG info
         Only available if configured, see 'Using extended EPG info' below.

     Category matching mode
         By  default,  all  selected  categories  must be present in the EPG and
         match the specified values. Selecting 'all except  missing  categories'
         prevents  an  event  from being excluded from the search results simply
         because a selected category is not present in the  EPG.  Alternatively,
         you  can specify 'at least one category', in which case matching a sin‐
         gle category will be sufficient.

         Caution: Using an alternate matching mode  without  other  sufficiently
         limiting criteria could flood the timers.

     Use channel
         Search only for events in the given channel interval, channel group, or
         free-to-air (FTA) channels only.

         Channel groups (e.g., sport channels or Pay-TV channels) can be managed
         with a submenu invoked with key 'blue'.

         Attention:  Please check the range settings of your search timers after
         changing the sequence of the channels!

     Use day of week
         Besides the weekdays, you can also create a user-defined  selection  to
         search, for instance, only on Mondays and Fridays.

         You'll  find  the  user-defined  selection  after  the list of weekdays
         ('So.', 'Mo.', ..., 'Sa.'). Press key 'red' for  creating  or  changing
         the selection.

     Use blacklists
         Blacklists allow excluding unwanted events. Select only global lists or
         one,  more  or  all  blacklists here. If any search result is also con‐
         tained in one of the selected blacklists, it will be skipped.

     Use in favorites menu
         Only available if turned on in setup. With this option, you can mark  a
         search to be used in the favorites menu. The search results of all such
         searches are listed in the favorites menu.

     Result menu layout
         Only  available  if  you  have  defined more than one menu template for
         search results in epgsearchmenu.conf. This option is used to  assign  a
         different menu layout for the search results of this search.

     Use as search timer
         If  set  to  'yes',  the plugin will run background scans of the EPG in
         certain intervals and add a timer if there is a match  (you  must  have
         activated  'Use search timers' in the setup). If set to 'user-defined',
         one can specify a time span with the key 'blue' during which the search
         timer shall be active.

     Action
         The default action is creating a timer for each search result. But  you
         can  also  choose to simply announce the found event via OSD as soon as
         it is found or to automatically switch to the event before  it  starts.
         It's  also  possible  to  get  an announcement via OSD before the event
         starts and to switch to its channel with key 'OK'. Further available is
         'Announce by mail' and 'inactive record'.

     Series recording
         If set to 'yes', the recordings will be stored in a folder with the ti‐
         tle as name of the series, and each recording will receive the subtitle
         as episode name.  If unavailable, the date and time  of  the  broadcast
         will be used instead.

     Directory
         Here you can assign a directory in which the recording shall be stored,
         like  'SciFi'.  Use  the key 'blue' to select directory entries already
         used in other search entries. The list can further be extended  by  en‐
         tries  in  the  file epgsearchdirs.conf, one directory per line without
         the preceding path of the video directory; also see epgsearch(4).

         If your provider delivers extended EPG information, you  can  also  use
         variables like '%Genre%' or '%Category%' in the directory entry.  These
         will  be  replaced  with  the event's respective EPG information once a
         timer gets created.

         See also "Using variables in the directory entry of a search timer"  in
         epgsearch(4).

     Delete recordings after ... days
         Some  recordings  should  only  be kept for a few days, like news. With
         this feature, you can instruct EPGSearch to delete  them  automatically
         after a chosen number of days.

     Pause when ... recordings exist
         If  the  given  number  of recordings exists, EPGSearch will not create
         further timers. After deleting one or more  of  these  recordings,  new
         timers will be generated again.

     Avoid repeats
         If  you don't want to record repeats, this feature tries to check if an
         event was already programmed or recorded and then skips it. Please  re‐
         fer to the section "Avoiding repeats in detail" below before using it.

     Allowed repeats
         If  you  like  to  accept  a certain number of repeats, you can specify
         their number here.

     Only repeats within ... days
         Specify the number of days during which a repeat must follow its  first
         broadcast. A value of 0 means no restriction.

     Compare title
         When comparing events, specify whether the title shall be considered.

     Compare subtitle
         When  comparing  events,  specify whether the subtitle shall be consid‐
         ered.  With 'yes', EPGSearch will classify two events only as equal  if
         their subtitles match and are not empty.

         With  'allow  empty',  two  events  may  be equal if both subtitles are
         empty.  Normally you would choose 'no' in this case.

     Compare description
         When comparing events, specify whether the description shall be consid‐
         ered.

         Before comparing two descriptions, all parts looking like category val‐
         ues will be removed; the remaining texts will  be  compared  with  each
         other.   If the percentage of similarity regarding the Levenshtein-Dis‐
         tance algorithm complies with the value of the  next  option,  the  de‐
         scriptions will be considered equal.

     Min. match in %
         The needed minimum match of descriptions in percent.

     Compare date
         Sometimes  a  broadcast is repeated many times within some period (day,
         week, month, etc.), but the repeats cannot be  distinguished  based  on
         the  EPG  contents.  So, the only available information is its time. To
         use this for comparison, select the appropriate period.

     Compare categories
         With the button 'Setup' you can also specify which categories should be
         compared. As with subtitles, an event is different if it has no  corre‐
         sponding category value.

     Priority, lifetime, margins for start and stop
         Each  search timer can have its own settings for these parameters.  De‐
         faults can be adjusted in the plugin's setup.

     VPS If set to 'yes', VPS will be used if activated in VDR's setup menu  and
         if the broadcasting provides VPS information.

     Auto delete
         For  automatically deleting a search timer if one of the following con‐
         ditions is met:

         • after ... recordings

         • after ... days after the first recording

         Only complete recordings will be counted. The deletion will be executed
         directly after the respective recording was completed.

     To toggle the flag 'Use as search timer' without editing the search  entry,
     you  can  use  the key 2. This will call directly the second command of the
     command menu.

     1.2.2 Menu 'Search results'

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

   1.3 Extended 'Now' and 'Next'
     The setup allows adding up to four additional times for extending the  but‐
     ton  'green',  like  'afternoon',  'prime  time', or 'late night'.  As past
     times are skipped, you won't get 'afternoon' in the evening.  However, if a
     user-defined time lies less than 20 hours in the future, the menu  for  the
     next day will be displayed.

     You  can  shift the currently displayed time in this menu back and forth by
     pressing 'FRew' or 'FFwd'. If you don't have these keys on your remote con‐
     trol, you can access this function by pressing  0  to  toggle  the  buttons
     'green' and 'yellow' to '<<' and '>>'. Toggling can be adjusted by setup.

     You can also have a progress bar displayed in 'Now' and 'Next'.

     Furthermore, you can enable a favorites menu in the setup. By enabling 'Use
     in  favorites  menu',  you can configure a search to display the results as
     favorites. This menu displays events within (by default) the next 24  hours
     in chronological order.

   1.4 Menu 'Setup'
     1.4.1 General

     Hide main menu entry
         This hides the main menu entry 'Search'.

         Attention:  If the plugin is assigned to key 'green', hiding the plugin
         will give you VDR's standard schedule menu.  See  below  how  to  avoid
         this.

     Main menu entry
         If  not hidden, the name of main menu entry can be set here. Default is
         'Program guide'.

         Note: When changing the default name, the main menu entry no longer de‐
         pends on the OSD language. Clearing or reverting to  the  default  name
         restores the language mapping again.

     Start menu
         Select 'Schedules' or 'Now' as start menu.

     1.4.2 EPG menus

     OK key
         Choose  here  the  behavior  of key 'OK'. You can use it to display the
         summary or to switch to the corresponding channel.

         Note: The function of key 'blue' ('Switch', 'Info',  or  'Search')  de‐
         pends on this setting.

     Red key
         Select  if you like to have 'Record' (default) or 'Commands' as assign‐
         ment for key 'red'.

     Blue key
         Select if you like to have 'Switch' (default) or 'Search' as assignment
         for key 'blue'.

     Show progress in 'Now'
         Allows displaying a progress bar in the menu 'Now' that shows  the  al‐
         ready elapsed time of the current broadcast.

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

     Show channel separators
         Select this if you like to have separators between  channel  groups  in
         the menu 'Overview - Now' and its mate menus.

     Show day separators
         Select  this if you like to have a separator between broadcasts on dif‐
         ferent days in the 'Schedule' menu.

     Show radio channels
         Allows to get radio channels listed.

     Limit channels from 1 to
         If you have a large channel set, you can speed up things when you limit
         the displayed channels with this setting. Use 0 to disable  the  limit.
         If  the  current  channel is above the limit, the limit is ignored, and
         all channels will be displayed again.

     'One press' timer creation
         If set to 'yes', a timer will  immediately  be  created  when  pressing
         'Record', else the timer-edit menu will be displayed.

     Show channels without EPG
         Display channels without EPG to allow switching or creating a timer.

     Time interval for 'FRew' / 'FFwd' [min]
         In  the  menus  'Now' and 'Next' as well as the menus with user-defined
         times, the displayed point in time can be shifted  by  pressing  'FRew'
         and  'FFwd' on the remote control. Adjust the number of minutes to jump
         here.

     Toggle Green/Yellow
         Set this to 'yes' if you don't have 'FRew' and 'FFwd'  on  your  remote
         control.  When pressing 0 in respective menus, this toggles the assign‐
         ment  of  the  color  keys  and  assigns, for example, '<<' and '>>' to
         'green' and 'yellow'.

     Show favorites menu
         The favorites menu can display a list of your favorite broadcasts.  En‐
         able  this if you want an additional menu besides 'Now' and 'Next'. You
         can choose between displaying this menu before or after the menus  with
         user-defined times. Any search can be used as a favorite; you only have
         to set the option 'Use in favorites menu' when editing a search.

     for the next ... hours
         This value lets you adjust the time span for displaying the favorites.

     1.4.3 User-defined EPG times

     Use user-defined time 1..4
         Add up to four user-defined times to 'Now' and 'Next'.

     Description
         Name of the user-defined time, like 'Afternoon', 'Prime time', or 'Late
         night'.

     TimeThe time at which the user-defined span of time starts.

     1.4.4 Timer programming

     Use VDR's timer edit menu
         When programming a standard timer, EPGSearch uses an extended menu that
         also  offers  a  destination  directory, distinct weekday selection and
         subtitle completion. If you are using a patched version of the VDR that
         also provides an extended timer edit menu and  prefer  using  this  one
         rather than the one of EPGSearch, set this option to 'yes'.

     Default recording directory
         This entry will be used in standard timer programming as default direc‐
         tory.  You  can  also  use  EPG category variables, like 'Movies~%Cate‐
         gory%~%Genre%'. When the timer edit menu  is  launched,  EPGSearch  at‐
         tempts  to  replace all variables with the values found in the descrip‐
         tion of the event. If not all variables could be replaced,  the  direc‐
         tory entry remains empty.

     Add episode to manual timers
         When  manually creating a timer, EPGSearch can automatically append the
         subtitle to the timer's filename. This will store the  recording  in  a
         directory named like the title, using the subtitle as episode name.

         Choose  here whether or how this should be done: based on the length of
         the event, 'smart' attempts to determine whether a subtitle would  make
         sense  as  an  episode name. If the event is longer than 80 minutes, no
         episode name is added.

     Default timer check method
         Manual timers can be checked for EPG changes. Here you can set  up  the
         default check method for each channel. The following methods exist:

         No check


         By event ID
             Checks by an event ID supplied by the channel provider.

         By channel and time
             Checks by matching the duration.

         Not  all  channels provide a proper event ID. That's why you can set up
         the default for each channel. When programming a manual timer, this de‐
         fault is used in EPS-Search's own timer edit menu.

     1.4.5 Search and search timers

     Use search timers
         If 'yes', the plugin runs background scans of the EPG and  adds  timers
         if  matching  entries  are  found. This applies only to searches marked
         with 'Use as search timer'.

         Search timers will always be created locally, even if  another  default
         host has been set up for recording.

     Update interval
         The  update  interval  of the background scan for search timers in min‐
         utes.

     SVDRP port
         For VDR versions through 1.7.14,  the  default  SVDRP  port  was  2001.
         Starting  with VDR 1.7.15, the port changed to 6419. If you want to use
         a port other than the default, enter its number here to get the  search
         timers working.

     Delay internal threads
         The start of the search-timer update thread and the subsequent conflict
         check can be delayed after 'VDR Ready' between 0..300 seconds (default‐
         ing to 10 seconds).

     Priority, lifetime, margin at start/stop
         Define the respective default values for newly created search timers.

     Allowed errors
         Allowed  errors  before  a recording is marked as incomplete (available
         since VDR 2.5.4).

     No announcements when replaying
         Suppress event announcements while a replay is in progress.

     Recreate timers after deletion
         EPGSearch remembers by default which timers already had been created by
         search timers and will not recreate them if they were  removed.  Select
         'yes' for disabling this behavior.

     Check if EPG exists for ... [h]
         If  you  get EPG content from external providers, the download may fail
         and thus some recordings be skipped because of the  missing  EPG.  With
         this  function one can check if EPG content exists for the given number
         of hours. A value of 0 disables the check.

     Warn by OSD
         Set this to 'yes' to receive warnings via OSD.

     Warn by mail
         Set this to 'yes' to receive warning by e-mail.  Please  configure  the
         e-mail account in 'Email notification'.

     Channel group to check
         Select the channel group to check. It must have been created beforehand
         in 'Channel groups'.

     Limit timer creation [d]
         Limits the creation of timers to a time span in days. A value of 0 dis‐
         ables the limitation.

     Ignore PayTV channels
         Set  this to 'yes' if you don't want to include events from PayTV chan‐
         nels when searching for a repeat.

     Search templates
         Here you can manage search templates that can be used when creating new
         searches and search timers.

     Blacklists
         Here you can manage blacklists that can be  used  to  discard  unwanted
         events within a search.

         A  blacklist can also be marked as global. Since the default setting of
         a search timer for 'Use blacklists' is 'only global', this is a  simple
         way to exclude unwanted events from all search timers.

         But:  If  'Use  blacklists'  has been set to 'none' for a search timer,
         blacklists are not considered. Furthermore, searching for repeats  from
         within the OSD will ignore the blacklists.

     Channel groups
         Here  you  can set up channel groups (e.g., Sport channels, PayTV chan‐
         nels) that can be used as criterion in  searches. The same can be  done
         in the menu 'Edit search'.

     Important:  If  your EPG is retrieved from external sources, make sure that
     search-timer updates are disabled while the EPG is updated. The reason  for
     this  is that EPGSearch will remove timers without events assigned to them.
     This situation can exist while the new EPG is fed into the VDR.

     A simple way to disable search-timer updates is  using  the  SVDRP  command
     'SETS' in the EPG update script:

         svdrpsend PLUG epgsearch SETS off
         perform-epg-updates
         svdrpsend PLUG epgsearch SETS on

     1.4.6 Timer conflict checking

     Ignore below priority
         If a timer should fail with a priority below the given value, you won't
         get an OSD notification, and the conflict will be classified as irrele‐
         vant in the conflicts overview.

     Ignore conflict duration less ... min.
         If a conflict should only cover the given minutes, you won't get an OSD
         notification,  and the conflict will be classified as irrelevant in the
         conflicts overview.

     Only check within next ... days
         Here you can specify the range of days that should be used for the con‐
         flict check.

     Check also remote conflicts
         If SVDRP peering is active and  set  to  'yes',  conflicts  for  remote
         timers will be checked as well. This requires that the plugin EPGSearch
         is active on the remote host, too. Default is 'no'.

     After each timer programming
         This  performs a conflict check after each manual timer programming and
         issues an OSD message if the new or modified timer should  be  involved
         in a conflict.

     When a recording starts
         Set  this  to  'yes'  if  the conflict check should be performed when a
         recording starts.  In case of a conflict, an OSD notification  will  be
         issued  immediately. However, the message will only be displayed if the
         conflict lies within the next two hours.

     After each search timer update
         Specify here if you want to run a  conflict  check  after  each  search
         timer update. If set to 'no', the settings below take effect.

     Every ... minutes
         Specifies  the  cycle for performing conflict checks in the background.
         Relevant conflicts will be notified via OSD. A value of 0 disables this
         feature.

     If conflicts within next ... minutes
         If a conflict should be detected within the given interval, the  subse‐
         quently specified check cycle shall be used.

         Every ... minutes
             This  allows a more frequent conflict check and OSD notification if
             a conflict should appear within the given time.

     Avoid notification when replaying
         Set this to 'yes' if you don't want to get OSD notifications about con‐
         flicts while replaying some video. Nevertheless, notifications will  be
         displayed if the first upcoming conflict is within the next two hours.

     Please   also   consider   "Working   with   the  timer-conflict  menu"  in
     epgsearch(4).

     1.4.7 E-mail notification

     Please make sure that sendEmail.pl is in a  directory  of  $PATH  and  that
     epgsearchupdmail.templ and epgsearchconflmail.templ exist in the configura‐
     tion directory of EPGSearch.

     Search timer notification
         Enable  this  if  you want to get an e-mail notification as soon as the
         search timer background thread has:

         • created a new timer
         • modified an existing timer
         • deleted a void timer resulting from EPG changes or user actions

         In addition, 'Use search timers' must be activated in the  search-timer
         setup.

     Time between mails [h]
         For  search timer notifications, this specifies the minimum distance in
         hours between notification e-mails. Once this time has elapsed,  a  new
         e-mail  will  be  sent after the next search-timer update. A value of 0
         will cause immediate e-mail delivery.

     Timer conflict notification
         Enable this to get an e-mail notification about  timer  conflicts.  The
         notification  will  only include relevant conflicts as specified in the
         timer conflict setup.  EPGSearch will only send a new  notification  if
         the current conflicts have encountered a change.

         Note: This requires 'After each search timer update' or 'every ... min‐
         utes' to be activated in the conflict-check settings.

     Send to
         The full (!) e-mail address of the recipient.

         Note:  Some  providers  (like  Arcor)  don't allow identical e-mail ad‐
         dresses for sender and recipient.

     Mail method
         You can choose between:

         sendEmail.pl
             A simple script shipped with EPGSearch that allows e-mail  delivery
             also on systems without a configured mail server. The script should
             be located within a directory of $PATH.

         sendmail
             Requires a properly configured e-mail system.

     Email address
         The  full(!)  e-email address of the account to be used for sending the
         notifications.

     SMTP server
         The name of your SMTP server to be used for sending the notifications.

     Use SMTP authentication
         Select 'yes' if your account needs authentication to send e-mails.

     AUTH user
         Specify your account's username if the account requires authentication.

     AUTH password
         Specify your account's password if the account requires authentication.

         Caution: The password is saved as plain text. You must make  sure  that
         the  system is secure and no VDR configuration files are accessible for
         unauthorized people.

     After the account setup, check with 'Test' that all works as  intended.  If
     using  sendEmail.pl  for  e-mail  delivery, the test output should end with
     something like 'Email sent successfully'. No test function is available for
     sendmail.

     Please also consider "E-mail notifications" in epgsearch(4).

2. Search timers
     The search timers are rather the same as VDRAdmin's auto-timers but need no
     external software. When creating a search, you can designate it  as  search
     timer.   The  plugin  then scans EPG entries in certain update intervals in
     the background (see 'Update interval') and creates timers if  matching  en‐
     tries are found. If you don't want a new timer to be created, but only want
     to be notified about the event, select 'Announce by OSD'.

     Since  these  search timers are quite useful for television series, you can
     set the option 'Series recording' in a search. This will result  in  timers
     whose  recordings  are stored in a folder with the title as name of the se‐
     ries, and each recording will receive the subtitle as episode name. If  un‐
     available, the date and time of the broadcast will be used instead.

     To  use  search  timers, you also must activate them in the plugin's setup.
     Also edit the SVDRP port if you are not using the default 2001.

     If you want to trigger a background scan manually simply execute:

         touch /etc/vdr/plugins/epgsearch/.epgsearchupdate

     This command can also be part of your shutdown script. However, a delay  of
     several  seconds  should be appended to give the plugin sufficient time for
     finishing the scan.

     For more info about search timers, please refer to  epgsearch(4),  sections
     "Description of the search process" and "How do Search Timers work?".

   2.1 Avoiding repeats in detail
     Preventing  multiple  recordings  of a broadcast only by setting respective
     search criteria is not feasible all the time.  This  section  explains  the
     feature 'Avoid repeats' for a search timer.

     The feature 'Avoid repeats' thus checks before creating a timer whether the
     same broadcast has already been recorded in the past or whether a timer for
     recording  the  same broadcast (but not the same event!) already exists. In
     this case, no new timer for the event will be created.

   2.2 How do we compare two events?
     For checking whether two events are the same, a search  timer  offers  many
     options. You can choose whether to compare the title, subtitle, description
     or  extended EPG categories within the description of an event with the re‐
     spective properties of another event.

     This comparison is always case-sensitive and covers the whole term. But  an
     event's description is an exception to this: First, all text within the de‐
     scription  that  looks like an extended category entry, like 'Rating: tip',
     will be eliminated. Such an extended category  entry  is  a  line  of  text
     starting  with up to 40 characters, followed by a ':' character, and ending
     with at most 60 further characters. The reason for this filtering  is  that
     some  extended  categories, like the rating of an event, are often not part
     of the repeated event's description anymore.

     The resulting text will then be compared by length. If the  difference  ex‐
     ceeds  90  percent, the description of the two events is considered differ‐
     ent. Otherwise, the Levenshtein-Distance-Algorithm (LD)  will  be  applied,
     which  performs  a  fuzzy text comparison. We accept the description of the
     events as equal if LD yields a match of more than 90 percent.

     Since LD is quite run-time intensive (complexity  O(mn)),  you  should  not
     choose  'Compare  summary' as the only criterion but always combine it with
     other criteria.

   2.3 How and when do we compare?
     As already mentioned, each search-timer update checks  search  timers  with
     this  feature  for  recordings in the past or an already existing timer for
     the same event.  To remember past recordings, EPGSearch stores their infor‐
     mation in the file epgsearchdone.data. You can inspect the contents of this
     file by calling 'Show recordings done' in the 'Actions' of the 'Search  en‐
     tries'  menu.   This file only stores information about recordings that are
     complete, that is, which started and stopped in time.  A  broken  recording
     will  hence not be stored in this file and EPGSearch will automatically at‐
     tempt to record the next repeat, if there is any.

     Since VDR 2.5.4, recordings with errors are not stored, too. If  you  would
     like  to  allow a certain number of errors, you can raise the value of 'Al‐
     lowed errors' accordingly.

     2.3.1 How to use it?

     As you can see, the whole feature depends on the quality of the EPG.  After
     creating such a search timer, you should first check if it behaves  as  in‐
     tended. Therefore, the menu 'Search results' has an additional mode for the
     key  'blue',  called  'Timer  preview'. This preview shows which timers the
     next update would create. Existing timers  are  labeled  with  'T',  future
     timers with 'P'.

     Hint:  If  the  programming  results in a conflict, simply disable the con‐
     flicting timer in the menu 'Timers'. The next search timer update will  at‐
     tempt to program a different timer for the same event, if one should exist.

     2.3.3 If it does not work correctly

     To gain better insight of whether or why a timer was programmed or not when
     using this feature, a log file was introduced. When starting EPGSearch with
     a  log  level  of  2  or  above  ('−v 2'), supplemental information will be
     recorded in the file epgsearch.log. Also refer to the command-line  options
     above.

3. Usage from other plugins or scripts
     See epgsearch(4).

4. Using extended EPG information
     Some  EPG  providers deliver supplemental EPG information, like the kind of
     event, the video and audio format, cast, etc. in the content summary.

     Note: This is different from the content descriptors specified  in  DIN  EN
     300  468,  Table  18. These are delivered as supplemental data and are sup‐
     ported since VDR 1.7.11. However, not all providers supply such data or use
     correct descriptors. The approach of "extended EPG  information"  thus  at‐
     tempts to extract such information from the content summary.

     Using  tools  like tvmovie2vdr or epg4vdr, EPG content like this can be im‐
     ported into the VDR.  Such information allows,  for  instance,  creating  a
     search  for  finding  all  tips of the day broadcasted in 16:9 format quite
     easily.  For this purpose, EPGSearch scans the  summary  of  an  event  for
     lines  starting  with the names of categories, followed by ':' and a space,
     that have one or more values set in the search timer. The search  is  case-
     sensitive for both the category name and its values.

     To use this kind of information in search timers, appropriate settings must
     have  been  made in the file epgsearchcats.conf in the EPGSearch configura‐
     tion directory.  Lines within this file have the following format:

         ID|category name[,format]|name in menu|values|search mode

     A line's fields have the following meaning:

     1 – Unique identifier (ID)
         Integer with a positive value.

         Caution: Changing the identifier later on  will  require  updating  the
         search timers!

     2 – Category name
         String  with  the EPG category's name as delivered by the EPG provider,
         like 'Genre'.

         If an optional 'format' is supplied, the category value will be  inter‐
         preted  as integer and formatted as specified by the format string (see
         'man printf' for applicable format strings).

     3 – Name in menus
         String with the EPG category's name for display in EPGSearch menus.

     4 – Values
         String with an optional, comma-separated list of  values  for  the  EPG
         category.

     5 – Search mode
         Optional enumeration with the following values:

             Textual comparison:

             0 = the whole term must appear as substring
             1 = all single terms (delimited by one of ',;|~') must exist as
             substrings; this is the default search mode
             2 = at least one term (delimited by one of ',;|~') must exist as
             substring
             3 = exact match
             4 = regular expression

             Numerical comparison:

             10 = less
             11 = less or equal
             12 = greater
             13 = greater or equal
             14 = equal
             15 = not equal

     Sample  files  for epgsearchcats.conf can be found in the directory conf of
     EPGSearch. Quite often, copying  the  one  that  fits  best  as  epgsearch‐
     cats.conf  to  the  EPGSearch configuration directory and making some minor
     adjustments might be sufficient. Then just  restart  the  VDR  and  open  a
     search timer's edit menu for making use of the EPG categories.

     Since setting up a new epgsearchcats.conf is quite a lot of work, EPGSearch
     comes with the small tool createcats that does the biggest part of the job.
     It should have been installed to the directory of the VDR.  Simply run:

         createcats <path_to>/epg.data

     The tool scans the existing EPG information and attempts to extract the ex‐
     tended  information.  The  result  is  a new file epgsearchcats.conf, which
     still needs to be edited because not everything will be exactly right. Then
     copy the file to the plugin's configuration directory.

     See createcats(1) for further information on how to use it.

5. Replacing the standard schedule menu
     To use this plugin as a replacement for the VDR's default menu  'Schedules'
     invoked by the key 'green', simply insert the line:

         Green @epgsearch

     into keymacros.conf. If you don't like to have the plugin's 'Program guide'
     appearing in the main menu, this menu entry can be hidden in the setup.

6. Add-ons
     EPGSearch  includes two additional small plugins. Both require an installed
     EPGSearch (but EPGSearch can be hidden in the main menu):

     epgsearchonly
         If just the search feature and/or search timers are needed, or  a  dis‐
         tinct  main-menu  entry  for the search feature is desired, this plugin
         does the job.  It creates a main-menu entry  'Quick  search'  that  in‐
         stantly calls the EPGSearch menu 'Edit search'.

         Activation in the VDR start script with '−Pepgsearchonly'.

     conflictcheckonly
         The timer-conflict check can also have a main-menu entry of its own for
         instantly  opening the EPGSearch menu 'Timer conflicts'. A setup option
         allows displaying the results of the last check directly from its main-
         menu entry.

         Activation in the VDR start script with '−Pconflictcheckonly'.

FILES
     epgsearch.conf
         Contains the search timers; see epgsearch.conf(5).

     epgsearchblacklists.conf
         Contains the blacklists; See epgsearchblacklists.conf(5).

     epgsearchcats.conf
         Contains  the  categories  for  the  extended  EPG   information;   see
         epgsearchcats.conf(5).

     epgsearchchangrps.conf
         Defines the channel groups; see epgsearchchangrps.conf(5).

     epgsearchcmds.conf
         Contains  commands  similar to those of the file commands.conf that can
         be applied to EPG entries; see epgsearchcmds.conf(5).

     epgsearchdirs.conf
         Contains predefined paths that can be selected while editing  a  search
         timer; see epgsearchdirs.conf(5).

     epgsearchdone.data
         Stores  data  about successfully recorded search timers; see epgsearch‐
         done.data(5).

     epgsearchmenu.conf
         Defines the layouts of selected OSD menus; see epgsearchmenu.conf(5).

     epgsearchswitchtimers.conf
         Contains the switch timers; see epgsearchswitchtimer.conf(5).

     epgsearchtemplates.conf
         Contains templates for search timers; see epgsearchtemplates.conf(5).

     epgsearchuservars.conf
         Provides user-defined variables; see epgsearchuservars.conf(5).

NOTES
     A detailed description of the plugin's internal functions can be  found  in
     epgsearch(4).

AUTHORS (man pages)
     Originally provided by Mike Constabel <epgsearch (at) constabel (dot) net>.

     Revised and adapted to recent plugin features by the current maintainers.

PROJECT SITE
     The plugin is maintained as GitHub project:

     <https://github.com/vdr-projects/vdr-plugin-epgsearch/>

REPORTING BUGS
     Issues  can  be  reported, and features be suggested, through the project's
     bug tracker:

     <https://github.com/vdr-projects/vdr-plugin-epgsearch/issues/>

COPYRIGHT and LICENSE
     Copyright (C) 2004-2010 Christian Wieninger

     Copyright © 2011-2025 TomJoad (VDR-Portal), et al.

     This program is free software; you can redistribute it and/or modify it un‐
     der 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  FIT‐
     NESS 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 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

     The original author can be reached via cwieninger@gmx.de.

     Current maintainers can be reached  via  the  project's  GitHub  site  (see
     above).

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

SEE ALSO
     epgsearch(4),  epgsearch.conf(5),  epgsearchblacklists.conf(5),  epgsearch‐
     cats.conf(5),       epgsearchchangrps.conf(5),       epgsearchcmds.conf(5),
     epgsearchdirs.conf(5),    epgsearchdone.data(5),     epgsearchmenu.conf(5),
     epgsearchswitchtimer.conf(5), epgsearchuservars.conf(5)

perl v5.40.1                       2026-04-19                       epgsearch(1)
