vdr/FORMATS

Video Disk Recorder File Formats
--------------------------------

* channels.conf

  This file contains the channel setup.
  It consists of two types of lines: "group delimiters" and "channel
  definitions".

  A "group delimiter" is a line starting with a ':' as the very first
  character, followed by arbitrary text.
  Example: ":First group"

  A "channel definition" is a line with channel data, where the fields
  are separated by ':' characters:
  Example: "RTL:12188:h:1:27500:163:104:105:0:12003"

  The fields in a channel definition have the following meaning (from left
  to right):

  - Name: the channel's name (if the name originally contains a ':' character
    it has to be replaced by '|')
  - Frequency in MHz for DVB-S and DVB-C, kHz for DVB-T (as an integer)
  - Polarization (one of 'h', 'H', 'v', 'V') **
  - Diseqc number **
  - Symbol rate ***
  - Video PID (set to '0' for radio channels, '1' for encrypted radio channels)
  - Audio PID (either one number, or two, separated by a comma)
    If this channel also carries Dolby Digital sound, the Dolby PIDs follow
    the audio PIDs, separated by a semicolon, as in "...:101,102;103,104:..."
  - Teletext PID
  - Conditional Access (0 = Free To Air, 1..4 = explicitly requires the DVB card
    with the given number, >=100 = requires a specific decryption method defined
    in 'ca.conf').
  - Program Number

  Fields marked with ** are only meaningful for DVB-S receivers.
  DVB-C and DVB-T receivers simply ignore these.
  Fields marked with *** are only meaningful for DVB-S and DVB-C receivers.
  DVB-T receivers simply ignore these.

* ca.conf

  This file contains the definitions of the various conditional access code
  numbers. Anything after (and including) a '#' character is comment.
  Value lines consist of an integer number, followed by a text describing
  this decryption method (typically the name of the pay tv service using this
  decryption method).
  The special value 0 means "Free To Air", i.e. can be used for channels that
  don't require additional decryption hardware.
  The values 1..4 can be used for channels that for some reason explicitly
  need a given DVB card (for backward compatibility).
  The values defined in this file are the ones used in the 'Ca' parameter of
  'channels.conf'.

* timers.conf

  This file contains the timer setup.

  The fields in a timer definition have the following meaning (from left
  to right):

  - Timer active (0 = inactive, 1 = active, 3 = instant recording)
    Values other than these can be used by external programs to mark active timers
    and recognize if the user has modified them. When a user modifes an active
    timer the 'active' field will be explicitly set to '1' (or '0', respectively,
    if the user deactivates the timer).
    Note: in order to allow future extensibility, external programs using the
    'active' parameter should only use the upper 16 bit of this 32 bit parameter
    and leave the lower 16 bit untouched.
  - Program number of the channel to record
  - Day of recording (in case of a repeating timer), either one or more of
      M------ = Monday
      -T----- = Tuesday
      --W---- = Wednesday
      ---T--- = Thrusday
      ----F-- = Friday
      -----S- = Saturday
      ------S = Sunday
    (any combination is possible, for example MTWTF--, and the days may be
    indicated by any characters except '-', so for example ABC---- would set
    a timer that records on monday, tuesday and wednesday) or the "day of month"
    (1..31) in case of a single shot timer.
    The day definition of a repeating timer may be followed by the date when that
    timer shall hit for the first time. The format for this is @YYYY-MM-DD,
    so a complete definition could look like this: MTWTF--@2002-02-18. This
    "first day" feature can be used to disable a repeating timer for a couple
    of days, or for instance to define a new Mon...Fri timer on wednesday, which
    actually starts "monday next week". The "first day" date given need not be
    that of a day when the timer would actually hit.
  - Start time (first two digits for the hour, second two digits for the minutes)
  - End time (first two digits for the hour, second two digits for the minutes)
  - Priority (from 0 to 99, 0 = lowest prioity, 99 = highest priority)
  - Guaranteed lifetime of recording (in days); 0 means that this recording may
    be automatically deleted by a new recording with higher priority, 99 means
    that this recording will never be automatically deleted
  - Name of timer (will be used to name the recording); if the name contains
    any ':' characters, these have to be replaced with '|'. If the name shall
    contain subdirectories, these have to be delimited by '~' (since the '/'
    character may be part of a regular programme name).
    The special keywords TITLE and EPISODE, if present, will be replaced 
    with the title and episode information from the EPG data at the time of
    recording (if that data is available). If at the time of recording either
    of these cannot be determined, TITLE will default to the channel name, and
    EPISODE will default to a blank.
  - Summary (any newline characters in the summary have to be replaced with '|';
    the summary may contain ':' characters)

* setup.conf

  This file contains the basic configuration options for VDR.

  Each line contains one option in the format "Name = Value".

  See the MANUAL file for a description of the available options.

* commands.conf

  This file contains the definitions of commands that can be executed from
  the "VDR" menu's "Commands" option.

  Each line contains one command definition in the following format:

    title : command

  where 'title' is the string the will be displayed in the "Commands" menu,
  and 'command' is the actual command string that will be executed when this
  option is selected. The delimiting ':' may be surrounded by any number of
  white space characters.

  In order to avoid error messages to stderr, every command should have
  stderr redirected to stdout. Everything the command prints to stdout will
  be displayed in a result window, with 'title' as its title.

  Examples:

   Check for new mail: /usr/local/bin/checkmail 2>&1
   CPU status        : /usr/local/bin/cpustatus 2>&1
   Disk space        : df -h | grep '/video' | awk '{ print 100 - $5 "% free"; }'

* svdrphosts.conf

  This file contains the IP numbers of all hosts that are allowed to access the
  SVDRP port.

  Each line contains one IP number in the format

    IP-Address[/Netmask]

  where 'IP-Address' is the address of a host or a network in the usual dot
  separated notation (as in 192.168.100.1). If the optional 'Netmask' is given
  only the given number of bits of 'IP-Address' are taken into account. This
  allows you to grant SVDRP access to all hosts of an entire network. 'Netmask'
  can be any integer from 1 to 32. The special value of 0 is only accepted if
  the 'IP-Address' is 0.0.0.0, because this will give access to any host (USE
  THIS WITH CARE!).

  Everything following (and including) a '#' character is considered to be
  comment.

* marks.vdr

  This file (if present in a recording directory) contains the editing marks
  defined for this recording.

  Each line contains the definition of one mark in the following format:

    hh:mm:ss.ff comment

  where 'hh:mm:ss.ff' is a frame position within the recording, given as "hours,
  minutes, seconds and (optional) frame number". 'comment' can be any string
  and may be used to describe this mark. If present, 'comment' must be separated
  from the frame position by at least one blank.

  The lines in this file need not necessarily appear in the correct temporal
  sequence, they will be automatically sorted by time index.

  CURRENT RESTRICTIONS:

  - the 'comment' is currently not used by VDR
  - marks must have a frame number, and that frame MUST be an I-frame (this
    means that only marks generated by VDR itself can be used, since they
    will always be guaranteed to mark I-frames).

* 001.vdr ... 255.vdr

  These are the actual recorded MPEG data files. In order to keep the size of
  an individual file below a given limit, a recording is split into several
  files. The contents of these files is "Packetized Elementary Stream" (PES)
  and contains ES packets with ids 0xE0 for video, 0xC0 for audio 1 and 0xC1
  for audio 2 (if available). Dolby Digital data is stored in packets with
  ids 0xBD.

* epg.data

  This file contains the EPG data in an easily parsable format. The first
  character of each line defines what kind of data this line contains.

  The following tag characters are defined:

  C <service id> <channel name>
  E <event id> <start time> <duration> <table id>
  T <title>
  S <subtitle>
  D <description>
  e
  c

  Lowercase characters mark the end of a sequence that was started by the
  corresponding uppercase character. The outer frame consists of a sequence
  of one or more 'C'...'c' (Channel) entries. Inside these any number of
  'E'...'e' (Event) entries are allowed. The 'T', 'S' and 'D' entries are
  optional (although every event should at least have a 'T' entry).

  <service id>   is the "program number" as defined in 'channels.conf'
  <channel name> is the "name" as in 'channels.conf' (for information only)
  <start time>   is the time (as a time_t integer) in UTC when this event starts
  <duration>     is the time (in seconds) that this event will take
  <table id>     is a hex number that indicates the table this event is contained
                 in (if this is left empty or 0 this event will not be overwritten
                 or modified by data that comes from the DVB stream)
  <title>        is the title of the event
  <subtitle>     is the subtitle (typically the name of the episode etc.)
  <description>  is the description of the event

  This file will be read at program startup in order to restore the results of
  previous EPG scans.