=encoding utf8

=for syntax specification:
https://perldoc.perl.org/perlpod

=head1 NAME

F<EPGSearch> – search timers and replacement of the VDR's default schedules menu

=head1 OVERVIEW

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

=over 2

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

=item * The program guide allows switching between the next and the
current events.

=item * 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.

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

=item * Progress bar in the program guide for current and next events.

=item * 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.

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

=item * Search timer: Background search for matching events and
creation of respective timers (similar to VDRAdmin's auto-timers)
or just notification via OSD.

=item * Support of content descriptors and extended EPG information
for search timers.

=item * Avoiding multiple recordings of the same event:

=over 2

=item – timer preview

=item – recognition of broken recordings

=item – fuzzy event comparison

=back

=item * Extension of the timer-edit menu with a directory item, flexible
selection of weekdays, and subtitle ("episode name") completion.

=item * Background check for timer conflicts in combination with a
timer-conflict manager.

=item * Notification of detected timer conflicts via OSD messages.

=item * Detailed information of timer conflicts and suuport for
resolving them.

=item * E-mail notifications about search-timer updates and timer conflicts.

=back

Z<>

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

=head1 OPTIONS

=over 4

=item B<−f> I<file>,  B<−−svdrpsendcmd>=I<file>

The path to F<svdrpsend> for external SVDRP communication. As internal
communication will be used by default, this option is usually not required.

=item B<−c> I<path>,  B<−−config>=I<path>

Specifies a specific directory for all EPGSearch configuration files (defaults
to F<E<lt>plugins configuration directoryE<gt>/epgsearch>).

=item B<−l> I<file>,  B<−−logfile>=I<file>

Specifies a specific log file for EPGSearch. Default log file is
F<epgsearch.log> in the EPGSearch configuration directory.

=item -B<v> I<n>,  B<−−verbose>=I<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).

=item B<−r>,  B<−−reloadmenuconf>

Reload F<epgsearchmenu.conf> with each plugin call within the OSD.
This can be useful when testing customized menu layouts.

=item B<−m> I<file>,  B<−−mailcmd>=I<file>

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

=back

=head1 CONTENT

=over 3

=item 1. Description

=over 4

=item 1.1 Menu C<Commands>

=item 1.2 Menu C<Search>

=over 6

=item 1.2.1 Menu C<Edit search>

=item 1.2.2 Menu C<Search results>

=back

=item 1.3 Extended C<Now> and C<Next>

=item 1.4 Menu C<Setup>

=over 6

=item 1.4.1 General

=item 1.4.2 EPG menus

=item 1.4.3 User-defined EPG times

=item 1.4.4 Timer programming

=item 1.4.5 Search and search timers

=item 1.4.6 Timer conflict checking

=item 1.4.7 E-mail notification

=back

=back

=item 2. Search timers

=over 4

=item 2.1 Avoiding repeats in detail

=item 2.2 How do we compare two events?

=item 2.3 How and when do we compare?

=over 6

=item 2.3.1 How to use it?

=item 2.3.3 If it does not work correctly

=back

=back

=item 3. Usage from other plugins or scripts

=item 4. Using extended EPG info

=item 5. Replacing the standard schedule menu

=item 6. Add-ons

=back

=head1 1. Description

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

=head2 1.1 Menu Commands

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

=over 4

=item B<Repeats>

Searches for events with same title.

=item B<Record>

Creates a timer for recording the event.

=item B<Switch>

Switches to the channel broadcasting the event.

=item B<Create search>

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

=item B<Search in recordings>

Search the recordings for an event with the same name.

=item B<Mark as 'already recorded'?>

Adds the selected event to the file F<epgsearchdone.data> and instructs
EPGSearch to avoid recording this event if the related search timer is set
to C<avoid repeats>. An already created timer will be automatically removed
with the next search-timer update.

=item B<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 C<Search> »
C<Actions> » C<Switch list> for accessing the entire switch list.

=item B<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.

=back

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

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

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

=over 4

=item B<$1>

Title of the EPG entry.

=item B<$2>

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

=item B<$3>

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

=item B<$4>

Channel number of the EPG entry.

=item B<$5>

Long channel name of the EPG entry.

=item B<$6>

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

=back

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

=head2 1.2 Menu C<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.

=head3 1.2.1 Menu C<Edit search>

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

=over 4

=item B<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 C<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 C<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.

B<Note:> Fuzzy searching is limited to 32 characters!

=item B<Search mode>

A search can be performed in several flavors:

=over 4

=item I<Phrase>

Searches for the expression within the EPG.

=item I<All words>

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

=item I<At least one word>

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

=item I<Match exactly>

Requires that the search term exactly matches the found title, subtitle
or description. This is particularly helpful for short titles, like "ALF".

=item I<Regular expression>

A regular expression serves as search term. Enclosing C</> characters are
not required.

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

Without automatic configuration, simply edit the F<Makefile> and change
C<#REGEXLIB = pcre2> to C<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.

=item I<Fuzzy>

Compares the search term based upon the Levenshtein-Distance algorithm.
The value of C<Tolerance> determines how much deviation is acceptable.

=back

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

=item B<Use content descriptors>

Some providers deliver content descriptors in their EPGs, like C<movie/drama>,
C<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).

=item B<Use extended EPG info>

Only available if configured, see C<Using extended EPG info> below.

=item B<Category matching mode>

By default, all selected categories must be present in the EPG and match the
specified values. Selecting C<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 C<at least one category>,
in which case matching a single category will be sufficient.

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

=item B<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 C<blue>.

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

=item B<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
(C<So.>, C<Mo.>, ..., C<Sa.>). Press key C<red> for creating or
changing the selection.

=item B<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.

=item B<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.

=item B<Result menu layout>

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

=item B<Use as search timer>

If set to C<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 C<Use search timers> in the setup). If set to C<user-defined>, one
can specify a time span with the key C<blue> during which the search timer
shall be active.

=item B<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 C<OK>. Further available is C<Announce by mail> and C<inactive record>.

=item B<Series recording>

If set to C<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.

=item B<Directory>

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

If your provider delivers extended EPG information, you can also use
variables like C<%Genre%> or C<%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 B<epgsearch>(4).

=item B<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.

=item B<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.

=item B<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.

=item B<Allowed repeats>

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

=item B<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.

=item B<Compare title>

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

=item B<Compare subtitle>

When comparing events, specify whether the subtitle shall be considered.
With C<yes>, EPGSearch will classify two events only as equal if their
subtitles match and are not empty.

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

=item B<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.

=item B<Min. match in %>

The needed minimum match of descriptions in percent.

=item B<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.

=item B<Compare categories>

With the button C<Setup> you can also specify which categories should
be compared. As with subtitles, an event is different if it has no
corresponding category value.

=item B<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.

=item B<VPS>

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

=item B<Auto delete>

For automatically deleting a search timer if one of the following conditions
is met:

=over 2

=item * after ... recordings

=item * after ... days after the first recording

=back

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

=back

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

=head3 1.2.2 Menu C<Search results>

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

=head2 1.3 Extended C<Now> and C<Next>

The setup allows adding up to four additional times for extending the
button C<green>, like C<afternoon>, C<prime time>, or C<late night>.
As past times are skipped, you won't get C<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 C<FRew> or C<FFwd>. If you don't have these keys on your remote
control, you can access this function by pressing C<0> to toggle the buttons
C<green> and C<yellow> to C<E<lt>E<lt>> and C<E<gt>E<gt>>. Toggling can be
adjusted by setup.

You can also have a progress bar displayed in C<Now> and C<Next>.

Furthermore, you can enable a favorites menu in the setup. By enabling
C<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.

=head2 1.4 Menu C<Setup>

=head3 1.4.1 General

=over 4

=item B<Hide main menu entry>

This hides the main menu entry C<Search>.

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

=item B<Main menu entry>

If not hidden, the name of main menu entry can be set here. Default is
C<Program guide>.

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

=item B<Start menu>

Select C<Schedules> or C<Now> as start menu.

=back

=head3 1.4.2 EPG menus

=over 4

=item B<OK key>

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

B<Note:> The function of key C<blue> (C<Switch>, C<Info>, or C<Search>)
depends on this setting.

=item B<Red key>

Select if you like to have C<Record> (default) or C<Commands>
as assignment for key C<red>.

=item B<Blue key>

Select if you like to have C<Switch> (default) or C<Search>
as assignment for key C<blue>.

=item B<Show progress in 'Now'>

Allows displaying a progress bar in the menu C<Now> that
shows the already elapsed time of the current broadcast.

=item B<Show channel numbers>

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

=item B<Show channel separators>

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

=item B<Show day separators>

Select this if you like to have a separator between broadcasts on different
days in the C<Schedule> menu.

=item B<Show radio channels>

Allows to get radio channels listed.

=item B<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 C<0> to disable the limit. If the
current channel is above the limit, the limit is ignored, and all channels will
be displayed again.

=item B<'One press' timer creation>

If set to C<yes>, a timer will immediately be created when pressing C<Record>,
else the timer-edit menu will be displayed.

=item B<Show channels without EPG>

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

=item B<Time interval for 'FRew' / 'FFwd' [min]>

In the menus C<Now> and C<Next> as well as the menus with user-defined times,
the displayed point in time can be shifted by pressing C<FRew> and C<FFwd> on
the remote control. Adjust the number of minutes to jump here.

=item B<Toggle Green/Yellow>

Set this to C<yes> if you don't have C<FRew> and C<FFwd> on your remote control.
When pressing C<0> in respective menus, this toggles the assignment of the color
keys and assigns, for example, C<E<lt>E<lt>> and C<E<gt>E<gt>> to C<green> and
C<yellow>.

=item B<Show favorites menu>

The favorites menu can display a list of your favorite broadcasts. Enable this
if you want an additional menu besides C<Now> and C<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
C<Use in favorites menu> when editing a search.

=item B<for the next ... hours>

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

=back

=head3 1.4.3 User-defined EPG times

=over 4

=item B<Use user-defined time 1..4>

Add up to four user-defined times to C<Now> and C<Next>.

=item B<Description>

Name of the user-defined time, like C<Afternoon>, C<Prime time>, or
C<Late night>.

=item B<Time>

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

=back

=head3 1.4.4 Timer programming

=over 4

=item B<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 C<yes>.

=item B<Default recording directory>

This entry will be used in standard timer programming as default
directory. You can also use EPG category variables, like
C<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.

=item B<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,
C<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.

=item B<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:

=over 4

=item I<No check>

Z<>

=item I<By event ID>

Checks by an event ID supplied by the channel provider.

=item I<By channel and time>

Checks by matching the duration.

=back

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.

=back

=head3 1.4.5 Search and search timers

=over 4

=item B<Use search timers>

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

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

=item B<Update interval>

The update interval of the background scan for search timers in minutes.

=item B<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.

=item B<Delay internal threads>

The start of the search-timer update thread and the subsequent conflict check can be delayed
after C<VDR Ready> between 0..300 seconds (defaulting to 10 seconds).

=item B<Priority, lifetime, margin at start/stop>

Define the respective default values for newly created search timers.

=item B<Allowed errors>

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

=item B<No announcements when replaying>

Suppress event announcements while a replay is in progress.

=item B<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 C<yes>
for disabling this behavior.

=item B<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 C<0> disables the check.

=item B<Warn by OSD>

Set this to C<yes> to receive warnings via OSD.

=item B<Warn by mail>

Set this to C<yes> to receive warning by e-mail. Please configure the
e-mail account in C<Email notification>.

=item B<Channel group to check>

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

=item B<Limit days of timer creation>

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

=item B<Ignore PayTV channels>

Set this to C<yes> if you don't want to include events from PayTV channels
when searching for a repeat.

=item B<Search templates>

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

=item B<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 C<Use blacklists> is C<only global>, this is a simple way to exclude unwanted events
from all search timers.

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

=item B<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 C<Edit search>.

=back

B<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 C<SETS>
in the EPG update script:

=over 4

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

=back

=head3 1.4.6 Timer conflict checking

=over 4

=item B<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.

=item B<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.

=item B<Only check within next ... days>

Here you can specify the range of days that should be used for the conflict
check.

=item B<Check also remote conflicts>

If SVDRP peering is active and set to C<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 C<no>.

=item B<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.

=item B<When a recording starts>

Set this to C<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.

=item B<After each search timer update>

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

=item B<Every ... minutes>

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

=item B<If conflicts within next ... minutes>

If a conflict should be detected within the given interval, the subsequently
specified check cycle shall be used.

=over 4

=item B<Every ... minutes>

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

=back

=item B<Avoid notification when replaying>

Set this to C<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.

=back

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

=head3 1.4.7 E-mail notification

Please make sure that F<sendEmail.pl> is in a directory of C<$PATH> and
that F<epgsearchupdmail.templ> and F<epgsearchconflmail.templ> exist in
the configuration directory of EPGSearch.

=over 4

=item B<Search timer notification>

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

=over 2

=item • created a new timer

=item • modified an existing timer

=item • deleted a void timer resulting from EPG changes or user actions

=back

In addition, C<Use search timers> must be activated in the search-timer setup.

=item B<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 C<0> will cause immediate e-mail
delivery.

=item B<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.

B<Note:> This requires C<After each search timer update> or C<every ... minutes> to
be activated in the conflict-check settings.

=item B<Send to>

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

B<Note:> Some providers (like Arcor) don't allow identical e-mail addresses
for sender and recipient.

=item B<Mail method>

You can choose between:

=over 4

=item I<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 C<$PATH>.

=item I<sendmail>

Requires a properly configured e-mail system.

=back

=item B<Email address>

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

=item B<SMTP server>

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

=item B<Use SMTP authentication>

Select C<yes> if your account needs authentication to send e-mails.

=item B<AUTH user>

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

=item B<AUTH password>

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

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

=back

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

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

=head1 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 C<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 C<Announce by OSD>.

Since these search timers are quite useful for television series, you can set the
option C<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:

=over 4

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

=back

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 B<epgsearch>(4), sections
"Description of the search process" and "How do Search Timers work?".

=head2 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
C<Avoid repeats> for a search timer.

The feature C<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.

=head2 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 C<Rating: tip>, will be eliminated. Such an extended
category entry is a line of text starting with up to 40 characters,
followed by a C<:> 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 I<O(mn)>), you should not
choose C<Compare summary> as the only criterion but always combine it with
other criteria.

=head2 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
F<epgsearchdone.data>. You can inspect the contents of this file by calling
C<Show recordings done> in the C<Actions> of the C<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 C<Allowed errors>
accordingly.

=head3 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 C<Search results> has an additional
mode for the key C<blue>, called C<Timer preview>. This preview shows which
timers the next update would create. Existing timers are labeled with C<T>,
future timers with C<P>.

B<Hint:> If the programming results in a conflict, simply disable the
conflicting timer in the menu C<Timers>. The next search timer update
will attempt to program a different timer for the same event, if one
should exist.

=head3 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 (C<−v 2>), supplemental information will be
recorded in the file F<epgsearch.log>. Also refer to the command-line options
above.

=head1 3. Usage from other plugins or scripts

See B<epgsearch>(4).

=head1 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.

B<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 F<tvmovie2vdr> or F<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 C<:> 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 F<epgsearchcats.conf> in the EPGSearch
configuration directory.
Lines within this file have the following format:

=over 4

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

=back

A line's fields have the following meaning:

=over 4

=item B<1 – Unique identifier (ID)>

Integer with a positive value.

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

=item 2 – B<Category name>

String with the EPG category's name as delivered by the EPG
provider, like C<Genre>.

If an optional C<format> is supplied, the category value will be
interpreted as integer and formatted as specified by the format
string (see C<man printf> for applicable format strings).

=item 3 – B<Name in menus>

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

=item 4 – B<Values>

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

=item 5 – B<Search mode>

Optional enumeration with the following values:

=over 4

B<Textual comparison:>

=over 4

=item 0 = the whole term must appear as substring

=item 1 = all single terms (delimited by one of C<,;|~>)
must exist as substrings; this is the default search mode

=item 2 = at least one term (delimited by one of C<,;|~>)
must exist as substring

=item 3 = exact match

=item 4 = regular expression

=back

B<Numerical comparison:>

=over 4

=item 10 = less

=item 11 = less or equal

=item 12 = greater

=item 13 = greater or equal

=item 14 = equal

=item 15 = not equal

=back

=back

=back

Sample files for F<epgsearchcats.conf> can be found in the directory
F<conf> of EPGSearch. Quite often, copying the one that fits best
as F<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 F<epgsearchcats.conf> is quite a lot of work,
EPGSearch comes with the small tool F<createcats> that does the
biggest part of the job. It should have been installed to the directory
of the VDR.
Simply run:

=over 4

    createcats <path_to>/epg.data

=back

The tool scans the existing EPG information and attempts to extract the
extended information. The result is a new file F<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 B<createcats>(1) for further information on how to use it.

=head1 5. Replacing the standard schedule menu

To use this plugin as a replacement for the VDR's default menu
C<Schedules> invoked by the key C<green>, simply insert the line:

=over 4

    Green @epgsearch

=back

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

=head1 6. Add-ons

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

=over 4

=item B<F<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 C<Quick search> that instantly calls the
EPGSearch menu C<Edit search>.

Activation in the VDR start script with C<−Pepgsearchonly>.

=item B<F<conflictcheckonly>>

The timer-conflict check can also have a main-menu entry of its own for
instantly opening the EPGSearch menu C<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 C<−Pconflictcheckonly>.

=back

=head1 FILES

=over 4

=item B<F<epgsearch.conf>>

Contains the search timers; see B<epgsearch.conf>(5).

=item B<F<epgsearchblacklists.conf>>

Contains the blacklists; See B<epgsearchblacklists.conf>(5).

=item B<F<epgsearchcats.conf>>

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

=item B<F<epgsearchchangrps.conf>>

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

=item B<F<epgsearchcmds.conf>>

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

=item B<F<epgsearchdirs.conf>>

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

=item B<F<epgsearchdone.data>>

Stores data about successfully recorded search timers; see B<epgsearchdone.data>(5).

=item B<F<epgsearchmenu.conf>>

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

=item B<F<epgsearchswitchtimers.conf>>

Contains the switch timers; see B<epgsearchswitchtimer.conf>(5).

=item B<F<epgsearchtemplates.conf>>

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

=item B<F<epgsearchuservars.conf>>

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

=back

=head1 NOTES

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

=head1 AUTHORS (man pages)

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

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

=head1 PROJECT SITE

The plugin is maintained as GitHub project:

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

=head1 REPORTING BUGS

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

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

=head1 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 L<https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

The original author can be reached via L<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.

=head1 SEE ALSO

B<epgsearch>(4),
B<epgsearch.conf>(5),
B<epgsearchblacklists.conf>(5),
B<epgsearchcats.conf>(5),
B<epgsearchchangrps.conf>(5),
B<epgsearchcmds.conf>(5),
B<epgsearchdirs.conf>(5),
B<epgsearchdone.data>(5),
B<epgsearchmenu.conf>(5),
B<epgsearchswitchtimer.conf>(5),
B<epgsearchuservars.conf>(5)
