1epgsearch(4) Epgsearch Version 2.4.1 epgsearch(4)
2
6 epgsearch - Searchtimer and replacement of the VDR program menu
7
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
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
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 1|Category|Kategorie|Information,Kinder,Musik,Serie,Show,Spielfilm,Sport|3
38 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 My Movies~%Category%
44 Childrens Movies~%category%
45 %CATEGORY%~%genre%
46 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 %Category%~%Genre%~%Title%~%Subtitle%
54 is the same as
56 %Category%~%Genre%
58 (with 'serial recording' set to 'yes').
59 The %chlng% variable gets replaced with the name of the channel.
61 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 %Category%~%Genre%~%Title%~%Episode%~%Subtitle%
67 There are also the following search variables:
69 %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 See also "epgsearchuservars.conf(5)".
74
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 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 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 See also "epgsearch.conf(5)".
163
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 title~subtitle~description
170 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 - 'Phrase' matches
176 if the search term is found anywhere in the search text.
177 - '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 Then we check if at least one or all words appear in the search
183 text.
184 - 'match exactly'
186 matches if search term and search text are identical.
187 - '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 If the search was successful until now, the other criterions (start
195 time, duration, week day) are checked.
196
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 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 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
220 the update of search timers runs in its own thread. There are several
221 ways to trigger it:
222 - 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 - manually extern
229 the thread observes the file '.epgsearchupdate' in the plugins
230 config directory. When you
231 touch /path_to_file/.epgsearchupdate
233 this will also trigger an update. So this is a simple solution to
235 make an update e.g. by a script.
236 - manually intern
238 calling actions or pressing '3' in the menu of searches asks also
239 for an update.
240 - from other plugins
242 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
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 * 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 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 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
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 { "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 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 See also "epgsearchcmds.conf(5)".
305
307 Searching the EPG and other functionality can be used by other plugins
308 or scripts. There are two approaches:
309 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 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 Then call Epgsearch via svdrpsend (you must have assigned a key to it),
322 e.g.
323 svdrpsend HITK green
325 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 A sample script recrep.sh, that searches for the repeats of a recording
330 exists in the scripts subdirectory of Epgsearch.
331 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 - searching the EPG for some criteria and display the result list
337 - extended timer edit menu
338 I have added a quick and dirty dummy plugin
340 (source/vdr-epgsearchclient-0.0.1.tgz), that demonstrates the usage.
341
343 epgsearch implements a SVDRP interface, that can be accessed for
344 example like this
345 svdrpsend PLUG epgsearch LSTS
347 the following commands are available:
349 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 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 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 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 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 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 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 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 1190232780:152|30|50#152#45:45|10|50#152#45
442 '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 '152|30|50#152#45' is the description of the first conflicting timer. Here:
447 '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 '45|10|50#152#45' describes the next conflict
453
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 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 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 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 '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 MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35
485 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 The following variables exist:
494 %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 %<epg-category>% - a value from the extended EPG categories, specified in
523 epgsearchcats.conf, like %genre% or %category%
524 for the 'Whats on...' and 'Search results' menu there are also:
526 %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 some independent variables:
536 %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 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 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 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 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 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 To enable icons from the VDRSymbols font simply put the line
570 WarEagleIcons=1
572 to epgsearchmenu.conf. The VDRSymbols font is available at
574 http://andreas.vdr-developer.org/fonts/download.html
575 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 See also "epgsearchmenu.con(5)".
581
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 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 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 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 - 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 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 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 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 epgsearch.ConflCheckCmd = system(your_script_handling_the_conflict.sh,
627 any_arguments like %timer.file%)
628 (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
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 Variables looks like %Variablename%.
643 "Variablename" can be consist of any alphanumerical character. Space
645 and special characters are not allowed.
646 The variable names are case-insensitive.
648 Examples for possible names:
650 %Series% %DocuVar1% %ThemesSubtitleDate1%
652 Assignment
654 %Series%=New series~Thriller
655 The variable %Series% will be assigned with the string "New
657 series~Thriller".
658 Assignments are always strings. Spaces stay spaces.
660 %Path%=%Series%
662 The variable %Path% gets the content of the variable %Series%.
664 You can do nearly everything:
666 %Path%=%Serie%~Lost
668 The variable %Path% contains now the string "New series~Thriller~Lost".
670 Control structures
672 You can use simple "if then else" constructions.
673 These constructions cannot contain strings, only variables. Spaces are
675 ignored.
676 %Foo%=Other
678 %Variable%=%Path% ? %Path% : %Foo%
680 If %Path% is not empty, assign the content of %Path% to %Variable%,
682 otherwise the content of %Foo%.
683 "%Path% ?" means "not empty?". You can use other checks.
685 %Variable%=%Path%!=5 ? %Path% : %Foo%
687 "%Path%!=5 ?" means "is %Path% equal 5?"
689 You can also compare variables.
691 %Five%=5
693 %Variable%=%Path%!=%Five% ? %Path% : %Foo%
695 Other possible checks:
697 == equal
699 != not equal
700 Calling a system command
702 You can call external commands. The returned string will be assigned to
703 a variable
704 %uservar%=system(scriptname[, parameters])
706 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 Sample:
713 %myVar%=system(/usr/local/bin/myscript.sh, -t %title% -s %subtitle% -u %myOtherVar%)
715 The script must return a string without line break!
717 If the script returns nothing, an empty string will be assigned to the
719 Variable %Result%.
720 Calling a TCP service
722 You can call a TCP service with the following syntax:
723 %uservar%=connect(<addr>, <port>, [<data>])
725 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 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 %uservar%=length(<any arguments>)
737 Sample:
739 %length_title%=length(%title%)
741 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 See "epgsearchcats.conf(5)".
748 EXAMPLES
750 # Weekday, Date, Time
751 %DateStr%=%time_w% %date% %time%
752 # Themes or Subtitle or Date
754 %ThemesSubtitleDate1%=%Subtitle% ? %Subtitle% : %DateStr%
755 %ThemesSubtitleDate%=%Themes% ? %Themes% : %ThemesSubtitleDate1%
756 # 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
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 - epgsearchupdmail.templ (for search timer update notifications)
771 - epgsearchconflmail.templ (for timer conflict notifications)
772 You can find sample files in the 'conf' directory. Copy them to the
774 epgsearch config directory (e.g. /etc/vdr/plugins/epgsearch).
775 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 - "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 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 The following variables can be used in the section <mailbody>:
797 - %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 The following variables can be used in the section <timer>:
823 - %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 The following variables can be used in the section <event>:
840 - 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 For a conflict notification mail the following sections exist:
849 - "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 The following variables can be used in the section <mailbody>:
861 - %conflict.count% - complete number of timer conflicts
863 - %conflict.conflicts% - list of times with conflicting timers
864 The following variables can be used in the section <conflictsat>:
866 - %conflict.date% - date of the conflict
868 - %conflict.time% - time of the conflict
869 - %conflict.confltimers% - list of conflicting timers for this time
870 The section <conflicttimer> can use the same variables as the section
872 <timer> in an update mail (see above).
873
875 epgsearch supports a configuration mechanism well-known in linux. The
876 settings of the configuration files
877 - epgsearchuservars.conf
879 - epgsearchdirs.conf
880 - epgsearchmenu.conf
881 - epgsearchcats.conf
882 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 [<section name>]
889 <settings>
890 ...
891 [<section name>]
893 <settings>
894 ...
895 where <section_name> is one of the following:
897 - epgsearchuservars
899 - epgsearchdirs
900 - epgsearchmenu
901 - epgsearchcats
902 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
911 epgsearch(1), "epgsearch.conf(5)", "epgsearchuservars.con(5)",
912 "epgsearchdirs.conf(5)", "epgsearchmenu.conf(5)",
913 "epgsearchcmds.conf(5)"
914
916 Mike Constabel <epgsearch (at) constabel (dot) net>
917
919 Bug reports (german):
920 <http://projects.vdr-developer.org/projects/plg-epgsearch>
922 Mailing list:
924 <http://www.vdr-developer.org/mailman/listinfo/epgsearch>
926
928 Copyright (C) 2004-2010 Christian Wieninger
929 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 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 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 The author can be reached at cwieninger@gmx.de
946 The project's page is at http://winni.vdr-developer.org/epgsearch
948 The MD5 code is derived from the RSA Data Security, Inc. MD5 Message-
950 Digest Algorithm.
951perl v5.34.0 2022-02-03 epgsearch(4)