SMPEG xmms plugin 0.3.3

TABLE OF CONTENTS
*****************

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

1. Install notes
----------------

This plugin uses the smpeg library (http://www.lokigames.com/development/smpeg.php3)
0.4.1 or better. 

Smpeg itself requires SDL 1.1.5+ (www.libsdl.org) or better to work and here
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,

Installing after this issue has been solved is pretty straightforward.
This will apply for both smpeg-xmms plugin only and smpeg-xmms with
included smpeg.
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 smpeg-xmms in your Input list and you are ready to play mpeg movies
using XMMS.

If you do have Xfree 4.0.1 and would like to use HW acceleration make sure
you have one of these cards:
- Matrox G200 or G400.
- Any NVIDIA card except GeForce2 with installed binary driver, that is 
available from http://www.nvidia.com.
- Intel I810.
- ATI Rage 128 with driver from current CVS.
If HW acceleration still do not work then it might work by doing an export.
export SDL_VIDEO_X11_NODIRECTCOLOR=1
Apperently a X problem.

2. Usage
--------

Add mpegs to xmms playlist just like you normal would do.
When you want to play a VCD movie use the "open location" and type
vcd:/dev/cdrom to play track 2 on device /dev/cdrom to play
another track you just do vcd:/dev/cdrom:1 where 1 is track.

In the SDL window you have these key bindings.

Left mouse button =  (in fullscreen only) pause
Middle mouse button/Space = Toggle doublesize
Right mouse button/Return = Toggle fullscreen
Mouse wheel up = Volume up 5%
Mouse wheel down = Volume down 5%
Pause/Break = Toggle pause
PageUp = next song
PageDown = previous song
Arrow key up = Volume up 5%
Arrow key down = Volume down 5%
Arrow key right = Skip 5 seconds forward in song
Arrow key left = Skip 5 seconds back in song
KeyPad plus = Resize the window 10% larger
KeyPad minus = Resize the window 10% smaller
Tab = Reset volume to xmms volume when mpeg started
Esc = Stop and close the video window
z = previous song
x = play
c = pause
v = stop
b = next song
f = toggle bilinear filtering
CTRL+p = bring up plugin preferences.

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

Start in doublesize:
Will start the window in doublesize.

Start in fullscreen:
Will start the movie in fullscreen.

Start with centered window:
will center the window on the screen.

Save states between sessions:
this will make xmms save the window state when you change song/quit/stop
xmms's smpeg plugin like if it is doublesized or fullscreen etc.

Save windowsize between sessions:
This will save the size of the window and use that as size for the next
mpeg. This option obey the "aspected ratio when resizing video window"
option. To make use of this option enable "Save states between sessions"

Close video window between sessions:
Enabling this will make the video window close when changing song.

Do NOT keep aspected ratio in fullscreen:
When enabled this will resize the mpeg to fit fullscreen mode 100% and not
keep the aspected ratio of the mpeg.

Do NOT keep aspected ratio when resizing video window:
Enable this option will turn of the aspected ratio when resizing the mpeg.

Use software blinear filtering:
This options enables smpeg's filtering to smooth the video.

Use same resolution as X when using fullscreen:
When jumping to fullscreen it will use the same resolution as your X.
*WARNING* if you don't have YUV acceleration this will be SLOOOW!

Use XMMS Audio system:
This will send the audio in to XMMS enabling effect/vis/output plugins.
This do not sync with video right now but useful anyway sometimes.

Audio only (no video):
As it say.. plays the audio and not video, here it's really useful to use
the option above.

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:
Movies that has been cat'ed together eg. cat file1.mpeg >> file2.mpeg
will show incorrect time and the timer will be twice as slow as normal.

Solution:
This is an issue with smpeg and not xmms, should be fixed soon we hope.


Bug:
Some mpegs crash xmms due to some error in mpeg frames.

Solution:
Also smpeg 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.


Bug:
Starting with "xmms *.mpeg" pops up windows as many as mpegs added

Solution:
Only happens when you enable the option
"Close video window between sessions"


Bug:
Hitting stop and then change from mpeg to mp3 or something without
SDL window will leave the SDL window open.

Solution:
Fixed in 0.3.4 :)

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

Send an email to mpeg@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)
