SDL MPEG Player Library (SMPEG)

                             Version 0.4.4
                           September 28, 2000


Written by Karl Robillard and Sam Lantinga, Loki Software, Inc.
Streaming MPEG support contributed by Vivien Chappelier.

SMPEG is a free MPEG1 video player library with sound support.  Video playback
is based on the ubiquitous Berkeley MPEG player, mpeg_play v2.2.  Audio is
played through a slightly modified mpegsound library, part of Splay v0.8.2.
SMPEG supports MPEG audio (MP3), MPEG-1 video, and MPEG system streams.

This library is distributed under the GNU Library Public License (LGPL)
version 2.

plaympeg, gtv, and glmovie are simple video players provided to test the
library.  The C library interface is 'documented' in smpeg.h, and the C++
library interface is spread out over the MPEG*.h files.

This is a work in progress.  Only 16 or 32 bit color depth is supported.
The player will dynamically conver to other color depths, but playback
will be much faster if your display is already set to 16 bit color depth.
Currently it has only been tested on Linux.


Requirements:

	* Simple DirectMedia Layer v1.2.0 or newer
		http://www.libsdl.org/

To make:

	Type 'make all'.  This should build libsmpeg.a and plaympeg

Usage:

	plaympeg [--noaudio] [--novideo] [--double|-2] [--loop|-l] file ...


Known Issues:

	The MPEG decoding is a fairly slow and mathematically intensive
	process.  It could use even further optimization.

	There isn't any synchronization between the audio and video threads,
	and system stream timestamps are ignored.  The video is synchronized
	with audio by using video framerate and elapsed time.  They are
	are synchronized well enough for short clips, but long movies, or
	movies with visual audio cues (like speech) don't look very good.

Reporting bugs:

	Please report any bugs and/or fixes to smpeg@lokigames.com.


Looking at the code:

	The functions that should be optimized to improve performance are:
		Color16DitherImageMod() (Uses 5ms CPU, called few times)
		Twox2Color16DitherImageMod() (Uses 10ms CPU, called few times)
		j_rev_dct()         (Uses 0.01ms CPU, but called many times)
		ParseReconBlock()   (Uses 0.01ms CPU, but called many times)

	To improve framerate scheduling, look at timeSync() in video/gdith.cpp

Links:

	Berkeley MPEG player   http://bmrc.berkeley.edu/frame/research/mpeg
	Splay                  http://my.netian.com/~polarb
	SDL                    http://www.libsdl.org/

There is no longer explicit support for the SDL_mixer library.

You can have the SDL mixer library mix audio from a movie by hooking into
the SDL mixer music hooks:

#include "smpeg.h"
#include "SDL_mixer.h"

        .. set up the mixer audio ...

        /* Note the last parameter is zero! */
        mpeg = SMPEG_new("file.mpg", &info, 0);

        /* Play the movie, using SDL_mixer for audio */
        SMPEG_enableaudio(mpeg, 0);
        if ( play_audio ) {
                SDL_AudioSpec audiofmt;
                Uint16 format;
                int freq, channels;

                /* Tell SMPEG what the audio format is */
                Mix_QuerySpec(&freq, &format, &channels);
                audiofmt.format = format;
                audiofmt.freq = freq;
                audiofmt.channels = channels;
                SMPEG_actualSpec(mpeg, &audiofmt);

                /* Hook in the MPEG music mixer */
                Mix_HookMusic(SMPEG_playAudioSDL, mpeg);
                SMPEG_enableaudio(mpeg, 1);
        }
        SMPEG_play(mpeg);

        /* Stop the movie and unhook SMPEG from the mixer */
        SMPEG_stop(mpeg);
        Mix_HookMusic(NULL, NULL);