XINE and the divx4 decoder plugin
=================================

0: History of this readme

oct 9 2001: inital version
oct 27 2001: update - version checking and other things
nov 21 2001: update - version checking revisited and decoder releasing

1. Overview

The divx4 plugin can decode divx4 (formerly OpenDivx, a subset of 
mpeg4) and divx3.11 (or divx ;-) or msmpeg4v3) bitstreams, using
the library "libdivxdecore" from the binary divx4linux package or
a good (if you can find one) OpenDivx variant.

In versions of xine before 0.9.2, the only plugin for decoding these
streams is the ffmpeg plugin. Of course it's still available, but
you might want to consider switching to the divx4 plugin because
- it is more optimized than ffmpeg, therefore uses fewer cpu resources
- it has a postprocessing function to remove some encoding artefacts
from the decoded image.

The default settings are such that this plugin has a lower priority 
than the ffmpeg plugin. You need to actively enable the divx4 plugin 
to start using it (see section 3).

2. Requirements 

You'll need the libdivxdecore library of the divx project. Currently, 
there are two implementations: 

- divx4, commercial version of opendivx, binary package available for x86 
linux at http://www.divx.com (be careful not to wander onto an OpenDivx
link! The download link on the main page only has divx for windows. Select the 
software tab, then codecs) or http://avifile.sourceforge.net

- opendivx, open source (but not GPL, so it probably won't be included
in the xine sources), available at http://www.projectmayo.com.
There is an alternative (but based on opendivx) project at 
http://www.videocoding.de and mplayer (http://www.mplayerhq.hu) includes 
another tweaked opendivx version (but the API differs from what xine's
divx4 plugin needs).

OpenDivx development seems not very active these days. I couldn't get
the one from projectmayo to work at all (divxcore nor divx4linux).
The one from videocoding did work but has some issues, most notably
that it only worked if compiled with the -g flag, not -O2. 

Recent versions of the divx4 package include a method for getting their
version number (really the date). By default, the xine divx4 plugin
will only accept packages that
 * support the version number command
 * report that they are newer than oktober 2001
   (that used to be august, but some august packages crashed on 
    the RELEASE command, which is very important now to prevent memory
    leaks)

The version check is performed when the xine decoder is first asked to
decode a stream, not at initialization. This has a good and a bad
side:
* The good: you'll never be bothered about the version check if you don't
use the divx4 plugin (it's disabled by default, see below). This is
especially good considering some crap opendivx versions can trigger
a segmentation fault when probed for the version.
* The bad: if you use the divx4 plugin and your package is too old,
you must manually disable the plugin again in the xine input file; the
check happens too late for the plugin to disable itself (it's a long
story...)

If the version check says it's too old, but you're sure your package is OK, 
you can override the version check (see below).

3. .xinerc 

There are a number of settings that can be configured in .xinerc.
If you're using the binary divx4 package in a standard library
location, you'll probably only be interested in the priority and 
postproc settings. Adventurous souls with OpenDivx should carefully 
read all descriptions ;-)

- divx4_priority (int, default 4)

The priority of the divx4 plugin. By default, lower than the ffmpeg
priority, so you'll actively need to set this priority to a value
higher that that of ffmpeg (5) to enable this plugin. 

- divx4_libdivxdecore (string, default "libdivxdecore.so")

The decore library that the plugin attempts to open. Use a relative
filename, like the default, to search in the library path, or an
absolute one for a specific file. If the library is not found, the
divx4 plugin will disable itself, so that ffmpeg can take over.

- divx4_postproc (int, default 3)

The postprocessing level, 0 = none and fast, 6 = all and slow. You
might want to set this to 0 if you're having problems with opendivx.
Also, lower this to reduce the cpu load if you're getting dropped
frames.

- divx4_msmpeg4 (int, default 1)

Determines wether this plugin should say it can decode msmpeg4v3 or
not. The binary divx4 package can, opendivx cannot and it's difficult
to tell which is which. Set to 1 for divx4, 0 for opendivx. If you're
getting a lot of DEC_EXIT messages, chances are you're trying to
decode a msmpeg4v3 avi with OpenDivx.

- divx4_forceversion (int, default 0)

The default 0 enables version checking and is recommended for most
users. If libdivxdecore is found, but the version is not high
enough the divx4 plugin will print a warning and disable itself.
In order to test a new variant of libdivxdecore that does not 
implement version checking, or to test an old library that you 
expect to work, set divx4_forceversion to some date that xine 
accepts, for example 20010901.

Some old versions of OpenDivx are known to cause a segmentation fault
when probed for the version number. The divx4 plugin attempts to
catch this signal and prints a message when it happens. The solution
is to either
- remove the offending libdivx4decore, or
- set the divx4 priority back to a low value (like 0) (the check is
  performed at decode time, not at initalization time), or
- disable the version check by forcing the version to a too low number, 
e.g. set "divx4_forceversion:1" in .xinerc