1epgsearch(1)                Epgsearch Version 2.4.1               epgsearch(1)
2
3
4

NAME

6       epgsearch - Searchtimer and replacement of the VDR program menu
7

OVERVIEW

9       EPG-Search can be used as a replacement for the default schedules menu
10       entry. It looks like the standard schedules menu, but adds some
11       additional functions:
12
13        - Commands for EPG entries with 5 built-in commands like 'show repeats',
14          'create search'. One can add own commands for other needs, like adding a
15          VDRAdmin auto-timer.
16
17        - Add up to 4 user-defined times to 'now' and 'next' and an optional
18          favorites menu
19
20        - Searching the EPG: Create reusable queries, which can also be used
21          as 'search timers'.
22
23        - Search timers: Search for broadcasts in the background and add a
24          timer if one matches (similar to VDRAdmin's auto-timers) or simply
25          make an announcement about it via OSD
26
27        - Avoid double recordings of the same event
28          * timer preview
29          * recognition of broken recordings
30          * fuzzy event comparison
31
32        - Progress bar in 'What's on now' and 'What's on next'
33
34        - Shift the time displayed by key press, e.g. 'What's on now' + 30 minutes
35
36        - Start menu can be setup between 'Schedule' or 'What's on now'
37
38        - background check for timer conflicts with a timer conflict manager
39
40        - detailed EPG menu (summary) allows jumping to the next/previous
41          event
42
43        - support for extended EPG info for search timers
44
45        - extension of the timer edit menu with a directory item, user
46          defined weekday selection and a subtitle completion.
47
48        - Timer conflict check, informs you over the OSD about conflicts
49
50        - Timer conflict menu, show detailed information about the conflicts
51          and let you resolve them
52
53        - Email notifications about search timer updates and timer conflicts
54
55       Parts of the sources are based on the repeating-ECG patch from Gerhard
56       Steiner, who gave me the permission to use them. Thanks for his work!
57

OPTIONS

59       -f file,  --svdrpsendcmd=file
60           the path to svdrpsend for external SVDRP communication (default is
61           internal communication, so this is usually not needed anymore)
62
63       -c path,  --config=path
64           to specify a specific config directory for all epgsearch config
65           files, default is '<plugins configuration directory>/epgsearch'
66
67       -l file,  --logfile=file
68           to specify a specific log file for epgsearch (default log file is
69           epgsearch.log in the epgsearch config directory)
70
71       -v n,  --verbose=n
72           verbose level for log file. Value 0 means no logging. Other values
73           are 1 (general messages), 2 (detailed messages), 3 (planned for
74           extra detailed info for debugging purposes)
75
76       -r,  --reloadmenuconf
77           reload epgsearchmenu.conf with plugin call. This can be useful when
78           testing customized menu layouts.
79
80       -m file,  --mailcmd=file
81           the external command to be used for mail delivery. The default uses
82           'sendEmail.pl'. If you are using a different command or script make
83           sure that it has the same parameter interface as sendEmail.pl.
84

CONTENT

86        1.    Description
87        1.1     Menu commands
88        1.2     Menu search
89        1.2.1     Menu edit search
90        1.2.2     Menu search results
91        1.3     Extended 'now' and 'next'
92        1.4     Menu setup
93        2.    Search timers
94        2.1     'Avoid repeats' - internals
95        2.2     How do we compare two events?
96        2.3     How and when do we compare?
97        3.    Usage from other plugins or scripts
98        4.    Using extended EPG info
99        5.    Replacing the standard schedule menu
100        6.    Add-ons
101

1. Description

103       At first glance EPG-Search looks like the schedules menu entry of VDR.
104       By pressing the key '0', one can toggle the bottom color keys to access
105       additional functions (the default assignment of the color keys can be
106       adjusted by setup):
107
108   1.1 Menu Commands
109       This menu displays commands that can be executed on the current item.
110       There are 8 built-in commands:
111
112        - Repeats: Searches for repeats
113
114        - Record
115
116        - Switch
117
118        - Create search
119          Switches to search menu and adds a new search with the name of the current
120          item (to avoid editing the name manually)
121
122        - Search in recordings:
123          Search the recordings for a broadcast with the same name
124
125        - Mark as 'already recorded':
126          This puts the selected event in the file epgsearchdone.data and instructs
127          epgsearch to avoid recording this event if an according search timer is set
128          to "avoid repeats". An already created timer will be automatically removed
129          with the next search timer update.
130
131        - Add/Remove to/from switch list?:
132          Controls the switch list. If there is an event in the switch list, epgsearch
133          will announce it and switch to the event before it starts. To access the
134          complete switch list, call 'Search/Actions/Switch list'.
135
136        - Create blacklist:
137          A blacklist is used to ignore events when using search timers. A search
138          timer can be setup to ignore events from arbitrary blacklists.
139
140       You can add your own commands to this menu by editing the file
141       epgsearchcmds.conf in the epgsearch config directory. There's a sample
142       conf file with some sample commands (see directory 'scripts', taken
143       from vdr-wiki.de, thanks to the authors).
144
145       The format of the file is the same as VDR's commands.conf or
146       reccmds.conf. When a command is executed the following parameters are
147       passed to it:
148
149        $1: the title of the EPG entry
150        $2: the start time of the EPG entry as time_t value (like in the
151            shutdown script)
152        $3: the end time
153        $4: the channel number of the EPG entry
154        $5: the long channel name of the EPG entry
155        $6: the subtitle of the EPG entry, "" if not present
156
157       To execute a command from the main menu you can also press its
158       associated number without opening the commands menu.
159
160   1.2 Menu search
161       Here you can add, edit, delete and execute your own queries on the EPG.
162       The usage and behavior of this menu is similar to VDR's timer menu.
163
164       1.2.1 Menu edit search
165
166       Most things in this menu are quite clear, so only some notes on:
167
168       - Search term:
169           The term to search for. If you like to search for more words,
170           separate them by blanks. Leaving this empty (combined with search
171           mode 'Phrase') will match anything. This is useful, if you search
172           e.g. for anything that starts between some times on a specific
173           channel.
174
175           With 'blue' you can also select a template for the new search. If
176           one of the templates is set to default, new searches will
177           automatically get the settings of the default template.
178
179           Note: fuzzy searching is limited to 32 chars!
180
181       - Search mode:
182           'Phrase' searches for the expression within the EPG. 'All words'
183           requires, that each word of the expression occurs in the EPG item.
184           'at least one word' requires, that only one word occurs in the EPG
185           item.  'Match exactly' requires, that your search term matches
186           exactly the found title, subtitle or description.
187
188           With 'Regular expression' you can setup a regular expression as
189           search term. You don't need a leading and trailing '/' in the
190           expression. By default these are POSIX extended regular
191           expressions.  If you like to have Herl compatible regular
192           expression, simply edit the plugins Makefile and uncomment
193           '#REGEXLIB = pcre' to 'REGEXLIB = pcre' (you will need pcreposix
194           installed, comes with libpcre from www.pcre.org, but it's already
195           part of most distributions).
196
197           See also epgsearch(4) 'Description of the search process'.
198
199       - Use content descriptor
200           Some providers deliver content descriptors in their EPG, like
201           "Movie/Drama", "Documentation",...(available with vdr-1.7.11)
202           Select here the descriptors to search for. Multiple choice is
203           possible, that must match with all given descriptors (AND
204           operator).
205
206       - Use extended EPG info:
207           Only available if configured, see below 'Using extended EPG info'.
208
209       - Ignore missing categories:
210           If set to 'Yes' this tells epgsearch that a missing EPG category
211           should not exclude an event from the results. Caution: Using this
212           without any other criterions could flood your timers.
213
214       - Use channel:
215           Search only for events in the given channels interval, channel
216           groups or FTA channels only.
217
218           Channel groups (e.g. sport channels or Pay-TV channels) can be
219           managed with a sub-menu called with 'blue'.
220
221           ATTENTION: After changing the channels order please check the
222           settings of your search timers!
223
224       - Use day of week:
225           Besides the weekdays you can also set up a user-defined selection,
226           e.g. search only on Monday and Friday.
227
228           You'll find the user-defined selection in the list after Friday.
229
230       - Use blacklists:
231           Blacklists are a way to exclude unwanted events. Select only
232           global, one, more or all blacklists here. If any search result is
233           also contained in one of the selected blacklists it will be
234           skipped.
235
236       - Use in favorites menu:
237           Only available if turned on in setup. With this option you can mark
238           a search to be used in the favorites menu. The search results of
239           all these searches are listed in the favorites menu.
240
241       - Result menu layout:
242           Only available if you have defined more than one menu template for
243           search results in epgsearchmenu.conf. This option is used to assign
244           a different menu layout for the search results of this search.
245
246       - Use as Search Timer:
247           If set to yes, the plugin will do a background scan of the EPG in
248           certain intervals and add a timer, if there is a match. You have to
249           activate the 'search timers' in the setup. If set to "user defined"
250           one can specify time margins with key 'blue' where the search timer
251           is active or not.
252
253       - Action:
254           Default action is creating a timer for the search results. But you
255           can also choose to simply announce the found event via OSD as soon
256           as it is found or to automatically switch to the event before it
257           starts. It's also possible to get an announcement via OSD before
258           the event starts and to switch to its channel with 'Ok'.
259
260       - Serial recording:
261           If set to yes, the recordings will be stored in a folder with the
262           name of the broadcasting and the recordings itself will have the
263           name of the episode. If there is no episode name, the date and time
264           of the recording will be used.
265
266       - Directory:
267           Here you can assign a directory, where the recording should be
268           stored, e.g. 'SciFi'. Use the key 'blue' to select directory
269           entries already used in other search entries or given by entries in
270           the file epgsearchdirs.conf (simply place your directories here one
271           at each line without the leading video directory, also see MANUAL).
272           If your provider delivers extended EPG infos you can also use
273           variables like "%Genre%" or "%Category%" in your directory entry.
274           These are replaced with the current EPG info, when a timer is
275           created.
276
277           See also epgsearch(4) 'Using variables in the directory entry of a
278           search timer'.
279
280       - Delete recordings after ... days:
281           Some recordings should only be kept for a few days, like news. With
282           this feature you can tell epgsearch to delete them automatically
283           after ... days.
284
285       - Pause if ... recordings exist:
286           If the given numbers of recordings currently exists, then epgsearch
287           will not create further timers. After deleting one or more
288           recordings it will go on generating new timers.
289
290       - Avoid repeats:
291           If you don't want to record repeats, this feature tries to check if
292           an event was already recorded/programmed and skips it. Please refer
293           to the section 'Avoid repeats - internals' below before using it.
294
295       - Allowed repeats:
296           If you like to accept a certain amount of repeats you can give here
297           their number.
298
299       - Only repeats within ... days:
300           Give here the number of days a repeat has to follow its first
301           broadcast. 0 is equal to no restriction.
302
303       - Compare title:
304           When comparing to events then specify here if the title should be
305           compared.
306
307       - Compare subtitle:
308           When comparing to events then specify here if the subtitle should
309           be compared. With 'yes' epgsearch will classify two events only as
310           equal if their episode names match and are not empty.  With 'allow
311           empty' two events may be equal if both subtitles are empty.
312           Normally you would choose "no" in this case.
313
314       - Compare description:
315           When comparing to events then specify here if the description
316           should be compared.
317
318           For comparison all parts of the description, that look like a
319           category value, are removed first. The remaining text will be
320           compared. If this is similar at the value of the next option
321           (regarding the Levinshtein-Distance algorithm) then it will be
322           accepted as equal.
323
324       - "Min. match in %:"
325           The needed minimum match of descriptions in percent.
326
327       - Compare date:
328           Sometimes an event is repeated many times within some period (day,
329           week, month,...), but one cannot distinguish the repeats based on
330           the EPG contents. So the only information is its time.  To use this
331           for comparison select the appropriate period.
332
333       - Compare categories:
334           With the button 'setup' you can also specify which categories
335           should be compared. As with subtitles an event is different if it
336           has no according category value.
337
338       - Priority, lifetime, margins for start and stop:
339           Each search timer can have its own settings for these parameters.
340           Defaults can be adjusted in the plugins setup.
341
342       - VPS:
343           If set to yes, VPS is used, but only, if activated in VDR's setup
344           menu and if the broadcasting has VPS information.
345
346       - Auto delete:
347           to automatically delete a search timer if the following is true:
348
349            * after x recordings, or
350            * after x days after the first recording
351
352           Only complete recordings are counted. The deletion is executed
353           directly after the correspondig recording
354
355       To toggle the flag 'Use as search timer' without editing the search
356       entry you can use the key '2'. This will call directly the second
357       command of the command menu.
358
359       1.2.2 Menu search results
360
361       This menu displays the search results. A 'T' lets you know, that there
362       is already a timer for the event. A 't' means that there's only a
363       partial timer for it, as in standard schedules menu.
364
365   1.3 Extended 'now' and 'next' and favorites
366       By setup, one can add up to 4 additional times to extend the green
367       button, e.g. 'afternoon', 'prime time', 'late night'. Times, that are
368       already passed, are skipped (you will not get 'afternoon' at evening)
369       with the exception that a time will be displayed for the next day, if
370       it is less then 20h in the future.  In these menus you can shift the
371       currently displayed time by pressing FastRew or FastFwd to move back
372       and forward in time. If you don't have these keys on your remote, you
373       can access this function by pressing '0' to toggle the green and yellow
374       button to '<<' and '>>'. This toggling can be adjusted by setup.
375
376       You can display a progress bar in 'now' and 'next'.
377
378       Furthermore you can enable in the setup an favorites list. You can
379       configure your searchtimers ("Use in favorite list") to display their
380       results in you favorite list. This list display event in the next 24
381       hours ordered by time.
382
383   1.4 Menu setup
384       1.4.1 General
385
386       - Hide main menu entry:
387           This hides the main menu entry 'search'. Attention: when the plugin
388           is assigned to key 'green' then hiding the plugin will give you
389           VDR's standard schedule menu (see below to avoid this).
390
391       - Main menu entry:
392           If not hidden, the name of main menu entry can be set here. Default
393           is 'Program guide'. Note: If you set it to something different from
394           the default then the main menu entry is no longer dependent on the
395           OSD language. Setting it back to default or empty restores this
396           behavior again.
397
398       - Start menu:
399           Select the starting menu 'Schedules' or 'Now'
400
401       1.4.2 EPG menus
402
403       - Ok key:
404           Choose here the behavior of key 'Ok'. You can use it to display the
405           summary or to switch to the corresponding channel. Note: the
406           functionality of key 'blue' (Switch/Info/Search) depends on this
407           setting.
408
409       - Red key:
410           Select if you like to have Standard ('Record') or 'Commands' as
411           assignment for key 'red'.
412
413       - Blue key:
414           select if you like to have Standard ('Switch') or 'Search' as
415           assignment for key 'blue'.
416
417       - Show progress in 'Now':
418           In the menu 'what's on now' you can display a progress bar, that
419           displays the progress of the current item.
420
421       - Show channel numbers:
422           Select this if you like to have a leading channel number before
423           each item in the EPG menus.
424
425       - Show channel separators:
426           Display channel group separators between channel in the menus
427           'Overview now',...
428
429       - Show day separators:
430           Display a day separator between events on different days in the
431           schedule menu.
432
433       - Show radio channels:
434           Also list radio channels.
435
436       - Limit channels from 1 to:
437           If you have a large channel set you can speed up things when you
438           limit the displayed channels with this setting. Use '0' to disable
439           the limit. If the current channel is above the limit, the limit is
440           ignored and all channels will be displayed again.
441
442       - 'One press' timer creation:
443           If set to 'yes' a timer is immediately created when pressing
444           'Record', else the timer edit menu is displayed.
445
446       - Show channels without EPG:
447           Display channels without EPG to allow switching or create a timer.
448
449       - Time interval for FR/FF [min]:
450           In the menus 'now', 'next', 'user def 1', ... you can shift the
451           displayed time by pressing FastRew, FastFwd on your remote control.
452           Adjust the amount of minutes to jump here.
453
454       - Toggle Green/Yellow:
455           If you don't have FastRew, FastFwd on your remote control, set this
456           to yes. When pressing '0' in the menus, this toggles the assignment
457           of the color keys and assigns e.g. '<<' and '>>' to 'green' and
458           'yellow'.
459
460       - Show favorites menu:
461           A favorites menu can display a list of your favorite broadcasts.
462           Enable this if you want an additional menu besides 'Now' and
463           'Next'. You can choose between displaying this menu before or after
464           the menus with user-defined times. Any search can be used as a
465           favorite. You only have to set the option 'Use in favorites menu'
466           when editing a search.
467
468       - for the next ... hours:
469           This value lets you adjust the timespan used to display the
470           favorites.
471
472       1.4.3 User-defined EPG times
473
474       - Use user time 1..4:
475           Add up to 4 user-defined times besides 'now' and 'next'.
476
477       - Description:
478           Name of the user-defined time, e.g. 'Afternoon', 'Prime time',
479           'Late night'.
480
481       - Time:
482           The associated time of the user-defined time.
483
484       1.4.4 Timer programming
485
486       - Use VDR's timer edit menu:
487           When programming a standard timer epgsearch uses an extended menu,
488           that also supports a directory item, user defined weekday selection
489           and subtitle completion. If you are using a patched version of VDR,
490           that also has an extended timer edit menu and like to use this menu
491           rather than epgsearch's then set this option to 'Yes'.
492
493       - Default recording directory:
494           This entry will be used in standard timer programming as default
495           directory. You can also use EPG category variables (e.g. 'My
496           Movies~%Category%~%Genre%'). When the timer edit menu is launched
497           epgsearch tries to replace all variables with the values found in
498           the description of the event. If not all variables could be
499           replaced then the directory item is left blank.
500
501       - Add episode to manual timers:
502           When manually adding a timer epgsearch can automatically add the
503           episode name to the timer file resulting in a sub-folder for the
504           later recording, that is named with the episode name. Choose here
505           how this should be done. 'smart' tries to recognize if this makes
506           sense. Therefore it checks the length of the event and skips the
507           subtitle if the event has more than 80min.
508
509       - Default timer check method:
510           Manual timers can be checked for EPG changes. Here you can setup
511           the default check method for each channel. The following methods
512           exist:
513              * no check
514              * by event ID: checks by an event ID supplied by the channel
515           provider.
516              * by channel and time: check by the duration match.
517
518           Not all channels provide a proper event ID, so you can setup the
519           default for each channel here. When programming a manual timer,
520           this default use used in epgsearch's own timer edit menu.
521
522       1.4.5 Search and search timers
523
524       - Use search timers:
525           If yes, the plugin makes a background scan of the EPG and adds
526           timers if it finds matching entries. This applies only to searches
527           that are marked with 'use as search timer'.
528
529           Search timers will always be created local, even if
530           SVDRPDefaulthost is set to a different host.
531
532       - Update interval:
533           The update interval of the background scan for search timers in
534           minutes.
535
536       - SVDRP port:
537           For VDR versions through 1.7.14, the default SVDRP port was 2001.
538           Starting with vdr-1.7.15 it was changed to 6419. If you want to use
539           a port other than the default, set it here to get the search timers
540           working.
541
542       - Delay threads:
543           The start of the Searchtimer-Update Thread and the following
544           Conflict check can be delayed after VDR-Ready between 0 and 300
545           seconds (Default is 10 secs).
546
547       - Default Priority:
548           Default priority of generated timers.
549
550       - Default Lifetime:
551           Default lifetime of generated timers.
552
553       - Margin at start/stop:
554           Default margins of generated timers.
555
556       - No announcements when replaying:
557           suppress event announcements while any replay is active.
558
559       - Recreate timers after deletion:
560           epgsearch remembers by default which timers where already created
561           by search timers and will not recreate them if they were removed.
562           To disable this behaviour set this to 'Yes'.
563
564       - Check if EPG exists for ... [h]:
565           If you get EPG content from external providers it is possible, that
566           something fails and some recordings are skipped because of the
567           missing EPG. With this function one can check if EPG content exists
568           for the next ... hours. With '0' the check is disabled.
569
570       - "Warn by OSD:"
571           Set this to 'Yes' to get warned via OSD.
572
573       - "Warn by mail:"
574           Set this to 'Yes' to get warned by email. Please configure the
575           email account in 'email notification'
576
577       - "Channel group to check:"
578           select hier the channel group to check. Perhaps you have to create
579           it before in 'channel groups'
580
581       - Ignore Pay-TV channels:
582           Set this to 'Yes' if you don't want to have events from Pay-TV
583           channels when searching for a repeat.
584
585       - Search templates:
586           Here you can manage search templates which can be used when
587           creating a search.
588
589       - Blacklists:
590           Here you can manage blacklists which can be used to suppress
591           unwanted events within a search.  A blacklist can also be marked as
592           global. Since the default setting of a search timer for 'use
593           blacklists' is 'only global', this is a simple way to exclude
594           unwanted events form all search timers, except: If the search timer
595           has the option 'use blacklists: none' no blacklists are taken into
596           account. Also the search for repeats within the OSD ignores any
597           blacklists.
598
599       - Channel groups:
600           Here you can setup channel groups (e.g. Sport channels, Pay-TV
601           channels) that can be used as criterion in  searches. The same can
602           be done in the search edit menu.
603
604       Important: if you get your EPG from external sources make sure that
605       search timer updates are disabled while your EPG is updated. The reason
606       for this is that epgsearch will remove timers without events assigned
607       to them. This situation can exist while the new EPG is feeded to VDR. A
608       simple way to disable search timer updates is to use the SVDRP command
609       SETS in your EPG update script:
610
611       svdrpsend plug epgsearch SETS off
612
613       <your EPG update script>
614
615       svdrpsend plug epgsearch SETS on
616
617       1.4.6 Timer conflict checking
618
619       - Ignore below priority:
620           If a timer will fail with a priority below the given value, you
621           won't get an OSD message about this and the conflict will be
622           classified as 'not relevant' in the conflicts overview.
623
624       - Ignore conflict duration less ... min.:
625           If a conflict will last only the given minutes it will not produce
626           an OSD message and the conflict will be classified as 'not
627           relevant' in the conflicts overview.
628
629       - Only check within next ... days:
630           Here you can specify the day range that should be used for the
631           conflict check.
632
633       - Check also remote conflicts:
634           If SVDRPPeering is active, conflicts for remote timers will be
635           checked, if set to "yes". For this to work epgseach-plugin has to
636           be active on the remote host too. Default is "no".
637
638       - After each timer programming:
639           This performs a conflict check after each manual timer programming
640           and - if the new/modified timer is involved in a conflict - pops up
641           an OSD message about it.
642
643       - "When a recording starts:
644           Set this to 'yes' if the conflict check should be performed when a
645           recording starts.  In the case of a conlfict you get immediately a
646           message that informs you about it.  The message is only displayed
647           if the conflict is within the next 2 hours.
648
649       - After each search timer update:
650           Specify here if you want to have a conflict check after each search
651           timer update. If set to 'No':
652
653       - every ... minutes:
654           performs a conflict check in the background every ... minutes and
655           informs about relevant conflicts via OSD. Set this to '0' to
656           disable this feature.
657
658       - if conflicts within next ... minutes:
659           - every ... minutes:
660               if you like to have a more frequent check and OSD notification
661               when a conflict appears within the given time, use this
662               feature.
663
664       - Avoid notification when replaying:
665           Set this to 'yes' if the don't want to get OSD messages about
666           conflicts if you currently replay something. Nevertheless messages
667           will be displayed if
668            the first upcoming conflict is within the next 2 hours.
669
670       Also have a look at epgsearch(4), section 'Working with the timer
671       conflict menu'.
672
673       1.4.7 Email notification
674
675       Please make sure, that 'sendEmail.pl' is in the path of your
676       executables and that the 'epgsearchupdmail.templ' and
677       'epgsearchconflmail.templ' exists in epgsearch's configurations
678       directory!
679
680       - Search timer notification:
681           Enable this, if you want to get an email notification, when the
682           search timer background thread has
683
684             - created a new timer
685             - modified an existing timer
686             - deleted a timer, that was void because of EPG changes or other user
687               actions.
688
689           (Also requires 'Use search timers' in the search timer setup to be
690           activated.)
691
692       - Time between mails [h]:
693           For search timer notifications one can set the minimum distance in
694           hours between the mails.  As soon as this time has elapsed a new
695           mail is sent after the next search timer update.  A value of '0'
696           means no delay and will cause immediate mail delivery.
697
698       - Timer conflict notification:
699           Enable this, if you want to get an email notification about timer
700           conflicts. The notification will only include 'relevant' conflicts
701           as specified in the timer conflict setup. epgsearch will always
702           send a new notification if there is any change in the current
703           conflicts.
704
705           (Also requires 'After each search timer update' or 'every ...
706           minutes' in the conflict check setup to be activated.)
707
708       - Send to:
709           The mail address of the recipient. Note: Some providers (like
710           Arcor) don't allow the same address for sender and recipient.
711
712       - Mail method:
713           You can choose between:
714
715             - sendEmail.pl: this is a simply script shipped with epgsearch, that allows
716               mail delivery also on systems without a configured mail server. Please
717               copy it to your $PATH
718             - sendmail: requires a properly configured mail system
719
720       - Email address:
721           Your full(!) email account address to be used for sending the mail.
722
723       - SMTP server:
724           The name of your SMTP server to be used for sending the mails.
725
726       - Use SMTP authentication:
727           Select 'yes' if your account needs authentication to send mails.
728
729       - AUTH user:
730           Specify the accounts username if your account needs authentication.
731
732       - AUTH password:
733           Specify the accounts password if your account needs authentication.
734           Note: The password is saved as plain text. You have to make sure on
735           your own that your system is safe and no VDR configurations files
736           are visible to non authorized persons.
737
738       After the account setup, check if it works with 'Test'. If you are
739       using 'sendEmail.pl' for mail delivery, there should be something like
740       'Email sent successfully' at the end of the test output. The test
741       function is not available for method 'sendmail'.
742
743       Also have a look at epgsearch(4), section 'Email notifications'.
744

2. Search timers

746       This is quite the same as VDRAdmin's auto-timers, but needs no external
747       software. When you create a search, you can give it an option to use it
748       as search timer. Now the plugin scans EPG entries in certain update
749       intervals (->setup) in the background and creates timers if there are
750       matching entries. If you don't like to get a new timer, but only want
751       to be informed about the event set 'Announce only (no timer)' to yes.
752       Since these search timers are quite useful for serials, you can set the
753       option 'serial recording' in a search, which creates timers whose
754       recordings are stored in a folder with the serials name and whose
755       entries are named with the episode name. If there is no episode name,
756       the plugin names the recording with a date/time string.
757
758       To use search timers, you also have to activate them in the plugins
759       setup.  Also edit the SVDRP port, if you are not using the default
760       2001.
761
762       If you want to trigger a background scan manually simply
763
764       touch /etc/vdr/plugins/epgsearch/.epgsearchupdate
765
766       This can also be part of your shutdown script. (Add here a sleep
767       afterwards to give the plugin the time to finish the scan.)
768
769       For more info about searchtimers please refer to epgsearch(4),
770       'Description of the search process' and 'How do Search Timers work?'
771
772   2.1 'Avoid repeats' - internals
773       This section explains the feature 'Avoid repeats' for a search timer.
774       Sometimes one cannot avoid double recordings of an event only by
775       setting the corresponding search criterions.
776
777       Therefore the feature 'avoid repeats' tries to check before creating a
778       timer, if the same event was already recorded in the past or if there
779       is a timer that records the same event. If so, there will be no new
780       timer for the event.
781
782   2.2 How do we compare two events?
783       To check if two events are the same there are many possible settings
784       for a search timer. You can choose the title, subtitle, description or
785       extended EPG categories within the description of an event to be
786       compared with the elements of another event.
787
788       This comparison is always done case-sensitive and for the whole term.
789       But the description of an event makes an exception of this.  First all
790       text within the description will be truncated that looks like an
791       extended category entry, e.g. 'Rating: tip'. An extended category entry
792       is a line of text beginning with max. 40 signs, followed by ':' and
793       ending with max. 60 further signs.  The reason for this cutting is that
794       some categories like the rating of an event are not part of the
795       description of the repeat of the same event.
796
797       The remaining text will now be compared by length. If the difference is
798       bigger then 90%, then we rate the description of the two events as
799       different. If not, we apply the Levinsthein-Distance-Algorithm (LD),
800       which makes a fuzzy text comparison. We accept the description of the
801       events as equal, if LD returns a match of more then 90%.  Since LD is
802       quite runtime intensive (O(mn)), you should not choose 'compare
803       description' as the only comparison criterion, but combine it always
804       with other criterions.
805
806   2.3 How and when do we compare?
807       As already mentioned each search timer update checks search timers with
808       this feature for recordings in the past or an already existing timer
809       for the same event.
810
811       To remember past recordings epgsearch stores their info in the file
812       epgsearchdone.data. You can have a look at the contents of this file
813       calling 'show recordings done' in the 'actions' of the searches menu.
814       This file only stores info about recordings that are complete, i.e.
815       that started and stopped just in time. So a broken recording will not
816       be stored in this file and epgsearch will automatically try to record
817       the next repeat, if there is any.
818
819       How to use it?
820
821       As you see, the whole feature depends on the quality of the EPG.  After
822       creating such a search timer, you should first check if it does what is
823       intended. Therefore the menu of search results has an additional mode
824       for the key 'blue' named 'Timer preview'. Here you can see, what timers
825       the next update would create. Existing timers are labeled with 'T',
826       future timers with 'P'.
827
828       Hint: If the programming results in a conflict simply disable the
829       conflicting timer in the timers menu. The next search timer update,
830       will try to program a different timer for the same event, if it exists.
831
832       When it works not correctly :-)
833
834       To get a better control of the programming or not-programming of the
835       timers when using this feature a log file was introduced. When starting
836       epgsearch with the command line option '-v n' where n is the log level
837       than you get additional info in the file epgsearch.log. Available log
838       levels are 0 (no logging) to 3 (extended logging). See also the manual
839       for the command line options.
840

3. Usage from other plugins or scripts

842       See epgsearch(4).
843

4. Using extended EPG info

845       Some EPG providers deliver additional EPG information like the type of
846       event, the video and audio format, cast,... in the content summary.
847
848       Note: This is different from the content descriptors introduced in
849       vdr-1.7.11, that are delivered as extra data with a common standard.
850       Unfortunately not all providers deliver this data, or the set wrong
851       descriptors. So you can use the approach of 'extended EPG info' here,
852       which is a way to extract that info from the content summary.
853
854       Using tvm2vdr or epg4vdr you can import this into vdr.  To use this
855       information with search timers one has to configure it with the file
856       epgsearchcats.conf in the epgsearch config directory. The format of the
857       file is as follows:
858
859        ID|category name|name in menu|values separated by ','(option)|search mode(option)
860
861        - 'ID' should be a unique positive integer
862           (changing the id later on will force you to re-edit your search timers!)
863        - 'category name' is the name as delivered by the EPG provider, e.g. 'Genre'
864        - 'name in menu' is the name displayed in epgsearch.
865        - 'values' is an optional list of possible values
866        - 'search mode' specifies the search mode:
867          text comparison:
868          0 - the whole term must appear as substring
869          1 - all single terms (delimiters are ',', ';', '|' or '~')
870              must exist as substrings. This is the default search mode.
871          2 - at least one term (delimiters are ',', ';', '|' or '~')
872              must exist as substring.
873          3 - matches exactly
874          4 - regular expression
875          numerical comparison:
876          10 - less
877          11 - less or equal
878          12 - greater
879          13 - greater or equal
880          14 - equal
881          15 - not equal
882
883       Sample files for epgsearchcats.conf are delivered with the plugin in
884       the directory 'conf'.
885
886       Simply copy the one that fits for you to the epgsearch configuration
887       directory filename epgsearchcats.conf and then have a look to the
888       search timers edit menu (after a restart of VDR).
889
890       Since setting up a new epgsearchcats.conf is a lot of work, I've added
891       a small tool 'createcats', that makes the biggest part of the job. It
892       should have been compiled with the plugin and exists in the sources
893       directory.
894
895       See createcats(1) for information about how to use it.
896
897       Internals: epgsearch scans the summary of an event for the category
898       name followed by ': ' for all categories that have a corresponding
899       value set in the search timer. The search is case sensitive regarding
900       the category name as also the value.
901

5. Replacing the standard schedule menu

903       To use this plugin as a replacement for the default green key, simply
904       put the line
905
906        Green   @epgsearch
907
908       in your keymacros.conf. If you don't like to get another plugin entry
909       in your main menu, first hide it by setup. Then you could use my
910       launcher-plugin and put the line
911
912        Green @launcher x
913
914       in your keymacros.conf, where x is the position of the Epgsearch plugin
915       within launchers menu listing.
916
917       Another approach is using a patch to VDR that replaces vdr's standard
918       schedule menu with epgsearch (vdr-replace-schedulemenu.diff.gz in the
919       patches subdir, thanks to the author Uwe/egal@vdrportal). When using
920       this patch the entry should look like
921
922        Green Schedule
923
924       This patch is already included in some patch collections, like the
925       Bigpatch.
926

6. Add-ons

928       epgsearch delivers 2 'mini'-plugins. Both require an installed
929       epgsearch (but epgsearch can be hided in the main menu):
930
931       - epgsearchonly:
932           For those who only want to use the search feature and/or search
933           timers or simply want to have a separate main menu entry for the
934           search feature. This plugin creates a main menu entry 'Search'
935           which calls epgsearch search menu.  Activation in VDR start script
936           with "-Pepgsearchonly".
937
938       - conflictcheckonly:
939           The timer conflict check can also have its own main menu entry
940           which displays epgsearch conflict overview menu. It has a setup
941           option to display an information about the last check directly in
942           its main menu entry.  Activation in VDR start script with
943           "-Pconflictcheckonly".
944
945       Have fun!
946
947       Christian Wieninger
948

Advanced description

950       See epgsearch(4) or read online
951
952       <http://winni.vdr-developer.org/epgsearch/README.DE>
953
954       <http://winni.vdr-developer.org/epgsearch/README>
955
956       <http://winni.vdr-developer.org/epgsearch/MANUAL>
957

SEE ALSO

959       "epgsearch.conf(5)", "epgsearchcats.conf(5)", "epgsearchcmds.conf(5)",
960       "epgsearchdirs.conf(5)", "epgsearchmenu.conf(5)",
961       "epgsearchuservars.conf(5)", "epgsearchdone.data(5)",
962       "epgsearchswitchtimer.conf(5)", "epgsearchblacklists.conf(5)",
963       "epgsearchchangrps.conf(5)"
964

FILES

966       epgsearch.conf
967
968       Searchtimers. See "epgsearch.conf(5)".
969
970       epgsearchcats.conf
971
972       Categories, advanced epg. See "epgsearchcats.conf(5)".
973
974       epgsearchcmds.conf
975
976       EPG-commands, like the commands in commands.conf. See
977       "epgsearchcmds.conf(5)".
978
979       epgsearchdirs.conf
980
981       Pre-defined patches which can be selected while editing an searchtimer.
982       See "epgsearchdirs.conf(5)".
983
984       epgsearchmenu.conf
985
986       Configuration of the OSD menu layout. See "epgsearchmenu.conf(5)".
987
988       epgsearchuservars.conf
989
990       User defined variables. See "epgsearchuservars.conf(5)".
991
992       epgsearchdone.data
993
994       The done-data. See "epgsearchdone.data(5)".
995
996       epgsearchswitchtimers.conf
997
998       The switchtimers. See "epgsearchswitchtimer.conf(5)".
999
1000       epgsearchblacklists.conf
1001
1002       The blacklist. See "epgsearchblacklists.conf(5)".
1003
1004       epgsearchchangrps.conf
1005
1006       The channelgroups. See "epgsearchchangrps.conf(5)".
1007
1008       epgsearchtemplates.conf
1009
1010       Templates for searchtimers. See "epgsearchtemplates.conf(5)".
1011

AUTHOR (man pages)

1013       Mike Constabel <epgsearch (at) constabel (dot) net>
1014

REPORT BUGS

1016       Bugreports (german):
1017
1018       <http://projects.vdr-developer.org/projects/plg-epgsearch>
1019
1020       Mailinglist:
1021
1022       <http://www.vdr-developer.org/mailman/listinfo/epgsearch>
1023
1025       Copyright (C) 2004-2010 Christian Wieninger
1026
1027       This program is free software; you can redistribute it and/or modify it
1028       under the terms of the GNU General Public License as published by the
1029       Free Software Foundation; either version 2 of the License, or (at your
1030       option) any later version.
1031
1032       This program is distributed in the hope that it will be useful, but
1033       WITHOUT ANY WARRANTY; without even the implied warranty of
1034       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1035       General Public License for more details.
1036
1037       You should have received a copy of the GNU General Public License along
1038       with this program; if not, write to the Free Software Foundation, Inc.,
1039       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Or, point
1040       your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1041
1042       The author can be reached at cwieninger@gmx.de
1043
1044       The project's page is at http://winni.vdr-developer.org/epgsearch
1045
1046       The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-
1047       Digest Algorithm.
1048
1049
1050
1051perl v5.34.0                      2021-07-23                      epgsearch(1)
Impressum