NAME
vdr_files - the Video Disk Recorder Files
DESCRIPTION
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 Television,RTL:12188:h:S19.2E:27500:163:104:105:0:12003:1:1089: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 '|'). 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
RTL Television,RTL:...
If present, the name of the service provider or "bouquet" is
appended to the channel name, separated by a semicolon, as in
RTL Television,RTL;RTL World:...
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
B Bandwidth (6, 7, 8)
C Code rate high priority (0, 12, 23, 34, 45, 56, 67, 78, 89)
D Code rate low priority (0, 12, 23, 34, 45, 56, 67, 78, 89)
G Guard interval (4, 8, 16, 32)
H Horizontal polarization
I Inversion (0, 1)
L Left circular polarization
M Modulation (0, 16, 32, 64, 128, 256)
R Right circular polarization
T Transmission mode (2, 8)
V Vertical polarization
Y Hierarchy (0, 1, 2, 4)
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). 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 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
...: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
...: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
...:101=deu,102=eng+spa;103=deu,104=eng:...
TPID The teletext PID.
Conditional access
A hexadecimal integer defining how this channel can be accessed:
0000 Free To Air
0001...000F explicitly requires the device with the given number
0010...00FF reserved for user defined assignments
0100...FFFF specific decryption methods as broadcast in the data stream
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
...: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.
SID The Service ID of this channel.
NID The Network ID of this channel.
TID The Transport stream ID of this channel.
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-1-1089-12003-0
The components of this string are the Source (S19.2E), NID (1), TID
(1089), SID (12003) and RID (0) as defined above. The last part can be
omitted if it is 0, so the above example could also be written as
S19.2E-1-1089-12003).
The channel ID is used in the timers.conf and epg.data files to
properly identify the channels.
If a channel has both NID and TID set to 0, the channel ID will use the
Frequency instead of the TID. For satellite channels an additional
offset of 100000, 200000, 300000 or 400000 is added to that number,
depending on the Polarization (H, V, L or R, respectively). This is
necessary because on some satellites the same frequency is used for two
different transponders, with opposite polarization.
TIMERS
The 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):
Flags The individual bits in this field have the following meaning:
1 the timer is active (and will record if it hits)
2 this is an instant recording timer
4 this timer uses VPS
8 this timer is currently recording (may only be up-to-date with SVDRP)
All other bits are reserved for future use.
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 date on which this
timer shall record, given in ISO notation (YYYY-MM-DD), as in:
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 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 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
ABCDE-- (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 timers.conf 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 @YYYY-MM-DD, so a complete definition could look
like this:
MTWTF--@2002-02-18
which would implement a timer that records Monday through
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.
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 info.vdr file of the
recording with the '@' tag.
SOURCES
The 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
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.
DISEQC
The 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
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.
REMOTE CONTROL KEYS
The 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 MACROS
The 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 Up, Down, Ok, Back, Left, Right, Red, Green, Yellow,
Blue, 0...9 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. 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. 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.
COMMANDS
The 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 COMMANDS
The 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 HOSTS
The 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!)
SETUP
The 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.
THEMES
The files themes/<skin>-<theme>.theme in the config directory contain
the color theme definitions for the various skins. In the actual file
names <skin> will be replaced by the name if the skin this theme
belongs to, and <theme> 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 colors or a description.
Colors are in the form
clrTitle = FF123456
where the name (clrTitle) is one of the names defined in the source
code of the skin that uses this theme, through the THEME_CLR() 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 description can be given as
Description = Shades of blue
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
Description.eng = Shades of blue
Description.ger = Blaut"one
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.
AUDIO/VIDEO DATA
The 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...0xEF for video (only one of these may actually occur in a file),
0xC0...0xDF for audio 1...32 (up to 32 audio tracks may occur). Dolby
Digital data is stored in packets with ids 0xBD ("Private Stream 1")
and substream ids 0x80...0x87. DVB subtitle data is stored in packets
with ids 0xBD ("Private Stream 1") and substream ids 0x20...0x27.
INDEX
The 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.
INFO
The file info.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). The Aux 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 EPG DATA file
(see the description of the epg.data file). Note that the lowercase
tags ('c' and 'e') will not appear in an info.vdr file. Lines tagged
with '#' are ignored and can be used by external tools to store
arbitrary information.
RESUME
The 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.
MARKS
The 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 DATA
The 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:
C <channel id> <channel name>
E <event id> <start time> <duration> <table id> <version>
T <title>
S <short text>
D <description>
X <stream> <type> <language> <descr>
V <vps time>
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. All other tags are
optional (although every event should at least have a T entry). There
may be several X tags, depending on the number of tracks (video, audio
etc.) the event provides. The special tag character @ is used to mark
the auxiliary data from a timer definition in the info.vdr file.
<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 or 0 this event will not be overwritten or modified by data that comes from the DVB stream)
<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)
<stream> is the stream content (1 = video, 2 = audio, 3 = subtitles)
<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
This file will be read at program startup in order to restore the
results of previous EPG scans.
Note that the event id 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.
SEE ALSO
vdr(1)
AUTHOR
Written by Klaus Schmidinger.
REPORTING BUGS
Report bugs to <vdr-bugs@cadsoft.de>.
COPYRIGHT
Copyright (C) 2008 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.