AviPreview Console v0.71 Beta
06-02-2002
by Oliver Stephenson (olly@funkster.org)


PLEASE READ THIS FILE BEFORE USING AVIPREVIEW!

   Dear user, thank you for downloading a beta version of AviPreview (Console version)
for win32. Please note that this is a BETA release and is not guaranteed to work in any
way at all. If you run this program and it melts your hard disks, screams obscenities
at your mother-in-law and violates your household pet, don't blame me.


LICENCE:

   You may use this software without charge, as long as it is not modified in any way
or used for any illegal purpose. You may not redistribute this software in any way
(this includes putting a copy of the released file on your web server) without the
author's express permission.

   If you wish to link to the software, please link to http://www.funkster.org/ and
direct the user towards the software section. By downloading or using any of the
software on my web site you are agreeing to the terms of this licence so please be
sure you have understood it.


REQUIREMENTS:

   - Windows 95/98/Me/NT/2k/XP (Please note that 95, 98 and Me are not tested)
   - At least 32Mb RAM
   - DivX Codec v3.11a or v3.20a
   - DivX Codec v4.12
   - A command prompt (if you don't know what this is you shouldn't be playing with
     beta software!)
   - Some DivX3 or DivX4 AVI Content to try it on (this means 4cc codes of div3, div4
     or divx)


USAGE:

To use AviPreview, open a command prompt in the relevant directory and type:

AviPreviewC inputfilename outputfilename [optional switches]

where:
   - inputfilename is a file containing compressed video frames with an AVI structure.
   - outputfilename is the name of the file you want to be created with your preview in
     (don't forget to use a .avi extension!)

Optional switches (without the quotes and with spaces inbetween):
   "-c (value)" = Codec that the input file is encoded with (see requirements above).
   "-h (value)" = Horizontal resolution.
   "-v (value)" = Vertical resolution.
   "-r (value)" = Framerate to use for output (frames per second, no more than 9
                  significant figures).
   "-k (value)" = Target keyframe for starting detection at a specified point in the movie.
   "-n (value)" = Number of keyframes to extract for preview (all delta frames between
                  these keyframes are extracted too, so keep this low).
   "-s (value)" = Size of file (in bytes) to create for preview, so you can make a
                  predictable size output file.
   "-f"         = Force resolution detection (in case resolution in the header is wrong).
   "-a"         = Attempt to detect and extract audio.

   If no optional switches are supplied, AviPreview tries to detect the codec used. If the
codec is found, detection is started at the first keyframe and all available video frames
are extracted for the preview. Watch out, the output will be nearly as big as the input
file!

   Currently support for video codecs other than DivX3 and DivX4 (using the -c switch) is
only preliminary, and resolution detection is not possible. This means that for MS v2 and
other codecs, AviPreview is only useful if you have the header of the AVI file, or already
know the resolution.

   Please note that -h and -v must be used as a pair. Only use these switches if you
know the resolution of the movie from an earlier detection run.

   If you don't want to have AviPreview in the same directory as your input and output
files, just type in the full paths to the files. If the path contains spaces don't forget
to use "speech marks"!


WHAT IT DOES:

   When AviPreview starts, it opens the input file and looks to see what of the original
AVI file is there. If it finds the header, you're lucky and you have the beginning of the
file. Otherwise, AviPreview will try to detect the relevant information needed to let you
preview the file. If it gets the resolution correct, write it down so you can check out
other frames without having to detect (enter the resolution on the command line as detailed
above).

   Once AviPreview knows the resolution, it extracts some frames from your input file
and saves them out to your output AVI file. When this file has been created go ahead
and open it in your favourite media player or AVI editor.


WHY IT'S NEEDED:

   When the AVI header is lost, the resolution (dimensions) of the image data is lost
also. Although other more user-friendly utilities exist that allow you to play an AVI
that has lost some of its data, they all require that the AVI header is intact.
   AviPreview tries to get around this issue by way of Magic.


HOW IT WORKS:

   Once a keyframe is found in the video stream, AviPreview tries to decode it at
various resolutions. Unfortunately in this situation, the video codec will report
that the frame has decoded okay even when the resolution is wrong. Because of this,
AviPreview uses various kinds of Jiggery Pokery (TM) to try to determine the
correct resolution.
   The algorithm is much improved over previous versions, and a big speed increase
has been achieved. However, more than one keyframe is needed to enable AviPreview
to check that it has found the correct resolution.


CODECS SUPPORTED:

   - div3 (DivX3 Low Motion)	 - detection and extraction
   - div4 (DivX3 Fast Motion)	 - detection and extraction
   - divx (DivX4 Final)		 - detection and extraction
   - mp42 (Microsoft MPEG4 v2)	 - extraction only


KNOWN BUGS IN THIS RELEASE (v0.70 Beta):

   - It's a bit slow (much faster than previous versions though). But then, nothing
     else does this job...

   - If the data you are using it on does not contain many keyframes then it sometimes
     cannot find a resolution at all.

   - If you Ctrl-C while detecting the resolution of a DivX4 stream, you get an access
     violation.


FEATURES COMING SOON:

   - Framerate detection (maybe).
   - More code optimisation for speed.
   - Better support for different video codecs.


CHANGE HISTORY:

0.01 - Alpha. First public release.

0.02 - Beta status achieved. Algorithm more accurate although much slower.

0.10 - Beta. First version to reach 100% resolution detection success on my tests.
       Version number increased accordingly :o). User can now enter a known resolution
       on the command line for when a previous detection run has found the correct
       resolution. AviPreview no longer finds infinite numbers of 12-byte keyframes
       when the end of the original avi is present.

0.11 - Beta. Hopefully sorted the problems some people were having playing back the
       output files. I'm not quite sure why my system was immune to the omission I made
       but that's the trouble of doing all your testing on one machine. Both VirtualDub
       v1.4.6 and Windows Media Player v6.4 now play files fine on my machine.

0.15 - Beta, not publicly released. First experiments with slideshow output, had several
       really nasty bugs.

0.20 - Beta. Slideshow output now working, most memory leaks removed.

0.21 - Beta. Same as v0.20 but memory exception problem fixed.

0.22 - Beta. Command line input changed so switches are used and order no longer matters.
       Also, user intervention is no longer needed once the program is running so you can
       use unattended batch files to run it. Defaults set up so if the user just enters
       the filenames AviPreview will do something, including making a slideshow of ALL
       available keyframes.

0.40 - Beta. Extraction of motion! Hurrah! Actually it's rather buggy but I still find
       it useful, as long as DivX AntiFreeze is installed. Audio'll be along in a
       minute...

0.45 - Beta. Corruption problem solved, should now be useful even if you don't have DivX
       AntiFreeze. Has a memory leak that only becomes a problem with files with big
       gaps in the data.

0.46 - Beta. Fixed the bug where the framerate was not written if a resolution detection
       run had taken place. Other various bits tidied up a bit, should be a little bit
       quicker and hopefully there should be less problems with exceptions. Otherwise
       identical to v0.45.

0.50 - Beta. Audio extraction support for mp3 audio, and preliminary support for codecs
       other than DivX3. Has a bug where some input files will cause it to loop back to
       the beginning when it reaches the last frame, producing infinitely large output
       files.

0.51 - Beta. Looping bug fixed, otherwise identical to v0.50.

0.55 - Beta. Finally sorted out the problem with the massive memory hog for files with
       largy empty spaces. Now runs much much faster and uses very little memory. Also
       should be slightly more successful at spotting a supported audio track, if there
       is one. Still misses some audio tracks, depending on the program that interleaved
       the file in the first place.

0.56 - Beta. Fixed the bug where some audio tracks were not found. Tidied up a little
       more code so resolution detection should be slightly quicker with some files.

0.57 - Beta. Framerate is now picked up if you have the AVI header, and you can set a
       framerate on the command line. Not publicly released.

0.60 - Beta. First release with resolution detection for DivX4 streams. Mono mp3 audio
       tracks detected as stereo, causing double-speed playback of audio.

0.62 - Beta. Audio detection now supports all layers of both MPEG 1 and 2. Fixed a bug
       that stopped any keyframes from being found during the extraction phase. Also
       tweaked the DivX4 resolution detection algorithm, so it's now faster and more
       accurate than before.

0.70 - Beta. Massive detection core rewrite, can now detect the codec used for the
       video stream. DivX4 resolution detection faster and more accurate. Version number
       increased accordingly :o). Had a bug where DivX3 codec sometimes wouldn't be
       detected, and command-line codec setting did not allow resolution detection.

0.71 - Beta. DivX3 detection bug fixed, and command-line codec input now has the proper
       effect. Otherwise identical to v0.70.


FINALLY:

   I'd like to thank programmer extraordinaire Dominic Hopton (http://www.codevoid.net/)
for helping me out with code when I've been Thick. Cheers Dom!

   If you really like this piece of software, then consider slinging me a buck or two -
just visit my homepage and there's a Paypal Donation bit on the main Software page.
Cheers!

   If you find a new bug (you probably will!) email olly@funkster.org and tell me about
it, stating the version of AviPreview that you are using. Please don't tell me about
things I already know about (see above).

Enjoy!
--
Oliver Stephenson
http://www.funkster.org/