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 allows 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 example, 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 respective 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 selection 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 required.

−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 purposes).

−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 sample 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, separate 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, subtitle or description. This is particularly helpful for short titles, like "ALF".

    Regular expression
        A regular expression serves as search term. Enclosing '/' characters 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 regular-expression library to the one desired, and recompile the plugin. The required library must possibly be installed beforehand using the machine's packet manager.

    Fuzzy
        Compares the search term based upon the Levenshtein-Distance algorithm. 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 selection 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 sufficient (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 single 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 contained 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 title 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 entries 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 refer 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 considered. 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 considered.

    Before comparing two descriptions, all parts looking like category values will be removed; the remaining texts will be compared with each other. If the percentage of similarity regarding the Levenshtein-Distance algorithm complies with the value of the next option, the descriptions 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 corresponding category value.

Priority, lifetime, margins for start and stop
    Each search timer can have its own settings for these parameters. Defaults 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 conditions 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 button '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 control, 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 depends 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') depends on this setting.

Red key
    Select if you like to have 'Record' (default) or 'Commands' as assignment 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 already 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 different 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 assignment 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. Enable 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'.

Time
    The 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 directory. You can also use EPG category variables, like 'Movies~%Category%~%Genre%'. When the timer edit menu is launched, EPGSearch attempts to replace all variables with the values found in the description of the event. If not all variables could be replaced, the directory 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 default 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 minutes.

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 (defaulting 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 disables the limitation.

Ignore PayTV channels
    Set this to 'yes' if you don't want to include events from PayTV channels 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 channels) 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 irrelevant 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 conflict 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 subsequently 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 conflicts 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 configuration 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 ... minutes' 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 addresses 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 entries 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 series, and each recording will receive the subtitle as episode name. If unavailable, 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 respective 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 description 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 exceeds 90 percent, the description of the two events is considered different. 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 information in the file epgsearchdone.data. You can inspect the contents of this file by calling 'Show recordings done' in the 'Actions' of the 'Search entries' 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 attempt 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 'Allowed 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 intended. 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 conflicting timer in the menu 'Timers'. The next search timer update will attempt 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 supported since VDR 1.7.11. However, not all providers supply such data or use correct descriptors. The approach of "extended EPG information" thus attempts to extract such information from the content summary.

Using tools like tvmovie2vdr or epg4vdr, EPG content like this can be imported 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 configuration 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 interpreted 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 epgsearchcats.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 extended 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 distinct main-menu entry for the search feature is desired, this plugin does the job. It creates a main-menu entry 'Quick search' that instantly 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 epgsearchdone.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 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 <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), epgsearchcats.conf(5), epgsearchchangrps.conf(5), epgsearchcmds.conf(5), epgsearchdirs.conf(5), epgsearchdone.data(5), epgsearchmenu.conf(5), epgsearchswitchtimer.conf(5), epgsearchuservars.conf(5)