epgsearch - Man Page

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.

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.

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.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 days of timer creation

Limits the creation of timers to this timespan (days).

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

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.

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.

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.