Installation of the Video Disk Recorder --------------------------------------- Version 1.7 ----------- Compiling and running the program: ---------------------------------- VDR requires the Linux-DVB driver header files to compile. As of kernel 2.6 these are part of the official Linux kernel distribution, and so they should be automatically found in /usr/include/linux/dvb. If your DVB driver header files are in a different location, you can rename the file Make.config.template to Make.config and adjust the definition of DVBDIR in that file. Refer to http://linuxtv.org for more information about the Linux-DVB driver. VDR requires the Linux-DVB driver version that supports the S2API interface. You will also need to install the following libraries, as well as their "devel" packages to get the necessary header files for compiling VDR: fontconfig freetype2 gettext libcap libjpeg If the "capability" module is not compiled into your kernel, you may need to do "modprobe capability" before running VDR. After extracting the package, change into the VDR directory and type 'make'. This should produce an executable file named 'vdr', which can be run after the DVB driver has been installed. IMPORTANT: See "Configuration files" below for information on how ========= to set up the configuration files at the proper location! By default the 'vdr' program can be controlled via the PC keyboard. If you want to disable control via the keyboard, you can add NO_KBD=1 to the 'make' call, or use the '--no-kbd' option at runtime. If you have an infrared remote control unit you can define the REMOTE macro to one of the following values in the 'make' call to make the respective control the default: REMOTE=RCU control via the "Remote Control Unit" receiver (see http://www.tvdr.de/remote.htm) REMOTE=LIRC control via the "Linux Infrared Remote Control" (see http://www.lirc.org) Alternatively you can use the '--rcu' or '--lirc' options at runtime. These options accept an optional path to the remote control device, the defaults of which can be set via the RCU_DEVICE and LIRC_DEVICE macros, respectively. If your video directory will be on a VFAT partition, you can call VDR with the command line option '--vfat'. When running, the 'vdr' program writes status information into the system log file, which is usually /var/log/messages (or /var/log/user.log, depending on your syslog configuration). You may want to watch these messages (tail -f /var/log/messages) to see if there are any problems. The program can be controlled via a network connection to its SVDRP port ("Simple Video Disk Recorder Protocol"). By default, it listens on port 2001 (use the --port=PORT option to change this). For details about the SVDRP syntax see the source file 'svdrp.c'. WARNING: DUE TO THE OPEN SVDRP PORT THIS PROGRAM MAY CONSTITUTE A ======= POTENTIAL SECURITY HAZARD! IF YOU ARE NOT RUNNING VDR IN A CONTROLLED ENVIRONMENT, YOU MAY WANT TO DISABLE SVDRP BY USING '--port=0'! The file 'svdrphosts.conf' can be used to define which hosts are allowed to access the SVDRP port. By default only localhost (127.0.0.1) is granted access. If you want to give other hosts access to your SVDRP port you need to add their IP numbers to 'svdrphosts.conf'. If the program shall run as a daemon, use the --daemon option. This will completely detach it from the terminal and will continue as a background process. When starting the program through an entry in /etc/inittab, use the --terminal option to set the controlling terminal, as in vdr:123:respawn:/usr/local/bin/vdr --terminal=/dev/tty8 -w 60 See the man page vdr(1) for complete information about all command line options. Locale ------ When presenting the list of recordings, VDR sorts the entries according to the current "locale" settings. This makes sure that special characters (like the German "umlauts") appear at the expected positions. In order to benefit from this you may have to set the locale environment variable, for instance export LANG=de_DE for a German locale. If you don't want this to result in German error messages in the log file, it is sufficient to just set export LC_COLLATE=de_DE which only influences the way strings are sorted and leaves error messages in English. Note that for VDR's internationalized texts to work, the LANG environment variable must be set to a valid locale! Workaround for providers not encoding their EPG data correctly -------------------------------------------------------------- According to "ETSI EN 300 468" the default character set fo SI data is ISO6937. But unfortunately some broadcasters actually use ISO-8859-9 or other encodings, but fail to correctly announce that. Users who want to set the default character set to something different can do this by setting the environment variable VDR_CHARSET_OVERRIDE to something like ISO-8859-9. Start script with automatic restart in case of hangups: ------------------------------------------------------- The VDR source directory contains a 'runvdr.template'. Just copy it as 'runvdr' into your /usr/bin or /usr/local/bin directory and adjust it to your particular requirements. (See the comments inside the script for more information.) If you run VDR using the 'runvdr' shell script it will use the built-in watchdog timer to restart the program in case something happens that causes a program hangup. If you change the command line options for the call to the VDR program, be sure to NOT use the '-d' option! Otherwise VDR will go into 'daemon' mode and the initial program call will return immediately! 'runvdr' needs to be started as user 'root'. Use the '-u' option to run the actual 'vdr' program under a different user id. Setting the system time: ------------------------ If you want VDR to set the system time according to the data received from the transponder, you need to start VDR as user 'root'. For security reasons you should then use the '-u' option to define a lesser privileged user id under which VDR should actually run. It will then only keep the capability to set the system time, and set its user id to the given one. You also need to enable the "EPG/Set system time" option in VDR's Setup menu, and select a transponder from which you want to receive the time in "Use time from transponder". Make sure you select a transponder that has a reliable clock - some transponders are quite off. Automatic shutdown: ------------------- If you define a shutdown command via the '-s' command line option, VDR will call the given command if there is currently no recording or replay active, the user has been inactive for at least MinUserInactivity minutes and the next timer event is at least MinEventTimeout minutes in the future (see the Setup parameters in MANUAL). The command given in the '-s' option will be called with five parameters. The first one is the time (in UTC) of the next timer event or plugin wakeup time (as a time_t type number), and the second one is the number of seconds from the current time until the next timer event. Your program can choose which one to use for programming some sort of hardware device that makes sure the computer will be restarted in time before the next timer event. Your program must also initiate the actual shutdown procedure of the computer. VDR will not automatically exit after calling the shutdown program, but will rather continue normally until it receives a SIGTERM when the computer is actually shut down. So in case the shutdown fails, or the shutdown program for some reason decides not to perform a shutdown, VDR will stay up and running and will call the shutdown program again after a while. The command will be started in a separate background session, so it can continue to run even after VDR has terminated. If there are currently no timers active and there is no plugin wakeup time, both parameters will be '0'. In that case the program shall not set the hardware for automatic restart and only perform the system shutdown. A program that uses the second parameter to set the hardware for restart must therefore also check whether the first parameter is '0'. If the wakeup time is given by a timer, the third parameter will be the number of the channel that will be recorded, otherwise it will be 0. The fourth parameter contains the file name of the recording as defined in the timer, the name of the plugin that requested the wakeup time, or an empty string if no wakeup time is present. These can be used by the shutdown program to show that information on some display interface etc. The fifth parameter indicates the reason why the shutdown was requested. '0' means this is an automatic shutdown due to some timeout, while '1' means that this is a user requested shutdown (resulting from pressing the "Power" key). The shutdown program may use this information to decide whether or not to actually perform the system shutdown. If a timer is currently recording, or a recording would start within the next 30 minutes (default for the "Min. event timeout" setup parameter), and the user insists in shutting down now, the first and second parameter will correspond to a time that is "Min. event timeout" minutes in the future. Before the shutdown program is called, the user will be prompted to inform him that the system is about to shut down. If any remote control key is pressed while this prompt is visible, the shutdown will be cancelled (and tried again later). The shutdown prompt will be displayed for 5 minutes, which should be enough time for the user to react. A sample shell script to be used with the '-s' option might look like this: #!/bin/sh setRTCwakeup $(($1 - 300)) sudo halt Here 'setRTCwakeup' would be some program that uses the first parameter (which is the absolute time of the next timer event) to set the Real Time Clock so that it wakes up the computer 5 minutes (i.e. 300 seconds) before that event. The 'sudo halt' command then shuts down the computer. You will have to substitute both commands with whatever applies to your particular hard- and software environment. If the '-s' option is present, the VDR machine can be turned off by pressing the "Power" key on the remote control. Executing commands before and after a recording: ------------------------------------------------ You can use the '-r' option to define a program or script that gets called before and after a recording is performed, and after an editing process has finished. The program will be called with two string parameters. The first parameter is one of before if this is *before* a recording starts after if this is *after* a recording has finished edited if this is after a recording has been *edited* and the second parameter contains the full name of the recording's directory (which may not yet exists at that moment in the "before" case). In the "edited" case it will be the name of the edited version. Within this program you can do anything you would like to do before and/or after a recording or after an editing process. However, the program must return as soon as possible, because otherwise it will block further execution of VDR. Be especially careful to make sure the program returns before the watchdog timeout you may have set up with the '-w' option! If the operation you want to perform will take longer, you will have to run it as a background job. An example script for use with the '-r' option could look like this: #!/bin/sh case "$1" in before) echo "Before recording $2" ;; after) echo "After recording $2" ;; edited) echo "Edited recording $2" ;; *) echo "ERROR: unknown state: $1" ;; esac Command line options: --------------------- Use "vdr --help" for a list of available command line options. Replaying Dolby Digital audio: ------------------------------ If you have a "full featured" DVB card with SPDIF output you can replay Dolby Digital audio directly through the DVB card. You can also use an external program that reads the DD data from stdin and processes it in a way suitable for your audio hardware. This program must be given to VDR with the '-a' option, as in vdr -a ac3play The video data directory: ------------------------- All recordings are written into directories below "/video". Please make sure this directory exists, and that the user who runs the 'vdr' program has read and write access to that directory. If you prefer a different location for your video files, you can use the '-v' option to change that. Please make sure that the directory name you use with '-v' is a clean and absolute path name (no '..' or multiple slashes). Note that the file system need not be 64-bit proof, since the 'vdr' program splits video files into chunks of about 2GB. You should use a disk with several gigabytes of free space. One GB can store roughly half an hour of video data. If you have more than one disk and don't want to combine them to form one large logical volume, you can set up several video directories as mount points for these disks. All of these directories must have the same basic name and must end with a numeric part, which starts at 0 for the main directory and has increasing values for the rest of the directories. For example /video0 /video1 /video2 would be a setup with three directories. You can use more than one numeric digit, and the directories need not be directly under '/': /mnt/MyVideos/vdr.00 /mnt/MyVideos/vdr.01 /mnt/MyVideos/vdr.02 ... /mnt/MyVideos/vdr.11 would set up twelve disks (wow, what a machine that would be!). To use such a multi directory setup, you need to add the '-v' option with the name of the basic directory when running 'vdr': vdr -v /video0 Note that you should not copy any non-VDR files into the /videoX directories, since this might cause a lot of unnecessary disk access when VDR cleans up those directories and there is a large number of files and/or subdirectories in there. If you have a large disk that you want to use for VDR's video data as well as other stuff, you may want to create a subdirectory for VDR, as in /mydisk/video0 and put your other stuff into, say, /mydisk/otherstuff If your video directory is mounted via a Samba share, and you are experiencing problems with replaying in fast forward mode, you can comment out the line #define USE_FADVISE in the file tools.c, which may lead to better results. Configuration files: -------------------- There are several configuration files that hold information about channels, remote control keys, timers etc. By default these files are assumed to be located in the video directory, but a different directory can be used with the '-c' option. Plugins assume their configuration files in a subdirectory called "plugins" of this directory. For starters just copy all *.conf files from the VDR directory into your video directory. The configuration files can be edited with any text editor, or will be written by the 'vdr' program if any changes are made inside the on-screen menus. Take a look at man page vdr(5) for information about the file formats. The files that come with this package contain the author's selections, so please make sure you adapt these to your personal taste. Also make sure that the channels defined in 'channels.conf' are correct before attempting to record anything. Channel parameters may vary and not all of the channels listed in the default 'channels.conf' file have been verified by the author. As a starting point you can copy the 'channels.conf' file that comes with the VDR archive into your video directory (or into your config directory, respectively, in case you have redirected it with the -c option). Setting up DiSEqC: ------------------ If you are using a DVB-S card with a satellite equipment that needs to be accessed using DiSEqC, you have to go to the "Setup" menu and set the "DiSEqC" parameter to "on". You also need to set up the file 'diseqc.conf' to properly access your DiSEqC equipment (see man vdr(5) for details). Running VDR with DVB-C (cable) or DVB-T (terrestrial): ------------------------------------------------------ VDR automatically recognizes if the DVB card in use is a cable or a terrestrial card. The only thing that needs to be different when using digital cable or terrestrial reception is the 'channels.conf' file. The distribution archive contains a default 'channels.conf.cable' and 'channels.conf.terr', respectively, which users of such cards can rename or copy to 'channels.conf' in order to receive digital cable or terrestrial channels. The format of these files is mostly the same as for satellite channels, however, some fields have different or extended meanings (see man vdr(5) for details). You can even use a mixture of DVB-S, DVB-C and DVB-T cards in the same system. All you need to do is to put all the channel definitions into one big 'channels.conf' file. VDR will automatically know which channels can be received with which card(s) by evaluating the 'source' parameter. Learning the remote control keys: --------------------------------- There is no default 'remote.conf' file, so you will have to go through a "teach-in" session that allows the program to learn your remote control codes. It will first attempt to determine the basic data transfer mode and timing of your remote control unit, and then will ask you to press one key after the other so that it can learn the various key codes. You will at least need to provide an "Up" and a "Down" key, so that you can switch channels. The rest of the key definitions is optional, but the more keys you define, the more you will be able to navigate through the menus and control recording/replaying. The program uses only a very small number of keys which have multiple meanings in the various modes (see MANUAL for a detailed description). The recommended PC key assignments are: Up, Down, Left, Right Crsr keys in numeric block Menu 'Home' in numeric block Ok 'Enter' Back 'End' in numeric block Red, Green, Yellow, Blue 'F1'..'F4' 0..9 '0'..'9' in top row Power 'P' Volume+/- '+', '-' Mute 'm' If you prefer different key assignments, or if the default doesn't work for your keyboard, simply delete the file 'remote.conf' and restart 'vdr' to get into learning mode. Generating source code documentation: ------------------------------------- You can do a 'make srcdoc' to generate source code documentation using the Doxygen tool. To do so you need the Doxygen package from http://www.doxygen.org and the Graphviz package from http://www.research.att.com/sw/tools/graphviz. After installing these two packages you can do 'make srcdoc' and then use your HTML browser to read srcdoc/html/index.html.