vdr for Debian
--------------

The following options can be configured in /etc/default/vdr.

KEYB_TTY="<CONSOLE>"

    Default: "" (No console input)

    Console for controlling VDR by keyboard (e.g. /dev/tty8). On startup VDR
    will automatically switch to this console.

    NOTE: This setting only works with the SysVinit-Script.
    For systemd copy /usr/share/doc/vdr/examples/switch-tty.conf to
    /etc/systemd/system/vdr.service.d/

    e.g.:

    sudo mkdir -p /etc/systemd/system/vdr.service.d/ && \
    sudo cp /usr/share/doc/vdr/examples/switch-tty.conf /etc/systemd/system/vdr.service.d/ && \
    sudo systemctl daemon-reload && \
    sudo systemctl restart vdr

KEYB_TTY_SWITCH=<0|1>

    Default: 0

    Set this to 1, to make VDR switch to the console specified in KEYB_TTY
    on startup.

    NOTE: This setting only works with the SysVinit-Script.
    See the note above for setting this up for systemd.

SHUTDOWNCMD="<COMMAND>"

    Default: "/sbin/shutdown -h now"

    VDR executes <COMMAND> when the power-off-key of the remote is pressed after
    processing all shutdown hook scripts. Shutdown hooks may override this
    command. See section "Shutdown-Hooks" below. SHUTDOWNCMD will be executed
    detached in background.

VDR_LANG=<LANG>

    Default: read from LANG or LC_ALL in /etc/default/locale or /etc/environment,
             falling back to C, if no locale is specified

    Locale which is used when running vdr.

    NOTE: This setting only works with the SysVinit-Script.
    To make VDR use a specific locale with systemd, create a file 
    /etc/systemd/system/vdr.service.d/ with e.g.:

    [Service]
    Environment="LANG=de_DE.utf8"
    Environment="LC_ALL=de_DE.utf8"

Automatic Loading of Plugins
----------------------------

When starting the vdr daemon, it will search in /etc/vdr/conf.d for plugin config
files, optionally containing command line parameters passed to these plugins, and
load these plugins.

Usually the files in /etc/vdr/conf.d/ will be symlinks to the real config files 
in /etc/vdr/conf.avail/. By deleting or renaming these symlinks, a plugin can be
disabled or the plugin load order can be changed.

Command-Hooks
-------------

VDR has the ability, to start external commands using the OSD menu. There are
two types of external commands - normal commands and recording commands. Normal
commands are shown under VDR's main menu entry "commands" while, recording
commands are accessible only in VDR's recordings menu. While normal commands are
executed without any parameters, recording commands will receive the directory
of the selected recording as the first command line argument.

In order to allow other packages (Addons) to install their own commands, the
command files passed to vdr in /etc/init.d/vdr are generated out of the files
commands.<descriptor>.conf and reccmds.<descriptor>.conf found in
/usr/share/vdr/command-hooks/. <descriptor> normally should be the name of
the package, that wants to add these commands to VDR. The order of the
commands can be defined in the files order.commands.conf and order.reccmds.conf
in /etc/vdr/command-hooks/.

If the author of a package wants the user to be able to customize the commands
added to vdr, the command file should be installed to /etc/vdr/command-hooks/
and only symlinked to /usr/share/vdr/command-hooks/.

For a description of the command file syntax, refer to commands.conf and
reccmds.conf in the vdr documentation.

Commands added by the user, should go to commands.custom.conf and
reccmds.custom.conf in /etc/vdr/command-hooks/. These files contain also some
examples.


Recording-Hooks
---------------

VDR can execute an external command before a recording starts, after a
recording ends and after a recording has been edited.
In order to allow other packages to specify their own recording actions,
all files in /usr/share/vdr/recording-hooks are executed one after another.
If a file is not an executable or a link to an executable, it is executed as
a shell script.

Recording hooks are called in their alphabetical order and should follow this
naming scheme:

R<XX>.<identifier>

Where <XX> is a two digit number, that mainly specifies the execution order
and <identifier> is a unique descriptor.

Two parameters are passed to each recording hook:

Parameter 1 can have the values "before", "after" and "edited", depending
on whether the recording hook is called before the recording starts,
after the recording ends or after the recording has been edited.

Parameter 2 is the directory of the recording. Be aware, that this directory
doesn't exist before the recording starts. if parameter 1 is "edited", this
is the result of the cutting.

Parameter 3 is the directory of the original recording if parameter 1 is
"edited"

If the author of a package wants the user to be able to customize a recording
hook, it should be installed to /etc/vdr/recording-hooks/ and only symlinked
to /usr/share/vdr/recording-hooks/.

Custom user commands associated with the vdr package, can be added by the user
to /etc/vdr/recording-hooks/R90.custom.


Shutdown-Hooks
---------------

If you press the power key on your remote control, VDR executes a script
provided by the command line option -s. By default, this script will
execute all files in /usr/share/vdr/shutdown-hooks/ in their alphabetical order.
If a file in there is not executable, it is treated as a shell script. These
so called "shutdown hooks" should follow this naming scheme:

S<XX>.<identifier>

Where <XX> is a two digit number, that mainly specifies the execution order
and <identifier> is a unique descriptor.

All shutdown hooks will be passed the same parameters as the main shutdown
script. I.e. the first parameter is the start time of the next timer. Please
refer to the vdr documentation for the other parameters.

After all shutdown hooks have been processed, VDR will be terminated and the
machine will be shut down.

A shutdown hook may abort the shutdown process by exiting with an errorlevel
unequal to 0. To provide the user with an OSD-message about the reason for
aborting the shutdown, the shutdown hook may write an abort message to stdout
like this:

ABORT_MESSAGE=<message to display>

If the shutdown should only be deferred (e.g. because some background process,
is still active), the shutdown hook may write to stdout:

TRY_AGAIN=<minutes to wait before next shutdown request>

In this case, no further shutdown hooks will be processed and the shutdown will
be invoked in TRY_AGAIN minutes again.

To overwrite the command defined in /etc/default/vdr that will be executed to
shutdown the machine after all shutdown hooks have been processed, a shutdown
hook may write to stdout:

SHUTDOWNCMD=<new shutdown command>


Group memberships
-----------------

A few plugins require that the user vdr is member in additional system groups
like audio or cdrom. To be a little bit more flexible, we have designed a
mechanism which can be used by plugins to specify additional group memberships.
Plugins can add a file /usr/share/vdr/groups.d/<plugin-name>.groups and call
/usr/lib/vdr/vdr-groups.sh in postinst and prerm. vdr-groups.sh will then take
care of adding/removing vdr to/from the groups listed in the specified
<plugin-name>.groups file. vdr will be removed from a group only, if no other
plugin requires this group membership.

In postinst a plugin should call:

    /bin/sh /usr/lib/vdr/vdr-groups.sh --add vdr-plugin-foo

and in prerm:

    /bin/sh /usr/lib/vdr/vdr-groups.sh --remove vdr-plugin-foo

If you manually add vdr to a group, you must add the group to
/etc/vdr/vdr.groups. If you don't do so, vdr may be removed from this group when
uninstalling a plugin.


Optional Patches
----------------

A lot of VDR enthusiasts have improved VDR by creating patches that fix
existing problems or add new functionality. Some of these patches may not work
for everyone, so we decided to make them optional. This means, that these
patches are only included as dpatch files in the vdr source package, NOT in
the binary packages. They are named opt-<nn>_<patch name>, where <nn> is a
two-digit-number and <patch name> a unique identifier. To enable a patch, just
uncomment it in debian/patches/00list and recompile vdr.

Most of these optional patches modify the interfaces used by the plugins. This
means, that the plugins become binary incompatible. If you activate/deactivate
patches in the vdr package, all plugins must be recompiled with the new vdr-dev
package! There is only one exception from this rule - patches named
opt-<nn>-x_<patch name> do not affect the plugin interfaces and can therefore
be enabled or disabled without the need to recompile the plugins.

Keep in mind, that if you enable any optional patches, you can't use apt-get
anymore on the official Debian repositories to update existing vdr or plugin
packages or install additional plugins. You always have to compile the plugins
yourself! The optional patches are mainly intended for people who would like to
create their own customized vdr distribution.


Getting Started / Initial channels.conf
---------------------------------------

If the provided example channels.conf files do not suit your needs, you might
need to search for an initial channels.conf online. There are also various DVB
scanning tools available, which can create a channels.conf for you by scanning
all possible transponders/frequencies. E.g. w_scan or scan/dvbscan from the
dvb-apps package or dvbv5-scan from the dvb-tools package.
