This is a "plugin" for the Video Disk Recorder (VDR).

Written by:                  Mikko Novaro <miknov@gmail.com>

Project's homepage:          http://users.utu.fi/miknov/vdr-openmhp/

Latest version available at: http://users.utu.fi/miknov/vdr-openmhp/

See the file COPYING for license information.

Description:

This is an OpenMHP adaptation for VDR. OpenMHP is a free open source
MHP implementation. The purpose of the plugin is to enable MHP
applications, called xlets, to be run in VDR.

Please note, that this is not a finished product.


FEATURES (or the lack thereof):

The plugin is currently based on a specific version of OpenMHP, namely
1.04, and it may not work with a given later version.

OpenMHP is not a complete MHP implementation, so even in theory, all
the xlets will not work. The number of working xlets is also limited
by the restricted features of this plugin. Basically a candidate for a
working xlet should
  1) work in plain OpenMHP and
  2) require only key command input

This said, the plugin has already been succesfully used to run several
xlets.

Xlet graphics are displayed on VDR's on screen display (OSD), and as
such the maximum number of colors is restricted to 256, and may be
lower depending on the display device in use. The color reduction is
done by the plugin, and a dithering option is provided. MHP's
background layer is also displayed on the OSD.

Scaling video window by the xlets is supported using the method used
by the YAEPG plugin. This method is supported apparently only by full
featured cards and the Xine plugin (with which I have tested
it). Using the method requires applying yaepg's patches to VDR and DVB
driver's "osd.h" include file. Installing the yaepg itself is not
required. The feature disabled by default.

An X environment is requirement, but a virtual X server can be
used. Options for using Xvfb or Xvnc are provided. Choosing to use
either one even while running X (e.g. when using Xine) is usefull to
avoid the "flashing" of xlet's window while starting an xlet. The
flashing can, in addition of causing an undesired visual effect, lead
to loss of focus on other GUI applications.

OpenMHP printouts are discarded by default. They can be turned on or
directed to log files (at /tmp/openmhp-log) from the plugin's
options.

Receiving xlets from dvb transmission is beyond the scope of this
plugin. To this end, vdr-mhp plugin (0.0.3) can be used.


REQUIREMENTS:

In addition to the libraries listed in the installing section below,
you'll need Sun Java JRE. The plugin has been tested with version
1.4.2, but at least newer versions should work too.

Perl and ImageMagick are also required, but with any luck, they'll be
supplied with your Linux distribution.

ImageMagick uses a program called mpeg2decode, which can be obtained
from

http://www.mpeg.org/MSSG/ , or directly from
ftp://ftp.mpegtv.com/pub/mpeg/mssg/mpeg2vidcodec_v12.tar.gz .

Build it, and place mpeg2decode from src/mpeg2dec on your path.

(I'd be interested in hearing of a more readily awailable way of
converting an "i-frame" mpeg to an image format, such as jpeg.)

Opting to use Xvfb or Xvnc (RealVNC has been tested), the respective
software is of course needed.

The plugin has been tested with recent versions of VDR (1.3.27 at the
time of writing), and I don't know whether it works with older
versions. Also, the plugin has in effect been tested only with VDR's
xine plugin.

For reasonable performance, hardware mpeg decoding or a fast (over 1
GHz) computer should be used.


----------------------------------------------------------------------

INSTALLING:

For generic guide on installing VDR plugins, see
http://www.linuxtv.org/vdrwiki/index.php/Plugin_installation

1) INSTALL THE LIBRARIES

Get the following libraries and install them as a directory tree as
shown below. The version numbers are of tested releases; others may or
may not work.

 - OpenMHP binary distribution (1.04)
   http://www.openmhp.org/ *download requires registration*

      - JMF, Java Media Framework (2.1.1e; jmf-2_1_1e-alljava.zip)
        http://java.sun.com/products/java-media/jmf/2.1.1/download.html

      - JavaTV (1.0)
        http://www.sun.com/software/communitysource/javatv/download.xml
        *download requires registration*

 - Apache Xerces2 Java (2.7.0; Xerces-J-bin.2.7.0.tar.gz)
   http://xml.apache.org/xerces2-j/

Choose a location for the base directory [1] of the libraries. It can
of course be in the plugin directory, but this is not required. Unpack
the libraries and create symbolic links as shown in the tree (->'s).

.
`-- openmhp_lib [1]
    |-- JMF -> JMF-2.1.1e/
    |-- JMF-2.1.1e
    |   |-- bin
    |   |-- doc
    |   `-- lib
    |       `-- jmf.jar
    |-- javatv_fcs
    |   `-- javatv.jar
    |-- openmhp -> openmhp104_bin/
    |-- openmhp104_bin
    |   |-- documentation
    |   |-- examples
    |   |-- org
    |   |-- policy
    |   |-- projects
    |   `-- static
    |-- xerces -> xerces-2_7_0/
    `-- xerces-2_7_0
        |-- xercesImpl.jar
        `-- xml-apis.jar

To create the symlinks go to the library base directory [1], and give
the following commands (if you have different version of any library,
change them as needed):

ln -s openmhp104_bin openmhp
ln -s xerces-2_7_0 xerces
ln -s JMF-2.1.1e JMF


2) MODIFY SETUP VARIABLES TO SUIT YOUR SYSTEM

Open file "exec_java.sh" from the plugin directory for editing. Locate
variable "OPENMHP_DIR" and change it to point to the location of your
library base directory [1].

Also, make sure that the path variables in the Makefile match your
system.


3) BUILD AND TEST THE PLUGIN

Create a symlink for the plugin in the vdr plugin directory and make
the plugins. If all goes well, the plugin should now be ready for use.
You can use the plugin by running VDR with "-Popenmhp" argument. Of
course, you're still missing MHP applications.

To test the plugin properly, create a directory to store the xlets in
(default is "/video/plugins/mhp-cache", which can be changed from the
plugin's setting through vdr's menus):

     mkdir /video/plugins/mhp-cache

Copy the example xlets from the OpenMHP directory. "cd" into the
openmhp104_bin directory, and do

     cp -r examples /video/plugins/mhp-cache/001
     
Go to this plugin's directory, and do

     cp misc/examples.ait /video/plugins/mhp-cache/001.ait
     
The "001" refers to the first channel in VDR. You're free to replace
it with any other you might prefer. Start VDR (with "-Popenmhp") and
change to channel 1. OpenMHP menu should now have two entries, "Hello
world" and "Color demo".

To add your own xlets, use the examples.ait as a template.


4) ENABLING VIDEO SCALING

To enable video scaling, you'll need to apply the patches required by
the yaepg plugin. You won't need to install the plugin itself.

First you'll need the patch for VDR, named vdr-X.X.XX-core-yaepg.diff,
the X's signifying your VDR version.  To apply the patch, copy the
patch into your VDR directory, cd into it and do

     patch -p1 < vdr-X.X.XX-core-yaepg.diff

Next you'll need to patch the DVB driver includes your VDR
installation uses. To do this, change into the driver include
directory (/home/vdr/DVB/include/linux/dvb in my case). Copy the patch
(osd.h.diff, supplied with the yaepg plugin) there, and (with
appropriate rights) do

     patch -p0 < osd.h.diff

You'll also need to un-comment variable ENABLE_VIDEO_SCALING in the
OpenMHP plugin's Makefile to enable the scaling.

If you are using Xine plugin, enable VDR_XINE_SET_VIDEO_WINDOW in the
plugin's Makefile. Also make sure, that when you run Xine itself, use
"--post vdr" command line parameter, as in

     xine --post vdr

Now, recompile VDR and the OpenMHP (and Xine) plugin ("make
plugins-clean", "make plugins").

The patches are supplied with the yaepg plugin, but the VDR patches
included are rather old. Newer patches can be found from
http://www.hoochvdr.info/ .


5) THE VDR-MHP PLUGIN

This plugin relies on vdr-mhp plugin (v.0.0.3) to receive xlets from
the dvb transmission. There are, however, a few things to note.

If you are using a recent version of VDR (somewhere around 1.3.20 or
later; you can check if you need it by trying to make the plugin
first), you'll need to patch the mhp plugin. To do that, change to mhp
plugin's directory, and do

     patch -p1 < ../openmhp/patches/mhp-0.0.3.diff

If you are using xine plugin, issue also the following command (still
in the mhp plugin's directory):

     patch -p1 < ../openmhp/patches/mhp-0.0.3-xine.diff

To use mhp plugin with OpenMHP plugin, use the following settings for
mhp plugin (accessible through VDR's menus, when mhp is in use, or by
editing the /video/setup.conf file):

     Carousel files save path:       /video/plugins/mhp-cache
     One subdirectory per carousel:  no

If you haven't previously installed the mhp plugin, it may be more
convenient, while you're at it, to give yet another command in the mhp
plugin's directory to change the setup defaults to those above:

     patch -p1 < ../openmhp/patches/mhp-0.0.3-setup.diff

Now "make" the plugins as usual.

The mhp plugin can be downloaded from
http://www.powarman.de/vdr_plugins.htm

----------------------------------------------------------------------

TROUBLESHOOTING:

If an xlet doesn't work, try to run it with just plain OpenMHP first.


DEVELOPER NOTES:

I have tried to fashion the VDR independent part of this plugin as a
separate OpenMHP library, so that it might be used to enable OpenMHP
functionality in other software than VDR also. It is located in the
libopenmhp directory. The interface isn't set in stone, though.

The plugin's and the libopenmhp's debug printout can be turned on from
their corresponding Makefiles.

The java part of the plugin is compiled with the scripts located in
the libopenmhp/java subdirectory. They are to be run in the same
directory they are located in.

Some source files modified from the original OpenMHP are included in
the java subdirectory. The modifications are made against OpenMHP
version 1.04, and may need to be updated or remodified when switching
to newer version of OpenMHP. The modifications are marked with
"miknov".


WISHLIST FOR VDR/DVB FEATURES ;)

 - Support for greater color depth OSD
 - Generic interface for video scaling
 - Support for layers (e.g. background layer)
