<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kvdr '<application>Kvdr</application>'>
  <!ENTITY kapp "&kvdr;"><!-- replace kvdr here -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY package "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
  
  
  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999 
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001   -->

<!--
This template was designed by: David Rugge davidrugge@mindspring.com
with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
of the KDE DocBook team.

You may freely use this template for writing any sort of KDE documentation.
If you have any changes or improvements, please let us know.

In the future, we may want to change from SGML-based DocBook to XML-based
DocBook. To make this change easier, please be careful :
- in XML, the case of the <tags> and attributes is relevant ;
- also, quote all attributes.

Please don't forget to remove all these comments in your final documentation,
thanks ;-).
-->

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The Kvdr Handbook</title>

<authorgroup>
<author>
<firstname>Guido</firstname>
<othername></othername>
<surname>Fiala</surname>
<affiliation>
<address><email>gfiala@s.netic.de</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2004</year>
<holder>Guido Fiala</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook 
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>03/20/2004</date>
<releaseinfo>0.62</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kvdr; is a frontend for the vdr-daemon and displays up to 4 video overlays.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeutils</keyword>
<keyword>Kapp</keyword>
<keyword>dvb</keyword>
<keyword>video</keyword>
<keyword>v4l</keyword>
<keyword>TV</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
If you have just a desktop computer with a dvb-card and are running KDE
you can have vdr running as a daemon (e.g. by init) handling all recording
and use Kvdr as a viewer.
</para>
<para>
Just start kvdr, it connects to the vdr-daemon using SVDRP and lets
you do anything vdr can do plus displays an overlay.
</para>
<para>
Changes:
<itemizedlist>
<listitem><para>0.62 seamless reconnect to vdr if it closes connection
</para></listitem>
<listitem><para>0.61 changed commandline options, added new ones, added multimode for Xv, added PiP-mode for Xv+Ovl-Modes, removed the need for amixer, now use a 768x576 modeline if available, ...
</para></listitem>
<listitem><para>0.52 made it compatible with KDE 3 (still compiles under KDE2)
</para></listitem>
<listitem><para>0.51 initial size can be larger than PAL/NTSC, a value of 0,0 disables this feature and lets KDE2 restore settings work if applied, 
zapping through video devices now works in xv-mode as well (multimode, however, so far not ;-) 
implemented mouse pointer show-on-move/autohide feature 
new command line option "-x 1" completly disables overlay mode and forces xv-mode on startup 
new command line option "-d 1" disables modeline switch for xv-mode (desktop resolution used instead) 
</para></listitem>
<listitem><para>0.5  fixed reconnect after driver reload, some configuration-dialog bugfixes, implemented Xv-display including deinterlacing: Key V switches to Xv-Display, D toggles deinterlacing, (minimum size in Xv-mod is PAL/NTSC size)
</para></listitem><listitem>
<para>0.42 fixed a silly bug in clipping code
</para></listitem><listitem>
<para>0.41 v4l-conf is used to set up the framebuffer, Key X shows up to 4 overlays at once, fixed the bahaviour if vdr does'nt respond on SVDRP-port
</para></listitem><listitem>
<para>0.4  kvdr now handles video device itself (see Configuration dialog), Key Z zaps to next video device, fixed kvdr.desktop
</para></listitem><listitem>
<para>0.35 fixed missing klocale.h (caused the debian compiling problem)
</para></listitem><listitem>
<para>0.34 kvdr automatically reconnects to vdr on restart, hopefully fixed Mandrake/Redhat compiling problems
</para></listitem><listitem>
<para>0.33 fixed volume-restore at program startup, configuration-dialog now centered in full-screen mode, fixed KDE2-way of "Help", reintegrated DPMS handling (can be activated in kvdr.h),command line option for colour-depth
</para></listitem><listitem>
<para>0.32 temporarily removed DPMS-handling, fixed one clipping-failure, 2 more key bindings
</para></listitem><listitem>
<para>0.31 fixed two more problems with the overlay, does this never end :-(
</para></listitem><listitem>
<para>0.3 switched to KDE2 and (hopefully) fixed the clipping problems
</para></listitem><listitem>
<para>0.2 changed handling of picture sliders to instant reaction, Apply-button closes configuration dialog now, implemented Front/Rear-balance - (tested with SBLive only), fixed bug with actual channel name in grabbed images
</para></listitem><listitem>
<para>0.1 initial test version
</para></listitem>
</itemizedlist>
</para>
</chapter>

<chapter id="using-kapp">
<title>Using Kvdr</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->

<para>
First, you must have running vdr in daemon mode (vdr -d), listening at
the port you choosed (defaults to 2001).
Then simply start Kvdr and you can use keys assignments following in the next chapters.

<!-- Note that all graphics should be in .png format. Use no gifs because of
patent issues. -->
</para>
<para>Features:
<itemizedlist>
<listitem><para>
anything vdr can do and will do
</para></listitem><listitem><para>
handles the overlay of your dvb-cards
</para></listitem><listitem><para>
lets you zap through your video devices or display up to
for overlays at once (if you have more than one card).
However - changing the channel via vdr is currently
only supported on the "primary" dvb-interface.
</para></listitem><listitem><para>
the Xv-mode lets you zoom the image to larger resolutions and optionally handles
deinterlacing by 50Hz half frame upscaling.
</para></listitem><listitem><para>
fullscreen-mode (mouse, dpms and screensaver automatically handled)
</para></listitem><listitem><para>
can be used for "remote" viewing of vdr-recordings if you have 2 dvb-cards
and the remote-video-directory mounted
</para></listitem><listitem><para>
let's you grab images during viewing, playback or recording in jpg or pnm
format, filename is automatically generated out of channel-name, date and
time.
</para></listitem><listitem><para>
let's you control Brightness, Colour, Hue and Contrast of the overlay (not
applied to grab-images!)
</para></listitem><listitem><para>
handles 4:3 and 16:9 aspect ratios corrected with viewport-dimensions (currently
at 4:3 monitors only)
</para></listitem><listitem><para>
handles PAL and NTSC accordingly (but only PAL tested so far - i'am living
in Germany ;-)
</para></listitem><listitem><para>
stores all configuration to file
</para></listitem><listitem><para>
sound-handling:&nbsp; mixer-channel, volume and mute using alsa/amixer
</para></listitem><listitem><para>
Front/Rear-volume balance
</para></listitem>
</itemizedlist>
</para></chapter>

<chapter id="commands">
<title>Command Reference</title>

<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
application windows and their menubar and toolbar commands for easy reference.
Also include any keys that have a special function but have no equivalent in the
menus or toolbars. This may not be necessary for small apps or apps with no tool
or menu bars. -->

<sect1 id="kapp-mainwindow">
<title>The main Kvdr window</title>
<para>
M.............activates menu
</para><para>
Return........activate selected item
</para><para>
Backspace.....goes to previous menu
</para><para>
Cursor-Up.....moves selection up | resumes a replay
</para><para>
Cursor-Down...moves selection down | pauses a replay
</para><para>
Cursor-Left...toggles rewind in replay, slow|fast depending on Pause|Play
</para><para>
Cursor-Right..toggles forward in replay, slow|fast depending on Pause|Play
</para><para>
0-9...........direct channel selection
</para><para>
F1,F2,F3,F4...Funktion key as shown in OSD-Menu
</para><para>
J | Space.....Grabs a jpg-image
</para><para>
P.............Grabs a pnm-image
</para><para>
R.............Single-Click instant Recording
</para><para>
O.............Toggels the overlay On|Off
</para><para>
C.............Opens the configuration dialog
</para><para>
Q.............Quits kvdr without disturbing vdr
</para><para>
Grey-Return...Mute On|Off
</para><para>
+|-...........Volume Up|Down
</para><para>
CTRL -|+......Rear-Volume Up|Down
</para><para>
H.............Shows HTML-Help
</para><para>
Pg-Up/Pg-Down.Emulate page up/down in vdr with cursor up/down
</para><para>
Z.............Zaps to next video device (0..3)
</para><para>
X.............Displays up to 4 overlays at once
</para><para>
V.............Switches to Xv-mode
</para><para>
D.............Toggles deinterlacing in Xv-mode (fullscreen,di-50Hz,di-field1)
</para><para>
I.............Toggles Picture-in-Picture-Mode during Multimode (X)
</para><para>
E.............Exchanges the 2 videos in Picture-in-Picture-Mode
</para><para>
S.............Zap's the video-device of the Picture-in-Picture
</para>
<para>configuration dialog:</para>
<para>
Ctrl-C|ESC....cancel configuration
</para>
<para>
Ctrl-S........apply and save configuration
</para>
<para>
Ctrl-A........apply configuration
</para>
</sect1>


</chapter>

<chapter id="developers">
<title>Developer's Guide to Kvdr</title>

<!-- (OPTIONAL) A Programming/Scripting reference chapter should be
used for apps that use plugins or that provide their own scripting hooks
and/or development libraries. -->

<para>
Kvdr could be enhanced with more fancy deinterlacing methods in class Xvdisplayer,
switching channels on extra overlays via corresponding tuner or SVDRP (if available),
switch audio output to corresponding overlay via mixerchannel,
a picture in picture feature and all the required configuration for this.
</para>

<!-- Use refentries to describe APIs.  Refentries are fairly complicated and you
should consult the docbook reference for further details. The example below was
taken from that reference and shortened a bit for readability. -->

</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

<!-- (OPTIONAL but recommended) This chapter should include all of the silly
(and not-so-silly) newbie questions that fill up your mailbox. This chapter
should be reserved for BRIEF questions and answers! If one question uses more
than a page or so then it should probably be part of the
"Using this Application" chapter instead. You should use links to
cross-reference questions to the parts of your documentation that answer them.
This is also a great place to provide pointers to other FAQ's if your users
must do some complicated configuration on other programs in order for your
application work. -->

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question><para>
configure fails?</para>
</question>
<answer>
<para>If configure fails at your system, try deleting config.cache and some of
the options configure --help shows (--prefix=/opt/kde2 and --with-qt-dir=/usr/lib/qt2; according
where the libs are installed at your system)
If it still complains please check if you can compile other kde2-programs, only then
it's a problem specific to kvdr.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>No overlay is shown or it is scrambled?
</para>
</question>
<answer>
<para>
At some systems the XServer reports the wrong color-bytes-depth in 24 bit Mode (32 bits, overlay
is trashing the screen), in that case please use the commandline-option -b 24 to force the right mode.
(see kvdr --help)
</para><para>
If kvdr shows only a black screen please check if kvdr uses the correct video device number, if you have
read/write access rights to the device "/dev/video*" and no other application blocks the device.
</para><para>
If you can't switch channels or vdr is not controllable, please check if no one
else (e.g. telnet or another kvdr) ist connected to vdr and if both use the same port.
(see configuration dialog and vdr-manpage)
</para>
<para>
Known Bugs:</para>
<para>
Under KDE 2.1 the KWM-option "show window content during moving" behaves different
than Version 2.0, leaving the overlay behind. Because other applications
like kwintv and xawtv show the same failure at my system, i assume it's not my fault, maybe even not
a bug at all - it's a feature ;-)
Whether deactivate it or live with it, let's see if newer version compensate for it...
</para>
<para>-deactivating KDE-Screensaver does not work as they does'nt provide this function
(to my knowledge)</para>
<para>-sometimes the mixer-channels in the list are not complete, restarting kvdr helps.</para>
<para>-i18n not complete, help appreciated</para>

</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kapp;
</para>
<para>
Program and Documentation copyright 2002 Guido Fiala <email>gfiala@s.netic.de</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under, 
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL, 
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->
</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kvdr">
<title>How to obtain Kvdr</title>

<para>
&kvdr; can be downloaded from
<ulink url="http://www.s.netic.de/gfiala">http://www.s.netic.de/gfiala</ulink>.
</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<!--
List any special requirements for your application here. This should include:
.Libraries or other software that is not included in kdesupport,
kdelibs, or kdebase.
.Hardware requirements like amount of RAM, disk space, graphics card
capabilities, screen resolution, special expansion cards, etc.
.Operating systems the app will run on. If your app is designed only for a
specific OS, (you wrote a graphical LILO configurator for example) put this
information here.
-->

<para>
In order to successfully use &kvdr;, you need KDE 2.x.
&kvdr; uses about 5 megs of memory to run, but this may vary depending on your platform and
configuration.
You need at least one DVB-Card, the DVB-driver, the VDR-package and Kde.
For fullscreen-switching have a 800x600 modeline in your XF86Config file,
for NTSC a 640x480 one. (The first one found is automatically choosed,
should have the frequency of your choice).
To get sound handling working get and install alsa (amixer).
The latest version of &kvdr; can be found on <ulink url="www.s.netic.de/gfiala">The &kvdr; home page</ulink>.
</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>
In order to compile and install KApp on your system, type the following in the base
directory of the Icon Editor distribution:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>Since KApp uses autoconf and automake you should have not trouble compiling it.
Should you run into problems please report them to the KDE mailing lists.</para>

<para>vdr-daemon installation details</para>

<para>First, get the latest dvb-driver and install it. (of course ;-),
compile vdr (make REMOTE=LIRC) and copy the channels.conf, timers.conf
and keys.conf in the VideoDirectory you may use.
</para>
<para>For a quick test, you can now simply start the vdr-daemon in a terminal
(of course you have to load the dvb-drivers first and launch kvdr.</para>
<para>
$>cd DVB/driver
</para><para>
$>make insmod
</para><para>
$>cd VDR
</para><para>
$>vdr -v VideoDirectory -d
</para><para>
$>kvdr
</para><para>
For a sophisticated installation follow the vdr manual.</para>

<para>WARNING</para>
<para>
Because of the open SVDRP port you should not run vdr in an open environment
(suggest using a firewall). Also, because the DVB-card does directly write
to physical grafics memory it can possibly crash your x-Server or your
entire System if the frame buffer address is incorrectly specified or reported
by the X-server's DGA extension (this is applicable for all overlay displaying
cards).
</para>
</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>Use the configuration dialog (Key-C) to change your favorite settings.</para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->