This page describes the formats of the various files vdr uses to
store configuration data and recordings.
SYNTAX
CHANNELS The file channels.conf contains the channel configuration.
Each line defines either a group delimiter or a channel.
A group delimiter is a line starting with a ':' as the very first
character, followed by arbitrary text. Example:
:First group
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
:@201 First group
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
:@201
Such a delimiter will not appear in the Channels menu.
A channel definition is a line with channel data, where the fields
are separated by ':' characters. Example:
RTL:12188:h:S19.2E:27500:163:104:105:0:12003:0:0:0
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 timers.conf file.
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
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).
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
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 999 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:
B8C23D12M64T2G32Y0
Source
The signal source of this channel, as defined in the file sources.conf.
For compatibility with files from older versions numeric values will be accepted
and also written back correctly, but they will have no meaning for the DiSEqC
settings. You should replace the numerical values with the proper source identifiers
defined in sources.conf.
Srate
The symbol rate of this channel (DVB-S and DVB-C only).
VPID
The video PID (set to '0' for radio channels, '1' for encrypted radio channels).
If this channel uses a separate PCR PID, it follows the VPID, separated by a
plus sign, as in
...:164+17:...
APID
The 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:...
TPID
The teletext PID.
Conditional access
An integer defining how this channel can be accessed:
l l.
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
SID
The Service ID of this channel.
NID
The Network ID of this channel (for future use, currently always 0).
TID
The Transport stream ID of this channel (for future use, currently always 0).
RID
The Radio ID of this channel (typically 0, may be used to distinguish channels where
NID, TID and SID are all equal).
A particular channel can be uniquely identified by its channel ID,
which is a string that looks like this:
S19.2E-0-12188-12003-0
The components of this string are the Source (S19.2E), Frequency
(12188, MHz) and SID (12003) as defined above. The parts that are currently
0 are reserved for future use (the last part can be omitted if it is 0,
so the above example could also be written as S19.2E-0-12188-12003).
The channel ID is used in the timers.conf and epg.data
files to properly identify the channels.
TIMERSThe file timers.conf contains the timer setup.
Each line contains one timer definition, with individual fields
separated by ':' characters. Example:
1:10:-T-----:2058:2150:50:5:Quarks & Co:
The fields in a timer definition have the following meaning (from left
to right):
Status
Defines whether this timer is inactive(0) or active(1) .
The value 3 is used for instant recordings.
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 status 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
status parameter should only use the upper 16 bit of this 32 bit parameter
and leave the lower 16 bit untouched.
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 timers.conf
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 timers.conf. Also, when timers are listed via SVDRP
commands, the channels are given as numbers.
Day
The day when this timer shall record.
If this is a `single-shot' timer, this is the day of month on which this
timer shall record. This must be in the range 1...31.
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:
MTWTF--
will define a timer that records on Monday thru Friday and does not record
on weekends. The same result could be achieved with ABCDE-- (this is
used to allow setting the days with language specific 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 @YYYY-MM-DD,
so a complete definition could look like this:
MTWTF--@2002-02-18
which would implement a timer that records Moday thru Friday, and will hit
for the first time on or after February 18, 2002.
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
A four digit integer defining when this timer shall start recording.
The format is hhmm, so 1430 would mean "half past two" in the
afternoon.
Stop
A four digit integer defining when this timer shall stop recording.
The format is the same as for the start time.
Priority
An integer in the range 0...99, defining the priority
of this timer and of recordings created by this timer.
0 represents the lowest value, 99 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
start 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 lifetime) 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.
Lifetime
The guaranteed lifetime (in days) of a recording created by this timer.
0 means that this recording may be automatically deleted at any time
by a new recording with higher priority. 99 means that this recording
will never be automatically deleted. Any number in the range 1...98
means that this recording may not be automatically deleted in favour of a
new recording, until the given number of days since the start time of
the recording has passed by.
File
The file name 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 TITLE and EPISODE, 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, TITLE will default to the channel name, and
EPISODE will default to a blank.
Summary
Arbitrary text that describes the recording made by this timer.
Any newline characters in the summary have to be replaced by '|', and
the summary may contain ':' characters. If this field is not empty, its
contents will be written into the summary.vdr file of the recording.
SOURCESThe file sources.conf defines the codes to be used in the Source field
of channels in channels.conf and assigns descriptive texts to them.
Example:
S19.2E Astra 1
Anything after (and including) a '#' character is comment.
The first character of the code must be one of
l l.
S@Satellite
C@Cable
T@Terrestrial
and is followed by further data pertaining to that particular source. In case of
Satellite this is the orbital position in degrees, followed by E for
east or W for west.
DISEQCThe file diseqc.conf defines the DiSEqC control sequences to be sent
to the DVB-S card in order to access a given satellite position and/or band.
Example:
S19.2E 11700 V 9750 t v W15 [E0 10 38 F0] W15 A W15 t
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 sources.conf 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 99999 for each satellite,
which covers the upper frequency range.
The third parameter defines the polarization to which this entry applies. It can
be either H for horizontal or V for vertical.
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
l l.
t@22kHz tone off
T@22kHz tone on
v@voltage low (13V)
V@voltage high (18V)
A@mini A
B@mini B
Wnn@wait nn milliseconds (nn may be any positive integer number)
[xx ...]@hex code sequence (max. 6)
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.
CONDITIONAL ACCESS The file ca.conf defines the numbers to be used in the Conditional access
field of channels in channels.conf and assigns descriptive texts to them.
Example:
101 Premiere World
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, which 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).
REMOTE CONTROL KEYSThe file remote.conf contains the key assignments for all remote control
units. Each line consists of one key assignment in the following format:
name.key code
where name is the name of the remote control (for instance KBD for the
PC keyboard, RCU for the home-built "Remote Control Unit", or LIRC for the
"Linux Infrared Remote Control"), key is the name of the key that is
defined (like Up, Down, Menu etc.), and code is a character string that
this remote control delivers when the given key is pressed.
KEY MACROSThe file keymacros.conf contains user defined macros that will be executed
whenever the given key is pressed. The format is
macrokey [@plugin] key1 key2 key3...
where macrokey is the key that shall initiate execution of this macro
and can be one of Red, Green, Yellow, Blue or
User1...User9. 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 @plugin can be used to automatically select
the given plugin from the main menu (provided that plugin has a main menu
entry). plugin is the name of the plugin, exactly as given in the -P
option when starting VDR. There can be only one @plugin per key macro,
and it implicitly adds an Ok key to the macro definition (in order to
actually select the plugins main menu entry), which counts against the total
number of keys in the macro. For instance
User1 @abc Down Down Ok
would call the main menu function of the "abc" plugin and execute two "Down"
key presses, followed by "Ok".
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
User1...User9 keys will always execute their macro function.
There may be up to 15 keys in such a key sequence.
COMMANDSThe file commands.conf contains the definitions of commands that can
be executed from the vdr main menu's "Commands" option.
Each line contains one command definition in the following format:
title : command
where title is the string that 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. If title 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.
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 titles with the numbers of your choice. vdr will suppress its
automatic numbering if the first entry in commands.conf 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
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"; }'
Calendar: date;echo;cal
Note that the commands 'checkmail' and 'cpustatus' are only examples!
Don't send emails to the author asking where to find these ;-)
The '?' at the end of the "Check for new mail?" entry will prompt the user
whether this command shall really be executed.
RECORDING COMMANDSThe file reccmds.conf 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 commands.conf. 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.
SVDRP HOSTSThe file svdrphosts.conf 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.
Examples:
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 (USE WITH CARE!)
SETUPThe file setup.conf 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.
AUDIO/VIDEO DATAThe files 001.vdr...255.vdr 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.
INDEXThe file index.vdr (if present in a recording directory) contains
the (binary) index data into each of the the recording files
001.vdr...255.vdr. 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 cIndexFile class for details about the
actual contents of this file.
SUMMARYThe file summary.vdr (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) or the Summary field of the corresponding
timer. This is a plain ASCII file and can contain arbitrary text.
RESUMEThe file resume.vdr (if present in a recording directory) contains
the position within the recording where the last replay session left off.
The data is a four byte (binary) integer value and defines an offset into
the file index.vdr.
MARKSThe file marks.vdr (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).
EPG DATAThe file epg.data 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:
l l.
C@<channel 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).
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)
<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 (any '|' characters will be interpreted as newlines)
This file will be read at program startup in order to restore the results of
previous EPG scans.
