annotate DOCS/README @ 281:6c3a2c2c966d

big review

MoviePlayer v0.11        (C) 2000-2001. by Arpad Gereoffy  (A'rpi/ESP-team)
=================           * See the file AUTHORS for the complete list! *

About:
~~~~~~
Yes. Yet another movie player for linux.
What is the special with this? It works, at least for me :)
I've tried lots of players under linux (mtv,xmps,dvdview,livid/oms,VideoLAN,
xine,xanim,avifile,xmmp) but they all have some problem. Mostly with
special files or with audio/video sync. Most of them is unable to play
both mpeg1, mpeg2 and avi (DivX) files. Many players have image quality
or speed problems too. So I've decided to write/modify one...

Short history:
- mpg12play v0.1 has born, using libmpeg3 from www.heroinewarrior.com
- mpg12play 2nd generation (v0.5-), using dvdview by Dirk Farin
- mpg12play 3nd generation (v0.9-), using libmpeg2 (mpeg2dec) by Aaron Holtzman
- mplayer has born, containing mpg12play 0.90pre5 and a new simple avi player
- mplayer 0.10, mpeg and avi player in a single binary
- mplayer 0.11: added .asf file support, and OpenDivX en/decoding

As you see, I didn't write any codecs, just some players. But I spent
a lot of time finding the best way to parse bad damaged input files
(both mpg and avi) and to do perfect A-V sync with seeking ability.
My player is rock solid playing damaged mpeg files (useful for some VCDs),
and it plays bad AVI files which are unplayable with the famous
windows media player. Even AVI files without index chunk are playable!
As you see, stability and quality are the most important things for me,
speed has lower priority, but is still very important.

What about the GUI?
I'm not a GUI programmer. I hate GUIs, I like the pure black 80x25 console.
So the player has only keyboard control from the controlling console/xterm now.
But there is a GUI development for the player, coordinated by Pontscho/Fresh!
It's still under development, but it will be merged and released soon.
BTW he needs some nice skins, if you are a good graphician, contact him!!!

Win32 codecs?
Yes, we are using Win32 (Video for Windows) codecs for AVI/ASF decoding.
They must be installed to the /usr/lib/win32/ directory, with all lower case.
You can grab the codecs package from our homepage, or can be found in your
C:\WINDOWS\SYSTEM\ dir, see codecs.c for filenames.
Some people asked why don't we use ActiveMovie/DirectShow codecs. The reason is
simple: we'd have to emulate the whole DirectX architecture and implement the
(patented!) COM interface to be able to use them. BTW the old VfW DivX codec
is faster than the new .AX version, but it has no quality/CPU setting
option (this is an improper name, since it doesn't affect the decoder. If
it's set to 1 or higher, it applies a filter which decreases blockiness and
eats away CPU cycles).

Supported input formats:
~~~~~~~~~~~~~~~~~~~~~~~~
- VCD (Video CD) directly from CD-ROM or from CDRwin's .bin image file
- MPEG 1/2 System Stream (PS/VOB) and Elementary Stream (ES) file formats
- RIFF AVI file format
- ASF 1.0 file format

Supported audio codecs:
~~~~~~~~~~~~~~~~~~~~~~~
- PCM (uncompressed) audio (8/16 bit, mono/stereo)
- MPEG layer 2/3 audio  (using mp3lib, based on mpg123 [www.mpg123.de])
- AC3 audio             (using ac3dec/libac3)
- Win32 ACM audio codecs (the *.ACM files)  [Only in the AVI player]
  tested with: DivX audio, MS-ADPCM
- aLaw audio            (using code from xanim)
- MS-GSM audio          (using modified xa_gsm.c from avifile)

Supported video codecs:
~~~~~~~~~~~~~~~~~~~~~~~
- MPEG 1 and MPEG 2 video decoder (using mpeg2dec/libmpeg2, supports         
  3DNow! and MMX)
- Win32 ICM (VfW) video codecs (for example DivX using DIVXC32.DLL)
- OpenDivX encore & decore (see ProjectMayo)

Supported video output devices:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- mga:	Matrox G200/G400 hardware YUV overlay via the mga_vid device
- xmga:	Matrox G200/G400 overlay (mga_vid) in X11 window
	(Xv emulation on X 3.3.x !)
- x11:	X11 optionally with SHM extension
- dga:	X11 DGA extension (only in 24/32bpp)
- fsdga:X11 DGA extension with fullscreen scaling (only 24/32bpp and MPEG!)
- xv:	X11 using overlays with the Xvideo extension (hardware YUV & scaling)
- gl:	OpenGL renderer, works only with Utah-GLX! (no DRI or nVidia drivers)
- syncfb: Matrox G400 YUV support on framebuffer (not tested, maybe broken)
- fbdev:Output to general framebuffers (only MPEG1/2 and OpenDivX)
- 3dfx:	Voodoo2/3 hardware YUV (/dev/3dfx) support (not yet tested, maybe broken)
- sdl:	SDL >= v1.1.7 driver (slower than 'x11', but supports software scaling)
	(NOT supported by us! Don't submit SDL bugreports!)
- null:	Null output (for speed tests/benchmarking)
- pgm:	PGM file output (for testing purposes)
- md5:	MD5sum output (for mpeg conformance tests)

NOTE: check DOCS/VIDEOCARDS !
NOTE: maybe not all are available for AVI files

Supported audio output devices:                                              
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- OSS driver
- ALSA driver with OSS emulation (NOT recommended, causes annoying delays)
- ESD with the esddsp utility (not tested)

NOTE: check DOCS/SOUNDCARDS !

Speed:
~~~~~~
Most of time-critical parts are optimized for MMX/SSE/3DNow!.
You can improve rendering speed by setting up MTRR registers, see doc in MTRR.
Some benchmark results can be found in the doc file SPEED.

Usage:
~~~~~~
  mplayer [options] [-vo driver] [path/]filename

  Options:
    see  mplayer -h for options
    see  mplayer -vo help for available output drivers

  Keys:
    <-  or  ->      seek backward/forward 10 seconds
    up or down      seek backward/forward 1 minute
    p or SPACE      pause movie (press any key to continue)
    q  or  ^C       stop playing and quit program

  Examples:
    mplayer -vo x11 /mnt/Films/Contact/contact2.mpg
    mplayer -afm 3 /mnt/DVDtrailers/alien4.vob
    mplayer -vcd 2 /dev/cdrom
    mplayer -alsa -abs 65536 -delay -0.4 -nobps ~/movies/test.avi

  Note:  for using Matrox YUV driver (-vo mga or xmga), you have to first
         load the driver: insmod drivers/mga_vid.o

License:                                                                     
~~~~~~~~
Since MPlayer incorporates a lot of code from other projects, this isn't
decided yet.
We're going for GPL (will be pretty hard, though).

TV output:
~~~~~~~~~~
If you have a Matrox G400 Dual-Head card, you can watch movies on TV,
using TV-out feature of the second head. You must have matroxfb support
enabled in your kernel (2.4.x kernels). You don't need X11 for this!
Tested only with PAL TV!

  cd TVout
  ./modules
  ./cloning or ./independ
  ./TV-704x528 (or another TV* script)

Sending bugreports:
~~~~~~~~~~~~~~~~~~~
First please read all the docs in this package, most of the problems are
described somewhere. At least read the Troubleshooting section!
We don't like answering questions which are already answered in this
readme or other docs.
You should try the latest test (pre) release version too, maybe your bug
is already fixed, but the new version hasn't been released.
If you couldn't solve the problem, then send a quality bugreport
via E-Mail to the MPlayer-users list : [e-mail]

*NEVER* send attached AVIs, MPEGs, or any big files to this list!!!
Upload them to ftp://thot.banki.hu/incoming , and inform the list about
your upload.

Please include these:
- your kernel version number ('uname -a')
- linux distribution and glibc version  (example: Slackware 7.1 + glibc 2.1.3)
- gcc and binutils version ('gcc -v' and 'as --version')
- your X11 version         (example: X 4.0.2 + DRI snapshot2001jan12)
- video card vendor/model  (example: Matrox G400 MAX AGP)
- CPU vendor and type      (example: Intel Celeron2-566 at 850MHz)

Also include the required logs (as attachment, may be compressed zip/gz/bz2)
depending the problem type (see bellow at Troubleshooting section).

To log output to a file, use the &> shell operator. For example:
  ./configure &>configure.log
  mplayer -v test.avi &>play.log

If we ask you for the file, then you have two choices:
- upload the file to ftp://thot.banki.hu/incoming (at least a few megabytes)
- send the exact URL of the file, and we'll download it soon.

Please do not ask for features already listed in the TODO!

Troubleshooting:
~~~~~~~~~~~~~~~~
1. Please read the docs first...

2. If you have compiling problems:
   - if you are an experienced programmer, please try to fix it, and send
     us the patch
   - if gcc reports problems around inttypes.h, try to copy DOCS/inttypes.h
     to the directory where the error occured. (or upgrade glibc to 2.1/newer)
   - if gcc reports problems around video_out_gl.c, try disabling OpenGL
     support: ./configure --disable-gl (you have broken OpenGL headers/libs)
   - if you are a user, send us a bugreport (see above), including these:
      - output of ./configure
      - output of make dep and make
      - config.h and all of config.mak files
   Note: many users reported that SSE was not detected while running on P3.
   Current stable 2.2.x kernels does NOT support SSE, so you can't use it
   without patches or using the 2.4.x series. (or try latest 2.2.19 or newer)

3. If you have a problem with the player, please run it with -v option, and
   send the output of it, with a detailed description of the problem.
   - can't play AVI files: check that codec .DLL and .ACM files are installed to
     /usr/lib/win32/ and are all lowercase (divxc32.dll instead of DivXc32.DLL)
   
4. If you have a file-specific problem (can't play a special file,
   crashes with it or similar) then please run with -v -v -v (debug level 3).
   Send us the output and the problem description via email bugreport.
   We may ask you to upload the file.
   - if it segfaults with an AVI file with MP3 audio, try with -afm 1 or -afm 4
   - if it's still bad, try with -nosound

5. If you have problem with display driver, please first check the list above,
   many of them isn't yet capable to AVI playing, and some of them are
   untested and/or unfinished.

6. If you have speed problems (too slow playing), then please first check that:
   - you don't use OpenGL driver while have software-only opengl (Utah-GLX
     disabled, or not yet installed, conflicting libs installed, or your
     hardware not supported etc...)
   - you have set up MTRR registers properly (many new cards are really
     slow without setting up MTRR registers. it's NOT done by X 3.3.x! Also,
     there are older K6-2's, which lack MTRR support /stepping=0/).
     Check DOCS/MTRR !
   - you have a fast machine (don't report that your 386 can't play DivX)
   - try with Null output (-vo null) and check CPU usage (first % value)

7. sound-related problems:
   - maybe your card doesn't support 48kHz playback and the movie requires it.
   - try player with the -noalsa option
   - delayed audio with some AVI files: try with -bps or -nobps option!
   - if you experienced delayed audio, try to compensate with -delay or -abs.
     you can specify audio card's buffer size in bytes with -abs option, or
     specify audio delay in seconds (positive/negative float) with -delay
     for example:  mplayer -alsa -delay -0.75 test.avi
                   mplayer -abs 65536 -delay 0.3 test.mpg
   - to play AVI files with VBR MP3 audio use the  -mc 0  option!
   - no sound at all: check that you have working OSS driver (/dev/dsp),
     and it isn't used by another program (for example esd, xmms etc.)
   - use OSS. If the problem persists, use ALSA ;)

8. unsupported codecs (AVI files):
   Check DOCS/CODECS

Contact information:
~~~~~~~~~~~~~~~~~~~~
Homepage:  http://mplayer.sourceforge.net

Mailing lists:
~~~~~~~~~~~~~~
There are some public mailing lists on MPlayer. Subscribing can be achieved on
the following addresses:

- MPlayer users list:  (send your ideas, bugreports, feature requests here)
	http://lists.sourceforge.net/lists/listinfo/mplayer-users

- MPlayer announce:    (information about new releases or big changes in CVS)
	http://lists.sourceforge.net/lists/listinfo/mplayer-announce

- MPlayer & Matrox G200/G400/G450 users: (about TV-out, mga_vid, syncfb, Xv)
	http://lists.sourceforge.net/lists/listinfo/mplayer-matrox

- MPlayer CVS-log:     (announce about _every_ CVS commits)
	http://lists.sourceforge.net/lists/listinfo/mplayer-cvslog

Standard Disclaimer:
~~~~~~~~~~~~~~~~~~~~
Use only at your own risk! There may be errors and inaccuracies that could 
be damaging to your system or your eye. Proceed with caution, and although
this is highly unlikely, I don't take any responsibility for that!