epgsearch(1)

📦

version 2.4.6 · 8 versions

2.4.6 · ubuntu stonking (latest)
2.4.6 · nixpkgs unstable
2.6.1 · alpine 3.24
2.4.3 · fedora 43
2.4.6 · fedora 43, fedora 44
2.4.1 · debian bookworm, ubuntu jammy, ubuntu noble
2.4.4 · ubuntu resolute
2.4.3 · debian trixie, ubuntu questing

💖 epgsearch(1) 💖

okay so this is the epgsearch(1) manual for EPGSearch Version 2.4.6, and it's literally the whole vibe for search timers + replacing VDR's default schedules menu. Buckle up bestie. 🫶

🌸 NAME 🌸

EPGSearch – search timers and replacement of the VDR's default schedules menu. That's the whole one-liner, no cap. ✨

💅 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 support 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 ✨

okay the flags are few but they matter, bestie:

−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). Lowkey iconic. 🎀

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

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.

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 inside the channel interval you set, the channel group you picked, or FTA (free-to-air) channels only. 📺

Channel groups (think sport channels, Pay-TV bundles, that whole vibe) are managed in a submenu you pop open with the 'blue' key.

⚠️ Heads up bestie: if you go and reorder your channels, please double-check the range settings of your search timers afterwards. Channels move, ranges don't. 😭

Use day of week

Besides the plain weekdays, you can build a user-defined selection so a search only fires on, like, Mondays and Fridays. Very "I only care about the weekend-adjacent content" of you. 🗓️

You'll find the user-defined selection right after the list of weekdays ('So.', 'Mo.', ..., 'Sa.'). Hit the 'red' key to create or change the selection.

Use blacklists

Blacklists = the "nope, not this" list. Exclude the events you never wanna see. Pick only global lists, or one, more, or literally all blacklists here. If a search result also lives in one of the selected blacklists, it gets skipped. Bye. 💅

Only shows up if you turned it on in setup. With this you can mark a search as "yes use this in the favorites menu", and the results of every search marked like that get listed together in the favorites menu. Cute, organised, slay. 🎀

Only available once you've defined more than one menu template for search results in epgsearchmenu.conf. This option assigns a different menu layout to the results of this search specifically.

Use as search timer

Set it to 'yes' and the plugin will run background scans of the EPG at certain intervals and add a timer whenever there's a match (you need 'Use search timers' activated in the setup for this, bestie). Set it to 'user-defined' and you get to specify a time span with the 'blue' key during which the search timer shall be active. 🕐

Action

Default action is creating a timer for each search result. But you've got options, and they're good ones:

simply announce the found event via OSD as soon as it's found
automatically switch to the event before it starts
get an announcement via OSD before the event starts, then switch to its channel with the 'OK' key
'Announce by mail'
'inactive record'

Pick your fighter. 💌

Series recording

Set to 'yes' and your recordings get stored in a folder named after the series title, and each recording gets the subtitle as its episode name. If the subtitle isn't available, the date and time of the broadcast is used instead. Iconic filing system behaviour. 🗂️

Delete recordings after ... days

Some recordings should only stick around for a few days — news, for example. With this feature you tell EPGSearch to delete them automatically after a chosen number of days. Poof, gone, boundaries. 🫧

Pause when ... recordings exist

If the given number of recordings exists, EPGSearch will not create further timers. Delete one or more of those recordings and new timers get generated again. It's giving "no room, no new friends". 🙈

Avoid repeats

If you don't want to record repeats, this feature tries to check whether an event was already programmed or recorded, and skips it if so.

📌 Please read the section "Avoiding repeats in detail" below before you use this one. Trust me on this.

Allowed repeats

If you're fine accepting a certain number of repeats, specify how many right 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. Zero = free spirit. 🦋

Compare title

When comparing events, this says whether the title shall be considered.

Compare subtitle

When comparing events, this says whether the subtitle shall be considered.

With 'yes', EPGSearch classifies two events as equal only if their subtitles match and are not empty.
With 'allow empty', two events may be equal if both subtitles are empty. Normally you'd choose 'no' in this case.

Compare description

When comparing events, this says whether the description shall be considered.

Before comparing two descriptions, all parts looking like category values get removed; the remaining texts are compared with each other. If the percentage of similarity according to the Levenshtein-Distance algorithm complies with the value of the next option, the descriptions are considered equal. Math but make it matching. 🧮

Min. match in %

The needed minimum match of descriptions, in percent.

Compare date

Sometimes a broadcast is repeated loads of times within some period (day, week, month, etc.), but the repeats can't be told apart based on the EPG contents. So the only info you actually have is its time. To use that for comparison, select the appropriate period. 🕰️

Compare categories

With the button 'Setup' you can also specify which categories should be compared. Same deal 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 it's 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 is 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. That calls the second command of the command menu directly. Sneaky shortcut, we love her. 💜

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

1.3 Extended 'Now' and 'Next' ✨

The setup lets you add up to four additional times for extending the 'green' button — stuff like 'afternoon', 'prime time', or 'late night'. Since past times are skipped, you won't get 'afternoon' in the evening. Makes sense, honestly. But 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 your remote control doesn't have those keys, no stress: press 0 to toggle the buttons 'green' and 'yellow' to '<<' and '>>'. That toggling can be adjusted by setup.

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

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

General

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

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

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

📝 Note: when you change the default name, the main menu entry no longer depends on the OSD language. Clearing it or reverting to the default name restores the language mapping again.

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

EPG menus

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

📝 Note: the function of the 'blue' key ('Switch', 'Info', or 'Search') depends on this setting.

Red key — Select whether you want 'Record' (default) or 'Commands' assigned to the 'red' key.
Blue key — Select whether you want 'Switch' (default) or 'Search' assigned to the 'blue' key.
Show progress in 'Now' — Displays a progress bar in the 'Now' menu showing the already elapsed time of the current broadcast.
Show channel numbers — Turn this on to get a leading channel number before each item in the EPG menus.
Show channel separators — Turn this on to get separators between channel groups in the menu 'Overview - Now' and its mate menus.
Show day separators — Turn this on to get a separator between broadcasts on different days in the 'Schedule' menu.
Show radio channels — Gets radio channels listed.
Limit channels from 1 to — Got a huge channel set? You can speed things up by limiting 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 are displayed again. 😌
'One press' timer creation — Set to 'yes' and a timer is created immediately when you press 'Record'; otherwise the timer-edit menu is displayed.
Show channels without EPG — Display channels without EPG, so you can still switch to them or create 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 right here.
Toggle Green/Yellow — Set this to 'yes' if your remote control has no 'FRew' and 'FFwd'. Then pressing 0 in the respective menus toggles the assignment of the color keys and assigns, for example, '<<' and '>>' to 'green' and 'yellow'. 🌈
Show favorites menu — bestie, this one makes a whole extra menu appear that lists your fave broadcasts 💖 enable it if you want another menu chilling alongside Now and Next. You even get to pick whether this menu shows up before or after the menus with user-defined times. Any search can be your favorite — you just gotta flip the Use in favorites menu option while editing a search, iykyk.
for the next ... hours — this value lets you tweak the time span for showing off those favorites ⏰

1.4.3 User-defined EPG times 🎀

Use user-defined time 1..4 — adds up to four (yes, FOUR) user-defined times to Now and Next ✨
Description — the name of your 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 — so when you're programming a standard timer, EPGSearch hits you with an extended menu that also offers a destination directory, distinct weekday selection, and subtitle completion. BUT if you're running a patched VDR that also has an extended timer edit menu and you'd rather use that one than EPGSearch's, set this to yes. Your call, bestie 💅
Default recording directory — this entry gets used as the default directory in standard timer programming. You can also use EPG category variables, like Movies~%Category%~%Genre% 🎬 When the timer edit menu launches, EPGSearch attempts to swap out all variables with the values it finds in the description of the event. If not all variables could be replaced, the directory entry stays empty — no cap.
Add episode to manual timers — when you manually create a timer, EPGSearch can auto-append the subtitle to the timer's filename 🏷️ This stores the recording in a directory named like the title, using the subtitle as the episode name. Choose here whether/how this should be done: based on the length of the event, smart attempts to figure out whether a subtitle would make sense as an episode name. If the event is longer than 80 minutes, no episode name gets added. It's giving thoughtful, honestly.
Default timer check method — manual timers can be checked for EPG changes, and here you set up the default check method for each channel. The methods that exist are:
- No check — literally none, zero, nada.
- 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, which is exactly why you can set up the default per channel. When programming a manual timer, this default is used in EPS-Search's own timer edit menu 👑

Use search timers — if yes, the plugin runs background scans of the EPG and adds timers whenever matching entries are found 🔍 This applies only to searches marked with Use as search timer. Also important: 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 a port other than the default, drop its number here so your search timers actually work 🔌
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). Give the girl a minute to wake up 😴
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 — suppresses 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 it will not recreate them if they were removed. Select yes to disable this behavior. Careful, bestie, that's a real change in vibe 💀
Check if EPG exists for ... [h] — if you get EPG content from external providers, the download may fail and thus some recordings get skipped because of the missing EPG 😭 With this function you 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 get warnings via OSD 📢
Warn by mail — set this to yes to get warnings 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 — and this is a big 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 entirely. The audacity, honestly 🙈
Channel groups — here you can set up channel groups (e.g., Sport channels, PayTV channels) that can be used as a 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. Not a drill, bestie 🚨

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 gets 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 gets classified as irrelevant in the conflicts overview ⏲️
Only check within next ... days — here you can specify the range of days 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 the plugin EPGSearch to be active on the remote host too. Default is no 🌐
After each timer programming — 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 gets 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 get 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 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. No template, no mail, periodt 📬

Search timer notification — enable this if you want 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 gets sent after the next search-timer update. A value of 0 will cause immediate e-mail delivery — inbox go brrr 📨
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. Rude, but okay.

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 that EPGSearch uses to send out notifications. 💌
Use SMTP authentication — pick 'yes' here if your account needs to authenticate itself before it's allowed to send e-mails.
AUTH user — your account's username, for the accounts that do require authentication.
AUTH password — your account's password, same deal.

⚠️ Caution, bestie, this one's serious: the password is saved as plain text. You have to make sure the system is secure and that no VDR configuration files are accessible to unauthorized people. Like, actually lock it down. 🔐

Once the account setup is done, hit 'Test' and check it all works the way you intended. If you're using sendEmail.pl for e-mail delivery, the test output should end with something like Email sent successfully. Heads up though: there's no test function for sendmail. 😭

And please also consider "E-mail notifications" in epgsearch(4). 🫶

🌸 2. Search timers 🌸

Okay so search timers are pretty much the same idea as VDRAdmin's auto-timers, except they need zero external software. Iconic. 💅

When you create a search, you can designate it as a search timer. The plugin then scans EPG entries in certain update intervals in the background (peep 'Update interval') and creates timers whenever it finds matching entries. And if you don't actually want a new timer created — you just want to know the event exists — select 'Announce by OSD'. 👀

Since these search timers are genuinely so useful for television series, you can set the option 'Series recording' in a search. What that does: timers get created whose recordings are stored in a folder with the title as the name of the series, and each recording receives the subtitle as its episode name. If the subtitle isn't available, the date and time of the broadcast gets used instead. Slay. ✨

To use search timers you also have to activate them in the plugin's setup. And edit the SVDRP port too, if you're not running on 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. But babe, append a delay of several seconds so the plugin actually has time to finish the scan. 🕐

For more deets 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 just by setting the respective search criteria is not feasible all the time. (The EPG simply isn't that girl.) So this section explains the feature 'Avoid repeats' for a search timer.

What 'Avoid repeats' does: before creating a timer, it checks 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 that case, no new timer for the event will be created. Periodt. 🚫

💜 2.2 How do we compare two events? 💜

For checking whether two events are actually the same, a search timer offers so many options. You can choose whether to compare the title, subtitle, description, or extended EPG categories within the description of an event against the respective properties of another event.

This comparison is always case-sensitive and covers the whole term. But an event's description is the exception to this rule: 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 whole reason for this filtering? Some extended categories, like the rating of an event, are often just not part of the repeated event's description anymore. 🙈

The resulting text then gets compared by length. If the difference exceeds 90 percent, the description of the two events is considered different. Otherwise the Levenshtein-Distance-Algorithm (LD) gets applied, which performs a fuzzy text comparison. We accept the descriptions as equal if LD yields a match of more than 90 percent.

😭 LD is quite run-time intensive (complexity O(mn)), so please don't choose 'Compare summary' as your only criterion — always combine it with other criteria. Your CPU will thank you.

🌈 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 for 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. (Vibe check on your EPG provider, ngl.) After creating such a search timer, you should first check if it behaves as intended. For that, the menu 'Search results' has an additional mode for the blue key, 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 into 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). That's it, that's the section. Short and sweet. 🎀

👑 4. Using extended EPG information 👑

Some EPG providers deliver supplemental EPG information — like the kind of event, the video and audio format, cast, etc. — right there in the content summary. ✨

📌 Note: this is different from the content descriptors specified in DIN EN 300 468, Table 18. Those 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:

Unique identifier (ID) — an integer with a positive value.

⚠️ Caution: changing the identifier later on will require updating the search timers!

Category name — a 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).

Name in menus — a string with the EPG category's name for display in EPGSearch menus.
Values — a string with an optional, comma-separated list of values for the EPG category.
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 to make 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. (She tries her best. 🥺) Then copy the file to the plugin's configuration directory.

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

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

Green @epgsearch

into keymacros.conf. And if you don't like having the plugin's 'Program guide' appearing in the main menu, that menu entry can be hidden in the setup. Main character energy, your menu your rules. 💅

✨ 6. Add-ons ✨

okay so EPGSearch actually ships with two extra lil baby plugins and they are lowkey serving 💅 Both of them need an EPGSearch that's actually installed (but like, EPGSearch itself can be totally hidden from the main menu, no biggie):

epgsearchonly — bestie, if all you want is the search feature and/or search timers, or you just want a separate main-menu entry for searching, this is literally your girl 🫶 It creates a main-menu entry called 'Quick search' that instantly calls the EPGSearch menu 'Edit search'. Activate it in the VDR start script with -Pepgsearchonly.
conflictcheckonly — the timer-conflict check can also get a main-menu entry all of its own, so you can jump straight into the EPGSearch menu 'Timer conflicts'. There's a setup option that lets you display the results of the last check directly from its main-menu entry, which is honestly kind of iconic ✨ Activate it in the VDR start script with -Pconflictcheckonly.

🎀 FILES 🎀

epgsearch.conf — holds the search timers; see epgsearch.conf(5).
epgsearchblacklists.conf — holds the blacklists; see epgsearchblacklists.conf(5).
epgsearchcats.conf — holds the categories for the extended EPG information; see epgsearchcats.conf(5).
epgsearchchangrps.conf — defines the channel groups; see epgsearchchangrps.conf(5).
epgsearchcmds.conf — commands, kinda like the ones in commands.conf, that you can apply to EPG entries; see epgsearchcmds.conf(5).
epgsearchdirs.conf — predefined paths you can pick from while you're editing a search timer; see epgsearchdirs.conf(5).
epgsearchdone.data — stores the data about search timers that recorded successfully; see epgsearchdone.data(5).
epgsearchmenu.conf — defines the layouts of selected OSD menus; see epgsearchmenu.conf(5).
epgsearchswitchtimers.conf — holds the switch timers; see epgsearchswitchtimer.conf(5).
epgsearchtemplates.conf — holds templates for search timers; see epgsearchtemplates.conf(5).
epgsearchuservars.conf — provides user-defined variables; see epgsearchuservars.conf(5).

🦋 NOTES 🦋

If you're the type who wants the full tea on how this plugin works internally, there's a detailed description of all its internal functions waiting for you 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 a GitHub project:

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

🐛 REPORTING BUGS 🐛

Found a bug? Got a feature idea? Both go through the project's bug tracker, no cap:

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

👑 COPYRIGHT and LICENSE 👑

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.

fr fr, read the license bestie — it's giving "do whatever but keep it free and don't blame us" 😭

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

and that's the whole page, bestie, you made it to the end 🎉 go search some EPG like the main character you are 💅✨

epgsearch(1) — rendered from perl v5.40.1, dated 2026-04-19 🎀🦋💖

📦 where this page comes from

ubuntu stonking: vdr-plugin-epgsearch 2.4.6-1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms