                                 mpeg2play
                                 =========

                          Version 1.1b, Oct 15 1994
                        With Motif/Wcl user interface
                                (2 versions)
                  (C) Thomas Woerner, tom@mpik-tueb.mpg.de

                                 based on
                         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)
- Motif or Motif/Wcl user interface with several functions

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].

The Motif/Wcl version is available via http from:

  http://134.2.172.13:4711/mpeg2play/

and will be available in a few days via anonymous ftp from:

  mpik-tueb.mpg.de:/pub/tom/mpeg2play

The Internet address of mpik-tueb.mpg.de is [192.124.28.81].

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

Please report user interface problems, bugs, suggestions etc. to

  tom@mpik-tueb.mpg.de

others 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).


Makefile and Imakefile
----------------------

If you are going to use the standard Makefile follow step 1.1 and 1.2.
For use of the Imakefile follow step 2.1 and 2.2.


  Step 1.1: edit Makefile
  -----------------------

  Copy Makefile.std to 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).
  For Wcl-version:
    Set the INCLUDEDIR to the location of your Wcl include files and the
    LIBRARYDIR to the location of the libraries.

  Use of shared memory (USE_SHMEM) requires SYSV shared memory support and
  a 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 1.2: make
  --------------

  Type 'make'.


  Step 1.3: installing
  --------------------

  Copy the Mpeg2play resource file to your app-defaults directory or let the
  XUSERFILESEARCHPATH point to it.
  Copy the bitmaps of the icons directory to your library location and 
  set the paths in the resource file to the directory where the bitmaps are
  located.
  Then copy the mpeg2play to your binary directory.



  Step 2.1: edit Imakefile
  ------------------------

  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, USE_TIME)

  For Wcl-version:
    Set the WCL_INC to the location of your Wcl include tree and the WCL_LIB to
    the location of the libraries.

  Use of shared memory (USE_SHMEM) requires SYSV shared memory support and
  a 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.


  Step 2.2: building mpeg2play
  ----------------------------

  Type 'xmkmf' and then 'make'.


  Step 2.3: installing
  --------------------

  see 1.3.


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

--
Thomas Woerner
Max-Planck-Institut fuer biologische Kybernetik (MPIK)
Spemannstr. 38
D-72076 Tuebingen, Germany.

URL:   http://134.2.172.13:4711
phone: +49-7071-601621
email: tom@mpik-tueb.mpg.de