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

NAME

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

OVERVIEW

9       Since the README get bigger and bigger this man page shall be used to
10       explain some things in detail. So it's not really a manual, but an
11       extended README.
12

CONTENT

14        1.  Using variables in the directory entry of a search timer
15        2.  The format of epgsearch.conf
16        3.  Description of the search process
17        4.  How do Search Timers work?
18        5.  How to trigger a search timer update?
19        6.  The sources of the 'Select directory' menu
20        7.  Language dependent commands for EPG
21        8.  Usage from other plugins or scripts
22        9.  SVDRP interface
23        10. Customizing the EPG menus
24        11. Working with the timer conflict menu
25        12. User defined variables
26        13. Email notifications
27        14. The conf.d subdirectory
28

1. Using variables in the directory entry of a search timer

30       If you are using extended EPG information, you can use variables as
31       part of a directory entry of a search timer. These variables always
32       have the form '%variable%'. The name of a variable corresponds with the
33       internal name of an extended EPG info, as specified in the file
34       epgsearchcats.conf (samples can be found in subdirectory 'conf').
35       Example:
36
37        1|Category|Kategorie|Information,Kinder,Musik,Serie,Show,Spielfilm,Sport|3
38
39       The category with ID 1 has the internal name 'Category'. So you could
40       use it with '%Category%'. The names are not case sensitive. Sample
41       directory entries could look like this:
42
43        My Movies~%Category%
44        Childrens Movies~%category%
45        %CATEGORY%~%genre%
46
47       There are also three other variables: %Title%, %Subtitle% and %chlng%.
48       If you don't use %Title%, the title is always automatically appended to
49       the directory entry, when a timer will be created. If you set 'serial
50       recording' to 'yes' in your search timer then also the subtitle will be
51       automatically appended. So the directory entry
52
53        %Category%~%Genre%~%Title%~%Subtitle%
54
55       is the same as
56
57        %Category%~%Genre%
58        (with 'serial recording' set to 'yes').
59
60       The %chlng% variable gets replaced with the name of the channel.
61
62       Attention: Automatically appending title and subtitle will not be done,
63       if you use the variables %Title% or %Subtitle% in the directory entry.
64       This allows one to form directory entries like this one:
65
66        %Category%~%Genre%~%Title%~%Episode%~%Subtitle%
67
68       There are also the following search variables:
69
70        %search.query% that will be replaced with the query of the search timer
71        %search.series% that is '1', if the search has its 'Series recording' flag set, else '0'.
72
73       See also "epgsearchuservars.conf(5)".
74

2. The format of epgsearch.conf

76       Due to some new features there was a change in the format. The format
77       is now signed with a comment in the first line. The field delimiter is
78       ':':
79
80         1 - unique search timer id
81         2 - the search term
82         3 - use time? 0/1
83         4 - start time in HHMM
84         5 - stop time in HHMM
85         6 - use channel? 0 = no,  1 = Interval, 2 = Channel group, 3 = FTA only
86         7 - if 'use channel' = 1 then channel id[|channel id] in vdr format,
87             one entry or min/max entry separated with |, if 'use channel' = 2
88             then the channel group name
89         8 - match case? 0/1
90         9 - search mode:
91              0 - the whole term must appear as substring
92              1 - all single terms (delimiters are blank,',', ';', '|' or '~')
93                 must exist as substrings.
94              2 - at least one term (delimiters are blank, ',', ';', '|' or '~')
95                  must exist as substring.
96              3 - matches exactly
97              4 - regular expression
98              5 - fuzzy searching (specify tolerance in parameter 42, not available
99                  for EPG categories)
100        10 - use title? 0/1
101        11 - use subtitle? 0/1
102        12 - use description? 0/1
103        13 - use duration? 0/1
104        14 - min duration in minutes
105        15 - max duration in minutes
106        16 - use as search timer? 0/1/2 (with 2 one can specify time margins in
107             parameter 48/49 where the search timer is active)
108        17 - use day of week? 0/1
109        18 - day of week (0 = Sunday, 1 = Monday...;
110             -1 Sunday, -2 Monday, -4 Tuesday, ...; -7 Sun, Mon, Tue)
111        19 - use series recording? 0/1
112        20 - directory for recording
113        21 - priority of recording
114        22 - lifetime of recording
115        23 - time margin for start in minutes
116        24 - time margin for stop in minutes
117        25 - use VPS? 0/1
118        26 - action:
119              0 = create a timer
120              1 = announce only via OSD (no timer)
121              2 = switch only (no timer)
122        27 - use extended EPG info? 0/1
123        28 - extended EPG info values. This entry has the following format
124             (delimiter is '|' for each category, '#' separates id and value):
125             1 - the id of the extended EPG info category as specified in
126                 epgsearchcats.conf
127             2 - the value of the extended EPG info category
128                 (a ':' will be translated to "!^colon^!", e.g. in "16:9")
129        29 - avoid repeats? 0/1
130        30 - allowed repeats
131        31 - compare title when testing for a repeat? 0/1
132        32 - compare subtitle when testing for a repeat? 0=no/1=yes/2=yes-if present
133        33 - compare description when testing for a repeat? 0/1
134        34 - compare extended EPG info when testing for a repeat?
135             This entry is a bit field of the category IDs.
136        35 - accepts repeats only within x days
137        36 - delete a recording automatically after x days
138        37 - but keep this number of recordings anyway
139        38 - minutes before switch (if action = 2)
140        39 - pause if x recordings already exist
141        40 - blacklist usage mode (0 none, 1 selection, 2 all)
142        41 - selected blacklist IDs separated with '|'
143        42 - fuzzy tolerance value for fuzzy searching
144        43 - use this search in favorites menu (0 no, 1 yes)
145        44 - number of the search menu template to use (only available if multiple
146             search result templates are defined in epgsearchmenu.conf)
147        45 - auto deletion mode (0 don't delete search timer, 1 delete after given
148             count of recordings, 2 delete after given days after first recording)
149        46 - count of recordings after which to delete the search timer
150        47 - count of days after the first recording after which to delete the search
151             timer
152        48 - first day where the search timer is active (see parameter 16)
153        49 - last day where the search timer is active (see parameter 16)
154        50 - ignore missing EPG categories? 0/1
155        51 - unmute sound if off when used as switch timer
156        52 - the minimum required match in percent when descriptions are compared to avoid repeats (-> 33)
157
158       A ':' in the search term or the directory entry will be translated in a
159       '|'. If a '|' exists in the search term, e.g. when using regular
160       expressions, it will be translated to "!^pipe^!" (I know it's ugly ;-))
161
162       See also "epgsearch.conf(5)".
163

3. Description of the search process

165       First, for each broadcasting a search text divided by '~' is created,
166       depending on the settings of 'Use title', 'Use subtitle' and 'Use
167       description':
168
169        title~subtitle~description
170
171       If "Match case" is not set, the search text and the search term are
172       transformed to lower case.  Now depending on the search mode, the
173       search term will be looked up in the search text:
174
175       - 'Phrase' matches
176           if the search term is found anywhere in the search text.
177
178       - 'at least one word', 'all words'
179           first the search term will be split in single words. Delimiters are
180           a blank and the characters ',' ';' '|' '~'.
181
182           Then we check if at least one or all words appear in the search
183           text.
184
185       - 'match exactly'
186           matches if search term and search text are identical.
187
188       - 'regular expression'
189           the search is done with a regular expression. You don't need a
190           leading and trailing '/' in your search term.  Two standards of
191           regular expression are supported: extended POSIX and Perl
192           compatible regular expressions (PCRE) (see INSTALL).
193
194       If the search was successful until now, the other criterions (start
195       time, duration, week day) are checked.
196

4. How do Search Timers work?

198       With each update, the plugin first sorts the search timers by timer
199       priority (descending) and search term and then searches for new matches
200       of your search timers. If a new match is found then a new timer is
201       created.  For serial recordings, the subtitle is appended to the
202       recording directory. Many providers deliver the subtitle just 1-2 days
203       before the event. The plugin uses then a date/time string for the
204       subtitle, but replaces this one later if the subtitle is present.
205
206       Start and end times of a broadcasting often vary a little bit. To avoid
207       getting many different timers for the same event, the plugin checks
208       before adding a new timer, if there is one, that has start and end
209       times which only differ by a maximum of 10 minutes (or the events
210       duration if this is less then 10 minutes). If so, the present timer is
211       modified, else a new timer is created. If the timer was set to inactive
212       there will be no update. Also manually corrected priority or lifetime
213       will not be changed when updating.
214
215       If you have set 'Announce only (no timer)' to yes, no timer is created.
216       Instead you get an OSD message about the event. This message is
217       displayed at each scan, but only if there is no timer for the event.
218

5. How to trigger a search timer update?

220       the update of search timers runs in its own thread. There are several
221       ways to trigger it:
222
223       - automatically
224           after VDR starts there is always an update (after a few seconds).
225           After this, the setup option 'Update interval' tells epgsearch when
226           the next update should be done repeatedly (in minutes).
227
228       - manually extern
229           the thread observes the file '.epgsearchupdate' in the plugins
230           config directory. When you
231
232            touch /path_to_file/.epgsearchupdate
233
234           this will also trigger an update. So this is a simple solution to
235           make an update e.g. by a script.
236
237       - manually intern
238           calling actions or pressing '3' in the menu of searches asks also
239           for an update.
240
241       - from other plugins
242
243       there's a service 'Epgsearch-updatesearchtimers-v1.0' that can be used
244       with the service interface of VDR from other plugins with the option to
245       inform via OSD when the update has finished
246

6. The sources of the 'Select directory' menu

248       This menu displays directories, that can be used for search timers or
249       ordinary timers. The items displayed are read from the following
250       sources:
251
252          * current recording directories
253          * current timer directories
254          * directories used in search timers
255          * directories specified in F<epgsearchdirs.conf>,
256            see C<epgsearchdirs.con(5)>
257          * entries in VDR's folders.conf
258
259       The menu merges theses directories and displays only distinct
260       directories. With key 'yellow' one can change the depth of the
261       directories shown. If there are items, that contain category variables
262       like '%genre%', these entries are always shown before any other
263       directories. They are also not level dependent, but are always shown
264       with their full directory.
265
266       If this menu is called from the timer edit menu and an item is selected
267       that contains the variables "%title%" or "%subtitle" then the 'file'
268       item of the timer gets cleared, since title or subtitle already exist
269       in the 'directory' item.  This list can also be accessed via the SVDRP
270       command 'LSRD'.
271

7. Language dependent commands for EPG

273       If you like to have a language dependent list of commands simply
274       translate your present epgsearchcmds.conf to your preferred OSD
275       language and store it with the filename epgsearchcmds-XXX.conf, where
276       XXX is the language code from i18n.c:
277
278         { "eng,dos",
279           "deu,ger",
280           "slv",
281           "ita",
282           "dut,nla,nld",
283           "por",
284           "fra,fre",
285           "nor",
286           "fin,smi",
287           "pol",
288           "esl,spa",
289           "ell,gre",
290           "sve,swe",
291           "rom,rum",
292           "hun",
293           "cat,cln",
294           "rus",
295           "hrv",
296           "est",
297           "dan",
298         }
299
300       If there are more codes for one language (e.g. "deu,ger") choose one of
301       them. If there is no language dependent file, epgsearch loads the file
302       epgsearchcmds.conf.
303
304       See also "epgsearchcmds.conf(5)".
305

8. Usage from other plugins or scripts

307       Searching the EPG and other functionality can be used by other plugins
308       or scripts. There are two approaches:
309
310   8.1. File-based (intended for use in scripts)
311       Therefore simply create the file '.epgsearchrc' in the plugins config
312       directory with the following lines in it:
313
314        Search=your search term
315        Searchmode=x  // 0=phrase, 1=and, 2=or, 3=regular expression
316        ChannelNr=x   // add this line, to search on a specific channel
317        UseTitle=x    // 1(default) or 0
318        UseSubtitle=x // 1(default) or 0
319        UseDescr=x    // 1(default) or 0
320
321       Then call Epgsearch via svdrpsend (you must have assigned a key to it),
322       e.g.
323
324        svdrpsend HITK green
325
326       At startup Epgsearch will look for this file and give you the search
327       results for your search, if it exists. After that the file is removed.
328
329       A sample script recrep.sh, that searches for the repeats of a recording
330       exists in the scripts subdirectory of Epgsearch.
331
332   8.2. via Plugin-Interface (intended for use in plugins)
333       A plugin can directly call two functions of epgsearch with only some
334       lines of source code:
335
336        - searching the EPG for some criteria and display the result list
337        - extended timer edit menu
338
339       I have added a quick and dirty dummy plugin
340       (source/vdr-epgsearchclient-0.0.1.tgz), that demonstrates the usage.
341

9. SVDRP interface

343       epgsearch implements a SVDRP interface, that can be accessed for
344       example like this
345
346        svdrpsend PLUG epgsearch LSTS
347
348       the following commands are available:
349
350   search management:
351        * 'LSTS [ID]' to list all searches, or the one with the passed ID
352          (format is the same as epgsearch.conf)
353        * 'NEWS <settings>' to add a new search
354          REMARK: the value of element ID is ignored. epgsearch will always
355          assign the next free ID
356        * 'DELS <ID>' to delete the search with ID
357        * 'EDIS <settings>' to modify an existing search
358        * 'UPDS [OSD]' to update the search timers. Passing the optional keyword
359          'OSD' pops up an OSD message after the update has finished.
360        * 'MODS ID ON|OFF' turns on/off the option 'Use as search timer'.
361        * 'UPDD' to reload the file epgsearchdone.data, e.g. after an
362          external tool has modified it.
363        * 'SETS <ON|OFF>' to temporarily activate or cancel the search timer background
364          thread.
365        * 'FIND <settings>' for searching the EPG
366          input is the same as with 'NEWS'. output is a list of found events formatted
367          as 'NEWT' lines. So they can be immediately used to create a new timer for
368          an event.
369        * 'QRYS < ID(s) >' to get the results for a search with the given
370          ID. Multiple IDs can also be passed and have to be separated with '|'.
371          The results are formatted like this:
372
373          search ID    : // the ID of the corresponding search timer
374          event ID     : // VDR event ID
375          title        : // event title, any ':' will be converted to '|'
376          episode name : // event short text, any ':' will be converted to '|'
377          event start  : // event start in seconds since 1970-01-01
378          event stop   : // event stop in seconds since 1970-01-01
379          channel      : // channel ID in VDR's internal representation (e.g. 'S19.2E-1-1101-28106')
380          timer start  : // timer start in seconds since 1970-01-01 (only valid if timer flag is > 0)
381          timer stop   : // timer stop in seconds since 1970-01-01 (only valid if timer flag is > 0)
382          timer file   : // timer file (only valid if timer flag is > 0)
383          timer flag   : // 0 = no timer needed, 1 = has timer, 2 timer planned for next update)
384        * 'QRYS <settings>' to get the results for a search with the given search
385          settings.
386        * 'QRYF [hours]' to get the results for the favorites menu, see QRYS for
387          result format. The optional parameter specifies the number of hours to
388          evaluate and defaults to 24h.
389        * 'MENU [PRG|NOW|SUM]' calls one of the main menus of epgsearch or the summary
390          of the current event.
391        * 'UPDT' reloads the search timers from epgsearch.conf
392
393   channel group management:
394        * 'LSTC [channel group name]'
395          list all channel groups or if given the one with name 'group name'
396        * 'NEWC <channel group settings>'
397          create a new channel group, format as in epgsearchchangrps.conf
398        * 'EDIC <channel group settings>'
399          modify an existing channel group, format as in epgsearchchangrps.conf
400        * 'DELC <channel group name>'
401          delete an existing channel group
402        * 'RENC <old channel group name|new channel group name>'
403          rename an existing channel group
404
405   blacklist management:
406        * 'LSTB [ID]' to list all blacklists, or the one with the passed ID
407          (format is the same as epgsearchblacklists.conf)
408        * 'NEWB <settings>' to add a new blacklist
409          REMARK: the value of element ID is ignored. epgsearch will always
410          assign the next free ID
411        * 'DELB <ID>' to delete the blacklist with ID
412        * 'EDIB <settings>' to modify an existing blacklist
413
414   search template management:
415        * 'LSTT [ID]' to list all search templates, or the one with the passed ID
416          (format is the same as epgsearch.conf)
417        * 'NEWT <settings>' to add a new search template
418          REMARK: the value of element ID is ignored. epgsearch will always
419          assign the next free ID
420        * 'DELT <ID>' to delete the search template with ID
421        * 'EDIT <settings>' to modify an existing search template
422        * 'DEFT [ID]' returns the ID of the default search template. When passing an
423          ID it activates the corresponding template as default.
424
425   extended EPG categories:
426        * 'LSTE [ID] to get the extended EPG categories defined in epgsearchcats.conf
427          or the one with the given ID. (format is the same as epgsearchcats.conf)
428
429   misc:
430        * 'SETP [option]' returns the current value of the given setup option or a
431          list of all options with their current values.
432          The following options can be accessed:
433           - ShowFavoritesMenu
434           - UseSearchTimers
435
436   timer conflicts:
437        * 'LSCC [REL]' returns the current timer conflicts. With the option 'REL' only
438          relevant conflicts are listed. The result list looks like this for example
439          when we have 2 timer conflicts at one time:
440
441          1190232780:152|30|50#152#45:45|10|50#152#45
442
443          '1190232780' is the time of the conflict in seconds since 1970-01-01. It's
444          followed by list of timers that have a conflict at this time:
445
446          '152|30|50#152#45' is the description of the first conflicting timer. Here:
447
448          '152' is VDR's timer id of this timer as returned from VDR's LSTT command
449          '30' is the percentage of recording that would be done (0...100)
450          '50#152#45' is the list of concurrent timers at this conflict
451
452          '45|10|50#152#45' describes the next conflict
453

10. Customizing the EPG menus

455       The file epgsearchmenu.conf in your epgsearch config directory is used
456       to store the entries for customizing the EPG menus. You specify the
457       look of each menu (What's on now, What's on next, What's on at ...,
458       Schedule, Search results, Favorites) with a separate line. Here's a
459       sample:
460
461        MenuWhatsOnNow=%chnr%:3|%progrt2s%:5| %time% %t_status%:8|%category%:6| %title% ~ %subtitle%:35
462        MenuWhatsOnNext=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
463        MenuWhatsOnElse=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
464        MenuSchedule=%time% %t_status%:8|%genre%:14| %title% ~ %subtitle%:35
465        MenuSearchResults=%chnr%:3|%datesh% %time% %t_status%:14|%genre%:8| %title%%colon% %subtitle%:35
466        MenuFavorites=%chnr%:3|%time%:6|%timespan%:7|%t_status%:14|%genre%:8| %title%%colon%%subtitle%:35
467
468       E.g. the entry 'MenuWhatsOnNow' tells epgsearch how you would like to
469       build a line for the menu 'What's on now'. This would create a menu
470       line starting with the channel number, followed by a progress bar in
471       text2skin style, a space of one char, the start time, the timer status,
472       the EPG category (like "movie") and finally the title and subtitle.
473
474       The values for MenuWhatsOnNext, MenuWhatsOnElse, MenuSchedule,
475       MenuSearchResults, MenuFavorites specify the menu 'What's on next',
476       'What's on at ...', 'Schedule', 'Search results' and 'Favorites'
477       respectively. If you do not specify one entry, epgsearch uses its
478       default menu look.
479
480       'MenuSearchResults' has something special: If you want to have
481       different layouts for your search results depending on the search, you
482       can use more then one menu template. Simply define e.g. an additional
483
484        MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35
485
486       This will produce an additional menu item "Result menu layout" in the
487       edit menu of a search where you can choose between the default menu
488       template and your own templates. In the example above you will get "Tip
489       of the Day" as selection entry, since epgsearch simply cuts the leading
490       "MenuSearchResults". When you display the search results the chosen
491       template will be used instead of the default one.
492
493       The following variables exist:
494
495        %time%           - start time in format HH:MM
496        %timeend%        - end time in format HH:MM
497        %date%           - start date in format DD.MM.YY
498        %datesh%         - start date in format DD.MM.
499        %date_iso%       - start date in format YYYY-MM-DD.
500        %year%           - year with century
501        %month%          - month (1-12)
502        %day%            - day (1-31)
503        %week%           - week number of the year (Monday as the first day of the week) as a decimal number [01,53]
504        %time_w%         - weekday name
505        %time_d%         - start day in format TT
506        %time_lng%       - start time in seconds since 1970-01-01 00:00
507        %timespan%       - timespan from now to the beginning of an event, e.g. 'in 15m'
508                           or the time an event is already running, e.g. '10m'.
509        %length%         - length in seconds
510        %title%          - title
511        %subtitle%       - subtitle
512        %summary%        - summary
513        %htmlsummary%    - summary, where all CR are replaced with '<br />'
514        %eventid%        - numeric event ID
515        %liveeventid%    - encoded event ID as used in the frontend 'live'
516        %t_status%       - timer status ('T', 't', 'R')
517        %v_status%       - VPS status
518        %r_status%       - running status
519        %status%         - complete status, the same as
520                           '%t_status%%v_status%%r_status%'
521
522        %<epg-category>% - a value from the extended EPG categories, specified in
523                           epgsearchcats.conf, like %genre% or %category%
524
525       for the 'Whats on...' and 'Search results' menu there are also:
526
527        %chnr%           - channel number
528        %chsh%           - the short channel name
529        %chlng%          - the 'normal' channel name
530        %chdata%         - VDR's internal channel representation (e.g. 'S19.2E-1-1101-28106')
531        %progr%          - graphical progress bar (not for menu 'Search results'),
532                           requires VDRSymbols font
533        %progrT2S%       - progress bar in text2skin style (not for menu 'Search results')
534
535       some independent variables:
536
537        %colon%          - the sign ':'
538        %datenow%        - current date in format DD.MM.YY
539        %dateshnow%      - current date in format DD.MM.
540        %date_iso_now%   - current date in format YYYY-MM-DD
541        %timenow%        - current time in format HH:MM
542        %videodir%       - VDR video directory (e.g. /video)
543        %plugconfdir%    - VDR plugin config directory (e.g. /etc/vdr/plugins)
544        %epgsearchdir%   - epgsearch config directory (e.g. /etc/vdr/plugins/epgsearch)
545
546       The variables are not case sensitive. You can also use variables for
547       extended EPG categories defined in epgsearchcats.conf or use your own
548       user defined variables defined in epgsearchuservars.conf
549
550       An entry consists of up to 6 tables separated with '|'. The last entry
551       of each table should declare the table width in chars, separated with
552       ':'.
553
554       If you use a separator like '~', '-' or '#' to separate items like
555       title or subtitle, e.g. %title% ~ %subtitle%, and the subtitle is
556       empty, then epgsearch will try to fix this automatically to avoid a
557       trailing separator.
558
559       You should vary the tab width values to fit your needs, since the look
560       often depends on the selected skin. epgsearchmenu.conf is not reloaded
561       with every plugin call, since this is only useful when testing the conf
562       file. To activate the permanent reload for testing your conf, pass the
563       new start parameter '-r' or '--reloadmenuconf' in your runvdr.
564
565       There's a sample epgsearchmenu.conf in the subdirectory "conf". For a
566       quick try copy it to your epgsearch config directory (e.g.
567       /etc/vdr/plugins/epgsearch).
568
569       To enable icons from the VDRSymbols font simply put the line
570
571        WarEagleIcons=1
572
573       to epgsearchmenu.conf. The VDRSymbols font is available at
574       http://andreas.vdr-developer.org/fonts/download.html
575
576       NOTE: As long as there is a file epgsearchmenu.conf with an entry for a
577       special menu, all setup settings regarding the look of this menu are
578       ignored.
579
580       See also "epgsearchmenu.con(5)".
581

11. Working with the timer conflict menu

583       If a conflict is detected within the periodic conflict background check
584       you get an OSD message which informs you about it. Pressing 'Ok' you
585       will get a menu that displays all relevant conflicts. You can manually
586       call this menu in epgsearch in the menu 'Search/Actions'.
587
588       Besides the relevant conflicts (relevance is controlled via the setup
589       options of epgsearch) there may also be conflicts which are not
590       classified as important. If so, you can press 'Show all' to get the
591       complete list. The menu title always displays the number of relevant
592       conflicts and the total number.
593
594       The list displays first the time when a conflict appears and then all
595       timers that will fail here. A timer entry consists of the channel
596       number and its name followed by the timer priority and the percentage
597       value that shows how much of the timer will be recorded. Finally the
598       timer's file entry is displayed.
599
600       When you select a timer entry and press 'Ok' or 'Details' you get a new
601       menu which displays all concurrent timers. This menu allows you to
602       resolve the conflict by
603
604        - searching a repeat for an event
605        - disabling a timer
606        - deleting a timer
607        - changing the timers start- or stop-time or its priority
608        - executing any other commands on this timer
609
610       An entry of this menu consists of the sign '>' to indicate an active
611       timer, the channel number, the start and stop time, the priority, the
612       number of the device that will do the recording (or 'C' for conflict)
613       and the timer's file entry. Pressing 'Ok' on a timer entry will show
614       you its event description if present.
615
616       If one returns from this menu to the conflict overview menu there will
617       be an automatic update to see if a conflict was really resolved. Some
618       changes to a timer (like modifying start/stop or deleting a timer) in
619       the conflict details menu also cause an immediate return to the
620       overview menu and produce an update.
621
622       Note: There's a 'hidden' setup option epgsearch.ConflCheckCmd, that
623       allows executing a command for each timer causing a conflict. You have
624       to set this directly in VDRs setup.conf like this:
625
626       epgsearch.ConflCheckCmd = system(your_script_handling_the_conflict.sh,
627       any_arguments like %timer.file%)
628
629       (Please have a look at 'Calling a system command' below for the
630       possible arguments) One could use this for example to forward a timer
631       to another VDR machine in case of a conflict.  This command is
632       evaluated for each timer causing a conflict whenever an automatic
633       conflict check is running. When calling the conflict check via OSD the
634       command is not evaluated.
635

12. User defined variables

637       You can create your own variables to be used in any place that supports
638       variables, like the default recording directory for manually created
639       timers, the recording directory of a search timer or in your customized
640       EPG menus.  Put them in the file epgsearchuservars.conf.
641
642       Variables looks like %Variablename%.
643
644       "Variablename" can be consist of any alphanumerical character. Space
645       and special characters are not allowed.
646
647       The variable names are case-insensitive.
648
649       Examples for possible names:
650
651        %Series% %DocuVar1% %ThemesSubtitleDate1%
652
653   Assignment
654        %Series%=New series~Thriller
655
656       The variable %Series% will be assigned with the string "New
657       series~Thriller".
658
659       Assignments are always strings. Spaces stay spaces.
660
661        %Path%=%Series%
662
663       The variable %Path% gets the content of the variable %Series%.
664
665       You can do nearly everything:
666
667        %Path%=%Serie%~Lost
668
669       The variable %Path% contains now the string "New series~Thriller~Lost".
670
671   Control structures
672       You can use simple "if then else" constructions.
673
674       These constructions cannot contain strings, only variables.  Spaces are
675       ignored.
676
677        %Foo%=Other
678
679        %Variable%=%Path% ? %Path% : %Foo%
680
681       If %Path% is not empty, assign the content of %Path% to %Variable%,
682       otherwise the content of %Foo%.
683
684       "%Path% ?" means "not empty?". You can use other checks.
685
686        %Variable%=%Path%!=5 ? %Path% : %Foo%
687
688       "%Path%!=5 ?" means "is %Path% equal 5?"
689
690       You can also compare variables.
691
692        %Five%=5
693
694        %Variable%=%Path%!=%Five% ? %Path% : %Foo%
695
696       Other possible checks:
697
698        ==   equal
699        !=   not equal
700
701   Calling a system command
702       You can call external commands. The returned string will be assigned to
703       a variable
704
705        %uservar%=system(scriptname[, parameters])
706
707       Calls the script "scriptname" with the parameters defined in the
708       optional list of 'parameters'. This can be an arbitrary expression
709       containing other user variables, but not again a system call or a
710       conditional expression.
711
712       Sample:
713
714        %myVar%=system(/usr/local/bin/myscript.sh, -t %title% -s %subtitle% -u %myOtherVar%)
715
716       The script must return a string without line break!
717
718       If the script returns nothing, an empty string will be assigned to the
719       Variable %Result%.
720
721   Calling a TCP service
722       You can call a TCP service with the following syntax:
723
724        %uservar%=connect(<addr>, <port>, [<data>])
725
726       This will connect to <addr> through the given port and pass the
727       optional given data. <addr> can be an IP address or the domain name of
728       the TCP service. The result returned by the service must be terminated
729       with a line feed.
730
731   Get the length of an argument
732       When passing any values to the connect or system command it can be
733       helpful to have the length of an argument for simple parsing. This can
734       be done with
735
736        %uservar%=length(<any arguments>)
737
738       Sample:
739
740       %length_title%=length(%title%)
741
742   Possible variables
743       for a list of already builtin variables refer to the section
744       "Customizing the EPG menus" Furthermore you can use every variable
745       defined in epgsearchcats.conf.
746
747       See "epgsearchcats.conf(5)".
748
749   EXAMPLES
750        # Weekday, Date, Time
751        %DateStr%=%time_w% %date% %time%
752
753        # Themes or Subtitle or Date
754        %ThemesSubtitleDate1%=%Subtitle% ? %Subtitle% : %DateStr%
755        %ThemesSubtitleDate%=%Themes% ? %Themes% : %ThemesSubtitleDate1%
756
757        # Calls this script to get a recording path
758        %DocuScript%=system(doku.pl, -t %Title% -s %Subtitle% -e %Episode% -th %Themes% -c %Category% -g %Genre%)
759        %Docu%=%DocuScript%
760

13. Email notification

762       If you want to get email notifications about timers
763       added/modified/removed by the search timer thread or about timer
764       conflicts, first copy the script 'sendEmail.pl' to the place where your
765       executables are (e.g. /usr/local/bin) and then configure your email
766       account in the setup. Press 'Test' to check if it works. There should
767       be something like 'Email successfully sent' at the end of the output.
768       The content of the mails is defined by the files
769
770         - epgsearchupdmail.templ (for search timer update notifications)
771         - epgsearchconflmail.templ (for timer conflict notifications)
772
773       You can find sample files in the 'conf' directory. Copy them to the
774       epgsearch config directory (e.g. /etc/vdr/plugins/epgsearch).
775
776   Customizing the notifications mails
777       The content of the mails can be customized in many ways. You can use
778       plain text or HTML (see the sample conf/epgsearchupdmail-html.templ).
779       For an update mail you have to define the following sections:
780
781         - "subject" to be used as mail subject
782         - "mailbody" the body of the mail:
783           put %update.newtimers% in the place where the list of new timers should
784           appear. The same for %update.modtimers%, %update.deltimers% and
785           %update.newevents% for the list of changed or deleted timers and event
786           announcements.
787         - "timer" the description of one timer and "event" with the description of
788           one event. This section is used to display one timer within a timer list,
789           e.g. in %update.newtimers%. The same for "event".
790
791       All sections are optional, e.g. if you don't use event announcements
792       you can drop "%update.newevents%" in the mailbody and the "event"
793       section. But of course you should have at least a mailbody ;-) Each
794       section is enclosed in a pseudo XML tag.
795
796       The following variables can be used in the section <mailbody>:
797
798         - %update.newtimers%      - will be replaced with the list of new timers
799                                     created with this update. The timers are
800                                     displayed as defined in the section '<timer>'
801         - %update.countnewtimers% - the number of new timers
802         - %update.modtimers%      - same as %update.newtimers% but for modified
803                                     timers.
804         - %update.countmodtimers% - the number of modified timers
805         - %update.deltimers%      - same as %update.newtimers% but for deleted
806                                     timers. (Note: a deleted timer has eventually
807                                     no event assigned to it. So all event variables
808                                     within the timer section will be substituted to
809                                     an empty string.)
810         - %update.countdeltimers% - the number of deleted timers
811         - %update.newevents%      - will be replaced with the list of events to
812                                     announce. These events are the search result of
813                                     search timers with the action "announce by mail".
814                                     The events are displayed as defined in the section
815                                     '<event>'
816         - %update.countnewevents% - the number of new events
817         - %colon%                 - the sign ':'
818         - %datenow%               - current date in format TT.MM.YY
819         - %dateshnow%             - current date in format TT.MM.
820         - %timenow%               - current time in format HH:MM
821
822       The following variables can be used in the section <timer>:
823
824         - %timer.date%            - date of the timer
825         - %timer.start%           - start time of the timer
826         - %timer.stop%            - stop time of the timer
827         - %timer.file%            - recording directory of the timer
828         - %timer.chnr%            - channel number
829         - %timer.chsh%            - short channel name
830         - %timer.chlng%           - channel name
831         - %timer.search%          - name of the search timer, that created the timer
832         - %timer.searchid%        - id of the search timer, that created the timer
833         - %timer.modreason%       - the reason for a timer modification in plain text
834         - %timer.liveid%          - encoded timer ID as used in the frontend 'live'
835         - any event variable (as in '10. Customizing the EPG menus')
836         - any extended EPG variable as defined in epgsearchcats.conf
837         - any user variable (as in '12. User defined variables')
838
839       The following variables can be used in the section <event>:
840
841         - any event variable (as in '10. Customizing the EPG menus')
842         - %search%                - the name of the search timer that triggered
843                                     this event
844         - %searchid%              - the ID of the corresponding search timer
845         - any extended EPG variable as defined in epgsearchcats.conf
846         - any user variable (as in '12. User defined variables')
847
848       For a conflict notification mail the following sections exist:
849
850         - "subject" to be used as mail subject
851         - "mailbody" the body of the mail. Put %conflict.conflicts% in the place
852           where the list of conflict times should appear (Note: there can be more
853           than one timer conflict at the same time!). A conflict time uses the
854           section 'conflictsat' to display its content.
855         - "conflictsat" the description of one time where one or more conflicts
856           exists. Put %conflict.confltimers% in the place where the list of conflict
857           timers should appear.
858         - "confltimer" the description of one conflicting timer
859
860       The following variables can be used in the section <mailbody>:
861
862         - %conflict.count%        - complete number of timer conflicts
863         - %conflict.conflicts%    - list of times with conflicting timers
864
865       The following variables can be used in the section <conflictsat>:
866
867         - %conflict.date%         - date of the conflict
868         - %conflict.time%         - time of the conflict
869         - %conflict.confltimers%  - list of conflicting timers for this time
870
871       The section <conflicttimer> can use the same variables as the section
872       <timer> in an update mail (see above).
873

14. The conf.d subdirectory

875       epgsearch supports a configuration mechanism well-known in linux. The
876       settings of the configuration files
877
878         - epgsearchuservars.conf
879         - epgsearchdirs.conf
880         - epgsearchmenu.conf
881         - epgsearchcats.conf
882
883       can also be given in a file with arbitrary name in the subdirectory
884       conf.d in <plugin-configuration-directory>/epgsearch. This allows one
885       to quickly test different setups only by exchanging files instead of
886       editing them. The format of these files is
887
888         [<section name>]
889         <settings>
890         ...
891
892         [<section name>]
893         <settings>
894         ...
895
896       where <section_name> is one of the following:
897
898         - epgsearchuservars
899         - epgsearchdirs
900         - epgsearchmenu
901         - epgsearchcats
902
903       The <settings> format follows the one in the corresponding
904       configuration file.  Comments beginning with # are allowed, also blank
905       lines.  At startup epgsearch first reads its 'regular' configuration
906       files and then the conf.d subdirectory.  It's allowed to overwrite
907       variables already defined in other files (although this is signaled
908       with a warning in epgsearch's log file.).
909

SEE ALSO

911       epgsearch(1), "epgsearch.conf(5)", "epgsearchuservars.con(5)",
912       "epgsearchdirs.conf(5)", "epgsearchmenu.conf(5)",
913       "epgsearchcmds.conf(5)"
914

AUTHOR (man pages)

916       Mike Constabel <epgsearch (at) constabel (dot) net>
917

REPORT BUGS

919       Bug reports (german):
920
921       <http://projects.vdr-developer.org/projects/plg-epgsearch>
922
923       Mailing list:
924
925       <http://www.vdr-developer.org/mailman/listinfo/epgsearch>
926
928       Copyright (C) 2004-2010 Christian Wieninger
929
930       This program is free software; you can redistribute it and/or modify it
931       under the terms of the GNU General Public License as published by the
932       Free Software Foundation; either version 2 of the License, or (at your
933       option) any later version.
934
935       This program is distributed in the hope that it will be useful, but
936       WITHOUT ANY WARRANTY; without even the implied warranty of
937       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
938       General Public License for more details.
939
940       You should have received a copy of the GNU General Public License along
941       with this program; if not, write to the Free Software Foundation, Inc.,
942       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Or, point
943       your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
944
945       The author can be reached at cwieninger@gmx.de
946
947       The project's page is at http://winni.vdr-developer.org/epgsearch
948
949       The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-
950       Digest Algorithm.
951
952
953
954perl v5.34.0                      2022-02-03                      epgsearch(4)
Impressum