annotate DOCS/tech/libavc-options.txt @ 7011:5781b305040a

bug & ver update

Description of what all those libavcodec options do ...
WARNING: I am no encoding expert so the recommendations might be bad ...
if you find any errors, missing stuff, ... send a patch or cvs commit if you
have an cvs account :)

lavcopts: (encoder options)
---------------------------

vqmin 2-31 (minimum quantizer) for pass1/2
	1 is not recommended (much larger file, little quality difference (if u are lucky) 
           and other weird things (if u are less lucky))
           weird things: msmpeg4, h263 will be very low quality
                         ratecontrol will be confused -> lower quality
                         some decoders will not be able to decode it
	2 is recommended for normal mpeg4/mpeg1video encoding
	3 is recommended for h263(p)/msmpeg4 (default)
	   the reason for 3 instead of 2 is that 2 could lead to overflows
           (this will be fixed for h263(p) by changing the quanizer per MB in	    
           the future, but msmpeg4 doesnt support that so it cant be fixed for
	   that)

vqscale 1-31 quantizer for constant quantizer / constant quality encoding
	1 is not recommended (much larger file, little quality difference and
        possible other weird things)
	lower means better quality but larger files
	see vqmin

vqmax 1-31 (maximum quantizer) for pass1/2
	15 default
	10-31 should be a sane range

vqdiff  1-31 (maximum quantizer difference between I or P frames) for pass1/2
	3 default

vmax_b_frames 0-4 (maximum number of B frames between non B frames)
	0 no b frames (default)

vme 0-5 (motion estimation)
	0 none  (not recommanded, very lq)
	1 full  (not recommanded, too slow)
	2 log   (not recommanded, lq)
	3 phods (not recommanded, lq)
	4 EPZS  (default)
	5 X1

vhq (high quality mode)
	encode each MB as in all modes and choose the best (this is slow but
        better filesize/quality)
	disabled by default

v4mv
	allow 4 MV per MB (little difference in filesize/quality)
	disabled by default
	cannot be used with B frames (should now work in lq mode)

keyint  0-300 (maximum interval between keyframes)
	keyframes are needed for seeking as seeking is only possible to a
        keyframe but they need more space than non-keyframes so larger numbers here
        mean slightly smaller files, but less precise seeking
	0 no keyframes 
	>300 is not recommended as the quality might be bad (depends upon
        decoder, encoder and luck)

vb_strategy 0-1 for pass 2
	0 allways use the max number of B frames (default)
	1 avoid B frames in high motion scenes (this will cause bitrate
          misprediction)

vpass
	1 first pass
        2 second pass
          (only need to specify if two-pass encoding is used)

vbitrate (kbits per second) for pass1/2
	800 is default
        (if value is bigger then 16000 it is interpreted as bit not kbit!)

vratetol (filesize tolerance in kbit) for pass1/2
	this is just an approximation, the real difference can be much smaller
        or larger
	1000-100000 is a sane range
	8000 is default

vb_qfactor (1.0-31.0) for pass1/2
        (B-Frame quantizer = IP-Frame quantizer * vb_qfactor)
	2.0 is default
	tip: to do constant quantizer encoding with different quantizers for
             I/P and B frames you can use:
             vqmin=<ip_quant>:vqmax=<ip_quant>:vb_qfactor=<b_quant/ip_quant>

vqblur (0.0-1.0) quantizer blur (only for pass1)
	0.0 qblur disabled
	0.5 is the default
	1.0 average the quantizer over all previous frames
	larger values will average the quantizer more over time so that it will
        be changed slower

vqcomp (0.0-1.0) quantizer compression (for pass1/2)
	0.0 constant bitrate encoding, so fast motion frames will get as many
            bits as low motion (high motion scenes look bad)
	0.5 (default)
	1.0 constant quantizer encoding (low motion scenes look bad)

vrc_strategy (0,1,2)
	FIXME (different rate control strategies)

vlelim (0-1000) single coefficient elimination threshold for luminance
	0 disabled (default)
	4 (JVT recommendation)

vcelim (0-1000) single coefficient elimination threshold for chrominance
	0 disabled (default)
	7 (JVT recommendation)

vstrict strict standard compliance
	only recommended if you want to feed the output into the mpeg4 reference
        decoder

vdpart	data partitioning
	adds 2 byte per video packet
	improves error-resistance when transfering over unreliable channels (eg.
        streaming over the internet)

vpsize	(0-10000) video packet size
	0 disabled (default)
	500-1000 good choice
	improves error-resistance (see vdpart for more info)

gray	grayscale only encoding (a bit faster than with color ...)

lavdopts: (decoder options)
---------------------------

ver	error resilience
	-1 needed for some very broken, encoders which completly ignore the
           standards (one M4S2 asf sample know to need this) (default)
	0 
	1 more aggressive error detection, lavc might think that some correct
          streams contain errors

bug	manual workaround encoder bugs (cant be easily detected automatically)
	0 (default)
	1 for msmpeg4v3	workaround for some old lavc generated msmpeg4v3 files
	1 for mpeg4	workaround some opendivx? files 
			see http://heroinewarrior.com for some samples

gray	grayscale only decoding (a bit faster than with color ...)


Notes:	1. lavc will strictly follow the quantizer limits vqmin, vqmax, vqdiff
           even if it violates the bitrate / bitrate tolerance
	2. changing some options between pass1 & 2 can reduce the quality

FAQ:	Q: Why is the filesize much too small?
	A: Try to increase vqmin=2 or 1 (be carefull with 1, it could cause
           strange things to happen).
	Q: Can I use -pass 1 & -pass 2 with vmax_b_frames>0 ?
	A: -pass x uses the divx4 twopass-encoding codem which is incompatible
           with the libavcodec encode.
           If you want to fix it read DOCS/tech/patches.txt and send a patch.
	Q: What provides better error recovery while keeping the filesize low?
           Should I increase data partitioning or the number of video packets?
	A: Data partitioning is better in this case.

Glossary:
MB	Macroblock (16x16 luminance and 8x8 chrominance samples)
MV	Motion vector
ME	Motion estimation
MC	Motion compensation
JVT	Joint Video Team Standard -- http://www.itu.int/ITU-T/news/jvtpro.html

Examples:
mencoder foobar.avi -lavcopts vcodec=mpeg4:vhq:keyint=300:vqscale=2 -o new-foobar.avi
mplayer  foobar.avi -lavdopts bug=1

--
Written 2002 by Michael Niedermayer and reviewed by Felix Buenemann.
Check the MPlayer documentation for contact-addresses.