README.orig

                                 mpeg2play
                                 =========

                         Version 1.1b, July 13, 1994

           (C) Stefan Eckart, stefan@lis.e-technik.tu-muenchen.de





  mpeg2play is based on mpeg2decode, (C) 1994, MPEG Software Simulation Group



Features
========

- plays MPEG-1 and MPEG-2 video bitstreams on 8 bit color X displays
- plays system layer (MPEG-1 only) streams, audio being ignored
- high quality ordered dither algorithm
- high speed interlaced to progressive scan conversion
- speed is about 90% of Berkeley's mpeg_play (somewhat platform and
  stream dependent)
- NCSA Mosaic compatible (as external viewer for video/mpeg)


Introduction
============

mpeg2play is a player for MPEG-1 and MPEG-2 video bitstreams. It is based on
mpeg2decode by the MPEG Software Simulation Group. In mpeg2decode the
emphasis is on correct implementation of the MPEG standard and comprehensive
code structure. The latter is not always easy to combine with high execution
speed. Therefore a version has been derived which is optimized for higher
decoding and display speed at the cost of a less straightforward
implementation and slightly non-compliant decoding. In addition all
conformance checks and some fault recovery procedures have been omitted from
mpeg2play.


Availability
============

The most recent versions of mpeg2play and of the MPEG Software Simulation
Group codec software are available by anonymous ftp from:

  ftp.netcom.com:/pub/cfogg/mpeg2

The Internet address of ftp.netcom.com is [192.100.81.1].


Installation
============

Please report problems, bugs, suggestions etc. to

  stefan@lis.e-technik.tu-muenchen.de

I'm also interested in speed comparisons with mpeg_play on platforms
other than Sparc (preferably based on 'well-known' bitstreams).


Step 1: edit Makefile
---------------------

You may have to set CC to your C compiler and CFLAGS to the flags required
by the compiler. Follow the instructions in the Makefile regarding the
correct setting of the other variables (USE_SHMEM, LIBS, INCLUDEDIR and
LIBRARYDIR).

Use of shared memory (USE_SHMEM) requires SYSV shared memory support and
an X server implementing the MIT-SHM extensions. It results in a
considerable speed increase if server and client run on the same machine.

If you use a C compiler which doesn't understand ANSI-C function prototypes
add -DNON_ANSI_COMPILER to CFLAGS.

Note that decoding speed depends on the compiler. Here are some results on
a SPARCstation 10 (single CPU) for a particular MPEG-2 sequence:

  compiler        user time
  ---------------------------
  cc  -O3         98.1 sec
  gcc -O2 (2.5.8) 90.4 sec
  acc -fast       83.2 sec


Step 2: make
------------

Type 'make'.


Usage
=====

mpeg2play {options} input.m2v {upper.m2v}

Options:

-vn  verbose output (n: level)

Instructs mpeg2play to generate informative output about the sequence
to stdout. Increasing level (-v1, -v2, etc.) results in more detailed
output.

-on  output format (0: X11, 1: none)

-o1 is sometimes useful for benchmarking.

X11: display decoded video on an X Window System server. The current version
     supports only 8 bit color display. You can use the DISPLAY environment
     variable to select a (non-default) display. The output routines perform
     8 bit dithering and interlaced to progressive scan conversion.


-l  loop sequence

Setting this flag results in repeated display of the sequence.


-s infile  spatial scalable sequence

Spatial scalable video is decoded in two passes. The -s option specifies
the names of the output files from the first (lower layer) pass to the
second (enhancement layer) pass. 'infile' describes the name format of the
lower layer pictures for spatial scalable sequences as a printf format
string. It has to contain exactly one integer format descriptor (e.g. %d,
%02d) and, a %c descriptor. The %d descriptor has to be before the %c.

-q

Set this switch to suppress output of warnings to stderr. Usually a bad idea.

-fn

Set frame rate to n frames / sec. Otherwise the sequence is played at maximum
speed.

input.m2v

name of the file containing the MPEG stream. '-' denotes reading the stream
from stdin.

upper.m2v

is the name of the upper layer bitstream of an SNR scalable stream or a
data partioning scalable bitstream (input.m2v is the lower layer).


Examples
========

non-scalable stream (one layer, one pass):

	mpeg2play base.m2v

SNR-scalable stream (two layers, one pass):

	mpeg2play base.m2v snr.m2v

spatial-scalable stream (two layers, two passes):

	mpeg2decode base.m2v l%d%c
	mpeg2play -s l%d%c spatial.m2v

hybrid spatial/SNR-scalable stream (three layers, two passes):

	mpeg2decode base.m2v l%d%c
	mpeg2play -s l%d%c spatial.m2v snr.m2v

hybrid SNR/spatial-scalable stream (three layers, two passes):

	mpeg2decode base.m2v snr.m2v l%d%c
	mpeg2play -s l%d%c spatial.m2v

etc.


Use with Mosaic
===============

mpeg2play can be used as an 'external viewer' in conjunction with the
WWW (World Wide Web) browser NCSA Mosaic:

- add the directory containing mpeg2play to your PATH environment variable
- make sure you have a file .mailcap in your home directory containing the
  line:

video/mpeg; mpeg2play %s

  (or rename mpeg2play to mpeg_play)

It is usually not required to add the MPEG-2 file suffix .m2v to the
mime-types file (if the HTTP server supplies the correct Content-Type: header).

If you want to set up a HTTP daemon to serve MPEG-2 files, you have to add
'AddType .m2v video/mpeg binary 1.0' to the server configuration file (at
least for CERN httpd 3.0).


Acknowledgements
================

Thanks to Dave Wecker for providing the frame rate control routines. I
have made some modifications, so it's me to blame if it doesn't work as
expected.

--
Stefan Eckart
Fraunhofer-Institut fuer Festkoerpertechnologie (IFT-ST)
Hansastr. 27D
D-80686 Muenchen, Germany.

E-mail: stefan@lis.e-technik.tu-muenchen.de