-----------------------------------------------------------------------
MPEG2AVI - MPEG-1/MPEG-2 video to AVI-video convertor v0.16B33 10/31/99
http://members.xoom.com/mpeg2avi  mpeg2avi@xoom.com
-----------------------------------------------------------------------

                                -------------
                                User's manual
                                -------------

--------------------------------------
Command reference (command-line usage)
--------------------------------------

          MPEG2AVI is a Win32-console application.  That means it must be run
     from a Windows95/NT4 DOS-box.
          MPEG2AVI recognizes commands by a hyphen (-).  Therefore  every
     command must begin with a hyphen.  The next character is usually a
     command letter, telling MPEG2AVI which operation to perform.  Finally,
     some commands require several additional parameters.  REQUIRED
     parameters are shown in <>, while OPTIONAL parameters are shown in [].

     MPEG2AVI commands are divided into 4 groups :
     
       1) INPUT
          Input commands tell MPEG2AVI how to treat input bitstreams.  They
          influence MPEG2AVI's input behavior (before any MPEG-video is
          decoded.)

       2) MPEG-VIDEO DECODING
          Decoding commands influence MPEG2AVI's MPEG-video decoder.
     
       3) FRAME PROCESSING
          Various effects (cropping, half-resolution, downsizing, IVTC)
     
       4) OUTPUT
          Output commands tell MPEG2AVI how to create the AVI file.
     
     +--------------+    +---------------    +-----------+    +----------+
     | INPUT module |    | MPEG-1/MPEG-2|    |   Video   |    | AVI, GDI |
     |              | -> |    video     | -> |   frame   | -> |  OUTPUT  |
     | VOB/MPEG/DAT |    |   DECODER    |    | PROCESSOR |    |  module  |
     +--------------+    +--------------+    +-----------+    +----------+


Some commands require several parameters.
REQUIRED parameters are marked <>.
OPTIONAL parameters are marked [].

     -----------------
     1) INPUT COMMANDS
     
     -b "filename" [streamID] choose "filename" as input bitstream.
        The bitstream must contain an MPEG-1 or MPEG-2 video stream.  For VOB
        files, the optional parameter, [streamID], allows the user to pick a
        specific video stream.  StreamID is interpreted as a hexidecimal
        number "0xID."  This is useful for VOB files encoded with
        multiple camera angles.  (The default streamID == 0xE0)
     
        eg. Mpeg2avi.exe -b input.vob ...
           (input file = input.vob, default streamID 0xE0)
        eg. Mpeg2avi.exe -b input.vob 0xE1 ...
           (input file = input.vob, user-selected streamID 0xE1)
     
     -b "listname.lst" [streamID] open the streamlist "listname.lst"
        The streamlist must have an extension of *.LST!
        A streamlist is a list of VOB-files, which MPEG2AVI reads as one
        continuous file.  See sample.lst for more information
     
        eg. Mpeg2avi.exe -b dvdmovie.lst ...
           (opens streamlist "dvdmovie.lst", the individual VOB files of
            the list are concatenated into one continuous VOB bitstream.)
     
     -@ <lba> Open VOB bitstream at specified logical block address (LBA)
        The demuxer opens the VOB-bitstream at the specified LBA.  This
        Feature on applies to VOB input streams.  1 LBA = 2048bytes.
        If the starting packet does not contain a SYSTEM HEADER, MPEG2AVI
        automatically scans forward until one is found.
     
        MPEG2AVI begins MPEG-decoding at the 1st valid system header.
     Depending
        on the bitstream, there may be video garbage at the lead-in point.
     
        (The BBDMUX summary displays the LBA of last 2 valid headers.)
        (Alternatively, '-*' will print the system header's LBA.  The
        LBA is on the 4th line from the top-left of the video frame.)
     
        To deal with the lead-in video garbage, you can combine with
        MPEG2AVI's '-# <start> <end>' option.  Use '-@ <lba>' to seek
        the general location of the desired starting-point, then use
     
          '-# <start#> <end#>' to skip the first few frames.

        Note, when combining -@ and -#, <start#> is relative to the LBA of
     the
        first system-header.  (i.e. frame#"0" is the first decoded frame
        sometime after the specified LBA.)
     
          eg. MPEG2AVI.EXE -b input.vob -@ 1000 ...
              (open input.vob at LBA-offset 1000, or byte offset 2048Kby)
     
          eg. MPEG2AVI.EXE -b dvdmovie.lst -@ 1500000 ...
              (open the stream at LBA-offset 1500000, or byte offset 3072M)
     
     -------------------------------
     2) MPEG-VIDEO DECODING COMMANDS
     
     -r<n> Chose different IDCT algorithm
          '-r0'  64-bit floating-point iDCT (slowest)
          '-r1' *32-bit MMX iDCT (default)
          '-r2'  16-bit MMX Chen iDCT (faster, slightly less accurate)
          '-r3'  16-bit MMX AAN  iDCT (fastest, inaccurate)
          '-r4'  32-bit int iDCT (obsolete)
     
          '-r0' very slow, reference-quality iDCT (IEEE-1180 compliant)
                overkill since all internal pixel manipulations are handled
                with 16-bit precision, and stored with 8-bit precision.
     
          '-r1' 32-bit MMX IDCT, IEEE-1180 compliant (*)
                MPEG2AVI uses '-r1' by default.  This algorithm is both
                accurate and fast.
     
          '-r2' 16-bit MMX high-speed IDCT, not IEEE-1180 compliant
                trims seconds (not minutes) off decoding time, so it's use
                should be restricted to generating preview-clips.
          
          '-r3' 16-bit MMX high-speed IDCT, not IEEE-1180 compliant
                inaccurate, rarely faster than '-r2', useful only for
                GDI preview ('-o6')
          
          '-r4' 32-bit integer IDCT, IEEE-1180 compliant  (obsolete)
                This algorithm is obsolete, but still available.  It offers
                the same level of precision as the MMX32 IDCT, but is
                slower.
          
          * = default
          
          **in v0.14 and later, integer-IDCT is the default for *ALL*
            output modes!
          
          eg. MPEG2AVI.EXE -b input.m2v -r2 ...
              (decode bitstream "input.m2v" with MMX Chen IDCT)
          
          (source documents for these IDCTs can be found in the LINKs section
           at the end of this document.)
     
     -# <start> <end>  Define range of MPEG-frames to decode.
          MPEG2AVI limits its output to frames <start> ... <end>
          The numbering is based on MPEG2AVI's internal counter.
          THERE IS NO FRAME# IN AN MPEG-BITSTREAM!  MPEG2AVI starts at 0
          (0=first decoded frame.)  When '-@ <lba>' is not simultaneously
          used, '0' = first frame of the bitstream
          
          Eg. MPEG2AVI.EXE -b longclip.mpg -# 4895 9999 ...
             (begin frame-output at decoded MPEG-frame #4895, run until
     #9999)
          
     -f decode video as whole-frames (ignored by progressive MPEG sequences)
        MPEG2AVI's AVI-writer can only deal with whole frames (not fields.)
        Thus interlaced MPEG-2 files require this option! (internally, the
     MPEG
        Decoder produces individual fields and whole frames.  This would
        Confuse the AVI-writer, which only is initialized to one image size.)
     
          Eg. MPEG2AVI.EXE -b interlaced_clip.m2v -f ...
              (MPEG-decoder concatenates fields into complete frames)
     
     ----------------------------
     3) VIDEO PROCESSING COMMANDS
     
     Video processing executes in this order :
     
       MPEG      Inverse     Downsizer    Half-res    Output crop     AVI/GDI
      decoded -> Telecine -> '-3X <x>' ->   mode   ->   Viewport   -> Output
       video     '-s<n>'     '-3Y <y>'      '-2'      '-1 <x> <y>'    '-o<#>'
     
     -s<#> enable manual inverse-telecine with offset <#>,  #=0..4
          (examples, -s0, -s1, -s2, -s3, -s4)
          requires that '-f' is simultaneously specified
          (IVTC is OFF by default, please refer to ivtc.txt)
          
          eg. MPEG2AVI.EXE -b darkcity.vob -s4 -f ...
              (enables inverse-telecine, set starting-offset to #4)
     
     -s<#>D activate IVTC with "auto-disable" (repeat_first_field detection)
          (examples, -s0D, -s1D, -s2D, -s3D, -s4D)
          MPEG2AVI opens the MPEG-file with user specified frame-offset.
          The IVTC-processor functions normally until the detection of
          'repeat_first_field'.  If the IVTC-processor sees two consecutive
          MPEG frames with no repeat_first_field, the IVTC re-activates.
          (Useful for VOB-trailers whose MPEG-sequence begins as hardcoded
          3:2-pulldown, but later toggle "repeat_first_field".)
     
          eg. MPEG2AVI.EXE -b starship.vob -s4D -f ...
              (enables inverse-telecine, set starting-offset to #4)
     
     -1 <x> <y> Crop MPEG frames to user-specified dimensions <x> * <y>,
          Note, <x> must be divisible by 8, and <y> divisible by 2
          The cropped output is always centered with respect to the source.
          MPEG2AVI performs this function *last*.
          
          Eg. MPEG2AVI.EXE -b mpeg720x480.m2v -1 352 240 ...
              (crops the frames from source resolution -> 352x240)
          
     -2 Half-resolution output mode (half-X and half-Y resolution)
        The output is downsampled using arithmetic (average) interpolation.
        A square of 4 source pixels are averaged to produce 1 output pixel.
        MPEG2AVI performs '-2' *after* the resizer (-3x, -3y).  Half-
     resolution
        is faster than using the shrink function ('-3X <x>' and '-3Y <y>')
        (this option is affected by quality-mode, see '-q<n>')
     
          eg. MPEG2AVI.EXE -b mpeg720x480.m2v -2 -1 352 240 ...
              (first operation : resolution -> 360x240,
              second operation: crop 360x240 -> 352x240 )
     
     -3X <x> Shrinks output X-resolution to xxx.  Does not change viewport
          size. (In other words, the output resolution is unchanged, but the
          image is shrunk and black borders are put to the left and right.)
            MPEG2AVI implements weighted mean pixel-averaging (1st order
            averaging.)  Decreases performance
     
          eg. MPEG2AVI.EXE -b mpeg720x480.m2v -3X 640 -1 640 480 ...
            (first operation : image 720x480 -> 640x480)
             (second operation: crop viewport 720x480 -> 640x480)
     
     -3Y <y> Shrinks output Y-resolution to yyy.
            As for -3X, also decreases performance
     
            Since downsizing inevitably reduces picture detail, you should
            avoid downsizing in both directions simultaneously (X & Y.)
     
     -f[n] same as "-f", except also specifies a frame-rate from the table.
          The choice of frame-rate does not affect the decoder's output.  It
          merely sets the appropriate data-field in the AVI's header.
     
          Eg. MPEG2AVI.EXE -b ntsc_film_vcd.dat -f0
              (Sets AVI-file's framerate field to "23.976fps")
     ------------------
     4) OUTPUT COMMANDS
     
     -o6 draw to screen, via GDI ( using RGB24 using Display_Dib() )
     
          eg. mpeg2avi.exe -b input.m1v -o6 ...
             (decodes input.m1v to the screen)
     
     -o7 <output AVI filename> write to AVI (RGB24 444)
         (standard bitmap format for VFW)
         MPEG2AVI 0.16B23's CSC (color space converter) was rewritten in MMX.
         The MMX-code has closed the speed-gap between RGB and YUV AVI modes.
         Now, the YUV AVI modes are (usually) only marginally faster.
     
          Eg. mpeg2avi.exe -b input.m1v -o7 output.avi ...
              (converts input.m1v -> output.avi, using RGB24 AVI writer)
     
     -o8 <output AVI filename> write to AVI (YV12 420)
         "YV12" is a Directdraw surface format, whose sampling-
     characteristics
         are identical to YCbCr 4:2:0.  Both formats have identical
     resolution
         parameters (luminance fullxfull, chroma halfxhalf.)
         not all VFW codecs accept YUV-input, see vfw_yuv.txt
     
          Eg. mpeg2avi.exe -b input.m1v -o8 output.avi ...
              (converts input.m1v -> output.avi, using YV12 AVI writer)
     
     -o9 <output AVI filename> write to AVI (YUY2 422)
         "YUY2" is a Directdraw surface format, whose sampling-
     characteristics
         are identical to YCbCr 4:2:2.  Both Formats have identical
     resolution
         parameters (luminance full x full, chroma half x full.)
         not all VFW codecs accept YUV-input, see vfw_yuv.txt
     
          Eg. mpeg2avi.exe -b input.m1v -o9 output.avi ...
              (converts input.m1v -> output.avi, using YUY2 AVI writer)
     
     -$ <n> Set AVI-autosplit size-threshold to <n> megabytes.
           MPEG2AVI's default size-threshold = 2040MB (~2GB)  When the
     current
           AVI-file's length reaches the threshold <n>, MPEG2AVI closes it
     and
           opens a new one.  The new file's name is arbitrarily chosen
          
          eg. MPEG2AVI.EXE -b dvdmovie.lst -f -o8 dvdmov.avi -$ 640 ...
              (Tells AVI writer to limit output file size to 640MB.  A new
               file is automatically created when the current AVI-file
     exceeds
               this size.)
     
     -! <n> Skip 1 frame for every <n> decoded frames.
           MPEG2AVI decodes every frame, but does not write the <n>th frame.
           The frame-drop can be considered decimation in the temporal sense.
          
          Eg. MPEG2AVI.EXE -b dvdmovie.lst -f -o8 dvdmov.avi -! 3350 ...
             (Tells output module to discard every 3350th frame it receives.)
             (this function is implemented after all other functions)
     
     -* Prints MPEG-data in upper left of output video.  The data has the
        following format :
          1) MPEG2AVI frame# (decoded frames, start from 0)
          2) GOP timecode (MPEG GOP header time code XX:XX:XX:frame)
             a white-square flashes briefly (duration of 1 frame) for
             MPEG I-frames.
          3) temporal reference (MPEG picture header)
          4) address (LBA) of last valid SYSTEM HEADER (VOB only)
          
          eg. mpeg2avi.exe -b trailer.vob -f -* ...
             (Prints header data in upper-left corner of output viewport)
     
          This information is probably only useful to MPEG techies.  I use it
          to debug.  The last item (4) is helpful for MPEG2AVI's LBA-seek
          option ('-@ <lba>')

-------------------------------------
"HOW DO I?" (USAGE EXAMPLES AND TIPS)
-------------------------------------

     Q: How do I ... with MPEG2AVI?
     
     I'll fill this in later...
     
     Don't forget to read these other important documents:

          mpeg2avi.txt  - User's Guide
          sample.lst    - "streamlist" sample file
          ivtc.txt      - inverse telecine information, incomplete!
          vfw_yuv.txt      - MPEG2AVI FAQ and YUV-AVI information
     
----------------
INVERSE-TELECINE
----------------

     (Please see ivtc.txt)

--------------------
PROGRAM REQUIREMENTS
--------------------
     + Windows95/NT4 or later, 32MB RAM (didn't test, ...)
     
     + CPU with MMX support (MPEG2AVI is optimized for Intel IA32(R) CPUs)
     
     + Windows Video-compression routines
       (Control Panel -> Add/Remove Programs -> Windows Setup)
     
     Despite some MMX optimization, MPEG2AVI does not approach the speed of a
     commercial softDVD player.  I estimate MPEG2AVI to be 2-3X slower than a
     commercial softDVD player.  However, MPEG2AVI can produce higher quality
     video than some commercial SoftDVD programs (like XingDVD 2.0x).
     
     I did run two benchmarks on my development system :
     
     Hardware : ASUS P2B-F i440BX, Intel Celeron-366 @ 458MHz, Win98SE
          
     Benchmark 1)
          Source : DolbyDigitalTrain.VOB (MPEG-2 video @ 720x480 29.97Hz IL)
          Output : Microsoft MPEG4V3 codec (kf:1sec, rate:1200KBps,
     Sharp:100)
          Notes  : inverse-telecine '-s4', FPU-IDCT '-r0', RGB24 AVI '-o7'
          
               C:\> MPEG2AVI.EXE -b Dolby.vob -f0 -r0 -s4 -o7 dolby.avi
               
               AVI output clip : 38-seconds @ 23.976 fps, 720x480 resolution
               Elapsed Encoding time : ~500 seconds
               
               Microsoft's MPEG4V3 codec no longer supports VFW.  The
          benchmark was run on a beta release of Windows Media Tools 4.0.
               
     Benchmark 2)
          Source : redcornertrailer.vob (MPEG-2 video @ 720x480 29.97Hz IL)
                  Source clip is coded as progressive (24fps) using rff
                  Source filesize is ~120MB
          Output : PicVideo M-JPEG v2.0 codec (LQ:34 CQ:38 SS:422)
          Notes  : Chen MMX-IDCT '-r2', YUY2 AVI '-o9', half-resolution '-2'
          
               C:\> MPEG2AVI.EXE -b rct.vob -f0 -r2 -2 -1 352 240 -o9 rct.avi
               
               AVI output clip : 2:40sec @ 23.976fps, 352x240 resolution
               Elapsed encoding time : ~240 seconds
               (with '-r1' IDCT, the same clip requires 350 seconds to
          encode)
               

-------------------
YEAR 2000 STATEMENT
-------------------

          "I have absolutely no clue what might happen if MPEG2AVI.EXE were
     to be run just before the new millennium.  It may exhibit strange
     behavior, anywhere from turning on your TV to causing the end of the
     world."

-----------------
SOURCE CODE NOTES
-----------------

     Please see source.txt for more information.

-----------------------
LIMITATIONS of MPEG2AVI
-----------------------
   -very limited multi-file input capability
    Only supports VOB files from a continuous stream (like a DVD-disc),
    where the files stored physically adjacent.

   -no audio decoding ... yet (audio streams are ignored)

   -resize options (-3X, -3Y) are limited to 8-pixel increments, and slow

   -Screen output (GDI) is slow and not updated correctly.
    Output is "messy"

   -MPEG-output cannot be enlarged (zoomed), only shrunk
    (no plans for zooming; zooming does not 'extract' more detail)

   -damaged input bitstreams cause MPEG2AVI to crash or malfunction

   -VOB vs M2V (same MPEG-2 video), VOB reading is slower due to demuxing
    overhead

   -no CSS support, MPEG2AVI cannot read encrypted VOB files
    (i.e. region-coded DVD movies)  Since DVD-movies are generally
    copyrighted, there are no plans for direct DVD-conversion

   -no CD-i "DigitalVideo" disc support (CD-i discs prior to 1994)
    CD-i DigitalVideo discs are *not* WhiteBook VideoCDs!

   -aborted AVI files are readable, but MPEG2AVI cannot resume aborted
    encoding-jobs (cannot append to end of a closed AVI file)

   -MPEG2AVI is slow compared to commercial MPEG decoders/players.
    (but conversion jobs where the encoding is inherently slow, there is
     little difference in overall throughput.)

   -clumsy command-line interface (will be addressed in future GUI)

---------------
CREDITS & LINKS
---------------

     Lots of people helped with the MPEG2AVI's development.  First of all,
     this project wasn't possible without the MSSG MPEG2V12 codec @
     http://www.mpeg.org.  Cheers to the standards organization for making
     the source-code free to the general public.  The VOB-demuxing is based
     on Brent Beyer's BBDMUX v1.3.  Portions of the AVI-writer received help
     (indirectly) from the authors of VideoMatrix and VirtualDub.

     Last but not least, the couple hundred or so devoted (or desperate...)
     users who try every new release and report-back broken features.
     (DOH...)
     
     -------------------------------------------------
     Hobbyist resources : Information for casual users
     -------------------------------------------------
     
          http://www.videodiscovery.com/vdyweb/dvd/dvdfaq.html
            An *excellent* DVD FAQ by Jim Taylor
          
          http://www.hollywood.com
            complete VOB trailers for BigHit, DarkCity, Lost in Space, and
            Wedding Singer.  (these trailers are coded with redundant fields;
             they are good candidates for MPEG2AVI's IVTC processor)
          
          http://dilapi.stu.rpi.edu/trailers/
            MPEG-2 VOB trailers of recent movies
          
          ftp://ftp.xingtech.com
            one clip of each kind MPG/M2V/VOB, (the shuttle.m2v clip has bad
            header info - shuttle.m2v must be demuxed by a third-party tool
            before MPEG2AVI can decode it)
          
          ftp://ftp.csst.net/csst/Dolby  (login:csst, passwd:csst)
            high-fidelity Dolby Digital VOB trailers
          
          http://www.inmatrix.com
            another PC-DVD site, lots of good user info
          
          http://www.concentric.net/~psilon
            VirtualDub - free AVI/ASF/MPEG-1 -> AVI converter with source-
          code!
             This is a *GREAT* freeware GUI application for linear-editing
          
          http://www.microsoft.com/windows/windowsmedia/en/
            Windows Media Technology homepage
     
     -------------------------------------------------
     Developer resources : Information for programmers
     -------------------------------------------------
     
          http://www.mpeg.org
            source of MPEG2V12 software encoder/decoder
          
          http://www.ece.ubc.ca/~knguyen/software/idct_chen_mmx1.c
            MMX 16-bit Chen IDCT 8x8 algorithm
          
          http://developer.intel.com/drg/mmx/appnotes/ap528.htm
            MMX 16-bit AAN IDCT 8x8 algorithm (AP-528)
          
          http://developer.intel.com/vtune/cbts/strmsimd/appnotes.htm
            MMX/SIMD accurate IDCT 8x8 algorithm (AP-922)
          
          http://members.home.net/beyeler/bbmpeg.html
            source of BBTOOLS, BBDMUX, and BBMPEG, an AVI->MPEG2 encoder
          
          http://www.webartz.com/fourcc
            Information on common YUV/RGB color formats. Focusues on PC VGA
            pixel foramts (Directdraw surface YV12, YUY2, UYVY, etc.)
     

------------------------------
DISTRIBUTION DISCLAIMER
------------------------------

     MPEG2AVI is a freeware program : end-users may download and use it
     without restriction.
     
     HOWEVER, major portions of MPEG2AVI uses source code provided by the
     MPEG Software Simulation Group. The MPEG2V12 codec is subject to MSSG's
     distribution terms, which means commercial applications/derivatives are
     subject to license/royalty payments.

     ---------------------------------------------------------------------
     Disclaimer of Warranty
     
     These software programs are available to the user without any license
     fee or royalty on an "as is" basis.  I disclaim any and all warranties,
     whether express, implied, or statuary, including any implied warranties
     or merchantability or of fitness for a particular purpose.  In no event
     shall the copyright-holder be liable for any incidental, punitive, or
     consequential damages of any kind whatsoever arising from the use of
     these programs.
     
     This disclaimer of warranty extends to the user of these programs and
     user's customers, employees, agents, transferees, successors, and
     assigns.
     
     The MPEG Software Simulation Group does not represent or warrant that
     the programs furnished hereunder are free of infringement of any third-
     party patents.
     
     Commercial implementations of MPEG-1 and MPEG-2 video, including
     shareware, are subject to royalty fees to patent holders.  Many of these
     patents are general enough such that they are unavoidable regardless of
     implementation design.
     ---------------------------------------------------------------------
     
