epgsearch(4)

NAME
EPGSearch – search timers and replacement of the VDR's default schedules menu

OVERVIEW
Since the former README got overly large, this man page serves as replacement and explains some features and behaviors in detail. It's thus not really a manual, but an extended README.

CONTENT

1. Using variables in the directory entry of a search timer
2. The format of the file epgsearch.conf
3. Description of the search process
4. How do search timers work?
5. How to trigger a search-timer update?
6. The sources of the 'Select directory' menu
7. Language-dependent commands for the EPG
8. Usage from other plugins or scripts
9. The SVDRP interface
10. Customizing the EPG menus
11. Working with the timer-conflict menu
12. User-defined variables
13. E-mail notifications
14. The conf.d directory

1. Using variables in the directory entry of a search timer
When using extended EPG information, variables can be part of the directory entry of a search timer. These variables always have the syntax '%Variable%'. The name of a variable corresponds with the internal name of an extended EPG information as specified in the file epgsearchcats.conf; samples can be found in subdirectory conf of the plugin's source directory.

Example:

    1|Category|Kind|Information,Children,Music,Series,Show,Movie,Sports|3

The category with ID 1 has the internal name 'Category'. So you could refer to it with '%Category%'. Variable names are case-insensitive.

Sample directory entries could look like this:

    My Movies~%Category%
    Children's Movies~%category%
    %CATEGORY%~%genre%

Three more variables are available:

%Title%
    Substituted by the name of the event.

%Subtitle%
    Substituted by the short text of the event.

%ChLng%
    Substituted by the long name of the channel on which the event is broadcasted.

If neither '%Title%' nor '%Subtitle%' is included or part of an inserted user-defined variable, the title is always automatically appended to the directory entry once a timer is created. If 'Series recording' is set to 'yes' in the search timer, the subtitle will be automatically appended, too. So, the directory entry:

    %Category%~%Genre%~%Title%~%Subtitle%

is the same as:

    %Category%~%Genre%

if 'Series recording' set to 'yes'.

Attention: Title and subtitle will not be appended automatically if one of the variables '%Title%' or '%Subtitle%' is part of the directory specification. This allows forming directory entries like this one:

    %Category%~%Genre%~%Title%~%Episode%~%Subtitle%

Furthermore, the following search variables are available in addition:

%Search.Query%
    Substituted by the search term of the search timer.

%Search.Series%
    Substituted by 1 if the search has the 'Series recording' flag set, or 0 otherwise.

See also epgsearchuservars.conf(5).

2. The format of the file epgsearch.conf
Every line within the file represents a search or search timer, comprising the following fields:

1 – Unique identifier (ID)
    Integer with a positive value.

2 – Search term ("query")
    String specifying the search criterion.

3 – Use time
    Flag with values 0 = no, 1 = yes.

4 – Start after [HHMM]
    Integer with HH = 0..23, MM = 0..59; other values may result in undefined behavior.

5 – Start before [HHMM]
    Integer with HH = 0..23, MM = 0..59; other values may result in undefined behavior.

6 – Use channel
    Enumeration with values 0 = no, 1 = interval, 2 = channel group, 3 = FTA (free-to-air) only.

7 – Channel selection
    if 'use channel' = 1:
        String with 'ChannelID' or 'MinChannelID'|'MaxChannelID'; the channel identifiers must conform to the VDR notation (e.g., 'S19.2E-1-1019-10301').

        Attention: Please check the range settings of your search timers after changing the sequence of the channels!

    if 'use channel' = 2:
        String referring to a previously configured channel-group name.

8 – Match case
    Flag with values 0 = no, 1 = yes.

9 – Search mode
    Enumeration with the following values:

    0 = phrase
    1 = all words
    2 = at least one word
    3 = match exactly
    4 = regular expression
    5 = fuzzy search (tolerance in field 42; not available for extended EPG categories)

    See "Description of the search process" for how these modes control the search.

10 – Use title
    Flag with values 0 = no, 1 = yes.

11 – Use subtitle
    Flag with values 0 = no, 1 = yes.

12 – Use description
    Flag with values 0 = no, 1 = yes.

13 – Use duration
    Flag with values 0 = no, 1 = yes.

14 – Minimum duration [HHMM]
    Integer with HH = 0..23, MM = 0..59; other values may result in undefined behavior.

15 – Maximum duration [HHMM]
    Integer with HH = 0..23, MM = 0..59; other values may result in undefined behavior.

16 – Use as search timer
    Enumeration with the following values:

    0 = no
    1 = yes
    2 = time span (fields 48 and 49)

17 – Use day of week
    Flag with values 0 = no, 1 = yes.

18 – Day of week
    Integer value from −127 to 6. The encoding is twofold:

    if dow ≥ 0: individual weekday
        Enumeration with values 0 = Sunday, 1 = Monday, ..., 6 = Saturday.

    if dow < 0: set of weekdays
        Integer in which the bits of −dow represent the weekdays. Bit masks result from shifting 0x01 by a weekday's enumeration value:

        0x01 = Sunday
        0x02 = Monday
        0x04 = Tuesday
        0x08 = Wednesday
        0x10 = Thursday
        0x20 = Friday
        0x40 = Saturday

        To encode the desired set of weekdays, the value resulting from their ORed bit masks must be negated.

        Example: −67 (negated: 0b01000011 = 0x40 | 0x02 | 0x01) encodes Saturday, Monday, and Sunday

19 – Series recording
    Flag with values 0 = no, 1 = yes.

20 – Directory for recording
    String with the name of a directory beneath the VDR's video directory, but without the path to that video directory.

21 – Priority of recording
    Integer value from 0 to 99.

22 – Lifetime of recording [days]
    Integer value from 0 to 99.

23 – Margin at start [minutes]
    Integer with a positive value.

24 – Margin at stop [minutes]
    Integer with a positive value.

25 – Use VPS
    Flag with values 0 = no, 1 = yes.

26 – Action
    Enumeration with the following values:

    0 = record
    1 = announce by OSD (no timer)
    2 = switch only (no timer)
    3 = announce by OSD and switch (no timer)
    4 = announce by e-mail
    5 = inactive record

27 – Use extended EPG information
    Flag with values 0 = no, 1 = yes.

28 – Extended EPG information values
    List of extended EPG category data, each represented by a tuple of:

    28.1 – Identifier
        Unique identifier of the extended EPG category as specified in epgsearchcats.conf.

    28.2 – Category values
        Comma-separated list of values as specified for the EPG category in epgsearchcats.conf. Spaces around values are ignored. A ':' character, like in '16:9', must be encoded as '!^colon^!'.

    The '|' character separates adjacent category tuples, whereas '#' separates ID and category names.

    Example: '1#Movie, Series|2#Horror|8#16!^colon^!9'

29 – Avoid repeats
    Flag with values 0 = no, 1 = yes.

30 – Allowed repeats
    Integer value from 0 to 99.

31 – Compare title (when testing for repeats)
    Flag with values 0 = no, 1 = yes.

32 – Compare subtitle (when testing for repeats)
    Enumeration with value 0 = no, 1 = yes, 2 = allow empty.

33 – Compare summary (when testing for repeats)
    Flag with values 0 = no, 1 = yes.

34 – Compare categories (when testing for repeats)
    Integer in which each bit represents an extended EPG category. The first EPG category specified in epgsearchcats.conf is represented by bit 0 (0x01), the second by bit 1 (0x02), etc. A nonzero value enables comparison.

    Note: The values of the EPG category identifiers (field 1 of an EPG category entry) are of no relevance for encoding the bit field. Changes to EPG categories may require an update of search timers.

35 – Only repeats within ... days
    Integer value from 0 to 999.

36 – Delete recordings after ... days
    Integer value from 0 to 999.

37 – Keep ... recordings
    Integer value from 0 to 999.

38 – Switch ... minutes before start
    Integer value from 0 to 99; only considered if 'action' = 2.

39 – Pause when ...recordings exist
    Integer value from 0 to 999.

40 – Blacklist usage mode
    Enumeration with values 0 = only global, 1 = selection, 2 = all, 3 = none.

41 – Blacklist selection
    List of blacklist identifiers, separated by '|' characters; only considered if 'blacklist usage mode' = 1.

42 – Fuzzy tolerance
    Integer value from 1 to 9, serving as threshold for fuzzy searching; only considered if 'search mode' = 5.

43 – Use in favorites menu
    Flag with values 0 = no, 1 = yes.

44 – Result menu layout for favorites menu
    Integer referencing a search-result template specified in epgsearchmenu.conf. The value is the index (starting at 0) within all entries having a prefix of 'MenuSearchResults'; see "10. Customizing the EPG menus" in epgsearch(4) for details.

    Note: The field is only of relevance if multiple search-result templates have been specified.

45 – Auto delete mode
    Enumeration with the following values:

    0 = don't delete the search timer
    1 = delete after a number of recordings (field 46)
    2 = delete after a number of days after the first recording (field 47)

46 – Delete after ... recordings
    Integer value from 0 to 999; only considered if 'auto delete mode' = 1.

47 – Delete after ... days after first recording
    Integer value from 0 to 999; only considered if 'auto delete mode' = 2.

48 – First day (use as search timer from)
    Date and time in Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC) from which on the search timer is active; a value of 0 disables the check.

    Note: Any Epoch value can be supplied. Thus, providing a time within a day (instead of midnight) will keep the timer inactive until that intra-day time has been reached.

49 – Last day (use as search timer until)
    Date and time in Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC) until which the search timer is active; a value of 0 disables the check.

    Note: Any Epoch value can be supplied. Thus, providing a time within a day (instead of midnight) will keep the timer active until that intra-day time has been reached.

50 – Matching mode of extended EPG information
    Enumeration with the following values:

    0 = all selected categories
    1 = all except missing categories
    2 = at least one category

    This allows including events with missing or just some matching categories. But without other sufficiently limiting criteria, this could yield a huge number of results.

51 – Unmute sound
    Flag with values 0 = no, 1 = yes; only considered if 'action' = 2 or 3.

52 – Minimum match in percent
    Integer value from 1 to 100, specifying the minimum match required to avoid repeats when summaries are to be compared; only considered if 'compare summary' = 1.

53 – Content descriptors
    String with content descriptors to be checked. Content descriptors are values from 0 to 255 (see DIN EN 300 468, Table 18), encoded as 2-digit hexadecimal numbers. The upper nibble (bits [7..4]) constitutes a content group, and the lower nibble (bits [3..0]) represents a distinct descriptor within that group. A group's first descriptor with a value of 0 usually is a general classification of that group (like 0x10 = movie, drama), whereas values 1..15 provide a subordinate, finer classification (like 0x11 = detective, thriller; 0x14 = comedy). But since content group 11 (special characteristics) does not comply to this scheme (as can be seen from 0xB0 = original language; 0xB1 = black & white), a distinct matching mode for its descriptors is available.

    The content descriptors to be checked are the concatenation of their 2-digit hexadecimal values without separators.

    Example: Content identifiers 17 (detective, thriller), 20 (comedy) and 176 (original language) are encoded as '1114B0'.

    The settings of fields 55 (content categories) and 56 (special characteristics) determine the conditions for an event to match the selected content descriptors.

    Leave empty for not taking content descriptors into account.

54 – Compare date (when testing for repeats)
    Enumeration with the values 0 = no, 1 = same day, 2 = same week, 3 = same month.

55 – Matching mode of content categories
    Enumeration with the following values:

    0 = all selected descriptors
    1 = any selected descriptor
    2 = some selected descriptor per group

    Modes 0 and 1 instantly match across all category groups but nevertheless use the matching mode of field 56 for checking the special characteristics. Thus, combinations like 'AND' for the category groups and 'OR' within the special characteristics can occur, and vice versa.

    Mode 2, however, uses a two-stage evaluation: First, category groups with selected content descriptors are checked (groups without selected content descriptors are not considered). A category group matches if an event includes at least one of the group's selected descriptors ('some selected', OR), except for the special-characteristics group that again uses the matching mode of field 56. Second, all checked groups must have matched ('per group', AND).

    Only considered if 'content descriptors' is not empty.

56 – Matching mode of special characteristics
    Enumeration with values 0 = all selected descriptors, 1 = any selected descriptor; only considered if 'content descriptors' is not empty.

57 – Use parental rating
    Flag with values 0 = no, 1 = yes.

58 – Minimum parental rating
    Integer value from 0 to 18.

59 – Maximum parental rating
    Integer value from 0 to 18.

A search timer's entry is considered valid if covers at least the first 11 fields.

The fields ("parameters") of a search timer are separated by ':' characters. Thus, a ':' character in strings, like the search term or the directory, will be encoded as '|' character. If a '|' character should be part of the string as well, like in regular expressions, it will be encoded as '!^pipe^!' (which is rather ugly but required for backward compatibility).

Fields depending on another field and being void due to that field's setting can (and actually should) be left empty. For instance, a search timer not having a time constraint can leave the fields 'start after' and 'start before' empty:

    1:My favorite series: 0::: 0::0:0
                          ^^^^

Furthermore, leading and trailing whitespace around a field value is discarded. This implies, however, that strings cannot start or end with whitespace.

Note: Strings within fields must not be enclosed in quotations marks or apostrophes, even if this should be indicated in a field's description. These characters have just been inserted during compilation of this man page.

See also epgsearch.conf(5).

3. Description of the search process
First, a temporary search text is created for each broadcast, in which title, subtitle and description are separated by '~' characters:

    title~subtitle~description

Depending on the settings of 'use title', 'use subtitle' and 'use description', these components are either inserted or remain empty.

If 'match case' has not been set, the search text and the search term are transformed into lowercase.

Depending on the search mode, the search term will then be looked up in the search text:

Phrase
    Matches if the search term is found anywhere in the search text.

All words
At least one word
    First, the search term will be split into single words; delimiters are spaces and one of the ',;|~' characters. Second, the search succeeds if at least one word, or all words, appear in the search text.

Match exactly
    Matches if search term and search text are identical.

Regular expression
    The search is performed with a regular expression. Two standards are supported: extended POSIX and Perl compatible regular expressions (PCRE) (see INSTALL).

    Note: Unlike in Perl, leading and trailing '/' characters are not required for the search term.

Fuzzy
    Compares the search term based upon the Levenshtein-Distance algorithm. The value of the field 'fuzzy tolerance' determines how much deviation is acceptable.

    Note: The search term is limited to 32 characters when using the fuzzy mode.

If the search was successful so far, the other criteria (start time, duration, weekday, etc.) are checked.

4. How do search timers work?
With each update, the plugin first sorts the search timers by timer priority (descending) and search term, before it searches for new matches of search timers. If a new match is found, a new timer will be created.

For series recordings, the subtitle is appended to the recording directory. Many providers deliver the subtitle just a few days before the event. If unavailable, the plugin temporarily uses date and time for the subtitle but replaces them once the subtitle has become available.

Start and stop times of broadcasts often vary slightly. To avoid many different timers for the same event, the plugin checks whether another timer's start and stop times only differ by a maximum of 10 minutes; if an event's duration is less than 10 minutes, the durations will be compared instead.

If a match is found, a present timer will be modified, else a new timer will be created; inactive timers will not be updated. Furthermore, manually adapted priority or lifetime settings will not be changed upon updates.

If 'action' was set to a variant of 'announce (no timer)', no timer will be created. Instead, a notification about the event will be issued: An OSD message will be displayed upon each scan, but only if there was no previous timer for the event. An e-mail will be sent according to the schedule configured if timers have been created or changed.

5. How to trigger a search-timer update?
The update of search timers runs in a thread of its own. An update can be triggered in several ways:

Periodically
    The search timers will be updated a few seconds after the VDR has started. Once finished, the setup option 'Update interval [min]' determines in which intervals future updates shall be done.

Externally
    The thread observes the file '.epgsearchupdate' in the plugin's configuration directory. After executing:

        touch /path_to_file/.epgsearchupdate

    an update will be performed. This offers a simple way to trigger an update, for example when running a script.

Internally
    Calling 'Actions' » 'Trigger search timer update' or pressing 3 in the menu 'Search entries' will also trigger an update.

By other plugins
    The service 'Epgsearch-updatesearchtimers-v1.0' can be used with the VDR's service interface by other plugins. The caller can request an OSD notification when the update has been finished.

6. The sources of the 'Select directory' menu
This menu displays directories that can be used for both search timers and ordinary timers. The items displayed are collected from the following sources:

•   current recording directories

•   current timer directories

•   directories used in search timers

•   directories specified in epgsearchdirs.conf, see epgsearchdirs.conf(5)

•   entries in the VDR's folders.conf

The menu merges these directories and displays only distinct directories. The key 'yellow' allows changing the level of the directories shown. Should there be items containing EPG category variables like '%Genre%', these entries are always shown before other directories. They also do not depend on the level, but are always shown with their full directory path.

If this menu is called from the timer-edit menu and the selected item already contains the variables '%Title%' or %Subtitle, the timer's 'File' entry gets cleared, since title or subtitle already included in the 'Directory' item.

This list can also be accessed via the SVDRP command 'LSRD'.

7. Language-dependent commands for the EPG
If you like to have a language-dependent list of commands, simply translate your present epgsearchcmds.conf to your preferred OSD language and store it with the filename epgsearchcmds-<LOC>.conf, where <LOC> is the locale's code from i18n.c:

    { "eng,dos",
      "deu,ger",
      "slv",
      "ita",
      "dut,nla,nld",
      "por",
      "fra,fre",
      "nor",
      "fin,smi",
      "pol",
      "esl,spa",
      "ell,gre",
      "sve,swe",
      "rom,rum",
      "hun",
      "cat,cln",
      "rus",
      "hrv",
      "est",
      "dan"
      // see the source file
      // for the complete list
    }

If more codes are listed for a language, like 'eng,dos', choose one of them.

If a file corresponding to the VDR's OSD language is available, it will be loaded. If no such file exists, the system will attempt to load the epgsearchcmds.conf file instead.

See also epgsearchcmds.conf(5).

8. Usage from other plugins or scripts
Searching the EPG and other functionality can be used by other plugins or scripts. There are two approaches:

  8.1. File-based (intended for use in scripts)
Therefore simply create the file .epgsearchrc in the plugin's configuration directory with the following lines in it:

    Search=the search term
    SearchMode=x  // 0 = phrase, 1 = all (default), 2 = single, 3 = exactly, 4 = regex
    ChannelNr=x   // searches on a specific channel, if present
    UseTitle=x    // 1 (default) or 0
    UseSubtitle=x // 1 (default) or 0
    UseDescr=x    // 1 (default) or 0

At startup, EPGSearch will look for this file and, if found, return the search results for the specified search. Once the search has finished, the file will be removed.

Later on, another search can be triggered by means of the SVDRP interface. Supposing that the key 'green' has been assigned to EPGSearch (see epgsearch(1), chapter 5), just call EPGSearch via svdrpsend:

    svdrpsend HITK green

A sample script recrep.sh that searches for the repeats of a recording is provided in the subdirectory scripts of EPGSearch.

  8.2 Via plugin interface (intended for use in plugins)
A plugin can directly call two functions of EPGSearch with only some lines of code:

•   searching the EPG for some criteria and displaying the list of results

•   invoking the extended timer-edit menu

A quick-and-dirty sample plugin provided in the EPGSearch source directory (vdr-epgsearchclient-0.0.1.tgz) demonstrates the usage.

9. The SVDRP interface
EPGSearch implements an SVDRP interface that can be accessed like this:

    svdrpsend PLUG epgsearch LSTS

The following sections describe the commands available at the SVDRP interface.

  9.1 Search management

LSTS [ID]
    Lists all searches, or just the one with the supplied ID. The format of the returned data is the same as in epgsearch.conf (see above).

NEWS settings
    Adds a new search. The data format of settings is identical to the one used in epgsearch.conf (see above).

    The unique identifier (field 1) will be ignored. EPGSearch will always assign the next free identifier and reports it in the response:

        svdrpsend PLUG epgsearch NEWS "0:Sample search:::::::::"

        220 HostName SVDRP VideoDiskRecorder 2.7.7; ...
        900 search 'Sample search' (with new ID 6) added
        221 HostName closing connection

EDIS parameters
    Modifies an existing search. The data format of parameters is identical to the one used in epgsearch.conf (see above). The identifier in field 1 specifies the search to be modified.

    Note: An empty field ('::') is ignored. However, the values of the fields 'search', 'directory' and 'content descriptors' will be cleared if no values have been supplied.

MODS ID ON|OFF
    Turns the option 'Use as search timer' on or off.

DELS ID
    Deletes the search with the supplied ID.

SETS ON|OFF
    Starts (switches 'ON') or stops (switches 'OFF') the search-timer background thread.

UPDS [OSD]
    Updates searches and search timers. Passing the optional keyword 'OSD' displays an OSD message once the update has finished.

UPDT
    Reloads the file epgsearch.conf, for instance, after an external tool has modified it.

UPDD
    Reloads the file epgsearchdone.data, for instance, after an external tool has modified it.

FIND <parameters>
    Searches the EPG for matching events. The data format of parameters is identical to the one used in epgsearch.conf (see above).

    Returns one line per found event, formatted as the VDR's 'NEWT' command. This comprises the following fields:

        timer    : // 1 = create new timer
        channel  : // channel number in VDR's channel list
        date     : // date on which the event starts [YYYY-MM-DD]
        begin    : // start time of the event [HHMM]
        end      : // stop  time of the event [HHMM]
        priority : // priority for recording
        lifetime : // lifetime for recording
        file     : // timer file

    Example:

        svdrpsend PLUG epgsearch FIND "0:The Rookie:::::::::"

        220 HostName SVDRP VideoDiskRecorder 2.7.7; ...
        900-NEWT 1:39:2025-08-07:1753:1845:50:99:The Rookie:
        221 HostName closing connection

    A search result can thus instantly be used to create a timer for the corresponding event.

    Note: If not controlled by VPS, the date and start/stop times include the start/stop margins specified in the parameters.

QRYS ID[|ID|...]
    Retrieves the results for a search with the supplied ID. Multiple IDs, separated by '|' characters, can be supplied as well.

    Returns one line per ID, using the following format:

        search   : // unique identifier of the corresponding search
        event    : // unique identifier of the event within the VDR's schedules
        title    : // event title, with C<:> characters converted to C<|>
        subtitle : // event subtitle, with C<:> characters converted to C<|>
        begin    : // event start in Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC)
        end      : // event stop  as Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC)
        channel  : // channel ID in VDR's internal representation (e.g., S19.2E-1-1101-28106)
        start    : // timer start in Epoch encoding; only valid if 'timer' > 0
        stop     : // timer stop  in Epoch encoding; only valid if 'timer' > 0
        file         : // timer file; only valid if 'timer' > 0
        timer    : // 0 = no timer, 1 = active timer, ... (VDR timer flags)

    Example:

        svdrpsend PLUG epgsearch QRYS 0

        220 HostName SVDRP VideoDiskRecorder 2.7.7; ...
        900-0:3124:The Rookie:Heartbreak:1756901400:1756903800:S19.2E-1-1011-11130:1756901280:1756904400:The Rookie~Heartbreak:1
        221 HostName closing connection

QRYS parameters
    Retrieves the results for a search with the given parameters, ignoring the unique identifier in field 1.

QRYF [hours]
    Retrieves the results for the favorites menu; see 'QRYS' for the data format of the results. The optional parameter specifies the number of hours to be inspected and defaults to 24 hours.

MENU [NOW|PRG|SUM]
    Invokes an EPGSearch menu or the summary of the current event:

    •   NOW – ongoing broadcasts

    •   PRG – schedule of the current channel

    •   SUM – description of the current event

    Caution: The menu will only be displayed if no other menu is open at that time, else the currently shown menu will be closed. Thus, this command is not fully deterministic.

  9.2 Channel-group management

LSTC [name]
    Lists all channel groups, or just the one with the supplied name. The format of the returned data is the same as in epgsearchchangrps.conf.

NEWC settings
    Creates a new channel group. The data format of settings is the same as in epgsearchchangrps.conf.

EDIC settings
    Modifies an existing channel group. The data format of settings is the same as in epgsearchchangrps.conf.

RENC old-name|new-name
    Renames an existing channel group.

DELC name
    Deletes an existing channel group.

  9.3 Blacklist management

LSTB [ID]
    Retrieves all blacklists, or just the one with the supplied ID. The format of the returned data is the same as in epgsearchblacklists.conf.

NEWB settings
    Adds a new blacklist. The data format of settings is the same as in epgsearchblacklists.conf.

    The unique identifier (field 1) will be ignored. EPGSearch will always assign the next free identifier and reports it in the response:

        svdrpsend PLUG epgsearch NEWB "0:Sample blacklist:::::::::::::::::"

        220 HostName SVDRP VideoDiskRecorder 2.7.7; ...
        900 blacklist 'Sample blacklist' (with new ID 3) added
        221 HostName closing connection

DELB ID
    Deletes the blacklist with the supplied ID.

EDIB settings
    Modifies an existing blacklist. The data format of settings is the same as in epgsearchblacklists.conf. The identifier in field 1 specifies the blacklist to be modified.

    Note: An empty field ('::') is ignored. However, the values of the fields 'search' and 'content descriptors' will be cleared if no values have been supplied.

  9.4 Search-template management

LSTT [ID]
    Lists all search templates, or just the one with the passed ID. The format of the returned data is the same as in epgsearch.conf (see above).

NEWT settings
    Adds a new search template. The data format of settings is the same as in epgsearch.conf (see above).

    The value of the search identifier (field 1) will be ignored. EPGSearch will always assign the next free identifier and reports it in the response:

        svdrpsend PLUG epgsearch NEWT "0:Sample template:::::::::"

        220 HostName SVDRP VideoDiskRecorder 2.7.7; ...
        900 search template 'Sample template' (with new ID 4) added
        221 HostName closing connection

EDIT settings
    Modifies an existing search template The data format of settings is the same as in epgsearch.conf (see above). The identifier in field 1 specifies the search template to be modified.

    Note: An empty field ('::') is ignored. However, the values of the fields 'search', 'directory' and 'content descriptors' will be cleared if no values have been supplied.

DELT ID
    Deletes the search template with the supplied ID.

DEFT [ID]
    Returns the ID of the default search template. When supplying an ID, the corresponding search template will be set as new default.

  9.5 Extended EPG categories

LSTE [ID]
    Lists the extended EPG categories defined in epgsearchcats.conf, or just the one with the supplied ID. The format of the returned data is the same as in epgsearchcats.conf.

  9.6 Timer conflicts

LSCC [REL]
    Returns the current timer conflicts. With the option 'REL', only relevant conflicts are listed. The list of results looks like the following example of two timer conflicts at a given time:

        1190232780:152|30|50#152#45:45|10|50#152#45

    1190232780 is the time of the conflict in Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC). It's followed by a list of timers that have a conflict at this time.

    '152|30|50#152#45' is the description of the first conflicting timer:

    •   152 is VDR's ID of this timer as returned by the VDR's 'LSTT' command

    •   30 is the percentage of recording that would be done (0..100)

    •   '50#152#45' is the list of all timers involved in this conflict

    '45|10|50#152#45' describes the another conflict for this point of time.

  9.7 Miscellaneous

LSRD
    Lists all recording directories used in recordings, timers, search timers or that are defined in epgsearchdirs.conf.

SETP [option]
    Returns the current value of the supplied setup option, or a list of selected setup options with their current values.

    The following setup options can be accessed:

    •   ShowFavoritesMenu

    •   UseSearchTimers

    •   DefRecordingDir

    •   AddSubtitleToTimerMode

    •   DefPriority

    •   DefLifetime

    •   DefMarginStart

    •   DefMarginStop

10. Customizing the EPG menus
The file epgsearchmenu.conf in the EPGSearch configuration directory stores the settings for customizing the EPG menus. Each line configures the display of a certain menu. The entries specify the layouts for the following menus:

MenuWhatsOnNow
    Template for the menu 'Now'.

MenuWhatsOnNext
    Template for the menu 'Next'.

MenuWhatsOnElse
    Template for the menu of a user-defined time.

MenuSchedule
    Template for the menu 'Schedule'.

MenuSearchResults
    Template for the menu 'Search results'.

MenuFavorites
    Template for the menu 'Favorites'.

For example:

    MenuWhatsOnNow=%chnr%:3|%progrt2s%:5| %time% %t_status%:8|%category%:6| %title% ~ %subtitle%:35
    MenuWhatsOnNext=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
    MenuWhatsOnElse=%chnr%:3|%time% %t_status%:8|%category%:8| %title% ~ %subtitle%:35
    MenuSchedule=%time% %t_status%:8|%genre%:14| %title% ~ %subtitle%:35
    MenuSearchResults=%chnr%:3|%datesh% %time% %t_status%:14|%genre%:8| %title%%colon% %subtitle%:35
    MenuFavorites=%chnr%:3|%time%:6|%timespan%:7|%t_status%:14|%genre%:8| %title%%colon%%subtitle%:35

The entry 'MenuWhatsOnNow' instructs EPGSearch how to format a line for the menu 'Now': The menu's line will start with the channel number, followed by a progress bar in text2skin style, a single space, the start time, the timer status, the value of the EPG category named 'Category' (e.g., "Movie") and, finally, the title and subtitle.

The values for 'MenuWhatsOnNext', 'MenuWhatsOnElse', 'MenuSchedule', 'MenuSearchResults' and 'MenuFavorites' specify the menu settings for 'Next', the menu of a user-defined time, 'Schedule', 'Search results', and 'Favorites', respectively. Without a corresponding entry, EPGSearch uses a menu's default layout.

The entry 'MenuSearchResults' has a special feature: If different layouts for search results are desired depending on the search, more than one menu template can be provided. For example, suppose the following entry gets added:

    MenuSearchResultsTip of the Day=%chnr%:3|%time_w%:4|%t_status%:3|%genre%:10|%title%%colon% %subtitle%:35

This will result in an additional menu item 'Result menu layout' in the menu 'Edit search' that allows choosing between the menu's default template and own templates. For the example above, 'Tip of the Day' will be listed as additional option, since EPGSearch simply strips the prefix 'MenuSearchResults'. When displaying the search results, the chosen layout will be used instead of the default one.

The following variables exist (case ignored):

%Time%
    An event's start time in 'HH:MM' format.

%TimeEnd%
    An event's end time in 'HH:MM' format.

%Time_D%
    An event's start date in 'DD' format.

%Time_W%
    Name of the weekday on which an event starts.

%Time_Lng%
    An event's start date and time in Epoch encoding (i.e., seconds since 1970-01-01 00:00 UTC).

%TimeSpan%
    Time span til the start of an event (like 'in 15m') or the time an event is already running (like '10m').

%Date%
    An event's start date in 'DD.MM.YY' format.

%DateSh%
    An event's start date in 'DD.MM' format.

%Date_ISO%
    An event's start date in 'YYYY-MM-DD' format.

%Day%
    An event's start day (1..31).

%Week%
    Calendar week of an event's start date (01..53).

    According to the ISO 8601 standard, Monday is the first day of a week. Calendar week 1 is the first week where four or more days fall within the new year, that is, the first week that contains a Thursday or has January 4 in it.

%Month%
    An event's start month (1..12).

%Year%
    An event's start year (1970..2038, or even later).

%EventID%
    An event's numeric identifier.

%LiveEventID%
    An event's identifier as used in the front end live.

%Title%
    An event's title.

%Subtitle%
    An event's subtitle.

%Summary%
    An event's summary.

%HtmlSummary%
    An event's summary with all line feeds replaced by '<br />'.

    Caution: The HTML reserved characters '<&">' will not be replaced by their substitutes '&lt;', '&amp;', '&quot;' and '&gt;'.

%<EPG Category>%
    An event's value of the respective EPG category as specified in epgsearchcats.conf, like '%Genre%' or '%Category%'.

%Length%
    An event's length in seconds.

%Status%
    An event's status (the same as '%T_Status%%V_Status%%R_Status%').

%T_Status%
    A timer's status ('T', 't', or 'R'), else a space.

%V_Status%
    An event's VPS status, else a space.

%R_Status%
    An event's running status, else a space.

For the menus of user-defined times and the menu 'Search results', there are also:

%ChNr%
    An event's channel number.

%ChSh%
    The short name of an event's channel.

%ChLng%
    The long name of an event's channel.

%ChData%
    The VDR's internal channel representation (e.g., 'S19.2E-1-1101-28106').

%Progr%
    A graphical progress bar; not available for the menu 'Search results'. The VDRSymbols font must be installed to display it.

%ProgrT2S%
    A progress bar in text2skin style; not available for the menu 'Search results'.

And, finally, some common variables:

%TimeNow%
    The current time in 'HH:MM' format.

%DateNow%
    The current date in 'DD.MM.YY' format.

%DateShNow%
    The current date in 'DD.MM' format.

%Date_ISO_Now%
    The current date in 'YYYY-MM-DD' format.

%VideoDir%
    The VDR's video directory (e.g., /video).

%PlugConfDir%
    The VDR's plugin configuration directory (e.g., /etc/vdr/plugins).

%EPGSearchDir%
    The EPGSearch configuration directory (e.g., /etc/vdr/plugins/epgsearch)

%Colon%
    The ':' character.

You can also use variables for extended EPG categories defined in epgsearchcats.conf or use your own variables defined in epgsearchuservars.conf. Variable names are not case sensitive.

An entry consists of up to six table columns, separated with '|' characters. The last entry of each table row should declare the table width in characters, separated with a ':' character.

When using characters like '~', '-' or '#' to separate items (e.g., '%Title% ~ %Subtitle%') with trailing elements being empty, EPGSearch will attempt to remove orphaned spaces and separators.

You should vary the tabulation-width values to fit your needs, since the look often depends on the selected skin.

The file epgsearchmenu.conf is not reloaded with every plugin call, since this is only useful when testing the configuration file itself. To activate permanent reloading the file during testing a configuration change, add the start parameter '−r' or '−−reloadmenuconf' in the VDR's start script (e.g., runvdr).

There's a sample epgsearchmenu.conf in the subdirectory conf. To quickly trying out, copy the file to the EPGSearch configuration directory (e.g., /etc/vdr/plugins/epgsearch).

To enable icons from the font VDRSymbols, simply put the line:

    WarEagleIcons=1

into epgsearchmenu.conf. The font VDRSymbols is available at <http://andreas.vdr-developer.org/fonts/download.html>.

Note: Once a file epgsearchmenu.conf is present and includes an entry for a certain menu, the default settings for displaying this menu are ignored.

See also epgsearchmenu.conf(5).

11. Working with the timer-conflict menu
If a conflict is detected within the periodic background conflict check, an an OSD message will notify about this conflict. Pressing 'OK' will raise a menu that displays all relevant conflicts. This menu can also be opened in EPGSearch navigating to 'Search entries' » 'Actions' » 'Timer conflict check'.

Besides the relevant conflicts (relevance is controlled via the setup options of EPGSearch), conflicts not classified as important may have been detected as well. Pressing 'Show all' will display the complete list. The title of the timer-conflict menu will always displays the number of relevant conflicts and the total number.

The list first displays the time when a conflict appears, followed by all timers that will be affected. Each timer entry includes the channel number and name, the timer's priority, and the percentage of how much of the event will be recorded. Finally, the timer's file entry is displayed.

Selecting a timer's entry and pressing 'OK' or invoking 'Details' opens a new menu that displays all concurrent timers. This menu allows resolving the conflict by:

•   searching for the repeat of an event

•   disabling or deleting a timer

•   changing the timers' start or stop time, or alternatively its priority

•   executing other commands on this timer

An entry of this menu consists of the '>' character to indicate an active timer, the channel number, the start and stop times, the priority, the number of the device that will be used for recording (or 'C' for a conflict) and the timer's file entry. Pressing 'OK' on a timer entry will show its event description, if present.

When returning from this menu, the conflict-overview menu will be updated to see if a conflict was really resolved. Some changes of a timer in the conflict-details menu (like modifying start/stop times or deleting a timer) will also bring up the updated conflict-overview menu.

Note: A "hidden" setup option 'ConflCheckCmd' allows executing a command for each timer causing a conflict. This command must directly be entered in the VDR's setup.conf like this:

    epgsearch.ConflCheckCmd = system(your_script_handling_the_conflict.sh, any_arguments like %Timer.File%)

    Please refer to "12.3 Calling a system command" below for the possible arguments.

The command is evaluated for each timer causing a conflict whenever an automatic conflict check is performed. The command will not be evaluated when invoking the conflict check though the OSD.

As an example for its purpose, this mechanism could be employed for forwarding a timer to another VDR machine in case of a conflict.

12. User-defined variables
Own variables can be used wherever variables are supported, like the default recording directory for manually created timers, the recording directory of a search timer, or in customized EPG menus. They are defined in the file epgsearchuservars.conf.

A variable has the syntax '%VariableName%'. Its name can comprise all alphanumeric characters, but no spaces or other special characters.

Examples for possible names:

    %Series%
    %DocuVar1%
    %ThemesSubtitleDate%

Variable names are case-insensitive.

  12.1 Assignment
Variables always get assigned strings whose spaces are retained. This is illustrated by the following examples:

    %Series%=New series~Thrillers

The variable '%Series%' will be assigned the string "New series~Thrillers". This can be used arbitrarily:

    %Path%=%Series%

The variable '%Path%' gets the content of the variable '%Series%' assigned.

    %Path%=%Series%~Lost

The variable '%Path%' contains the string "New series~Thrillers~Lost".

  12.2 Conditional assignment
Simple if-then-else constructs for assignments are supported by means of conditional expressions 'if ? then : else'. Conditional expressions cannot contain strings, only variables; spaces are ignored.

    %Foo%=Other
    %Variable%=%Path% ? %Path% : %Foo%

For the ternary operator '?:', the expression '%Path% ?' means "path not empty?". If this is true, '%Variable%' gets assigned the content of '%Path%', else the content of '%Foo%'.

Other checks are supported as well:

    == equal
    != not equal

Thus, for example:

    %Variable%=%Path%!=5 ? %Path% : %Foo%

The condition '%Path%!=5 ?' means "is '%Path%' not equal 5?".

Comparing variables is also feasible:

    %Five%=5
    %Variable%=%Path%!=%Five% ? %Path% : %Foo%

  12.3 Calling a system command
External commands can be called during variable evaluation as well. The returned string will be assigned to the respective variable:

    %UserVar%=system(<script-name>[, <parameters>])

Calls the script script-name with the parameters supplied by the optional list 'parameters'. Such a parameter can be an arbitrary expression, optionally containing other variables, but no system call or conditional expression.

Example:

    %Result%=system(/usr/local/bin/my-script.sh, -t %Title% -s %Subtitle% -u %MyOtherVar%)

Variables used as parameters will be enclosed in single quotes (apostrophes), if needed.

The script should return a string without line feeds, since their removal may cause undesired results. If the script does not return anything, an empty string will be assigned to the variable '%Result%'.

  12.4 Calling a TCP service
A TCP service can be called with the following syntax:

    %Result%=connect(<address>, <port>, [<data>])

This will connect to 'address' through the given 'port' and pass the optional 'data'. The parameter 'address' can be an IP address or the domain name of a TCP service. The result returned by the service must be terminated with a line feed.

  12.5 Length of arguments
When passing values to the connect or system command, it can be helpful to have the length of an argument for simple parsing. The length can be retrieved by:

    %Result%=length(<any arguments>)

Example:

    %TitleLength%=length(%title%)

  12.6 Other variables
Refer to the section "Customizing the EPG menus" for a list of built-in variables. Furthermore, every variable defined in epgsearchcats.conf can be used; see epgsearchcats.conf(5).

  12.7 Examples
    # Weekday, Date, Time
    %DateStr%=%time_w% %date% %time%

    # Themes or Subtitle or Date
    %SubtitleDate%=%Subtitle% ? %Subtitle% : %DateStr%
    %ThemesSubtitleDate%=%Themes% ? %Themes% : %SubtitleDate%

    # Calls a script to get a recording path
    %DocuScript%=system(docu.pl, -t %Title% -s %Subtitle% -e %Episode% -th %Themes% -c %Category% -g %Genre%)
    %Docu%=%DocuScript%

13. E-mail notifications
EPGSearch can send e-mail notifications when timers get added, modified, or removed by the search-timer thread, or when timer conflicts have been detected.

  13.1 Setting up e-mail notifications
First, copy the script sendEmail.pl to the place where executables are located (e.g., /usr/local/bin) and configure the e-mail accounts in the setup. Press 'Test' to check if sending and receiving e-mails works. A message like 'Email successfully sent' should appear at the end of the output.

The content of the e-mails is defined by the files:

epgsearchupdmail.templ
    Template for the notification of search-timer updates.

epgsearchconflmail.templ
    Template for the notification of timer conflicts.

Sample files are included in the conf directory. Copy them to the EPGSearch configuration directory (e.g., /etc/vdr/plugins/epgsearch) and adapt them as needed.

  13.2 Customizing the notification e-mails
The content of the e-mails can be customized in many ways. E-mails can contain plain text or HTML (see the sample conf/epgsearchupdmail-html.templ).

13.2.1 Update-notification e-mails

For an update-notification e-mail, the following sections must be defined:

Subject
    The term to be used as e-mail subject.

MailBody
    The body of the e-mail. Variables control which information to be inserted at which location within the body text.

    The variable '%Update.NewTimers%' inserts the list of new timers. Likewise, the variables '%Update.ModTimers%', '%Update.DelTimers%', and '%Update.NewEvents%' insert the list of changed or deleted timers and event announcements. Their appearance is controlled by the sections 'Timer' and 'Event'.

Timer
    Template for the representation of an individual timer. This section is used to format a timer within a timer list, like in '%Update.NewTimers%'.

Event
    Template for the representation of an individual event. This section is used to format an event within an event list, like in '%Update.NewEvents%'.

All sections are optional. If, for instance, not using event notifications, both the sections '%Update.NewEvents%' in the mail body and the 'Event' template can be dropped. Nevertheless, the section 'MailBody' must remain.

Each section is enclosed with a pseudo XML tag. Their spelling is not case-sensitive.

13.2.1.1 Section 'MailBody'

The following variables can be used in the section 'MailBody':

%Update.NewTimers%
    Will be replaced with the list of new timers created with this update. The timers are formatted as defined in the section 'Timer'.

%Update.CountNewTimers%
    The number of new timers.

%Update.ModTimers%
    Same as '%Update.NewTimers%', but for the modified timers.

%Update.CountModTimers%
    The number of modified timers.

%Update.DelTimers%
    Same as '%Update.NewTimers%', but for the deleted timers.

    Note: A deleted timer possibly has no event assigned to it. In such a case, all event variables within the 'Timer' section will be substituted by an empty string.

%Update.CountDelTimers%
    The number of deleted timers.

%Update.NewEvents%
    Will be replaced with the list of events to be announced. These events result from search timers with the action 'Announce by mail'. The events are formatted as defined in the section 'Event'.

%Update.CountNewEvents%
    The number of new events.

%DateNow%
    The current date in 'DD.MM.YY' format.

%DateShNow%
    The current date in 'DD.MM' format.

%TimeNow%
    Current time in 'HH:MM' format.

%Colon%
    The ':' character.

13.2.1.2 Section 'Timer'

The following variables can be used in the section 'Timer':

%Timer.Date%
    The start date of the timer.

%Timer.Start%
    A timer's start time.

%Timer.Stop%
    A timer's stop time.

%Timer.File%
    A timer's recording directory.

%Timer.ChNr%
    A timer's channel number.

%Timer.ChSh%
    The short name of a timer's channel.

%Timer.ChLng%
    The long name of a timer's channel.

%Timer.Search%
    The search term that created a timer.

%Timer.SearchID%
    The identifier of the search that created a timer.

%Timer.LiveID%
    A timer's identifier as used in the front end live.

%Timer.ModReason%
    The reason for a timer modification in plain text.

%<Event Variable>%
    See "10. Customizing the EPG menus".

%<EPG Category>%
    An event's value of the respective EPG category as specified in epgsearchcats.conf, like '%Genre%' or '%Category%'.

%<User Variable>%
    See "12. User-defined variables".

13.2.1.3 Section 'Event'

The following variables can be used in the section 'Event':

%Search%
    The search term that triggered the event.

%SearchID%
    The identifier of the search that triggered the event.

%<Event Variable>%
    See "10. Customizing the EPG menus".

%<EPG Category>%
    An event's value of the respective EPG category as specified in epgsearchcats.conf, like '%Genre%' or '%Category%'.

%<User Variable>%
    See "12. User-defined variables".

13.2.2 Conflict-notification e-mails

For a conflict-notification e-mail, the following sections exist:

Subject
    The term to be used as e-mail subject.

MailBody
    The body of the e-mail. Variables control which information to be inserted at which location within the body text.

    The variable '%Conflict.Conflicts%' inserts the list of conflicting times. The conflicts are formatted as defined in the section 'ConflictsAt'.

    Note: More than just one timer conflict can occur for the same time.

ConflictsAt
    Template for the representation of the time at which one or more conflicts have occurred.

ConflTimer
    The description of a conflicting timer.

13.2.2.1 Section 'MailBody'

The following variables can be used in the section 'MailBody':

%Conflict.Count%
    The number of all timer conflicts, including both relevant and irrelevant conflicts.

%Conflict.Conflicts%
    The list of times with conflicting timers.

13.2.2.2 Section 'ConflictsAt'

The following variables can be used in the section 'ConflictsAt':

%Conflict.Date%
    The date of the conflict.

%Conflict.Time%
    The time of the conflict.

%Conflict.ConflTimers%
    The list of conflicting timers for this time.

13.2.2.3 Section 'ConflictTimer'

The section 'ConflictTimer' can use the same variables as the section 'Timer' in an update e-mail (see above).

14. The conf.d directory
EPGSearch supports a configuration mechanism well-known in Linux. This applies to the settings of the following configuration files:

•   epgsearchuservars.conf

•   epgsearchdirs.conf

•   epgsearchmenu.conf

•   epgsearchcats.conf

Their settings also be provided by a single file with arbitrary name in the subdirectory conf.d in the plugin's configuration directory (e.g., /etc/vdr/plugins/epgsearch/conf.d). This allows quickly testing different setups by just exchanging files instead of editing them. The format of files within conf.d is:

    [<section name>]
    <settings>
    ...

    [<section name>]
    <settings>
    ...

A 'section name' is one of the following keywords:

•   epgsearchuservars

•   epgsearchdirs

•   epgsearchmenu

•   epgsearchcats

The format of 'settings' is the same as in the corresponding configuration file. Comments beginning with a '#' character and blank lines are both allowed.

At startup, EPGSearch first reads its "regular" configuration files and then inspects the conf.d subdirectory. Variables already defined in other files can be overwritten, although this is signaled with a warning in the EPGSearch log file.

AUTOREN (Man-Pages)
Ursprünglich erstellt von Mike Constabel <epgsearch (at) constabel (dot) net>.

Überarbeitet und an die aktuellen Features von EPGSearch adaptiert durch die derzeitigen Maintainer.

PROJEKTSEITE
Das Plugin wird als Projekt auf GitHub geführt:

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

FEHLER MELDEN
Fehlerberichte sowie Feature-Anfragen können über den Bugtracker des Projekts eingespeist werden:

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

COPYRIGHT und LIZENZ
Copyright © 2004-2010 Christian Wieninger

Copyright © 2011-2025 TomJoad (VDR-Portal) et al.

Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 2 der Lizenz oder (nach Ihrer Option) jeder späteren Version.

Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, dass es Ihnen von Nutzen sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN ZWECK. Details finden Sie in der GNU General Public License.

Sie sollten ein Exemplar der GNU General Public License zusammen mit diesem Programm erhalten haben. Falls nicht, schreiben Sie an die Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. Oder rufen Sie in Ihrem Browser <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html> auf.

Der ursprüngliche Autor kann über cwieninger@gmx.de erreicht werden.

Die aktuellen Maintainer können über die Projektseite auf GitHub (siehe oben) erreicht werden.

Der MD5-Code ist abgeleitet aus dem Message-Digest-Algorithmus MD5 von RSA Data Security, Inc.

SIEHE AUCH
epgsearch(1), epgsearchblacklists.conf(5), epgsearchcats.conf(5), epgsearchchangrps.conf(5), epgsearchcmds.conf(5), epgsearchdirs.conf(5), epgsearchdone.data(5), epgsearchmenu.conf(5), epgsearchswitchtimer.conf(5), epgsearchuservars.conf(5)