vdr/vdr.5

'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for vdr file formats
.\"
.\" Copyright (C) 2021 Klaus Schmidinger
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file COPYING that comes with the
.\" vdr distribution.
.\"
.\" $Id: vdr.5 5.5 2021/12/27 13:31:04 kls Exp $
.\"
.TH vdr 5 "27 Dec 2021" "2.6" "Video Disk Recorder Files"
.SH NAME
vdr_files \- the Video Disk Recorder Files
.SH DESCRIPTION
This page describes the formats of the various files \fBvdr\fR uses to
store configuration data and recordings.
.SH SYNTAX
.SS CHANNELS
The file \fIchannels.conf\fR contains the channel configuration.
Each line defines either a \fBgroup delimiter\fR or a \fBchannel\fR.

A \fBgroup delimiter\fR is a line starting with a ':' as the very first
character, followed by arbitrary text. Example:

\fB:First group\fR

Group delimiters may also be used to specify the number of the next channel.
To do this, the character '@' and a number must immediately follow the ':',
as in

\fB:@201 First group\fR

The given number must be larger than the number of any previous channel
(otherwise it is silently ignored).

A group delimiter can also be used to just set the next channel's number,
without an explicit delimiter text, as in

\fB:@201\fR

Such a delimiter will not appear in the Channels menu.

A \fBchannel definition\fR is a line with channel data, where the fields
are separated by ':' characters. Example:

.TS
tab (@);
l.
\fBRTL Television,RTL;RTL World:12187:hC34M2O0S0:S19.2E:27500:163=2:104=deu;106=deu:105:0:12003:1:1089:0\fR
.TE

The line number of a channel definition (not counting group separators,
and based on a possible previous '@...' parameter)
defines the channel's number in OSD menus and the \fItimers.conf\fR file.

The fields in a channel definition have the following meaning (from left
to right):
.TP
.B Name
The channel's name (if the name originally contains a ':' character
it has to be replaced by '|').
Some TV stations provide a way of deriving a "short name" from the
channel name, which can be used in situations where there is not
much space for displaying a long name. If a short name is available
for this channel, it follows the full name and is delimited by a comma,
as in

\fBRTL Television,RTL:...\fR

If the short name itself would contain a comma, it is replaced with a '.'.
Note that some long channel names may contain a comma, so the delimiting comma
is always the rightmost one.

If present, the name of the service provider or "bouquet" is appended
to the channel name, separated by a semicolon, as in

\fBRTL Television,RTL;RTL World:...\fR
.TP
.B Frequency
The transponder frequency (as an integer). For DVB-S this value is in MHz. For DVB-C
and DVB-T it can be given either in MHz, kHz or Hz (the actual value given will be
multiplied by 1000 until it is larger than 1000000).
.TP
.B Parameters
Various parameters, depending on whether this is a DVB-S, DVB-C or DVB-T channel.
Each parameter consist of a key character, followed by an integer number that
represents the actual setting of that parameter. The valid key characters, their
meaning (and allowed values) are
.TS
tab (@);
l l.
\fBB\fR@Bandwidth (1712, 5, 6, 7, 8, 10)
\fBC\fR@Code rate high priority (0, 12, 23, 34, 35, 45, 56, 67, 78, 89, 910)
\fBD\fR@coDe rate low priority (0, 12, 23, 34, 35, 45, 56, 67, 78, 89, 910)
\fBG\fR@Guard interval (4, 8, 16, 32, 128, 19128, 19256)
\fBH\fR@Horizontal polarization
\fBI\fR@Inversion (0, 1)
\fBL\fR@Left circular polarization
\fBM\fR@Modulation (2, 5, 6, 7, 10, 11, 12, 16, 32, 64, 128, 256, 999)
\fBN\fR@pilot mode (0, 1, 999)
\fBO\fR@rollOff (0, 20, 25, 35)
\fBP\fR@stream id (0-255)
\fBQ\fR@t2 system id (0-65535)
\fBR\fR@Right circular polarization
\fBS\fR@delivery System (0, 1)
\fBT\fR@Transmission mode (1, 2, 4, 8, 16, 32)
\fBV\fR@Vertical polarization
\fBX\fR@siso/miso mode (0, 1)
\fBY\fR@hierarchY (0, 1, 2, 4)
.TE

\fBBandwidth:\fR The bandwidth of the channel in MHz (1712 in kHz): (DVB-T/DVB-T2 only).

\fBCode rate high priority:\fR Forward Error Correction (FEC) of the high priority stream (DVB-T/DVB-T2).
For DVB-S/DVB-S2 this parameter specifies the inner FEC scheme.
12 = 1/2, 23 = 2/3, 34 = 3/4, ...

\fBCode rate low priority:\fR Forward Error Correction (FEC) of the low priority stream (DVB-T/DVB-T2 only).
If no hierarchy is used, set to 0.

\fBGuard interval:\fR The guard interval value (DVB-T only): 4 = 1/4, 8 = 1/8, 16 = 1/16, 32 = 1/32, 128 = 1/128, 19128 = 19/128, 19256 = 19/256.

\fBInversion:\fR Specifies whether the DVB frontend needs spectral inversion (DVB-T and DVB-C only). This is frontend specific, if in doubt, omit.

\fBModulation:\fR Specifies the modulation/constellation of the channel as follows:
.TS
tab (@);
l l.
\fB2\fR@QPSK (DVB-S, DVB-S2, DVB-T, DVB-T2, ISDB-T)
\fB5\fR@8PSK (DVB-S, DVB-S2)
\fB6\fR@16APSK (DVB-S2)
\fB7\fR@32APSK (DVB-S2)
\fB10\fR@VSB8 (ATSC aerial)
\fB11\fR@VSB16 (ATSC aerial)
\fB12\fR@DQPSK (ISDB-T)
\fB16\fR@QAM16 (DVB-T, DVB-T2, ISDB-T)
\fB32\fR@QAM32
\fB64\fR@QAM64 (DVB-C, DVB-T, DVB-T2, ISDB-T)
\fB128\fR@QAM128 (DVB-C)
\fB256\fR@QAM256 (DVB-C, DVB-T2)
.TE

\fBPilot mode:\fR The pilot mode (0 = "off", 1 = "on", 999 = "auto") for DVB-S2 multiplex (DVB-S2 only).

\fBRolloff:\fR The Nyquist filter rolloff factor for DVB-S (\fB35\fR) and DVB-S2 (\fB35\fR, 25, 20),
35 = 0.35, 25 = 0.25, 20 = 0.20, DVB-S/DVB-S2 default value is 0.35

\fBStream id:\fR Input Stream Identifier (ISI) (\fB0\fR-255) for DVB-S2 multiplex or
Physical Layer Pipe (PLP) id (\fB0\fR-255) for DVB-T2 multiplex (DVB-S2/DVB-T2 only,
with devices that support "multi streaming").

\fBT2 System id:\fR Unique identifier (\fB0\fR-65535) of T2 system within the DVB network (DVB-T2).

\fBTransmission mode:\fR Number of DVB-T OFDM carriers, 32 = 32k, 16 = 16k, 8 = 8k, 4 = 4k, 2 = 2k, 1 = 1k. If in doubt, try 8k.

\fBSISO/MISO mode:\fR Specifies the Single-Input/Multiple-Input Single-Output mode (\fB0\fR = SISO, 1 = MISO) (DVB-T2).

\fBHierarchy:\fR If set to 1, this transponder uses two streams, high priority and low priority.
If in doubt, try 0 (off). (DVB-T/DVB-T2 only).

\fBDelivery System:\fR The delivery system (0 = "first generation" (DVB-S/DVB-T), 1 = "second generation" (DVB-S2/DVB-T2).

\fBPolarization:\fR Satellite antenna polarization.
H = horizontal, V = vertical, R = circular right, L = circular left.

The polarization parameters have no integer numbers following them. This is for
compatibility with files from older versions and also to keep the DVB-S entries
as simple as possible.

The special value \fB999\fR is used for "automatic", which means the driver
will automatically determine the proper value (if possible).

An example of a parameter field for a DVB-T channel might look like this:
\fBB8C23D12G8M16T8Y0S0\fR

An example of a parameter field for a DVB-T2 channel might look like this:
\fBB8C23D12G8M16T8Y0P0S1\fR

An example of a parameter field for a DVB-C channel might look like this:
\fBC0M64\fR

An example of a parameter field for a DVB-S channel might look like this:
\fBHC56M2O35S0\fR

An example of a parameter field for a DVB-S2 channel might look like this:
\fBHC910M2O35S1\fR

Plugins that implement devices that need their own set of parameters may
store those in the parameters string in arbitrary format (not necessarily
the "character/number" format listed above). The only condition is that
the string may not contain colons (':') or newline characters.
.TP
.B Source
The signal source of this channel, as defined in the file \fIsources.conf\fR.
.TP
.B Srate
The symbol rate of this channel (DVB-S and DVB-C only).
.TP
.B VPID
The video PID (set to '0' for radio channels).
If this channel uses a separate PCR PID, it follows the VPID, separated by a
plus sign, as in

.B ...:164+17:...

If this channel has a video mode other than 0, the mode
follows the pids, separated by an '=' sign, as in

.B ...:164+17=27:...
.TP
.B APID
The audio PID (either one number, or several, separated by commas).
If this channel also carries Dolby Digital sound, the Dolby PIDs follow
the audio PIDs, separated by a semicolon, as in

.B ...:101,102;103,104:...

If certain audio PIDs broadcast in specific languages, the language
codes for these can be appended to the individual audio or Dolby PID, separated
by an '=' sign, as in

.B ...:101=deu,102=eng;103=deu,104=eng:...

Some channels broadcast two different languages in the two stereo channels, which
can be indicated by adding a second language code, delimited by a '+' sign, as in

.B ...:101=deu,102=eng+spa;103=deu,104=eng:...

The audio type is appended with a separating '@' character, as in

.B ...:101=deu@4,102=eng+spa@4,105=@4:...

Note that if there is no language code, there still is the separating '='
if there is an audio type.

.TP
.B TPID
The teletext PID.
If this channel also carries DVB subtitles, the DVB subtitling PIDs follow the
teletext PID, separated by a semicolon, as in

.B ...:201;2001,2002:...

If certain subtitling PIDs broadcast in specific languages, the language
codes for these can be appended to the individual subtitling PID, separated
by an '=' sign, as in

.B ...:201;2001=deu,2002=eng:...

.TP
.B Conditional access
A hexadecimal integer defining how this channel can be accessed:
.TS
tab (@);
l l.
\fB0000\fR@Free To Air
\fB0001...000F\fR@explicitly requires the device with the given number
\fB0010...00FF\fR@reserved for user defined assignments
\fB0100...FFFF\fR@specific decryption methods as broadcast in the data stream\fR
.TE
Values in the range 0001...00FF will not be overwritten, all other values
will be automatically replaced by the actual CA system identifiers received
from the data stream. If there is more than one CA system id broadcast, they
will be separated by commas, as in

.B ...:1702,1722,1801:...

The values are in hex because that's the way they are defined in the "ETR 162"
document. Leading zeros may be omitted.
.TP
.B SID
The Service ID of this channel.
.TP
.B NID
The Network ID of this channel.
.TP
.B TID
The Transport stream ID of this channel.
.TP
.B RID
The Radio ID of this channel (typically 0, may be used to distinguish channels where
NID, TID and SID are all equal).
.PP
A particular channel can be uniquely identified by its \fBchannel\ ID\fR,
which is a string that looks like this:

\fBS19.2E\-1\-1089\-12003\-0\fR

The components of this string are the \fBSource\fR (S19.2E), \fBNID\fR
(1), \fBTID\fR (1089), \fBSID\fR (12003) and \fBRID\fR (0) as defined above.
The last part can be omitted if it is \fB0\fR,
so the above example could also be written as S19.2E\-1\-1089\-12003).
.br
The \fBchannel\ ID\fR is used in the \fItimers.conf\fR and \fIepg.data\fR
files to properly identify the channels.

If a channel has both \fBNID\fR and \fBTID\fR set to 0, the \fBchannel\ ID\fR
will use the \fBFrequency\fR instead of the \fBTID\fR. For satellite channels
an additional offset of 100000, 200000, 300000 or 400000 is added to that
number, depending on the \fBPolarization\fR (\fBH\fR, \fBV\fR, \fBL\fR or \fBR\fR,
respectively). This is necessary because on some satellites the same frequency is
used for two different transponders, with opposite polarization.
.SS TIMERS
The file \fItimers.conf\fR contains the timer setup.
Each line contains one timer definition, with individual fields
separated by ':' characters. Example:

\fB1:10:\-T\-\-\-\-\-:2058:2150:50:5:Quarks & Co:\fR

The fields in a timer definition have the following meaning (from left
to right):
.TP
.B Flags
The individual bits in this field have the following meaning:
.TS
tab (@);
l l.
\fB0x0001\fR@the timer is active (and will record if it hits)
\fB0x0002\fR@this is an instant recording timer
\fB0x0004\fR@this timer uses VPS
\fB0x0008\fR@this timer is currently recording (may only be up-to-date with SVDRP)
\fB0x0010\fR@this timer was spawned from a pattern timer
\fB0x0020\fR@this timer will store the recording's name in donerecs.data
.TE

All other bits are reserved for future use.
.TP
.B Channel
The channel to record from. This is either the channel number as shown in the
on-screen menus, or a complete channel ID. When reading \fItimers.conf\fR
any channel numbers will be mapped to the respective channel ids and when
the file is written again, there will only be channel ids. Channel numbers
are accepted as input in order to allow easier creation of timers when
manually editing \fItimers.conf\fR. Also, when timers are listed via SVDRP
commands, the channels are given as numbers.
.TP
.B Day
The day when this timer shall record.

If this is a `single-shot' timer, this is the date on which this
timer shall record, given in ISO notation (\fBYYYY-MM-DD\fR), as in:

.B 2005-03-19

For compatibility with earlier versions of VDR this may also be just the day of month
on which this timer shall record (must be in the range \fB1...31\fR).

In case of a `repeating' timer this is a string consisting of exactly seven
characters, where each character position corresponds to one day of the week
(with Monday being the first day). The character '\-' at a certain position
means that the timer shall not record on that day. Any other character will
cause the timer to record on that day. Example:

.B MTWTF\-\-

will define a timer that records on Monday through Friday and does not record
on weekends.
Note that only letters may be used here, no digits.
For compatibility with timers created with earlier versions of VDR,
the same result could be achieved with \fBABCDE\-\-\fR (which was
used to allow setting the days with language specific characters).
Since version 1.5.3 VDR can use UTF-8 characters to present data to
the user, but the weekday encoding in the \fItimers.conf\fR file
always uses single byte characters.

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 \fB@YYYY\-MM\-DD\fR,
so a complete definition could look like this:

\fBMTWTF\-\-@2002\-02\-18\fR

which would implement a timer that records Monday through Friday, and will hit
for the first time on or after February 18, 2002.
This \fBfirst day\fR 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 \fBfirst day\fR date given need not be
that of a day when the timer would actually hit.
.TP
.B Start
A four digit integer defining when this timer shall \fBstart\fR recording.
The format is \fBhhmm\fR, so \fB1430\fR would mean "half past two" in the
afternoon.
.TP
.B Stop
A four digit integer defining when this timer shall \fBstop\fR recording.
The format is the same as for the \fBstart\fR time.
.TP
.B Priority
An integer in the range \fB0...99\fR, defining the \fBpriority\fR
of this timer and of recordings created by this timer.
\fB0\fR represents the lowest value, \fB99\fR the highest.
The priority is used to decide which timer shall be
started in case there are two or more timers with the exact same
\fBstart\fR time. The first timer in the list with the highest priority
will be used.

This value is also stored with the recording and is
later used to decide which recording to remove from disk in order
to free space for a new recording. If the disk runs full and a new
recording needs more space, an existing recording with the lowest
priority (and which has exceeded its guaranteed \fBlifetime\fR) will be
removed.

If all available DVB cards are currently occupied, a
timer with a higher priority will interrupt the timer with the
lowest priority in order to start recording.
.TP
.B Lifetime
The \fBguaranteed lifetime\fR (in days) of a recording created by this timer.
\fB0\fR means that this recording may be automatically deleted at any time
by a new recording with higher priority. \fB99\fR means that this recording
will never be automatically deleted. Any number in the range \fB1...98\fR
means that this recording may not be automatically deleted in favour of a
new recording, until the given number of days since the \fBstart\fR time of
the recording has passed by.
.TP
.B File
The \fBfile name\fR this timer will give to a recording.
If the name contains any ':' characters, these have to be replaced by '|'.
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 \fBTITLE\fR and \fBEPISODE\fR, if present, will be replaced
by 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, \fBTITLE\fR will default to the channel name, and
\fBEPISODE\fR will default to a blank.

The file name can be prepended with a pattern, enclosed in curly braces, as in

{Columbo}Movies~TITLE

which makes this a "pattern timer". A pattern timer records every event on the
given channel where the title contains the pattern (case sensitive).
The following special characters can be used in a pattern:
.TS
tab (;);
l l.
\fB^\fR;anchor to the beginning of the event's title
\fB$\fR;anchor to the end of the event's title
\fB*\fR;match every event
\fB@\fR;avoid duplicate recordings
.TE

If \fB@\fR is used, it must be the very first character of the pattern.
If both \fB@\fR and \fB^\fR are used, \fB@\fR must come first.
If \fB*\fR is used, it must be the only character in the pattern and may only be
prepended with \fB@\fR.

In addition to TITLE and EPISODE you can use the following macros to compose the file
name (the curly braces are part of the macros):
.TS
tab (@);
l l.
{<}@everything before the matching pattern
{>}@everything after the matching pattern
{=}@the matching pattern itself (just for completeness)
.TE
.TP
.B Auxiliary data
An arbitrary string that can be used by external applications to store any
kind of data related to this timer. The string must not contain any newline
characters. If this field is not empty, its contents will be written into the
\fIinfo\fR file of the recording with the '@' tag.
.SS SOURCES
The file \fIsources.conf\fR defines the codes to be used in the \fBSource\fR field
of channels in \fIchannels.conf\fR and assigns descriptive texts to them.
Example:

\fBS19.2E  Astra 1\fR

Anything after (and including) a '#' character is comment.

The first character of the \fBcode\fR must be one of
.TS
tab (@);
l l.
\fBA\fR@ATSC
\fBC\fR@Cable
\fBS\fR@Satellite
\fBT\fR@Terrestrial
.TE

and is followed by further data pertaining to that particular source. In case of
\fBS\fRatellite this is the orbital position in degrees, followed by \fBE\fR for
east or \fBW\fR for west.
Plugins may define additional sources, using other characters in the range 'A'...'Z'.
.SS DISEQC
The file \fIdiseqc.conf\fR defines the \fBDiSEqC\fR control sequences to be sent
to the DVB-S card in order to access a given satellite position and/or band.
Example:

\fBS19.2E  11700 V  9750  t v W15 [E0 10 38 F0] W15 A W15 t\fR

Anything after (and including) a '#' character is comment.

The first word in a parameter line must be one of the codes defined in the
file \fIsources.conf\fR and tells which satellite this line applies to.

Following is the "switch frequency" of the LNB (slof), which is the transponder
frequency up to which this entry shall be used; the first entry with an slof greater
than the actual transponder frequency will be used. Typically there is only one slof
per LNB, but the syntax allows any number of frequency ranges to be defined.
Note that there should be a last entry with the value \fB99999\fR for each satellite,
which covers the upper frequency range.

The third parameter defines the polarization to which this entry applies. It can
be either \fBH\fR for horizontal, \fBV\fR for vertical, \fBL\fR for circular left
or \fBR\fR for circular right.

The fourth parameter specifies the "local oscillator frequency" (lof) of the LNB
to use for the given frequency range. This number will be subtracted from the
actual transponder frequency when tuning to the channel.

The rest of the line holds the actual sequence of DiSEqC actions to be taken.
The code letters used here are
.TS
tab (@);
l l.
\fBt\fR@22kHz tone off
\fBT\fR@22kHz tone on
\fBv\fR@voltage low (13V)
\fBV\fR@voltage high (18V)
\fBA\fR@mini A
\fBB\fR@mini B
\fBPn\fR@use positioner to move dish to satellite position n (or to the satellite's orbital position, if no position number is given)
\fBSn\fR@Satellite channel routing code sequence for bank n follows
\fBWnn\fR@wait nn milliseconds (nn may be any positive integer number)
\fB[xx ...]\fR@hex code sequence (max. 6)
.TE
There can be any number of actions in a line, including none at all - in which case
the entry would be used only to set the LOF to use for the given frequency range
and polarization.

By default it is assumed that every DVB-S device can receive every satellite.
If this is not the case in a particular setup, lines of the form

\fB1 2 4:\fR

may be inserted in the \fIdiseqc.conf\fR file, defining the devices that are able
to receive the satellites following thereafter. In this case, only the devices
1, 2 and 4 would be able to receive any satellites following this line and up
to the next such line, or the end of the file. Devices may be listed more than
once.
.SS SATELLITE CHANNEL ROUTING (SCR)
The file \fIscr.conf\fR contains the channel definitions of the SCR device in use.
The format is

channel frequency [pin]

where channel is the SCR device's channel index (0-7), frequency is the user band
frequency of the given channel, and pin is an optional pin number (0-255). The
actual values are device specific and can be found in the SCR device's manual.

Examples:
.PP
.EX
0 1284
1 1400
2 1516
3 1632
4 1748
5 1864
6 1980
7 2096
.EE
.PP
By default it is assumed that the SCR configurations apply to all devices, and
each device will pick one. If you have several SCR sat cables connected to one
VDR machine, or if you want to explicitly assign the SCR channels to your devices,
lines of the form

\fB1 2 4:\fR

may be inserted in the \fIscr.conf\fR file, defining the devices that are allowed
to use the SCR channels thereafter. In this case, only the devices
1, 2 and 4 would be allowed to use the SCR channels following this line and up
to the next such line, or the end of the file. If a device is listed more than
once, only its first appearance counts.
.SS REMOTE CONTROL KEYS
The file \fIremote.conf\fR contains the key assignments for all remote control
units. Each line consists of one key assignment in the following format:

\fBname.key  code\fR

where \fBname\fR is the name of the remote control (for instance KBD for the
PC keyboard, or LIRC for the
"Linux Infrared Remote Control"), \fBkey\fR is the name of the key that is
defined (like Up, Down, Menu etc.), and \fBcode\fR is a character string that
this remote control delivers when the given key is pressed.
.SS KEY MACROS
The file \fIkeymacros.conf\fR contains user defined macros that will be executed
whenever the given key is pressed. The format is

\fBmacrokey  [@plugin] key1 key2 key3...\fR

where \fBmacrokey\fR is the key that shall initiate execution of this macro
and can be one of \fIUp\fR, \fIDown\fR, \fIOk\fR, \fIBack\fR, \fILeft\fR,
\fIRight\fR, \fIRed\fR, \fIGreen\fR, \fIYellow\fR, \fIBlue\fR, \fI0\fR...\fI9\fR
or \fIUser1\fR...\fIUser9\fR. The rest of the line consists of a set of
keys, which will be executed just as if they had been pressed in the given
sequence. The optional \fB@plugin\fR can be used to automatically select
the given plugin.
\fBplugin\fR is the name of the plugin, exactly as given in the \-P
option when starting VDR. There can be only one \fB@plugin\fR per key macro.
For instance

\fBUser1 @abc Down Down Ok\fR

would call the main menu function of the "abc" plugin and execute two "Down"
key presses, followed by "Ok".
.br
Note that the color keys will only execute their macro function
in "normal viewing" mode (i.e. when no other menu or player is active). The
\fIUser1\fR...\fIUser9\fR keys will always execute their macro function.
There may be up to 15 keys in such a key sequence.
.SS FOLDERS
The file \fIfolders.conf\fR contains the definitions of folders that can be used
in the "Edit timer" menu. Each line contains one folder definition. Leading whitespace
and everything after and including a '#' is ignored. A line ending with '{'
defines a sub folder (i.e. a folder that contains other folders), and a line
consisting of only '}' ends the definition of a sub folder.

Example:
.PP
.EX
Daily {
  News
  Soaps
  }
Archive {
  Movies
  Sports
  Sci-Fi {
    Star Trek
    U.F.O.
    }
  }
Comedy
Science
.EE
.PP
Note that these folder definitions are only used to set the file name under which
a timer will store its recording. Changing these definitions in any way has no
effect on existing timers or recordings.
.SS COMMANDS
The file \fIcommands.conf\fR contains the definitions of commands that can
be executed from the \fBvdr\fR main menu's "Commands" option.
Each line contains one command definition in the following format:

\fBtitle : command\fR

where \fBtitle\fR is the string that will be displayed in the "Commands" menu,
and \fBcommand\fR 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. If \fBtitle\fR ends with the character '?', there will
be a confirmation prompt before actually executing the command. This can be
used for commands that might have serious results (like deleting files etc)
to make sure they are not executed inadvertently.

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

You can have nested layers of command menus by surrounding a sequence of
commands with '{'...'}' and giving it a title, as in
.PP
.EX
My Commands {
  First list {
    Do something: some command
    Do something else: another command
    }
  Second list {
    Even more: yet another command
    So much more: and yet another one
    }
  }
.EE
.PP
Command lists can be nested to any depth.

By default the menu entries in the "Commands" menu will be numbered '1'...'9'
to make them selectable by pressing the corresponding number key. If you want
to use your own numbering scheme (maybe to skip certain numbers), just precede
the \fBtitle\fRs with the numbers of your choice. \fBvdr\fR will suppress its
automatic numbering if the first entry in \fIcommands.conf\fR starts with a
digit in the range '1'...'9', followed by a blank.

In order to avoid error messages to the console, every command should have
\fIstderr\fR redirected to \fIstdout\fR. Everything the command prints to
\fIstdout\fR will be displayed in a result window, with \fBtitle\fR as its title.

Examples:
.PP
.EX
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"; }'
Calendar: date;echo;cal
.EE
.PP
Note that the commands 'checkmail' and 'cpustatus' are only \fBexamples\fR!
Don't send emails to the author asking where to find these ;\-)
.br
The '?' at the end of the "Check for new mail?" entry will prompt the user
whether this command shall really be executed.
.SS RECORDING COMMANDS
The file \fIreccmds.conf\fR can be used to define commands that can be applied
to the currently highlighted recording in the "Recordings" menu. The syntax is
exactly the same as described for the file \fIcommands.conf\fR. When executing
a command, the directory name of the recording will be appended to the command
string, separated by a blank and enclosed in single quotes.
.SS SVDRP HOSTS
The file \fIsvdrphosts.conf\fR contains the IP numbers of all hosts that are
allowed to access the SVDRP port.
Each line contains one IP number in the format

\fBIP-Address[/Netmask]\fR

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

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

Examples:
.PP
.EX
127.0.0.1        # always accept localhost
192.168.100.0/24 # any host on the local net
204.152.189.113  # a specific host
0.0.0.0/0        # any host on any net (\fBUSE WITH CARE!\fR)
.EE
.SS SETUP
The file \fIsetup.conf\fR contains the basic configuration options for \fBvdr\fR.
Each line contains one option in the format "Name = Value".
See the MANUAL file for a description of the available options.
.SS THEMES
The files \fIthemes/<skin>\-<theme>.theme\fR in the config directory contain the
color theme definitions for the various skins. In the actual file names \fI<skin>\fR
will be replaced by the name if the skin this theme belongs to, and \fI<theme>\fR
will be the name of this theme.
Each line in a theme file contains one option in the format "Name = Value".
Anything after (and including) a '#' character is comment.

The definitions in a theme file are either \fBcolors\fR or a \fBdescription\fR.
.br
\fBColors\fR are in the form

\fBclrTitle = FF123456\fR

where the name (clrTitle) is one of the names defined in the source code of
the \fBskin\fR that uses this theme, through the \fBTHEME_CLR()\fR macro.
The value (FF123456) is an eight digit hex number that consist of four bytes,
representing alpha (transparency), red, green and blue component of the color.
An alpha value of 00 means the color will be completely transparent, while FF
means it will be opaque. An RGB value of 000000 results in black, while FFFFFF
is white.

A \fBdescription\fR can be given as

\fBDescription = Shades of blue\fR

and will be used in the Setup/OSD menu to select a theme for a given skin.
The description should give the user an idea what this theme will be like
(for instance, in the given example it would use various shades of blue),
and shouldn't be too long to make sure it fits on the Setup screen.
The default description always should be given in English. If you want,
you can provide language specific descriptions as

\fBDescription.eng = Shades of blue\fR
.br
\fBDescription.ger = Blaut\(:one\fR

where the language code is added to the keyword
"Description", separated by a dot. You can enter as many language specific
descriptions as you like, but only those that have a corresponding locale
messages file will be actually used.
If a theme file doesn't contain a Description, the name of the theme (as
given in the theme's file name) will be used.
.SS AUDIO/VIDEO DATA
The files \fI00001.ts\fR...\fI65535.ts\fR are the actual recorded data
files. In order to keep the size of an individual file below a given limit,
a recording may be split into several files. The contents of these files is
\fBTransport Stream\fR (TS) and contains data packets that are each 188 byte
long and start with 0x47. Data is stored exactly as it is broadcast, with
a generated PAT/PMT inserted right before every independent frame.
.SS INDEX
The file \fIindex\fR (if present in a recording directory) contains
the (binary) index data into each of the the recording files
\fI00001.ts\fR...\fI65535.ts\fR. It is used during replay to determine
the current position within the recording, and to implement skipping
and fast forward/back functions.
See the definition of the \fBcIndexFile\fR class for details about the
actual contents of this file.
.SS INFO
The file \fIinfo\fR (if present in a recording directory) contains
a description of the recording, derived from the EPG data at recording time
(if such data was available). The \fBAux\fR field of the corresponding
timer (if given) is copied into this file, using the '@' tag.
This is a plain ASCII file and contains tagged lines like the \fBEPG DATA\fR
file (see the description of the \fIepg.data\fR file). Note that the lowercase
tags ('c' and 'e') will not appear in an \fIinfo\fR file.
Lines tagged with '#' are ignored and can be used by external tools to
store arbitrary information.

In addition to the tags used in the \fIepg.data\fR file, the following tag
characters are defined:
.TS
tab (|);
l l.
\fBF\fR|<frame rate>
\fBL\fR|<lifetime>
\fBP\fR|<priority>
\fBO\fR|<errors>
\fB@\fR|<auxiliary data>
.TE

The 'O' tag contains the number of errors that occurred during recording.
If it is zero, the recording can be safely considered error free. The higher the value,
the more damaged the recording is.
If this is an edited recording, the number of errors is that of the original
recording.
.SS RESUME
The file \fIresume\fR (if present in a recording directory) contains
the position within the recording where the last replay session left off.
The file consists of tagged lines that describe the various parameters
necessary to pick up replay where it left off.

The following tag characters are defined:
.TS
tab (@);
l l.
\fBI\fR@<offset into the file \fIindex\fR>
.TE
.SS MARKS
The file \fImarks\fR (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:

\fBhh:mm:ss.ff comment\fR

where \fBhh:mm:ss.ff\fR is a frame position within the recording, given as
"hours, minutes, seconds and (optional) frame number".
\fBcomment\fR can be any string and may be used to describe this mark.
If present, \fBcomment\fR 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.

If a frame position doesn't point to an I-frame of the corresponding recording,
it will be shifted towards the next I-frame (either up or down, whichever is
closer).

\fBCURRENT RESTRICTIONS:\fR

-\ the comment is currently not used by VDR
.SS SORT MODE
The file \fI.sort\fR (if present in a directory) contains an integer number
defining the mode by which this directory shall be sorted when presented in a menu.

The following values are defined:
.TS
tab (@);
l l.
\fB0\fR@sort by name
\fB1\fR@sort by time
.TE
.SS RECORDING TIMER
The file \fI.timer\fR (if present in a recording directory) contains
the full id of the timer that is currently recording into this directory.
Timer ids are of the form

\fBid@hostname\fR

where \fBid\fR is the timer's numerical id on the VDR with the name \fBhostname\fR.
This file is created when the timer starts recording, and is deleted when it ends.
.SS EPG DATA
The file \fIepg.data\fR 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:
.TS
tab (|);
l l.
\fBC\fR|<channel id> <channel name>
\fBE\fR|<event id> <start time> <duration> <table id> <version>
\fBT\fR|<title>
\fBS\fR|<short text>
\fBD\fR|<description>
\fBG\fR|<genre> <genre>...
\fBR\fR|<parental rating>
\fBX\fR|<stream> <type> <language> <descr>
\fBV\fR|<vps time>
\fB@\fR|<auxiliary data>
\fBe\fR|
\fBc\fR|
.TE

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 \fBC\fR...\fBc\fR (Channel) entries. Inside these any number of
\fBE\fR...\fBe\fR (Event) entries are allowed.
All other tags are optional (although every event
should at least have a \fBT\fR entry).

There may be several \fBX\fR tags, depending on the number of tracks (video, audio etc.)
the event provides.
.TS
tab (@);
l l.
<channel id>   @is the "channel ID", made up from the parameters defined in 'channels.conf'
<channel name> @is the "name" as in 'channels.conf' (for information only, may be left out)
<event id>     @is a 32 bit unsigned int, uniquely identifying this event
<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 it will be set to 0x00; and value less than 0x4E it will be treated as if it were 0x4E)
<version>      @is a hex number that indicates the event's version number inside its table (optional, ignored when reading EPG data)
<title>        @is the title of the event
<short text>   @is the short text of the event (typically the name of the episode etc.)
<description>  @is the description of the event (any '|' characters will be interpreted as newlines)
<genre>        @is a two digit hex code, as defined in  ETSI EN 300 468, table 28 (up to 4 genre codes are supported)
<parental rating>@is the minimum age of the intended audience
<stream>       @is the stream content (1 = MPEG2 video, 2 = MP2 audio, 3 = subtitles, 4 = AC3 audio, 5 = H.264 video, 6 = HEAAC audio, 0x09=H.265 video, 0x19 = AC4 audio)
<type>         @is the stream type according to ETSI EN 300 468
<language>     @is the three letter language code (optionally two codes, separated by '+')
<descr>        @is the description of this stream component
<vps time>     @is the Video Programming Service time of this event
<auxiliary data>@is an arbitrary string that can be used by external applications to store data; newline characters will be replaced with '|' when writing the \fIepg.data\fR file.
.TE

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

Note that the \fBevent id\fR that comes from the DVB data stream is actually
just 16 bit wide. The internal representation in VDR allows for 32 bit to
be used, so that external tools can generate EPG data that is guaranteed
not to collide with the ids of existing data.

The \fBauxiliary data\fR can be used for plugin specific purposes and has no meaning
whatsoever to VDR itself. It will \fBnot\fR be written into the \fIinfo\fR file of
a recording that is made for such an event.
.SS CAM DATA
The file \fIcam.data\fR contains information about which CAM in the system can
decrypt a particular channel.
Each line in this file contains a channel id, followed by one or more (blank
separated) numbers, indicating the CAMs that have successfully decrypted this
channel earlier.

When tuning to an encrypted channel, this information is used to select the
proper CAM for decrypting this channel. This channel/CAM relationship is not
hardcoded, though. If a given channel can't be decrypted with a CAM listed
in this file, other CAMs will be tried just as well. The main purpose of this
file is to speed up channel switching in systems with more than one CAM.

This file will be read at program startup and saved when the program ends.
If the file is read-only, it will not be overwritten.
.SS CAM AUTO RESPONSE
If your CAM keeps popping up annoying messages or you want to make sure VDR
can record programmes with parental rating without having to enter the PIN
(in case you can't turn that off in your CAM), you can set up auto responses
in the file \fIcamresponses.conf\fR.

Each line in this file specifies one rule to apply to texts received from
the CAM. If the CAM's menu text matches the text in one of these rules,
the given action is taken and sent to the CAM as an automatic response,
without any menu appearing on the screen. The first match wins.

The format of these rules is:

nr text action

where
.TS
tab (@);
l l.
nr       @is the number of the CAM this action applies to (0 = all CAMs)
text     @is the text in the CAM menu to react on (must be quoted with '"' if it contains blanks, escape '"' with '\\')
action   @is the action to take if the given text is encountered
.TE

Possible actions are:
.TS
tab (@);
l l.
DISCARD  @simply discard the menu (equivalent to pressing 'Back' on the RC)
CONFIRM  @confirm the menu (equivalent to pressing 'OK' without selecting a particular item)
SELECT   @select the menu item containing the text (equivalent to positioning the cursor on the item and pressing 'OK')
<number> @the given number is sent to the CAM as if it were tyed in by the user (provided this is an input field).
.TE

Note that the text given in a rule must match exactly, including any leading or
trailing blanks. If in doubt, you can get the exact text from the log file.
Action keywords are case insensitive.

Everything following (and including) a '#' character is considered to be comment.
.SS COMMANDLINE OPTIONS
If started without any options, vdr tries to read any files in the directory
/etc/vdr/conf.d with names that do not begin with a '.' and that end with '.conf'.
These files are read in alphabetical order. The format of these files is
.PP
.EX
# comment
[name]
-a
-b 123
--long
--longarg=123
.EE
.PP
Any lines that begin with '#' as the first non-whitespace character are considered
comments and are ignored.
A command line option file consists of one or more sections, indicated by '[name]',
where 'name' is either the fixed word 'vdr' (if this section contains options for
the main VDR program) or the name of the plugin this section applies to.
Each option must be written on a separate line, including the leading '-' (for
a short option) or '--' (for a long option). If the option has additional arguments,
they have to be written on the same line as the option itself, separated from the
option with a blank (short option) or equal sign (long option).
.SH SEE ALSO
.BR vdr (1)
.SH AUTHOR
Written by Klaus Schmidinger.
.SH REPORTING BUGS
Report bugs to <vdr\-bugs@tvdr.de>.
.SH COPYRIGHT
Copyright \(co 2021 Klaus Schmidinger.

This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.