AVI Player for XMMS plugin 1.0.1

TABLE OF CONTENTS
~~~~~~~~~~~~~~~~~

1. Install notes (Read this!)
2. Usage
3. Known bugs
4. Report a bug

1. Install notes
~~~~~~~~~~~~~~~~

This plugin uses the aviplay library version 0.53.5. Avifile is included
in the archive and will compile to a static library and then static linked
into the plugin. This means there will not be any other files installed 
exept for the plugin itself. Please make sure you don't have avifile linked
to xmms as avi4xmms require that to function, if you do you will not be 
able to play any avi files as there will be a conflict between avifile
versions.

Also, SDL library (www.libsdl.org) is required to play movies using avi-xmms.
If you plan to use software YUV decoding, you should have SDL 1.1.7 or better,
because software YUV decoders of SDL 1.1.6 (and previous versions also) are 
broken and will cause XMMS to crash.

We have the big issue with this plugin: If SDL is compiled using Xfree 4.0
and NOT Xfree 4.0.1 it will not work in a correct way and crashes a lot.
Xfree 4.0 has a threading bug in libXv.a that SDL compiles statically and
XMMS is a threaded application and that's why this plugin won't work with
Xfree 4.0. Please upgrade Xfree to 4.0.1 Else you can compile SDL without
libXv.a but you won't get Hardware acceleration do (in SDL directory):
./configure --disable-video-x11-xv

Xfree 3.3.x do not have this problem. But is in general slower due to the
lack of Hardware acceleration. But still, you may have crash in "software YUV",
if you have SDL versions prior to 1.1.7.

Installing after this issue has been solved is pretty straightforward.

untar the package, cd into it and do:
./configure && make && make install
This should take care of the installation, restart xmms and you should
have avi-xmms in your Input list and you are ready to play AVI movies
using XMMS.

2. Usage
~~~~~~~~

Add AVI movie to xmms playlist just like you normal would do.

In the SDL window you have these key bindings.

Left mouse button          = Nothing (see advanced configuration how bind it)
Middle mouse button / D    = Toggle doublesize
Right mouse button / ENTER = Toggle fullscreen
SPACE, PAUSE               = Toggle pause

PAGEUP                     = Next song
PAGEDN                     = Previous song

UP                         = Volume up 5%
DOWN                       = Volume down 5%

LEFT                       = Unwind 5 seconds of movie
RIGHT                      = Skip 5 seconds forward

Esc                        = When pressed first time, pauses, 
                             second time - stops movie and closes the window

Z                          = Previous song
X                          = Play
C                          = Pause
V                          = Stop
B                          = Next song
P                          = Bring up plugin preferences.


Open preferences and click on the avi-xmms in the Input plugin list, choose
configure and you'll see the options.

WINDOW VISUALIZATION OPTIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~  

Always center:
 - will always center movie window

Preserve aspect ratio:
 - will make movie to be shown proportionally
 
Enable manual resize:
 - this option lets you resize the window manually
 - if you don't like the way movie is resized when aspect ration is preserved,
   you might look into advanced options.
 

FULLSCREEN OPTIONS
~~~~~~~~~~~~~~~~~~

Enable fullscreen:
 - play movie in fullscreen mode

Preserve aspect ration in fullscreen:
 - if the movie is designed for wide screen, this option will add black 
   bars around the movie to keep the proportion

Switch videomode, if possible:
 - by default, for fullscreen playback your desktop resolution is used; this
   option changes the mode to the lowest possible, to increase video output
   performance
 - in the "Advanced" options dialog you can specify different video mode
 

HARDWARE ACCELERATION
~~~~~~~~~~~~~~~~~~~~~

Use YUV acceleration, if available:
 - when this option is on, player tries to access your hardware directly and
   thus generally increase performance; this is available only on XFree 4.0.1
   and higher.
  
Use software YUV, if no hardware
 - this option tries to decode YUV via software; this will generally decrease 
   performance, so don't enable this option, unless you can't play movie other 
   way.
   
   
AVIPLAY AUDIO SYNCRONIZATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~   
  - use the slider to adjust audio playback time relative to video playback
    (in seconds)


3. Known bugs
-------------

Bug:
When using SDL compiled on Xfree 4.0 and not Xfree 4.0.1
xmms will crash on next song and/or stop.

Solution:
Install Xfree86 4.0.1 and recompile SDL or if you can manage without the
hardware acceleration recompiled SDL using:
 ./configure --disable-video-x11-xv
This will turn off hardware acceleration so things will get slower,
but on the other hand will solve the crashing issue.


Bug:
When you "Enable fullscreen" during movie playback, the checkbox will be 
still turned on, when you back from fullscreen.

Solution:
Just ignore this feature.


Bug:
Some AVI files crash xmms due to some error in AVI frames.

Solution:
This is AVIFILE library related bug and should be fixed soon if we are lucky.


Bug:
In KDE 1.1.x the window get about 10x10 pixels big.

Solution:
SDL related, please upgrade to SDL 1.1.4 where it's fixed.


Bug:
You installed SDL from package (rpm/deb/tgz) and it's slow
and uses a lot of CPU and you use Xfree 4.0.1

Solution:
Most precompiled packages don't compile libXv.a into SDL.
What you need to do is to uninstall the precompiled package
and compile SDL yourself to get the Hardware acceleration.


4. Report a bug
---------------

Send an email to avi@xmms.org please specify versions of:
Xfree86
SDL (also if this was compiled by you or a package)
XMMS
Your system config (cpu, gfx card, soundcard)
