1epgsearch(1) Epgsearch Version 0.9.25.beta17 epgsearch(1)
2
3
4
6 epgsearch - Searchtimer and replacement of the VDR program menu
7
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 Works only with >= vdr-1.3.46 or newer.
56
57 Parts of the sources are based on the repeating-ECG patch from Gerhard
58 Steiner, who gave me the permission to use them. Thanks for his work!
59
61 -f file, --svdrpsendcmd=file
62 the path to svdrpsend.pl for external SVDRP communication (default
63 is internal communication, so this is usually not needed anymore)
64
65 -c path, --config=path
66 to specify a specific config directory for all epgsearch config
67 files, default is '<plugins configuration directory>/epgsearch'
68
69 -l file, --logfile=file
70 to specify a specific log file for epgsearch (default log file is
71 epgsearch.log in the epgsearchs config directory)
72
73 -v n, --verbose=n
74 verbose level for log file. Value 0 means no logging. Other values
75 are 1 (general messages), 2 (detailed messages), 3 (planned for
76 extra detailed info for debugging purposes)
77
78 -r, --reloadmenuconf
79 reload epgsearchmenu.conf with plugin call. This can be useful when
80 testing customized menu layouts.
81
82 -m file, --mailcmd=file
83 the external command to be used for mail delivery. The default uses
84 'sendEmail.pl'. If you are using a different command or script make
85 sure that it has the same parameter interface as sendEmail.pl.
86
88 1. Description
89 1.1 Menu commands
90 1.2 Menu search
91 1.2.1 Menu edit search
92 1.2.2 Menu search results
93 1.3 Extended 'now' and 'next'
94 1.4 Menu setup
95 2. Search timers
96 2.1 'Avoid repeats' - internals
97 2.2 How do we compare two events?
98 2.3 How and when do we compare?
99 3. Usage from other plugins or scripts
100 4. Using extended EPG info
101 5. Replacing the standard schedule menu
102 6. Add-ons
103
105 At first glance EPG-Search looks like the schedules menu entry of VDR.
106 By pressing the key '0', one can toggle the bottom color keys to access
107 additional functions (the default assignment of the color keys can be
108 adjusted by setup):
109
110 1.1 Menu Commands
111 This menu displays commands that can be executed on the current item.
112 There are 8 built-in commands:
113
114 - Repeats: Searches for repeats
115
116 - Record
117
118 - Switch
119
120 - Create search
121 Switches to search menu and adds a new search with the name of the current
122 item (to avoid editing the name manually)
123
124 - Search in recordings:
125 Search the recordings for a broadcast with the same name
126
127 - Mark as 'already recorded':
128 This puts the selected event in the file epgsearchdone.data and instructs
129 epgsearch to avoid recording this event if an according search timer is set
130 to "avoid repeats". An already created timer will be automatically removed
131 with the next search timer update.
132
133 - Add/Remove to/from switch list?:
134 Controls the switch list. If there is an event in the switch list, epgsearch
135 will announce it and switch to the event before it starts. To access the
136 complete switch list, call 'Search/Actions/Switch list'.
137
138 - Create blacklist:
139 A blacklist is used to ignore events when using search timers. A search
140 timer can be setup to ignore events from arbitrary blacklists.
141
142 You can add your own commands to this menu by editing the file
143 epgsearchcmds.conf in epgsearchs config directory. There's a sample
144 conf file with some sample commands (see directory 'scripts', taken
145 from vdr-wiki.de, thanks to the authors).
146
147 The format of the file is the same as VDR's commands.conf or
148 reccmds.conf. When a command is executed the following parameters are
149 passed to it:
150
151 $1: the title of the EPG entry
152 $2: the start time of the EPG entry as time_t value (like in the
153 shutdown script)
154 $3: the end time
155 $4: the channel number of the EPG entry
156 $5: the long channel name of the EPG entry
157 $6: the subtitle of the EPG entry, "" if not present
158
159 To execute a command from the main menu you can also press its
160 associated number without opening the commands menu.
161
162 1.2 Menu search
163 Here you can add, edit, delete and execute your own queries on the EPG.
164 The usage and behavior of this menu is similar to VDR's timer menu.
165
166 1.2.1 Menu edit search
167
168 Most things in this menu are quite clear, so only some notes on:
169
170 - Search term:
171 The term to search for. If you like to search for more words,
172 separate them by blanks. Leaving this empty (combined with search
173 mode 'Phrase') will match anything. This is useful, if you search
174 e.g. for anything that starts between some times on a specific
175 channel.
176
177 With 'blue' you can also select a template for the new search. If
178 one of the templates is set to default, new searches will
179 automatically get the settings of the default template.
180
181 Note: fuzzy searching is limited to 32 chars!
182
183 - Search mode:
184 'Phrase' searches for the expression within the EPG. 'All words'
185 requires, that each word of the expression occurs in the EPG item.
186 'at least one word' requires, that only one word occurs in the EPG
187 item. 'Match exactly' requires, that your search term matches
188 exactly the found title, subtitle or description.
189
190 With 'Regular expression' you can setup a regular expression as
191 search term. You don't need a leading and trailing '/' in the
192 expression. By default these are POSIX extended regular
193 expressions. If you like to have Herl compatible regular
194 expression, simply edit the plugins Makefile and uncomment
195 '#REGEXLIB = pcre' to 'REGEXLIB = pcre' (you will need pcreposix
196 installed, comes with libpcre from www.pcre.org, but it's already
197 part of most distributions).
198
199 See also epgsearch(4) 'Description of the search process'.
200
201 - Use extended EPG info:
202 Only available if configured, see below 'Using extended EPG info'.
203
204 - Ignore missing categories:
205 If set to 'Yes' this tells epgsearch that a missing EPG category
206 should not exclude an event from the results. Caution: Using this
207 without any other criterions could flood your timers.
208
209 - Use channel:
210 Search only for events in the given channels interval, channel
211 groups or FTA channels only.
212
213 Channel groups (e.g. sport channels or Pay-TV channels) can be
214 managed with a sub-menu called with 'blue'.
215
216 ATTENTION: After changing the channels order please check the
217 settings of your search timers!
218
219 - Use day of week:
220 Besides the weekdays you can also set up a user-defined selection,
221 e.g. search only on Monday and Friday.
222
223 You'll find the user-defined selection in the list after Friday.
224
225 - Use blacklists:
226 You can select one or more or all blacklists here. If any search
227 result is also contained in one of the selected blacklists it will
228 be skipped.
229
230 - Use in favorites menu:
231 Only available if turned on in setup. With this option you can mark
232 a search to be used in the favorites menu. The search results of
233 all these searches are listed in the favorites menu.
234
235 - Result menu layout:
236 Only available if you have defined more than one menu template for
237 search results in epgsearchmenu.conf. This option is used to assign
238 a different menu layout for the search results of this search.
239
240 - Use as Search Timer:
241 If set to yes, the plugin will do a background scan of the EPG in
242 certain intervals and add a timer, if there is a match. You have to
243 activate the 'search timers' in the setup. If set to "user defined"
244 one can specify time margins with key 'blue' where the search timer
245 is active or not.
246
247 - Action:
248 Default action is creating a timer for the search results. But you
249 can also choose to simply announce the found event via OSD as soon
250 as it is found or to automatically switch to the event before it
251 starts. It's also possible to get an announcement via OSD before
252 the event starts and to switch to its channel with 'Ok'.
253
254 - Serial recording:
255 If set to yes, the recordings will be stored in a folder with the
256 name of the broadcasting and the recordings itself will have the
257 name of the episode. If there is no episode name, the date and time
258 of the recording will be used.
259
260 - Directory:
261 Here you can assign a directory, where the recording should be
262 stored, e.g. 'SciFi'. Use the key 'blue' to select directory
263 entries already used in other search entries or given by entries in
264 the file epgsearchdirs.conf (simply place your directories here one
265 at each line without the leading video directory, also see MANUAL).
266 If your provider delivers extended EPG infos you can also use
267 variables like "%Genre%" or "%Category%" in your directory entry.
268 These are replaced with the current EPG info, when a timer is
269 created.
270
271 See also epgsearch(4) 'Using variables in the directory entry of a
272 search timer'.
273
274 - Delete recordings after ... days:
275 Some recordings should only be kept for a few days, like news. With
276 this feature you can tell epgsearch to delete them automatically
277 after ... days.
278
279 - Pause if ... recordings exist:
280 If the given numbers of recordings currently exists, then epgsearch
281 will not create further timers. After deleting one or more
282 recordings it will go on generating new timers.
283
284 - Avoid repeats:
285 If you don't want to record repeats, this feature tries to check if
286 an event was already recorded/programmed and skips it. Please refer
287 to the section 'Avoid repeats - internals' below before using it.
288
289 - Allowed repeats:
290 If you like to accept a certain amount of repeats you can give here
291 their number.
292
293 - Only repeats within ... days:
294 Give here the number of days a repeat has to follow its first
295 broadcast. 0 is equal to no restriction.
296
297 - Compare title:
298 When comparing to events then specify here if the title should be
299 compared.
300
301 - Compare subtitle:
302 When comparing to events then specify here if the subtitle should
303 be compared. Besides 'no' and 'yes' there is also the option 'if
304 present'. With this setting epgsearch will classify two events
305 only as equal if their episode names match and are not empty.
306 Caution: if your EPG data has no episode names for different
307 episodes don't use this option! 'yes' will then be the better
308 choice even if this results in double recordings.
309
310 - Compare description:
311 When comparing to events then specify here if the description
312 should be compared.
313
314 For comparison all parts of the description, that look like a
315 category value, are removed first. The remaining text will be
316 compared. If this is similar at the value of the next option
317 (regarding the Levinshtein-Distance algorithm) then it will be
318 accepted as equal.
319
320 - "Min. match in %:"
321 The needed minimum match of descriptions in percent.
322
323 - Compare categories:
324 With the button 'setup' you can also specify which categories
325 should be compared. As with subtitles an event is different if it
326 has no according category value.
327
328 - Priority, lifetime, margins for start and stop:
329 Each search timer can have its own settings for these parameters.
330 Defaults can be adjusted in the plugins setup.
331
332 - VPS:
333 If set to yes, VPS is used, but only, if activated in VDR's setup
334 menu and if the broadcasting has VPS information.
335
336 - Auto delete:
337 to automatically delete a search timer if the following is true:
338
339 * after x recordings, or
340 * after x days after the first recording
341
342 Only complete recordings are counted. The deletion is executed
343 directly after the correspondig recording
344
345 To toggle the flag 'Use as search timer' without editing the search
346 entry you can use the key '2'. This will call directly the second
347 command of the command menu.
348
349 1.2.2 Menu search results
350
351 This menu displays the search results. A 'T' lets you know, that there
352 is already a timer for the event. A 't' means that there's only a
353 partial timer for it, as in standard schedules menu.
354
355 1.3 Extended 'now' and 'next' and favorites
356 By setup, one can add up to 4 additional times to extend the green
357 button, e.g. 'afternoon', 'prime time', 'late night'. Times, that are
358 already passed, are skipped (you will not get 'afternoon' at evening)
359 with the exception that a time will be displayed for the next day, if
360 it is less then 20h in the future. In these menus you can shift the
361 currently displayed time by pressing FastRew or FastFwd to move back
362 and forward in time. If you don't have these keys on your remote, you
363 can access this function by pressing '0' to toggle the green and yellow
364 button to '<<' and '>>'. This toggling can be adjusted by setup.
365
366 You can display a progress bar in 'now' and 'next'. When using
367 text2skin you should use the setup option "text2skin" in the setup
368 option "Show progress in 'Now'"/Show progress in 'Next'" (the setting
369 'graphical' may also work with text2skin, but this depends on the
370 selected skin).
371
372 Furthermore you can enable in the setup an favorites list. You can
373 configure your searchtimers ("Use in favorite list") to display their
374 results in you favorite list. This list display event in the next 24
375 hours ordered by time.
376
377 1.4 Menu setup
378 1.4.1 General
379
380 - Hide main menu entry:
381 This hides the main menu entry 'search'. Attention: when the plugin
382 is assigned to key 'green' then hiding the plugin will give you
383 VDR's standard schedule menu (see below to avoid this).
384
385 - Main menu entry:
386 If not hidden, the name of main menu entry can be set here. Default
387 is 'Program guide'. Note: If you set it to something different from
388 the default then the main menu entry is no longer dependent on the
389 OSD language. Setting it back to default or empty restores this
390 behavior again.
391
392 - Start menu:
393 Select the starting menu 'Schedules' or 'Now'
394
395 1.4.2 EPG menus
396
397 - Ok key:
398 Choose here the behavior of key 'Ok'. You can use it to display the
399 summary or to switch to the corresponding channel. Note: the
400 functionality of key 'blue' (Switch/Info/Search) depends on this
401 setting.
402
403 - Red key:
404 Select if you like to have Standard ('Record') or 'Commands' as
405 assignment for key 'red'.
406
407 - Blue key:
408 select if you like to have Standard ('Switch') or 'Search' as
409 assignment for key 'blue'.
410
411 - Show progress in 'Now':
412 In the menu 'what's on now' you can display a progress bar, that
413 displays the progress of the current item. When using text2skin you
414 should use the setup option "text2skin" (the setting 'graphical'
415 may also work with text2skin, but this depends on the selected
416 skin).
417
418 - Show channel numbers:
419 Select this if you like to have a leading channel number before
420 each item in the EPG menus.
421
422 - Show channel separators:
423 Display channel group separators between channel in the menus
424 'Overview now',...
425
426 - Show day separators:
427 Display a day separator between events on different days in the
428 schedule menu.
429
430 - Show radio channels:
431 Also list radio channels.
432
433 - Limit channels from 1 to:
434 If you have a large channel set you can speed up things when you
435 limit the displayed channels with this setting. Use '0' to disable
436 the limit. If the current channel is above the limit, the limit is
437 ignored and all channels will be displayed again.
438
439 - 'One press' timer creation:
440 If set to 'yes' a timer is immediately created when pressing
441 'Record' as introduced in vdr-1.3.38, else the timer edit menu is
442 displayed.
443
444 - Show channels without EPG:
445 Display channels without EPG to allow switching or create a timer.
446
447 - Time interval for FR/FF [min]:
448 In the menus 'now', 'next', 'user def 1', ... you can shift the
449 displayed time by pressing FastRew, FastFwd on your remote control.
450 Adjust the amount of minutes to jump here.
451
452 - Toggle Green/Yellow:
453 If you don't have FastRew, FastFwd on your remote control, set this
454 to yes. When pressing '0' in the menus, this toggles the assignment
455 of the color keys and assigns e.g. '<<' and '>>' to 'green' and
456 'yellow'.
457
458 - Show favorites menu:
459 A favorites menu can display a list of your favorite broadcasts.
460 Enable this if you want an additional menu besides 'Now' and
461 'Next'. You can choose between displaying this menu before or after
462 the menus with user-defined times. Any search can be used as a
463 favorite. You only have to set the option 'Use in favorites menu'
464 when editing a search.
465
466 - for the next ... hours:
467 This value lets you adjust the timespan used to display the
468 favorites.
469
470 1.4.3 User-defined EPG times
471
472 - Use user time 1..4:
473 Add up to 4 user-defined times besides 'now' and 'next'.
474
475 - Description:
476 Name of the user-defined time, e.g. 'Afternoon', 'Prime time',
477 'Late night'.
478
479 - Time:
480 The associated time of the user-defined time.
481
482 1.4.4 Timer programming
483
484 - Use VDR's timer edit menu:
485 When programming a standard timer epgsearch uses an extended menu,
486 that also supports a directory item, user defined weekday selection
487 and subtitle completion. If you are using a patched version of VDR,
488 that also has an extended timer edit menu and like to use this menu
489 rather than epgsearch's then set this option to 'Yes'.
490
491 - Default recording directory:
492 This entry will be used in standard timer programming as default
493 directory. You can also use EPG category variables (e.g. 'My
494 Movies~%Category%~%Genre%'). When the timer edit menu is launched
495 epgsearch tries to replace all variables with the values found in
496 the description of the event. If not all variables could be
497 replaced then the directory item is left blank.
498
499 - Add episode to manual timers:
500 When manually adding a timer epgsearch can automatically add the
501 episode name to the timer file resulting in a sub-folder for the
502 later recording, that is named with the episode name. Choose here
503 how this should be done. 'smart' tries to recognize if this makes
504 sense. Therefore it checks the length of the event and skips the
505 subtitle if the event has more than 80min.
506
507 - Default timer check method:
508 Manual timers can be checked for EPG changes. Here you can setup
509 the default check method for each channel. The following methods
510 exist:
511 * no check
512 * by event ID: checks by an event ID supplied by the channel
513 provider.
514 * by channel and time: check by the duration match.
515
516 Not all channels provide a proper event ID, so you can setup the
517 default for each channel here. When programming a manual timer,
518 this default use used in epgsearch's own timer edit menu.
519
520 1.4.5 Search and search timers
521
522 - Use search timers:
523 If yes, the plugin makes a background scan of the EPG and adds
524 timers if it finds matching entries. This applies only to searches
525 that are marked with 'use as search timer'.
526
527 - Update interval:
528 The update interval of the background scan for search timers in
529 minutes.
530
531 - SVDRP port:
532 If you are using a SVDRP port other than 2001 then enter this here
533 to get the search timers working.
534
535 - Default Priority:
536 Default priority of generated timers.
537
538 - Default Lifetime:
539 Default lifetime of generated timers.
540
541 - Margin at start/stop:
542 Default margins of generated timers.
543
544 - No announcements when replaying:
545 suppress event announcements while any replay is active.
546
547 - Recreate timers after deletion:
548 epgsearch remembers by default which timers where already created
549 by search timers and will not recreate them if they were removed.
550 To disable this behaviour set this to 'Yes'.
551
552 - Check if EPG exists for ... [h]:
553 If you get EPG content from external providers it is possible, that
554 something fails and some recordings are skipped because of the
555 missing EPG. With this function one can check if EPG content exists
556 for the next ... hours. With '0' the check is disabled.
557
558 - "Warn by OSD:"
559 Set this to 'Yes' to get warned via OSD.
560
561 - "Warn by mail:"
562 Set this to 'Yes' to get warned by email. Please configure the
563 email account in 'email notification'
564
565 - "Channel group to check:"
566 select hier the channel group to check. Perhaps you have to create
567 it before in 'channel groups'
568
569 - Ignore Pay-TV channels:
570 Set this to 'Yes' if you don't want to have events from Pay-TV
571 channels when searching for a repeat.
572
573 - Search templates:
574 Here you can manage search templates which can be used when
575 creating a search.
576
577 - Blacklists:
578 Here you can manage blacklists which can be used to suppress
579 unwanted events within a search.
580
581 - Channel groups:
582 Here you can setup channel groups (e.g. Sport channels, Pay-TV
583 channels) that can be used as criterion in searches. The same can
584 be done in the search edit menu.
585
586 Important: if you get your EPG from external sources make sure that
587 search timer updates are disabled while your EPG is updated. The reason
588 for this is that epgsearch will remove timers without events assigned
589 to them. This situation can exist while the new EPG is feeded to VDR. A
590 simple way to disable search timer updates is to use the SVDRP command
591 SETS in your EPG update script:
592
593 svdrpsend.pl plug epgsearch SETS off
594
595 <your EPG update script>
596
597 svdrpsend.pl plug epgsearch SETS on
598
599 1.4.6 Timer conflict checking
600
601 - Ignore below priority:
602 If a timer will fail with a priority below the given value, you
603 won't get an OSD message about this and the conflict will be
604 classified as 'not relevant' in the conflicts overview.
605
606 - Ignore conflict duration less ... min.:
607 If a conflict will last only the given minutes it will not produce
608 an OSD message and the conflict will be classified as 'not
609 relevant' in the conflicts overview.
610
611 - Only check within next ... days:
612 Here you can specify the day range that should be used for the
613 conflict check.
614
615 - After each timer programming:
616 This performs a conflict check after each manual timer programming
617 and - if the new/modified timer is involved in a conflict - pops up
618 an OSD message about it.
619
620 - "When a recording starts:
621 Set this to 'yes' if the conflict check should be performed when a
622 recording starts. In the case of a conlfict you get immediately a
623 message that informs you about it. The message is only displayed
624 if the conflict is within the next 2 hours.
625
626 - After each search timer update:
627 Specify here if you want to have a conflict check after each search
628 timer update. If set to 'No':
629
630 - every ... minutes:
631 performs a conflict check in the background every ... minutes and
632 informs about relevant conflicts via OSD. Set this to '0' to
633 disable this feature.
634
635 - if conflicts within next ... minutes:
636 - every ... minutes:
637 if you like to have a more frequent check and OSD notification
638 when a conflict appears within the given time, use this
639 feature.
640
641 - Avoid notification when replaying:
642 Set this to 'yes' if the don't want to get OSD messages about
643 conflicts if you currently replay something. Nevertheless messages
644 will be displayed if
645 the first upcoming conflict is within the next 2 hours.
646
647 Also have a look at epgsearch(4), section 'Working with the timer
648 conflict menu'.
649
650 1.4.7 Email notification
651
652 Please make sure, that 'sendEmail.pl' is in the path of your
653 executables and that the 'epgsearchupdmail.templ' and
654 'epgsearchconflmail.templ' exists in epgsearch's configurations
655 directory!
656
657 - Search timer notification:
658 Enable this, if you want to get an email notification, when the
659 search timer background thread has
660
661 - created a new timer
662 - modified an existing timer
663 - deleted a timer, that was void because of EPG changes or other user
664 actions.
665
666 (Also requires 'Use search timers' in the search timer setup to be
667 activated.)
668
669 - Time between mails [h]:
670 For search timer notifications one can set the minimum distance in
671 hours between the mails. As soon as this time has elapsed a new
672 mail is sent after the next search timer update. A value of '0'
673 means no delay and will cause immediate mail delivery.
674
675 - Timer conflict notification:
676 Enable this, if you want to get an email notification about timer
677 conflicts. The notification will only include 'relevant' conflicts
678 as specified in the timer conflict setup. epgsearch will always
679 send a new notification if there is any change in the current
680 conflicts.
681
682 (Also requires 'After each search timer update' or 'every ...
683 minutes' in the conflict check setup to be activated.)
684
685 - Send to:
686 The mail adress of the recipient. Note: Some providers (like Arcor)
687 don't allow the same adresse for sender and recipient.
688
689 - Mail method:
690 You can choose between:
691
692 - sendEmail.pl: this is a simply script shipped with epgsearch, that allows
693 mail delivery also on systems without a configured mail server. Please
694 copy it to your $PATH
695 - sendmail: requires a properly configured mail system
696
697 - Email address:
698 Your full(!) email account address to be used for sending the mail.
699
700 - SMTP server:
701 The name of your SMTP server to be used for sending the mails.
702
703 - Use SMTP authentication:
704 Select 'yes' if your account needs authentication to send mails.
705
706 - AUTH user:
707 Specify the accounts username if your account needs authentication.
708
709 - AUTH password:
710 Specify the accounts password if your account needs authentication.
711 Note: The password is saved as plain text. You have to make sure on
712 your own that your system is safe and no VDR configurations files
713 are visible to non authorized persons.
714
715 After the account setup, check if it works with 'Test'. If you are
716 using 'sendEmail.pl' for mail delivery, there should be something like
717 'Email sent successfully' at the end of the test output. The test
718 function is not available for method 'sendmail'.
719
720 Also have a look at epgsearch(4), section 'Email notifications'.
721
723 This is quite the same as VDRAdmin's auto-timers, but needs no external
724 software. When you create a search, you can give it an option to use it
725 as search timer. Now the plugin scans EPG entries in certain update
726 intervals (->setup) in the background and creates timers if there are
727 matching entries. If you don't like to get a new timer, but only want
728 to be informed about the event set 'Announce only (no timer)' to yes.
729 Since these search timers are quite useful for serials, you can set the
730 option 'serial recording' in a search, which creates timers whose
731 recordings are stored in a folder with the serials name and whose
732 entries are named with the episode name. If there is no episode name,
733 the plugin names the recording with a date/time string.
734
735 To use search timers, you also have to activate them in the plugins
736 setup. Also edit the SVDRP port, if you are not using the default
737 2001.
738
739 If you want to trigger a background scan manually simply
740
741 touch /etc/vdr/plugins/epgsearch/.epgsearchupdate
742
743 This can also be part of your shutdown script. (Add here a sleep
744 afterwards to give the plugin the time to finish the scan.)
745
746 For more info about searchtimers please refer to epgsearch(4),
747 'Description of the search process' and 'How do Search Timers work?'
748
749 2.1 'Avoid repeats' - internals
750 This section explains the feature 'Avoid repeats' for a search timer.
751 Sometimes one cannot avoid double recordings of an event only by
752 setting the corresponding search criterions.
753
754 Therefore the feature 'avoid repeats' tries to check before creating a
755 timer, if the same event was already recorded in the past or if there
756 is a timer that records the same event. If so, there will be no new
757 timer for the event.
758
759 2.2 How do we compare two events?
760 To check if two events are the same there are many possible settings
761 for a search timer. You can choose the title, subtitle, description or
762 extended EPG categories within the description of an event to be
763 compared with the elements of another event.
764
765 This comparison is always done case-sensitive and for the whole term.
766 But the description of an event makes an exception of this. First all
767 text within the description will be truncated that looks like an
768 extended category entry, e.g. 'Rating: tip'. An extended category entry
769 is a line of text beginning with max. 40 signs, followed by ':' and
770 ending with max. 60 further signs. The reason for this cutting is that
771 some categories like the rating of an event are not part of the
772 description of the repeat of the same event.
773
774 The remaining text will now be compared by length. If the difference is
775 bigger then 90%, then we rate the description of the two events as
776 different. If not, we apply the Levinsthein-Distance-Algorithm (LD),
777 which makes a fuzzy text comparison. We accept the description of the
778 events as equal, if LD returns a match of more then 90%. Since LD is
779 quite runtime intensive (O(mn)), you should not choose 'compare
780 description' as the only comparison criterion, but combine it always
781 with other criterions.
782
783 2.3 How and when do we compare?
784 As already mentioned each search timer update checks search timers with
785 this feature for recordings in the past or an already existing timer
786 for the same event.
787
788 To remember past recordings epgsearch stores their info in the file
789 epgsearchdone.data. You can have a look at the contents of this file
790 calling 'show recordings done' in the 'actions' of the searches menu.
791 This file only stores info about recordings that are complete, i.e.
792 that started and stopped just in time. So a broken recording will not
793 be stored in this file and epgsearch will automatically try to record
794 the next repeat, if there is any.
795
796 How to use it?
797
798 As you see, the whole feature depends on the quality of the EPG. After
799 creating such a search timer, you should first check if it does what is
800 intended. Therefore the menu of search results has an additional mode
801 for the key 'blue' named 'Timer preview'. Here you can see, what timers
802 the next update would create. Existing timers are labeled with 'T',
803 future timers with 'P'.
804
805 Hint: If the programming results in a conflict simply disable the
806 conflicting timer in the timers menu. The next search timer update,
807 will try to program a different timer for the same event, if it exists.
808
809 When it works not correctly :-)
810
811 To get a better control of the programming or not-programming of the
812 timers when using this feature a log file was introduced. When starting
813 epgsearch with the command line option '-v n' where n is the log level
814 than you get additional info in the file epgsearch.log. Available log
815 levels are 0 (no logging) to 3 (extended logging). See also the manual
816 for the command line options.
817
819 See epgsearch(4).
820
822 Some EPG providers deliver additional EPG information like the type of
823 event, the video and audio format, cast,...
824
825 Using tvm2vdr or epg4vdr you can import this into vdr. To use this
826 information with search timers one has to configure it with the file
827 epgsearchcats.conf in epgsearchs config directory. The format of the
828 file is as follows:
829
830 ID|category name|name in menu|values separated by ','(option)|search mode(option)
831
832 - 'ID' should be a unique positive integer
833 (changing the id later on will force you to re-edit your search timers!)
834 - 'category name' is the name as delivered by the EPG provider, e.g. 'Genre'
835 - 'name in menu' is the name displayed in epgsearch.
836 - 'values' is an optional list of possible values
837 - 'search mode' specifies the search mode:
838 text comparison:
839 0 - the whole term must appear as substring
840 1 - all single terms (delimiters are ',', ';', '|' or '~')
841 must exist as substrings. This is the default search mode.
842 2 - at least one term (delimiters are ',', ';', '|' or '~')
843 must exist as substring.
844 3 - matches exactly
845 4 - regular expression
846 numerical comparison:
847 10 - less
848 11 - less or equal
849 12 - greater
850 13 - greater or equal
851 14 - equal
852 15 - not equal
853
854 Sample files for epgsearchcats.conf are delivered with the plugin in
855 the directory 'conf'.
856
857 Simply copy the one that fits for you to epgsearchs configurations
858 directory filename epgsearchcats.conf and then have a look to the
859 search timers edit menu (after a restart of VDR).
860
861 Since setting up a new epgsearchcats.conf is a lot of work, I've added
862 a small tool 'createcats', that makes the biggest part of the job. It
863 should have been compiled with the plugin and exists in the sources
864 directory.
865
866 See createcats(1) for information about how to use it.
867
868 Internals: epgsearch scans the summary of an event for the category
869 name followed by ': ' for all categories that have a corresponding
870 value set in the search timer. The search is case sensitive regarding
871 the category name as also the value.
872
874 To use this plugin as a replacement for the default green key, simply
875 put the line
876
877 Green @epgsearch
878
879 in your keymacros.conf. If you don't like to get another plugin entry
880 in your main menu, first hide it by setup. Then you could use my
881 launcher-plugin and put the line
882
883 Green @launcher x
884
885 in your keymacros.conf, where x is the position of the Epgsearch plugin
886 within launchers menu listing.
887
888 Attention: Hiding the plugin without using the launcher plugin or other
889 patches that enable calling hidden plugins will show the standard
890 schedules menu when you press the green key. This is not needed anymore
891 after VDR >= 1.3.32.
892
893 Another approach is using a patch to VDR that replaces vdr's standard
894 schedule menu with epgsearch (vdr-replace-schedulemenu.diff.gz in the
895 patches subdir, thanks to the author Uwe/egal@vdrportal). When using
896 this patch the entry should look like
897
898 Gree Schedule
899
900 This patch is already included in some patch collections, like the
901 Bigpatch.
902
904 epgsearch delivers 2 'mini'-plugins. Both require an installed
905 epgsearch (but epgsearch can be hided in the main menu):
906
907 - epgsearchonly:
908 For those who only want to use the search feature and/or search
909 timers or simply want to have a separate main menu entry for the
910 search feature. This plugin creates a main menu entry 'Search'
911 which calls epgsearch search menu. Activation in VDR start script
912 with "-Pepgsearchonly".
913
914 - conflictcheckonly:
915 The timer conflict check can also have its own main menu entry
916 which displays epgsearch conflict overview menu. It has a setup
917 option to display an information about the last check directly in
918 its main menu entry. Activation in VDR start script with
919 "-Pconflictcheckonly".
920
921 Have fun!
922
923 Christian Wieninger
924
926 See epgsearch(4) or read online
927
928 <http://winni.vdr-developer.org/epgsearch/README.DE>
929
930 <http://winni.vdr-developer.org/epgsearch/README>
931
932 <http://winni.vdr-developer.org/epgsearch/MANUAL>
933
935 "epgsearch.conf(5)", "epgsearchcats.conf(5)", "epgsearchcmds.conf(5)",
936 "epgsearchdirs.conf(5)", "epgsearchmenu.conf(5)",
937 "epgsearchuservars.conf(5)", "epgsearchdone.data(5)",
938 "epgsearchswitchtimer.conf(5)", "epgsearchblacklists.conf(5)",
939 "epgsearchchangrps.conf(5)"
940
942 epgsearch.conf
943
944 Searchtimers. See "epgsearch.conf(5)".
945
946 epgsearchcats.conf
947
948 Categories, advanced epg. See "epgsearchcats.conf(5)".
949
950 epgsearchcmds.conf
951
952 EPG-commands, like the commands in commands.conf. See
953 "epgsearchcmds.conf(5)".
954
955 epgsearchdirs.conf
956
957 Pre-defined patches which can be selected while editing an searchtimer.
958 See "epgsearchdirs.conf(5)".
959
960 epgsearchmenu.conf
961
962 Configuration of the OSD menu layout. See "epgsearchmenu.conf(5)".
963
964 epgsearchuservars.conf
965
966 User defined variables. See "epgsearchuservars.conf(5)".
967
968 epgsearchdone.data
969
970 The done-data. See "epgsearchdone.data(5)".
971
972 epgsearchswitchtimers.conf
973
974 The switchtimers. See "epgsearchswitchtimer.conf(5)".
975
976 epgsearchblacklists.conf
977
978 The blacklist. See "epgsearchblacklists.conf(5)".
979
980 epgsearchchangrps.conf
981
982 The channelgroups. See "epgsearchchangrps.conf(5)".
983
984 epgsearchtemplates.conf
985
986 Templates for searchtimers. See "epgsearchtemplates.conf(5)".
987
989 Mike Constabel <epgsearch (at) constabel (dot) net>
990
992 Bugreports (german):
993
994 <http://www.vdr-developer.org/mantisbt/>
995
996 Mailinglist:
997
998 <http://www.vdr-developer.org/mailman/listinfo/epgsearch>
999
1001 Copyright (C) 2004-2010 Christian Wieninger
1002
1003 This program is free software; you can redistribute it and/or modify it
1004 under the terms of the GNU General Public License as published by the
1005 Free Software Foundation; either version 2 of the License, or (at your
1006 option) any later version.
1007
1008 This program is distributed in the hope that it will be useful, but
1009 WITHOUT ANY WARRANTY; without even the implied warranty of
1010 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1011 General Public License for more details.
1012
1013 You should have received a copy of the GNU General Public License along
1014 with this program; if not, write to the Free Software Foundation, Inc.,
1015 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Or, point
1016 your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1017
1018 The author can be reached at cwieninger@gmx.de
1019
1020 The project's page is at http://winni.vdr-developer.org/epgsearch
1021
1022 The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-
1023 Digest Algorithm.
1024
1025
1026
1027perl v5.10.0 2010-02-20 epgsearch(1)