                             MythDVD
                           Release 0.17

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

MythDVD is a MythTV module (see http://www.mythtv.org) that allows you to
play 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 playing features are simply myth-style wrappers for
your favorite DVD/XVCD playing software (mplayer, ogle, xine, etc). The
transcoding is based on and derived from the excellent transcode package
(see below).



BUILD INSTRUCTIONS
------------------

First, you need MythTV to be installed. If you don't have that
done, don't even bother with this, as it won't work.

Also, you need MythVideo installed (because mythDVD needs to know where you
like to store your videos, and that's defined in the MythVideo setup).

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.
                Crucial for ripping functionality of mythDVD.
                Currently using 0.9.4
                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.theorie.physik.uni-goettingen.de/
                ~ostreich/transcode/


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.7
                http://developers.videolan.org/pub/videolan/libdvdcss/   


To simply play DVD's (independent of transcoding), 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/


Ok, still with me? To configure the source code for transcoding and xvcd
viewing, type:

                ./configure --enable-transcode --enable-vcd

You can toggle xvcd playback functionality with the --enable-vcd argument.

For just DVD playback, you can do:

                ./configure 

                or

                ./configure --disable-transcode

Next:

                qmake mythdvd.pro
                make
                make install


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
-----------

    MythDVD 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
MythDVD 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.

FOR MORE INFO
-------------

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 CVS commit messages is available at:
http://www.mythtv.org/mailman/listinfo/mythtv-commits

