path: root/INSTALL

OVERVIEW
~~~~~~~~
Introduction
A note about VDPAU
Getting a recent xine
Patching xine's source
Building xine
Testing xine
Patching VDR
Makefile settings
Building vdr-xine
Xine VDR version mismatch
Testing vdr-xine
Using budget cards
Remote learning mode
Using full featured cards
Additional software
Last but not least


INTRODUCTION
~~~~~~~~~~~~
As you can read these lines, you've successfully extracted the tar archive of
VDR plugin xine. The plugin supplies VDR with an output device in software by
using xine. It's most useful if you don't own a DVB card which can be directly
connected to a TV set, or if you want to watch HDTV (MPEG2/H.264) content which
typically cannot be displayed by such a card.

Usually, the contents of this package should be below the PLUGINS subdirectory
of VDR. I've installed the source of VDR in directory "/soft/src/VDR", so the
files of this package reside in directory "/soft/src/VDR/PLUGINS/src/xine".


A NOTE ABOUT VDPAU
~~~~~~~~~~~~~~~~~~
VDPAU is a new API for hardware assisted video decoding. If you plan to use
VDPAU, you will need to choose different sources for xine-lib. To stay with
xine-lib-1.1 you can choose the VDPAU development fork named xine-vdpau which
is available via svn and go on with patching it for vdr-xine:

	svn co svn://jusst.de/xine-vdpau

In case you would like to use xine-lib-1.2 then you need to patch in VDPAU
support. You'll find updated patches against xine-lib-1.2 here:

	http://jusst.de/vdpau

The patches are named like xine-lib-1.2-vdpau-r157.diff.bz2 where r157 for
example indicates the vdpau svn revision this patch is based on.


GETTING A RECENT XINE
~~~~~~~~~~~~~~~~~~~~~
To compile and use this plugin, you must get a recent Hg/CVS version of xine.
When you are going to use xine-lib-1.2 then you can most often find binary
packages for your distribution. Additionally you'll have to install a suitable
devel-package too. After installing these packages, just read on in section
PATCHING VDR.

To retrieve xine via Hg/CVS, please go to the project homepage of xine (which
is http://xine.sf.net). On the main page, look for downloads and then for CVS
or Mercurial (Hg) respectively.
Follow the instructions on this page and checkout module "xine-lib". You also
need a recent version of a GUI for xine, so checkout module "xine-ui". I've 
checked out both modules and they reside in directory "/soft/src/xine-lib" 
and "/soft/src/xine-ui" respectively.
My Hg/CVS commands were:

  hg clone http://hg.debian.org/hg/xine-lib/xine-lib

  cvs -d:pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine login
  cvs -z9 -d:pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine co xine-ui

NOTE: As space permits you'll also find archives of both modules on my homepage
      which you might use if you don't have access to CVS servers. Just choose
      the most recent archives for the most recent vdr-xine plugin.

NOTE: The above command and my archives on the homepage supply xine-lib-1.1.x,
      which needs to be patched as mentioned below. If you like, you may want
      to try xine-lib-1.2, which contains already everything regarding vdr-xine
      and therefore doesn't need to be patched.


PATCHING XINE'S SOURCE
~~~~~~~~~~~~~~~~~~~~~~
Next, you have to extend xine-lib to support a media resource location (mrl)
type named "vdr:". Change to the parent directory of module "xine-lib", e. g.
in my case "/soft/src". Then apply the patches supplied with this distribution
(in case you are using xine-lib-1.2, there is no need for patching).

The patches will add new source files to xine-lib's source tree and will add
keybindings to xine-ui for supporting my plugin's remote functionality. I use
the following commands for patching:

  patch -dxine-lib -p1 < /soft/src/VDR/PLUGINS/src/xine/patches/xine-lib.patch
  patch -dxine-ui -p1 < /soft/src/VDR/PLUGINS/src/xine/patches/xine-ui.patch

NOTE: It might well be that some of the patch files are empty if my changes
      have been ported back into xine's CVS repository. But I didn't want to
      remove those empty files as it might break some build scripts which
      people created to build xine.


BUILDING XINE
~~~~~~~~~~~~~
Now, it's time to build xine-lib. Change back to the directory of module
"xine-lib", e. g. "/soft/src/xine-lib", and run "./autogen.sh".

Please don't call "configure" directly at this stage, even if you don't use
the CVS source. Doing so will miss necessary modifications to the Makefiles
and finally lead to not building the new plugins!

"./autogen.sh" will need some additional tools which must have at least a
certain minimum version to successfully build xine. If you look into the
head of "./autogen.sh" then you'll find the following information:

	# Minimum value required to build
	WANT_AUTOMAKE_1_8=1 export WANT_AUTOMAKE_1_8
	WANT_AUTOMAKE=1.8 export WANT_AUTOMAKE
	AUTOMAKE_MIN=1.8.0
	AUTOCONF_MIN=2.59
	LIBTOOL_MIN=1.4.0

On my openSUSE 11.1 I use the following versions:

	automake-1.10.1-4.286
	autoconf-2.63-1.136
	libtool-2.2.6-1.35

If you have trouble running "./autogen.sh" respectively the hereby called 
configure please consider upgrading the above mentioned tools.

Calling "./autogen.sh" will create all the files which configure needs, and
will finally run configure. If you need special options for configure, you can
specify them as command arguments to autogen.sh.

If you intend to use vdr-xine for watching H.264 channels, I highly recommend
to install a recent FFmpeg and to add the switch "--with-external-ffmpeg" when
compiling xine-lib (it's the default since xine-lib-1.1.15).

When building xine-ui I suggest the following configure options:

  --enable-vdr-keys

    Adds VDR's commands to xine's keybinding dialog. You're then able to assign
    keys in xine to VDR's commands and therefore control VDR by pressing the
    appropriate keys in xine's window.

For example I run the following command for building xine-ui:

  ./autogen.sh --prefix=/soft/xine-ui-cvs --enable-vdr-keys

As xine supports a lot of media, it also requires a lot of libraries to compile
all modules. Please see the file "config.log" and the xine documentation to get
all the required components for the plugins you want to build. After configure
has been run (automatically from autogen.sh), the commands "make" and "make
install" should provide you with a recent version of module "xine-lib". 

After that, you can go to the directory of module "xine-ui" and repeat the
steps for building the standard GUI for xine.


TESTING XINE
~~~~~~~~~~~~
Please test the newly compiled xine with a sample MPEG file, to see whether it
works. Be careful, that not any previously versions of xine respectively
plugins get loaded. Use the option "--verbose=2" and verify that the output
of xine contains a line which indicates loading "xineplug_vdr.so".


PATCHING VDR
~~~~~~~~~~~~
There may be further patches available on my homepage that enhance VDR for best
cooperation with vdr-xine. For further details about the patches please have a
look into the corresponding README file on my homepage. I highly recommend to
apply at least some of them.


MAKEFILE SETTINGS
~~~~~~~~~~~~~~~~~
Before you go on to compile vdr-xine, please make sure that you've installed
xine-lib already. Otherwise you'll get a lot of errors due to missing header
files respectively missing structure members if there are already old versions
of some header files available!

Then please have a look at my plugin's "Makefile" and locate "INCLUDES", 
"VDR_XINE_FIFO_DIR" and "VDR_XINE_SET_VIDEO_WINDOW".

As the plugin depends on xine's data structures of it's companion, it is 
necessary to include xine's header files. For this to work, INCLUDES must
contain the include path of xine's header files. Therefore, pkg-config is
asked to supply the path as it was set when xine was compiled. Make sure
that pkg-config reports the include directory of your previously installed
xine-lib by running the following command in a shell:

  pkg-config --cflags libxine

Depending on your setup, you may need to adapt the environment variable
PKG_CONFIG_PATH to change the order in which pkgconfig directories are
queried to achive the goal. One reason for getting a wrong directory 
reported is that a xine-lib-devel package is still installed. Simply
uninstall it and try building vdr-xine again.

The plugin will create its fifos (which are used for data exchange with xine)
below directory "VDR_XINE_FIFO_DIR" (e. g. "/tmp/vdr-xine"). It's up to
you to create and maintain any parent directories of the directory you specify
here (in this case "/tmp"); the plugin will itself try to create and remove
the final directory (in this case "vdr-xine"). So you may need to create the
vdr-xine directy too, if the plugin is not allowed to do it on its own at
runtime.

NOTE: xine's autoscan button "VDR" currently expects "VDR_XINE_FIFO_DIR" to
      be set to directory "/tmp/vdr-xine"!

If you are using the yaepg plugin and have patched VDR to support it, then you
might also enable VDR_XINE_SET_VIDEO_WINDOW. vdr-xine will then access the new
OSD member vidWin to extract position and size of the video window and ask xine
to position the video accordingly within the original frame.


BUILDING VDR-XINE
~~~~~~~~~~~~~~~~~
Just go to VDR's source directory and type "make plugins". This should compile
my plugin and "xineplayer". For more information about xineplayer please have
a look into MANUAL.


XINE VDR VERSION MISMATCH
~~~~~~~~~~~~~~~~~~~~~~~~~
In the case you've got a compilation error which asked you to read this
section, please try the following to solve this issue. Otherwise skip this
section.

- Make sure that the above mentioned pkg-config command shows you the
  correct location where xine-lib's include files reside.
- Make sure that there exists xine/vdr.h below this directory. In the
  case that it does not exist and you are building xine-lib-1.1.x please
  check whether you've applied the xine-lib.patch as mentioned above.
- When the file exists and you still get this error then you're most likely
  trying to mix different versions of vdr-xine and xine-lib. Make sure that
  you've installed a matching version of xine-lib. You may also need to
  upgrade vdr-xine to use a recent version of xine-lib.
- Try to clean the build if the error persists after any changes like that:
  make plugins-clean


TESTING VDR-XINE
~~~~~~~~~~~~~~~~
For a first run, go to the VDR directory (e. g. "/soft/src/VDR") and issue the
following command:

  ./runvdr "'-Pxine -r'"

This should start VDR and have it load my plugin, but if this is the first time
that you use my plugin it will also abort immediately with an error message
like this:

  vdr-xine: error: couldn't open '/video/plugins/xine/noSignal4x3.mpg'!
  vdr-xine: error: couldn't open '/video/plugins/xine/noSignal.mpg'!
  vdr-xine: error: couldn't open '/video/plugins/xine/noSignal16x9.mpg'!
  vdr-xine: error: couldn't open '/video/plugins/xine/noSignal.mpg'!

The exact path depends on VDR's directory for config files (typically '/video'
but see VDR's manual). To get vdr-xine working just create the directory
"xine" below "plugins" and copy the contents of the directory "data" (located
in my plugin's source directory) into the new directory. After that retry
starting VDR again as mentioned above.

If no errors are reported, six fifos should now exist below "VDR_XINE_FIFO_DIR"
(e. g. "/tmp/vdr-xine"), named "stream", "stream.control", "stream.result"
and "stream.event" as well as "external.control" and "external.result". All of
them have a size of 0 bytes.

At any time, you can use xine to connect to the above mentioned fifo "stream"
(while the "external" fifos are used by xineplayer). The MRL may look like 
this, depending on the "VDR_XINE_FIFO_DIR" at compile time:

  vdr://tmp/vdr-xine/stream

So either type something like

  xine vdr://tmp/vdr-xine/stream

or just hit the autoscan button "VDR" in xine.

You should now see a beautiful "vdr-xine" logo on screen!


USING BUDGET CARDS
~~~~~~~~~~~~~~~~~~
If your system only has budget DVB cards (i. e. cards that don't supply an 
MPEG decoder and rely on the CPU to decode the MPEG stream), then loading
vdr-xine will supply VDR with a "software device" with a software MPEG decoder.
VDR will choose this device as output device by default.

Depending on your previous usage of VDR, it might well be that VDR has entered
remote learning mode and you may see an OSD which invites you to press keys.
Please see the VDR manual for more information.

Where VDR's configuration suits your receiving equipment, it is most likely
that VDR enters transfer mode and you'll see live TV in xine!


REMOTE LEARNING MODE
~~~~~~~~~~~~~~~~~~~~
vdr-xine's internal remote (enabled by the "-r" switch) behaves different to
VDR's other remotes as there is no key learning necessary within VDR as the
keys have to be assinged in xine's keybinding dialog.

NOTE: Please don't worry about entries like the following in VDR's logfile
      as there is currently no other way to skip key learning for a still
      unknown remote: "ERROR: remote control XineRemote not ready!"

Any other remote (e. g. VDR's built in keyboard remote) will make VDR start in
remote learning mode if there are still no keys learnt in remote.conf for that
kind of remote or when no remote.conf exists so far.

To successfully enter remote learning mode, you'll have to connect xine to VDR
immediately after starting VDR. Otherwise you'll miss VDR's first prompt (which
is visible for about 10 seconds per remote) and VDR will either abort learning
mode or go on to learn the next remote.

NOTE: It may take about 10 seconds after pressing a remote key in "Phase 1" of
      remote learning mode until VDR goes on to "Phase 2".


USING FULL FEATURED CARDS
~~~~~~~~~~~~~~~~~~~~~~~~~
If your system is equipped with a full featured card (i. e. a card that has
its own MPEG decoder), you'll see in xine nothing more than "vdr-xine". This
is because VDR has chosen the hardware MPEG decoder over the software MPEG
decoder, so the output device is your full featured card. To get the output to
xine, you'll have to go to VDR's OSD setup menu and choose the highest device
available, which should be vdr-xine's software device. 


ADDITIONAL SOFTWARE
~~~~~~~~~~~~~~~~~~~
To be able to have VDR grab the image currently displayed in xine, you'll
need the programs "y4mscaler", "y4mtoppm" and "pnmtojpeg".

On my system I use the following versions:

	y4mscaler	9.0
	y4mtoppm	part of mjpegtools-1.8.0
	pnmtojpeg	part of netpbm-10.26.44-98.16

By default, vdr-xine assumes to find these utilities on your PATH. But you can
specify the absolute path to them by setting the Makefile variables
VDR_XINE_Y4MSCALER, VDR_XINE_Y4MTOPPM and VDR_XINE_PNMTOJPEG.


LAST BUT NOT LEAST
~~~~~~~~~~~~~~~~~~
After you can see VDR's OSD in xine, you've done everything well. Now go on
and setup xine and my plugin to suit your needs. See the file "MANUAL" for more
information, e. g. how to bind keys in xine to VDR commands.

As mentioned above you've copied some data files to ".../plugins/xine". Some of
them were named "noSignal*x*.mpg" and is responsible for displaying "vdr-xine"
on screen. After you've setup everything properly you might be annoyed of this
message whenever you switch channels or when listening to radio stations.

Therefore I've supplied additional files "noSignal*x*-completelyBlack.mpg"
which show a completely black screen instead. If you prefer a black screen
instead of "vdr-xine" just move "noSignal*x*-completelyBlack.mpg" over the
files named "noSignal*x*.mpg".

Alternatively you may try files like "noSignal4x3-smallTextAtBottom.mpg" or
"noSignal4x3-old.mpg".

BTW: the ...4x3... or ...16x9... indicate which aspect ratio should be assumed
     for the files. vdr-xine tries to load both specific files and falls back
     to the file name "noSignal.mpg" when a specific file does not exist.
     vdr-xine will then choose the file to display depending on VDR's DVB setup
     option video format.

In case none of the files suits, you may create your own files. Just provide
a suitable PNG image named noSignal*x*.png and run mkNoSignal.sh. Keep in mind
that the PNG image must be true color even if it just shows grey content and
it should be of a size which matches your TV channels e. g. something like
720x576 or 704x576. Furthermore it shouldn't be a too complex image as the
resulting MPG files must not exceed 64 kB.

BTW: mkNoSignal.sh requires the following tools on your path:

	pngtopnm	part of netpbm-10.26.44-98.16
	ppmtoy4m	part of mjpegtools-1.8.0
	mpeg2enc	part of mjpegtools-1.8.0

Have fun!