comparison DOCS/tech/libavc-options.txt @ 7088:9a0017ee11aa

support for the new ratecontrol code

7087:cf14ac26980d

	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)

        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)

        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)

	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 (-1000-1000) single coefficient elimination threshold for luminance
	0 disabled (default)
	-4 (JVT recommendation)
	negative values will allso consider the dc coefficient

	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

7088:9a0017ee11aa

	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 (default)
	3 is recommended for h263(p)/msmpeg4
	   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)

        possible other weird things)
	lower means better quality but larger files
	see vqmin

vqmax 1-31 (maximum quantizer) for pass1/2
	31 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)
	0-2 is a sane range for mpeg4

vme 0-5 (motion estimation)
	0 none  (not recommanded, very lq)
	1 full  (not recommanded, too slow)
	2 log   (not recommanded, lq)

        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)
        for strict mpeg1/2/4 compliance this would have to be <=132

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)

	this is just an approximation, the real difference can be much smaller
        or larger
	1000-100000 is a sane range
	8000 is default

vrc_maxrate (maximum bitrate in kbit/sec) for pass1/2
vrc_minrate (minimum bitrate in kbit/sec) for pass1/2
vrc_buf_size (buffer size    in kbit) for pass1/2
	this is for stuff like VCD
	VCD:  FIXME
	SVCD: ...
	DVD:  ...
	Note: vratetol should not be too large during the 2.pass or there might 
              be problems if vrc_(min|max)rate is used

vb_qfactor (-31.0-31.0) for pass1/2
	1.25 is default
vi_qfactor (-31.0-31.0) for pass1/2
	0.8 is default
vb_qoffset (-31.0-31.0) for pass1/2
	1.25 is default
vi_qoffset (-31.0-31.0) for pass1/2
	0.0 is default
        if v{b|i}_qfactor > 0  
            I/B-Frame quantizer = P-Frame quantizer * v{b|i}_qfactor + v{b|i}_qoffset
        else    
            do normal ratecontrol (dont lock to next P frame quantizer) and
            set q= -q * v{b|i}_qfactor + v{b|i}_qoffset
	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 (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
vqblur (0.0-99.0) quantizer blur (pass2)
	gaussian blur (gaussian blur cant be done during pass 1 as the future quantizers arent known)
	0.5 is the default
	larger values will average the quantizer more over time so that it will
        be changed slower

vqcomp  quantizer compression (for pass1/2) 
	depends upon vrc_eq

vrc_eq	the main ratecontrol equation (for pass1/2)
	1			constant bitrate
	tex			constant quality
	1+(tex/avgTex-1)*qComp	approximately the equation of the old ratecontrol code
	tex^qComp		with qcomp 0.5 or something like that (default)

        infix operators: +,-,*,/,^
        variables:
		tex		texture complexity
		iTex,pTex	intra, non intra texture complexity
		avgTex		average texture complexity
		avgIITex	average intra texture complexity in I frames
		avgPITex	average intra texture complexity in P frames
		avgPPTex	average non intra texture complexity in P frames
		avgBPTex	average non intra texture complexity in B frames
		mv		bits used for MVs
		fCode		maximum length of MV in log2 scale
		iCount		number of intra MBs / number of MBs
		var		spatial complexity
		mcVar		temporal complexity
		qComp		qcomp from the command line
		isI, isP, isB	is 1 if picture type is I/P/B else 0
		Pi,E		see ur favorite math book

        functions: 
		max(a,b),min(a,b)	maximum / minimum
		gt(a,b)			is 1 if a>b, 0 otherwise
		lt(a,b)			is 1 if a<b, 0 otherwise
		eq(a,b)			is 1 if a==b,0 otherwise
		sin,cos,tan,sinh,cosh,tanh,exp,log,abs

vrc_override	user specified quality for specific parts (ending credits ...) (for pass1/2)
	<start-frame>,<end-frame>,<quality>[/<start-frame>,<end-frame>,<quality>[/...]]
	quality 2..31 -> quantizer
	quality -500..0 -> quality correcture in %
        
vrc_init_cplx	(0-1000) initial complexity for pass1

vqsquish (0 or 1) for pass1/2 how to keep the quantizer between qmin & qmax
	0 use cliping
	1 use a nice differentiable function (default)

vlelim (-1000-1000) single coefficient elimination threshold for luminance
	0 disabled (default)
	-4 (JVT recommendation)
	negative values will allso consider the dc coefficient

	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 use data partitioning or increase 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
RC	Rate control
DCT	Discrete Cosine Transform
IDCT	Inverse Discrete Cosine Transform
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