
              MPEG 2 Transport Stream Player

                   version: 1.2
                   date: November, 1996

        Alex Theo de Jong (alex.dejong@nist.gov)

          Multi-Media and Digital Video Group
        Advanced Network Technologies Division
          Information Technology Laboratory
    National Institute of Standards and Technology
                Gaithersburg, MD 20899, U.S.A.


COPYRIGHT

This work is a contribution of the National Institute of Standards 
and Technology, and is not subject to copyright. However, original
audio and video player source code has a copyright by Tobias Bading,
Berlin University of Technology, Germany, and the MPEG Software 
and Simulation Group & Stefan Eckart at the Fraunhofer-Institut fuer 
Festkoerpertechnologie, Germany. All modifications do not have
copyright :-)


ACKNOWLEDGEMENTS

The MPEG 2 Transport Stream player uses pieces of the MPEG 2 Audio
player developed by Tobias Bading at Berlin University of Technology,
Germany, and for video decoding, pieces of the MPEG 2 Video player
are used which was developed by the MPEG Software Simulation Group 
and improved by Stefan Eckart at the Fraunhofer-Institut fuer 
Festkoerpertechnologie, Germany. 

NOTE: since the structure of the original source code has been changed
so drastically, the original copyright file headers have not been 
included. 


INTRODUCTION

The directory contains all the code for the MPEG 2 Transport Stream
player. The player is capable of de-multiplexing, synchronizing audio
and video, decoding, and playing audio and video. It can also de-multiplex 
MPEG 2 Program Streams (not tested; under construction), and decode 
MPEG 1 and 2 audio/video Packetized Elementary Streams (PES).

The player consists primarily of 3 classes: the Mpeg2Demux (De-multiplexor), 
Mpeg2Video (Video decoding and display), and Mpeg2Audio (Audio decoding and
playback). Support classes are available for synchronization and buffering. 


TOOLS

OS: 	  SGI Irix 5.3 or SUN Solaris 2.5
Compiler: GNU g++, version 2.6.3 or 2.7.2
          SUN Solaris 2.5 Sparc C++ Compiler
          SGI Irix 5.3 C++ Compiler
Make:     GNU gmake 3.70
Compress: gzip/gunzip


RELEASE NOTES

1) Create the NIST MPEG 2 Transport Stream player by going to directory
   "./NIST_mpeg2ts/Src":

   SUN Solaris: type "gmake install"
   SGI irix:    type "gmake -f makefile.sgi install"

The binaries, mpeg2audio (Audio player), mpeg2video (Video player), 
mpeg2player (MPEG 2 Transport Stream player) are available in 
./NIST_mpeg2ts/Bin/Irix or  ./NIST_mpeg2ts/Bin/Solaris .

Performance depends on the hardware that is used; bitrates of the 
MPEG 2 TS are upto 1.5 Mbps on an SGI Indigo 2 Impact workstation. It 
works also nice on the SUN Ultra Sparc and runs quite nicely on a Sparc 
10 MP (Multi-Processor, 2 x CPU). 
To improve audio, use the -fr <n> option and either -r or -l (only 
decode one channel). The former option will cause B-frames to be dropped 
in order to keep up with the sending bitrate.

2) The implementation is based on the use of Multi-Threading which is
supported on most System V operating systems. The Posix compliant PThread 
package from Christopher Angelo Provenzano (MIT, US), however, does not 
work with the X11 interface, I therefore use Multi-Processing on the 
SGI Irix 5.3 operating system. The next release of the software will most 
likely be using SGI Irix 6.2 which supports Multi-Threading. On SUN 
Solaris, the Solaris Multi-Threading capability is used. Note that with
the compiler option -DSOLARIS and -DSOLARIS_PTHREAD (-DIRIX and -DIRIX_PTHREAD)
can be used to turn use of the pthread package on/off (Default is Off).
All MT stuff is collected in the Util/athread.hh and Util/athread.cc files 
(athread = Alex' Threads :-)  )

3) The network option allows the player to wait for a network connection and 
receive data from the network instead of the filesystem. Currently, connections
from TCP/IP, Fore ATM SPANS signalling, and Fore ATM PVCs are implemented. To 
use Fore ATM, use the -DFORE_ATM compiler option. A FileSocket class provides 
a means to read from a file instead of a network connection. 

4) The "-DEOFEXIT" options allows the player to exit when a network
connection is terminated (ie. closed), without waiting audio/video threads
to terminate properly. This works Ok for Solaris since threads in the 
same process space are killed automatically when the parent process
terminates. On SGI Irix this can cause some processes to hog your system ...



TO DO

1) Implement PSI and PMT tables for MPEG 2 Transport Stream

2) Use PIDs and PSI to select stream for viewing. Currently the PES stream
ID is used for selection which assumes that audio and video stream IDs 
match for a program. 

3) ...

4) ...


KNOWN BUGS

1) Make sure a HOSTNAME environment value is set. The player relies on 
this value listening to the network.

2) The mpeg2player has been tested (partially) for MPEG 2 Transport Streams,
elementary Audio, and elementary Video streams. MPEG 2 Program Streams do 
not work (since I don't have a properly encoded MPEG 2 Program Stream).

3) The frame rate option is not implemented properly. In order to get
the fastest bitrate, set to >2000. This will result in only I and P frames 
to be displayed. Also, the frame rate (fps) displayed on the screen, is the 
frame rate at which the data is read; not the number of frames per second 
that appear on the screen (since not all B-frames are displayed).

4) The software has been developed on a SUN Ultra Sparc running Solaris 2.5
The software should work on a Sparc 5, Sparc LX, Sparc 10 and a Sparc 20 too
(Note: the software will not run on other Sparc's since they don't have the 
proper audio device).

The SGI version has been developed on an SGI Indy/Indigo 2 Impact running Irix 
5.3 . I have tried to run it on an SGI Indigo 2, Indy, and Indy R5000 without 
any problems, but don't know about other SGI machines. It should also work
fine for Irix 6.2, although the code is not really using 64 bit processing
(and is not yet using Multi-Threading because it seems impossible to get
the Posix Thread package from SGI ...)


CHANGES

1.0 -> 1.1

- Moved file reader for de-multiplexer to ./NIST_mpeg2ts/Src/Util/network. 
  This keeps the de-multiplexor class independent of reading from file or network. 
- Added display option with SUN Solaris 2.5 XIL Graphics libraries which 
  allows re-sizing of the image while playing. This also enables use of 
  24 bit colors (versus 8 bit). For specifics, have a look at the file: 
  ./NIST_mpeg2ts/Src/Video/display.hh . By default XIL is not used.
- Some bugs and cleaning of code.
- Added a small (draft) paper (./NIST_mpeg2ts/Docs/mpeg2ts.ps) which gives an
  outline of the implementation.

1.1 -> 1.2

- Included error recovery in audio player. This prevents the player from
  blocking when MPEG packets are lost. Instead both audio and video threads
  will try to resume playing at the next startcode.
- Improved robustness in sychronization object. A reset-sync mechanism has
  been included which allows the player to recover from a "drop" in 
  time stamp values. This is especially useful when the sender of the MPEG 
  stream (a "Stream Pump") implements random access (ie. jumping back and
  forth in the stream while playing the stream).
- Fixed memory leak on the SUN Solaris systems by turning the Multi-Threaded
  dither/display mechanism off. This might reduce performance on parallel
  machines (such as the Sparc 10/20 MP).
- Included options to allow native compilers (SUN and SGI) to compile the
  player. Pieces of the GNU libraries are included with the distribution
  to allow the use of the String class within the player. 
  The performance on the SUN Ultra Sparc is significantly better when using 
  the Sparc C++ compiler (with the "-fast" option).
- Moved SUN from Solaris 2.4 to SUN Solaris 2.5
- Automatic Stream ID selection. When no particular stream ID is set for 
  playing, the player automatically selects the first available stream ID
  for playing. 
- Made color cell allocation static. This means that color allocation is
  performed before a connection is received from the network. Especially 
  when receiving data over an unreliable ATM connection, this avoids buffer 
  overflow because of a slow color cell allocation.


MORE INFORMATION

Check:  http://muncie.ncsl.nist.gov/~vod/mpeg2ts.html
