			MpegUtil version 1.0
			
	 Developed by, and Copyright Phillip Lougher 1995.
			
MpegUtil is an analysis and edit program for MPEG-1 video files. One or
more input files can be specified, and the program will give a full range of
statistics about the files.  In addition to analysis, the program can
perform simple editing operations: file concatenation, clip extraction,
B and P frame removal.

The information generated includes a listing of all the frames and Groups of 
Pictures (GoP) contained within the input files.  For frames, this includes
their type (I, P, B) and their frame index in the file.  For GoPs this shows
the Gop start and end in the file, and whether they are Open, Closed, or
have the Broken link set.  This listing is given in both decode (the order
of frame appearance within the file) and display order.

A summary of various statistical information is generated, this shows:
frame width and height, pixel aspect ratio, picture rate/bit rate per second,
count of frames (I, P, B and total frames), Gops (Closed and Open),
average byte size and compression ratio of I, P and B frames etc.

In addition, some limited MPEG-1 conformance checks are made, this includes
checks on the type of frames at GoP start and ends in both decode and
display order, and checks on the correctness of frame temporal reference
counts.

USAGE
=====

SYNTAX: mpegUtil mpeg_file1 mpeg_file2 ... [options]

Options are:
    -full               Generate full MPEG file statistics
    -frames n           Only read the first n frames from the input file(s)
    -output filename    Write MPEG data to filename.  Most usefully used
                        in conjunction with the following options
    -start frame        Start frame display/output from this frame
    -end frame          Stop frame display/output at this frame
    -noP                Delete all P frames in output file.  All dependent
                        B frames are also removed
    -noB                Delete all B frames in output file
    -author             Where to send comments etc.


The simplest usage is to type the program name and the input files on their
own.  The following is a sample output, which serves to illustrate the
output format.

---------------------------------------------
%mpegUtil mpeg.mpg

Parsing file mpeg.mpg.  Please wait...
*IPBBPBBPBB*IBBPBBPBBPBB*IBBPBBPBBPBB*IBBPBBPBBPBB*IBBP



MPEG file information summary
-----------------------------

Frame sequence (decode order)
 ||   0   1   2   3   4   5   6   7   8   9 ||  10  11  12  13  14  15  16
 ||   I   P   B   B   P   B   B   P   B   B ||   I   B   B   P   B   B   P

  17  18  19  20  21 ||  22  23  24  25  26  27  28  29  30  31  32  33 ||
   B   B   P   B   B ||   I   B   B   P   B   B   P   B   B   P   B   B ||

  34  35  36  37  38  39  40  41  42  43  44  45 ||  46  47  48  49
   I   B   B   P   B   B   P   B   B   P   B   B ||   I   B   B   P

Frame sequence (display order)
 ||   0   2   3   1   5   6   4   8   9   7 ||  11  12  10  14  15  13  17
 ||   I   B   B   P   B   B   P   B   B   P ||   B   B   I   B   B   P   B

  18  16  20  21  19 ||  23  24  22  26  27  25  29  30  28  32  33  31 ||
   B   P   B   B   P ||   B   B   I   B   B   P   B   B   P   B   B   P ||

  35  36  34  38  39  37  41  42  40  44  45  43 ||  47  48  46  49
   B   B   I   B   B   P   B   B   P   B   B   P ||   B   B   I   P

Frame size: width 352, height 288
Pixel aspect ratio (height to width) 1.000 Square pixels
Picture rate: 25 frames per second
Bit rate: 1700000 bits/s (207.52 Kbytes/s)

Total number of pictures in sequence 50
    Made up of 5 I, 13 P and 32 B frames
Total number of Groups of Pictures (random access points) 5
    Made up of 5 closed, and 0 open GOPs

Uncompressed picture size 304128 bytes
Average picture size 8602.34 bytes, 2.83% of uncompressed picture
Average size of I frames 31589.60 bytes, 10.39% of uncompressed picture
Average size of P frames 12769.00 bytes, 4.20% of uncompressed picture
Average size of B frames 3317.87 bytes, 1.09% of uncompressed picture
Modal average number of pictures per GOP 12 pictures, occurs 3 times
Mean average number of pictures per GOP 10.00
Average size of GOPs 86031.40
--------------------------------------------------

The first part between the command line and "MPEG file information summary"
is produced as the file is parsed.  The asterisks are printed every time
a GoP start is found, and I, P or B is printed every time a frame is found.
If the program detects any errors in the file, these are printed here.

The second part gives a listing of the frames and GoPs found.  The numbers 
are the frame index within the file.  For the decode order, these should be
consecutive.  For the display order, the numbers may not be consecutive,
this indicates that frame reordering has taken place.  For example, the
DISPLAY order sequence IBBBBPBBBBP, has a number of B frames dependent on P
frames which occur in the future.  These P frames are reordered in DECODE
order (the order they appear in the MPEG file), so that they appear before
the B frames.  These appear in decode order as:

0 1 2 3 4 5 6 7 8 9 10
I P B B B B P B B B B

and in display order

0 2 3 4 5 1 7 8 9 10 6
I B B B B P B B B B  P

The bars (|) indicate the start of GoPs.  The exact form of the bars give 
a visual indication of the type of Gop.  Closed GoPs are denoted by double
bars ||, and open GoPs are denoted by single bars |.  Open GoPs which have
their broken link set (this indicates that the GoP posses B frames which are
dependent on the previous GoP, which is missing) are denoted by a Bar and a
Plus, or |+.

MORE ADVANCED USE
=================

The options.

-full
	This generates a full listing of information as the file is being
	parsed, instead of just printing GoP starts and frames.  This is
	useful if you need to find out how many SEQUENCE HEADERS are
	contained within the file, or need to know the exact length of a
	GoP rather than the average length.
	
-frames n
	If a file is many megabytes in size, it can be rather tedious to
	wait for the program to process it completely, if you're only
	interested in the first couple of hundred frames.  This allows
	you to specify how many frames the program reads before it
	stops parsing the file.  Note the program rounds the number up to
	the nearest frame sequence, where a sequence is a set of reference
	frames and their dependents (i.e. IPBBB in decode order is a
	frame sequence).  This is to prevent the program reading a reordered
	reference frame without reading the dependents.
	
-start frame &
-end frame
	(this describes their use in analysis mode only).  In many cases,
	you may want the entire file to be parsed by the program, but
	only want a small sample frame listing.  For example, in a
	file containing 6,000 frames, you may want the statistics to be
	based on the entire file, but only want frames 3,000 - 3,060 to be
	listed.  In this case you would type mpegUtil mpeg.mpg -start 3000
	-end 3060.
	
	
MPEG FILE EDITING
=================

The program can perform four editing operations: concatenation,
clip extraction, B and P frame removal.  

Disclaimer: MPEG file editing is a difficult task, and it can only be
performed where it has been provided for by the MPEG standard.  As
stated by the standard, it can be difficult to end up with a file that
complies with the requirements of the video buffering verifier (VBV).  This
program sets/resets the Gop open/closed and broken link bits, and
recomputes picture temporal reference counts as necessary. It does not,
however, alter the VBV or bit rate fields.  If your file or player uses
these fields (many do not) then things may choke on the edited output file.
The author accepts no responsibility for the loss of any data through the
use of this edit facility.

File concatenation
------------------
This can be performed by simply specifying the desired output file on the
command line, e.g.

%mpegUtil mpeg1.mpg mpeg2.mpg -output total.mpg

This will concatenate mpeg1.mpg and mpeg2.mpg into the one file total.mpg.
This will normally only work if the two files are similar, i.e. have the
same encoding characteristics.


Clip extraction
---------------
The extraction of a range of frames within a file can be performed using
-start and -end in conjunction with -output, e.g.

%mpegUtil mpeg.mpg -start 200 -end 300 -output clip.mpg

This will save frames 200 - 300 to the file clip.mpg.  It is important
to note that the program ROUNDS the specified frame numbers to the nearest
useful frame, i.e. the -start frame is rounded up to the nearest I frame
or GoP start (whichever is nearest).  The -end frame is rounded down to the
end of the nearest dependent frame sequence (for example IPBBB decode order
has 4 frames dependent on the I frame).

The -frames option can be used to restrict the number of frames parsed.
This can be set to the count of the maximum frame to be extracted, e.g
mpegUtil mpeg.mpg -start 30 -end 35 -frames 36 -output clip.mpg.

B and P frame removal
---------------------
These options allow B and P frames to be removed from a file.  This can be
useful to allow files to be replayed on players which only support I
frames, or to reduce file size or CPU load etc.  The output file is
specified using -output.

-noB removes all B frames within the file, or within the output clip if
start and end are used.

-noP removes all P frames from a file or clip.  Any B frames which depend on
a deleted P frame are also removed.

-noB -noP generates an I frame only file.

Please note: for constant bitrate files, removal of P and B frames
will alter the file bitrate.  This may cause some players to choke on
the edited output.


AUTHOR INFORMATION
==================

This program was written by Phillip Lougher, January - March 1995.

If you have any comments on the program, like it, or find any bugs then please
email me, phillip@comp.lancs.ac.uk.  I can also be contacted at
 
Computing Department, 
Lancaster University, 
Lancaster, LA1 4YR, 
United Kingdom.

LEGAL NOTE
==========

MpegUtil Copyright (c) Phillip Lougher, 1995.
    
Permission to use and distribute this software and its documentation is
hereby granted, subject to the provision that all files are distributed
unaltered, and that no profit is made from its distribution.

This software is provided "as is", without any warranty either express or
implied.  In no event shall the author (Phillip Lougher) be liable for
any damages arising out of the use of this software.  The user of this
software assumes all risk as to its quality and accuracy.

