MythVideo
                                 Version 0.21


GENERAL INFO
------------

MythVideo is a MythTV module (see http://www.mythtv.org) that allows you
to play videos, DVDs and (optionally) VCDs. It can also be configured to
let you rip DVDs and transcode their video and audio content to other
(generally smaller) formats. The player can either use the MythTV
internal software (which now supports DVD menus), or simply to invoke
your favorite DVD/XVCD playing software (mplayer, ogle, xine, etc) as an
external command. The transcoding is based on and derived from the
excellent transcode package (see below).


BUILD/CONFIGURATION INSTRUCTIONS
--------------------------------

Requirements:
    MythTV 0.21 or higher installed and working

Compiling note: If you get an error on building this, that says
                something about 'mkspecs', then you don't have the
                QTDIR environment variable set.  On Debian, this
                should be set to /usr/share/qt.  I hear on
                mandrake, it's /usr/lib/qt3.  You'll need to
                figure out what it should be on your system, set
                the variable, and attempt to compile again.

In addition to MythTV's prerequisites, you'll have to have the following
software packages installed for *transcoding* to work:

   libdvdread - Needed by transcode and most direct DVD players.
                No longer required directly by MythVideo.
                http://www.dtek.chalmers.se/groups/dvd/downloads.shtml

         nasm - Not *strictly* required, but transcode seems happier
                if it's around. Using 0.98.36. You may want to do
                a ./configure --prefix=/usr/local
                http://nasm.sourceforge.net/

   mjpegtools - If you're using a hardware mjpeg capture card, you 
                almost certainly already have this. Transcode wants
                it in any case. Currently using 1.6.1.
                http://mjpeg.sourceforge.net/
                Note that mjpegtools has dependencies of its own,
                (libmovtar etc.) but that those packages are all 
                available at the mjpegtools site. This includes 
                avifile (0.7.38).

         xvid - A useful MPEG-4 compliant video codec, which is far
                more free than divx. 
                Currently using 0.9.1
                http://www.xvid.org/

       liba52 - Library for dealing with ATSC A/52 (AC-3) to handle
                DVD audio.
                http://liba52.sourceforge.net/

      libfame - Transcode will use this if it's installed.
                Currently 0.9.0
                http://fame.sourceforge.net/

    transcode - The core of the re-encoding process (most of the items
                above are actually things that transcode wants for
                full functionality). The more codecs you have
                installed, the better. You almost certainly want to
                install the divx codec, even if you plan to use xvid
                (see below).  Developers currently using 0.6.12, but
                you can probably use an earlier version (unless you're
                using subtitles, in which case you'll almost certainly
                _need_ 0.6.12 or later).  http://www.transcoding.org

If you want to be able to read encrypted DVD's, you might want to have
this installed as well:

    libdvdcss - A way to access the bits on that DVD you payed for.
                Probably want 1.2.9
                http://downloads.videolan.org/pub/videolan/libdvdcss/

If the internal player can't play your DVDs, you will need a player.
These have their own dependencies, none of which are listed here.
Depending on your distribution, there may be pre-packaged versions of
these applications available. You'll want one or more of:

      mplayer - You probably already have this working if you have
                MythVideo installed. Try to install as many codecs as
                possible while you're at it.
                http://www.mplayerhq.hu/

         ogle - Another player.
                http://www.dtek.chalmers.se/groups/dvd/

         xine - Another player. Almost certainly required for
                fully functional XVCD playback. 
                http://xinehq.de/

Once the make is completed, you should switch to root and do a
'make install'.  

- libmythvideo.so will go into /usr/local/lib/mythtv/plugins/


RUNNING MYTHVIDEO
-----------------

All the configuration is now done within the program.


INTERNET INFORMATION
--------------------
 
MythVideo now supports contacting internet sites to grab information
about the videos found. It does this by cutting out unnecessary
information in the filename and doing a search. MythVideo will also grab
a movie poster or coverart if it is available.

In order to start this process, once your videos have been scanned by
MythVideo, in the 'Video Manager' screen, simply select the video you
want to find information/artwork for. MythVideo will contact imdb.com.
If there is just one result returned, MythVideo will use the information
from that page. Otherwise, MythVideo will present you with a list of
movies and the year of the movie.

IF MYTHVIDEO DOES NOT FIND YOUR MOVIE OR JUST SEEMS TO DO NOTHING - Do
not despair! MythVideo also allows you to enter the IMDB Movie number
manually.  To enter a movie number manually or reset an entry in the
event of bad information, simply hit 'M' and select either 'Reset Entry'
or 'Manually Enter IMDB #' (depending on what you want to do).

If that fails, or you wish to set the cover art by hand, then just hit a
number key on your remote. All will be well.

Note: the imdb.pl script has dependencies you may need to install before
using.

imdb.pl Dependencies
    libwww-perl 


PARENTAL LEVEL INFORMATION
--------------------------

MythVideo now (really ... honest) supports the ability to limit what can
be viewed without a password/pin. There are 4 different levels that a
video/file can be set at. From within the configuration you can select a
default level. Any videos/files at or below that level will show up in
the list. 

MythVideo will only stay at that level until you try to change the level
(by hitting keys 1-4 in the Browse or List screens).

Note: A video that is set to level 0 will not be seen in any lists other
than the video manager. The Video Manager has complete control over the
parental levels of each video. For this reason, if the level 4 password
is set, you will be prompted upon entering the Video Manager for the
level 4 password.


VCD INFO AND DEPENDENCIES
-------------------------

To get xine working with the vcdx plugin, you will need to follow these
instructions in the sequence indicated:

    1. compile and install xine-lib (build from source)

    2. compile and install xine-ui (build from source)

    3. compile and install libcdio (build from source)

    4. compile and install vcdimager (build from source)

    5. compile and install libcdio (yes, again - rebuild it from source)
       Make sure that you re-run the configure script to pick up libvcd
       from vcdimager.

    6. compile and install xine-vcdx plugin

Unfortunately the package I had for xine did not have the xine-config
script so it was impossible to build any plugins without going back to
the original source.
    
Keybindings with xine are also another area of great joy. In order to
emulate existing usability characteristics, we want the Escape key to
take us back to the MythTV menu. This means that we need to change the
key bindings slightly for xine.

The keybindings file can be found at:

    ~/.xine/keymap

    1. Locate the value for "Menu" and change it to the following:

        # Jump to Menu.
        Menu {
            key = Escape
            modifier = control
        }

    2. Locate the value for "Quit" and change it to the following:

        # Quit the program.
        Quit {
            key = Escape
            modifier = none
        }

The following versions of xine are recommended for XVCD playback:

    xine-lib-1-rc0a
    xine-ui-0.9.22
    xine-vcdx-1-rcd0

Other required libraries

    libcdio-0.62
    vcdimager-0.7.17-cdio


FILESYSTEMS
-----------

MythVideo can often generate very large files. If you are doing perfect
rips, you probably want to make sure that your MythVideo file location
(where final files end up) is on a filesystem (ext3, etc.) that can
handle files larger than 2 gigabytes. Alternatively, you can set the MB
limit for perfect rip sizes in the setup screen. This limit is also used
for intermediate (perfect) files used during real transcoding jobs, so
it should be possible to rip *and* transcode a source file which is
larger than 2 gigabytes on a filesystem which has a 2 gigabyte maximum
file size.


SUBTITLES
---------

Subtitling with transcode is pretty much a hit or miss affair. Some DVDs
work extremely well, and some generate awful results. If you find that
MythVideo transcodes a title with subtitles badly, you are encouraged to
try and use transcode from the command line. Hopefully, future versions
of transcode will offer more robust subtitling capabilities.


CONFIGURATION
-------------

You have to go into Setup (Top Level Myth Menu --> Setup --> DVD
Settings) and make some choices. A few (more or less random) thoughts on
these:

    * DVD device should probably be /dev/dvd

    * The command to play a DVD will often be something like
      "mplayer dvd://". But if you need to do special things to your
      sound card (to make it do 5.1 passthrough, for example) or
      otherwise mess with your system, there's no reason it can't be
      a custom shell script. This is also where you want to set 
      language and/or subtitle preferences, decide on menu mode, etc.
      If you come up with a decent shell script that might be of use
      to others, think about contributing it.

    * You can keep AC3 audio in the transcoded files. For Dolby 5.1,
      this is probably a good choice as long as your myth box has
      some way to handle 6 channel sounds (e.g. SB Live passthrough). 

    * Try and use xvid. It's free and open.


FURTHER INFORMATION
-------------------

Feel free to subscribe to the development mailing list at:
http://www.mythtv.org/mailman/listinfo/mythtv-dev

A list that's restricted to the svn commit messages is available at:
http://www.mythtv.org/mailman/listinfo/mythtv-commits