epgsearch.conf(5)

NAME
epgsearch.conf – searches and search timers

DESCRIPTION
This file contains the searches and search timers created by EPGSearch.

The file should not be edited manually. Better use the plugin's menus, its SVDRP interface or supplemental front ends (like live) for creating, editing, or deleting searches and search timers.

SYNTAX
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" in epgsearch(4) 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.

EXAMPLE
 1:Columbo:0:::2:Public broadcasting:1:3:1:0:0:0:::1:0:0:1:%Category%~%Genre%:50:99:10:60:0:0:0::1:0:1:1:0:0:0:0:0
 2:Schwarzenegger:0:::2:Major stations:0:0:0:0:0:0:::0:0:0:0:%Category%~%Genre%:50:99:10:10:0:0:1:1#|2#|3#|4#|5#|6#Arnold Schwarzenegger|7#|8#|9#|10#|11#|12#|13#:1:0:1:0:0:0:0:0:0

AUTHORS (man pages)
Originally provided by Mike Constabel <epgsearch (at) constabel (dot) net>.

Revised and adapted to recent plugin features by the current maintainers.

PROJECT SITE
The plugin is maintained as GitHub project:

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

REPORTING BUGS
Issues can be reported, and features be suggested, through the project's bug tracker:

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

COPYRIGHT and LICENSE
Copyright (C) 2004-2010 Christian Wieninger

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

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Or, point your browser to <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

The original author can be reached via cwieninger@gmx.de.

Current maintainers can be reached via the project's GitHub site (see above).

The MD5 code has been derived from the MD5 Message-Digest Algorithm of RSA Data Security, Inc.

SEE ALSO
epgsearch(1), epgsearch(4)