Readme for avi2mpg1 ver 1.8

This program is distributed under the GNU copyright, please see the accompanying
file COPYING for details. Please note that only the changes to the original source
code are copyrighted under GNU, except for the the multiplexer portions, which
are also under the GNU copyright. The copyrights for the other two source programs,
the video and audio encoders are detailed in their respective source, as well as the
original distributions. 


avi2mpg1 is a simple command line mpeg-1 encoder that runs at the command prompt
under Windows '95 or NT. Copy the file avi2mpg1.exe to any directory in your
path. C:\WINDOWS\COMMAND or C:\WINNT should work for most people.
Invoke the program with the following syntax:

 usage: avi2mpg1 [-options] inputfile.avi [inputfile2.avi ...] [outputfile.mpg]

     where:
           options can be:
                          -b byterate Where byterate is total system stream
                                     rate in KBytes/s (default 150)
                                     Valid range = 10 to 5000.

                          -s bitrate Where bitrate is total system stream 
                                     rate in K bits/s (default 1200)
                                     Valid range = 80 to 40000.

                          YOU CAN ONLY SPECIFY -b OR -s, NOT BOTH!

                          -a bitrate Where bitrate is audio bitrate in
                                     K bits/s (default 128)
                                     Valid values for layer I:
                                     32,64,96,128,160,192,224,256,288,320,352,
				     384,416,448
                                     Valid values for layer II:
                                     32,48,56,64,80,96,112,128,160,192,224,256,
				     320,384

                          -l layer   Where layer specifies which audio layer
                                     to use, valid values 1 or 2.
                                     (default 2)

                          -j         specifies use joint stereo mode IF
                                     input file contains stereo audio.
                                     Has no effect if audio portion of .avi
                                     is mono. (default non-joint stereo)

                          -v         specifies fixed datarates as defined
                                     for video cd streams. If this option
                                     is used, it overides any -a, -b or -s
                                     rates specified as well as -l, -n, -c and -y
                                     options.

				NOTE: The resulting mpeg is accepted by Adaptec's
                                      Video CD Creator version 3.0. avi2mpg1 does NOT
				      generate an mpeg that Adaptec's Video CD
				      creator will accept IF you have version 3.5
                                      (or later I presume) of Adaptec's EZ-CD Creator.
                                      I believe I have isolated the problem to
                                      the multiplexer used. However, it looks like it
                                      will take a total rewrite of the multiplexer
                                      code to fix this. If you really need to generate
                                      video CD's with Adaptec's Video CD Creator 3.5
                                      I suggest you use a commercial encoder.

                          -p filename.par specifies video encoding parameter
                                     file, (OPTIONAL) allows control over additional
                                     parameters. See Param.txt. Note that the
                                     parameter file as well as the matrix files
                                     must be in the current directory unless you
                                     specify full path names.

                          -e         specifies encode file even if some frames in
                                     avi are bad, ie: use previous good video frame
                                     or 0 data for audio if file is corrupt.
                                     At least FIRST frame must be valid!

                          -n         generate video stream only, ignore audio if
                                     there is an audio stream. You must use this
                                     option to encode an avi file that does not
                                     have an audio track. Result is a .m1v file.
                                     (Even if you specify .mpg)

                          -y         vbv_buffer size in 16K bit multiples,
                                     default = 20

                          -m         motion search magnitude, range 0 - 4, default 0,
                                     higher values MAY result in better encoding
                                     (depending on video), but will take
                                     SIGNIFICANTLY longer to encode.
                                     Try it on a short sample first!

                          -c hs vs   set output video size to hs horizontal and 
                                     vs vertical. Larger input video is cropped to
                                     fit while smaller video is padded out to size.

                          -f frame_rate_code force mpeg file frame rate regardless of
                                     input file frame rate. Implies -n (video only).
                                     Frame rates codes -> 1 = 23.976 FPS
                                                          2 = 24 FPS
                                                          3 = 25 FPS
                                                          4 = 29.97 FPS
                                                          5 = 30 FPS

                          -x suppress usage of MMX extensions

                          -d use double precision math (slower) for fdct routine

            inputfile.avi   A windows avi file (you can now specify multiple input
                            avi files for encoding to a single output file)
                            constrained to the following parameters:

                                 Horizontal size: < 4096 pixels
                                 Vertical size:   < 4096 pixels

				 Note: if dimensions are not a multiple of 16,
				 then frame data will be padded out to a multiple
                                 of 16 with resulting black bands around picture.

                                 Frame rate : 23.976, 24, 25, 29.97, or 30 FPS
                                              10, 12, and 15 FPS are upsampled.
                                 Colour depth: 8, 16, 24, or 32 bit.
                                               (palletized, thousands,
                                                millions, millions+)
                                 codec used in file must be installed in windows.

                                 Audio sample rate: 11.025, 22.05, and 44.1KHz
                                 Audio sample size: 8 or 16 bit
                                 Audio channels: 1 or 2
                                 Uncompressed PCM audio only.

            outputfile.mpg  Optional if only one input file specified, if not specified,
                            inputfilename with .mpg extension will be created.

		The optional template.par file contains the same values that the
                encoder has hard coded as default values for all other video
                encoding parameters. Use this file as your starting point for
                experimenting with other values, such as motion search vectors.
                See param.txt.

*** WARNING: VIDEO EXCEEDS CPB STANDARD!, if you get this warning during video
encoding, your video exceeds the Constrained Parameter Bitstream standard, and
may not be playable on many mpeg-1 players, either software or hardware.
Although many players can play mpeg-1 with higher than CPB bitrates, 
few are capable of higher resolutions than SIF (352x288).

Example 1:    avi2mpg1 test

		This example will encode an .avi file "test.avi" located in the
		current directory to test.mpg, at 150KB/sec total data rate
		with audio at 128Kb/sec.

Example 2:    avi2mpg1 -v file1.avi file2.avi file3.avi result.mpg

                This example will encode 3 input avi's (file1, file2, and file3)
                to a single mpeg "result.mpg" with VideoCD parameters.

You will need to make sure that the current directory has enough room for the
temporary files the encoder will produce, in other words, approximately twice
the space needed for the resulting .mpg file.

Credits:

This program is basically the combination of the video encoder by the
MPEG Software Simulation Group, available from:
"http://www.creative.net/~tristan/MPEG/mssg/mpeg2vidcodec_v12.tar.gz"

the ISO audio encoder, available from:
"ftp://ftp.iuma.com/audio_utils/converters/source/mpegaudio.tar.Z",

and Christoph Moar's systems stream multiplexer, available from:
"ftp://ftp.informatik.tu-muenchen.de/pub/comp/graphics/mpeg/mplex/mplex-1.1.tar.gz".
Note: this file has apparently been removed from this web site. I suggest doing
a search for "mplex".

into a single program to process windows .avi files. My goal was to create a
simple, one step program consisting of a single executable file with no required
.dll's,bit tables, or configuration files, making it extremely easy to use. 

My own use of MPEG-1 consists primarily of compressing 320x240x29.97FPS files captured
with a 'miro DC20 MJPEG capture board, to 150KB/sec with 128Kb audio .mpg streams for
burning to CD. As such, the default values for the program are obvious. I have 
used the encoder extensively to encode avi files of the above nature with no
problems. You may encounter some problems using avi files that differ from the above.


QUALITY:

	General Recommendations:
	The quality of your original source is extremely important! VHS video
	tape is generally not sufficient (very noisy and 220 lines horizontal
        resolution or less!!!). If you use live capture from a video
	camera, make sure you have LOTS of light. Any noise in the video will
	seriously degrade the encoded mpeg quality. This is true for all
	mpeg encoders!

	PLEASE NOTE: although this encoder accepts avi files with less than 24 FPS,
        24 bit video and less than 44.1KHz 16 bit audio, you aren't getting the full
        value of MPEG compression in these cases. Particularily if the video was
        highly compressed by another windows codec. Internally, the encoder simply
        upsamples the avi file to 24 bit video at 24 or higher FPS, and the audio
        is upsampled to 44.1Khz 16 bit. If your capturing the video yourself, try
        doing it at the maximum rate/resolution your equipment is capable of. The
        general rule for maximum quality is keep your source file as uncompressed
        as possible throughout all capturing and editing phases. Let the final
        compressor (MPEG in this case) do all the compression.

BUGS:

	Using the -v parameter has not been extensively tested, it does
	generate a valid, playable file, but it has only been tested with
        Adaptec's EZ CD Creator 3.0 to generate a Video CD, and while some
        software mpeg players can play the resulting Video CD, I have found 
        at least 1 which does not. You should test Video CD stream generation in
        your environment before any extensive use for Video CD generation.
	Please see note above under option -v regarding EZ CD Creator ver 3.5.
	Also note that the resulting video CD has NOT been tested with ANY DVD
	player. I don't own one yet, so I can't test it.

	Some combinations of parameters and certain video streams will result
	in vbv_buffer overflows or underflows. If this occurs, you will get a
	count of the number of times it has occured at the completion of the video
	stream encoding. An mpeg file will still be generated, and is still
	playable by most players (I haven't found any that can't). You can try
        adjusting the vbv_buffer_size using the -y parameter.

Changes:
	Ver 1.1 - Added support for 8-bit audio.
		- added support for 11.025 and 22.050 Khz sample rates
		- modified vbv_delay overflow reporting

	Ver 1.2 - improved low-pass filtering for 11025 & 22050 sample rate audio
                  sources.
                - added support for 8 bit palletized video
		- corrected chromatic subsampling
                - added option to specify system stream data rate in bits per second.
		- added option to specify video encoding parameter file and inter and
                  intra quantization matrix files (examples provided)(optional).

	Ver 1.2a- incorrect template.par included with 1.2, the correct one has been
                  added to this release.

        Ver 1.3 - added option (-e) to allow encoding of avi files with corrupt
                  frames, (from some versions of HyperCam). Missing frames are
                  replicated from last good frame, audio data is blanked.
                - added option to generate video only stream (-n)
                - added support for 10, 12, and 15 FPS video by upsampling to
                  30, 24, 30 FPS respectively.
                - made options case insensitive
                - handles odd pixel size video, pads out to even number.
                - corrected error in RGB->YUV conversion that caused pure white areas
                  in non-real (ie: computer animations) to appear black in mpg file.
                - intermediate file names (.m1v, .mp2) are based on output filename
                  (if any) instead of input filename.
                - opened max size limitation up to 704 x 480
                - increased max bit-rate to 4000kbit/sec, or 500Kbyte/sec
                - decreased min bit-rate tp 80kbit/sec, or 10KByte/sec
                - added -y option to adjust vbv_buffer_size from default of 20
                - appended .par extension to user supplied parameter file if none
                  provided
                - added -m option to allow easy selection of higher magnitude motion
                  search range.
                - eliminated estimated time remaining during video encode, it wasn't
                  very accurate, now reports % complete, and at end of video encode,
                  average time to encode one frame.

        Ver 1.4 - several minor corrections to VideoCD file generation, the -v
                  option generates a stream which has been tested with Adaptec's
                  EZ CD Creator 3.0 Video CD Creator.
                - added -c cropping option to specify horizontal and vertical size
                  of output file. Input files larger than specified have excess pixels
                  trimmed off, while input files smaller than specified are padded out
                  to specified size with blank pixels. The -v parameter implies
                  -c 352 240 (or 288), hence even input video which does not
                  correspond to VideoCD size can still be encoded.
                - when blank pixels are added to video to bring to multiple of 16, or
                  -c option is used, blank pixels are now added evenly to both sides
                  and top and bottom instead of just the right side and bottom.
                - added force frame rate option (-f), can be used to encode video of
                  arbitary frame rates (say, 6 FPS) to a standard frame rate. Video can
                  then be played back at normal speed with player which supports user
                  specified playback rates. Using this option implies -n (video only)
                  since there is no way to syncronise the resulting video with audio.
                - opened max size limitation to 720 x 480.

        Ver 1.5 - open max size limit to mpeg-1 limit, 4096x4096
                - dynamically allocated memory for U and Y buffers in readpic routine
                - open max data rate up to 40,000K bit/sec
                - report audio encoding progress in %

        Ver 1.6 - added ability to accept multiple input avi files to encode to
                  a single mpeg file (courtesy Adam Baker, aabaker@iee.org)
                - minor adjustments to bitrates to minimize syncronization
                  problems between video and audio

        Ver 1.7 - fixed minor bug in audio code which would cause
                  a GP fault on some machines with certain avi source
                  files at end of audio encoding, preventing generation
                  of a multiplexed mpg file.
                - added 12.5 to 25 fps upsampling rate
                - added MMX support by Ron Grenier to dist1 routine in motion.c
                - added -x switch to suppress MMX optimizations

        Ver 1.8 - added MMX support by Ron Genier to fdct routine
                - added 3DNow suport by Ron Grenier to dist1 routine
                - changed chroma subsampling to FIR algorithm, should give
                  better colour in detailed areas

For the latest revision check out http://www.mnsi.net/~jschlic1.

Compiling:

	The source code was compiled using MicroSoft Visual C++ 5.0, to
        recompile, create a new project of the type "Win32 Console
        Appplication". Add all the .c and .h files to the project, and
        under the Project Settings menu, under the Link tab, add
        vfw32.lib to the object/library modules list.


jschlic1@mnsi.net

