karl_lillevold
8th March 2004, 23:00
I wrote the following documentation for all the existing RealVideo 9/10 encoder codecProperties, so here we go:
Audience
To use these options, include the following in the
videoStream section of the audience:
<videoStream>
<codecProperties type="bag">
<customProperty type="mytype">setting</customProperty>
</codecProperties>
</videoStream>
Registry
All the options also have their corresponding registry
equivalent. The registry settings are meant as an
alternative to enable features when using GUIs that do
not (yet, or will ever) support some or all the custom features.
For instance, when a new codec is used in GUI Helix Producer,
Adobe Premiere, or Vegas Video, neither of which supports
custom codec options. If you edit your audiences by hand anyway,
or use a GUI that supports the custom options you would like to
use, you do not need registry settings at all.
The location is HKEY_LOCAL_MACHINE\SOFTWARE\RealNetworks\RV9.
For type="uint", use DWORD. Remember to use convert between
decimal and hex. For type="bool" also use DWORD, where 1 is
true, and 0 is false. For type='string' use String. An
example registry file would for instance be:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\RealNetworks\RV9]
"encoderComplexity"=dword:0000005a
"rcEnableCurveCompression"=dword:00000001
"rcAnalysisFileName"="\realvideo.pass"
"rcAnalysisLogFileName"="\realvideo.log"
Encoder general options
encoderComplexity
<encoderComplexity type="uint">[0-100]</encoderComplexity>
Set encoder complexity. This over-rides the setting passed
in from Producer.
100: Very High (95-100)
90 : High (85-94) ** Recommended
80 : Medium-High (78-84) ** 2nd Recommended
70 : Medium (70-77)
60 : Low (60-69)
50 : Very Low (50-59)
Default: 85
firstPassComplexity
<firstPassComplexity type="uint">[0-100]</firstPassComplexity>
Set encoder complexity to use for 1st pass in a 2-pass encode.
Default: Normally 65, or 50 when new
vbrUnconstrainedBitrate *) rate control is used.
*): This corresponds to the new rcEnableCurveCompression described below.
customPacketSize
<customPacketSize type="uint">[0-16000]</customPacketSize>
Force codec to use a certain packet (slice) size. Any number
can be specified, but larger than 16000 is not going to be
decodable by RealOne V2 and older, due to a bug in
interpreting the RM information.
Default : passed in from Producer (15000 for VBR with
bitrate greater than 450 kbps, otherwise 1352 or lower,
depending on bitrate)
calcPSNR
<calcPSNR type="bool">[true|false]</calcPSNR>
Enable or disable PSNR and other information being printed
in the rv9log.txt file
Default : false
enableRPR
<enableRPR type="bool">[true|false]</enableRPR>
Enable or disable the use of RPR (Reference Picture
Resampling) in the codec. Sometimes it may be desirable to
have the codec encode at the native resolution, no matter
how low the bitrate is. One good example is screen capture
video clips.
Default : true
enableAutoKeyFrames
<enableAutoKeyFrames type="bool">[true|false]</enableAutoKeyFrames>
Enable or disable the insertion of key frames at scene
changes. Since the encoder will have to re-encode the whole
frame, when it detects a scene change, this can be CPU
intensive for very high action sequences with frequent scene
changes.
Default : true, unless in Live mode under CPU duress.
noisyEdgeFilter
<noisyEdgeFilter type="bool">[true|false]</noisyEdgeFilter>
Enable or disable the noisy edge filter, i.e. the filter
that corrects single or double lines along the edge of the
video, resulting from bad capture or crop settings. The
noisy edge filter is bad for PSNR).
Default : true, unless calcPSNR is enabled.
useThreads
<useThreads type="bool">[true|false]</useThreads>
Enable or disable the use of threads in the encoder.
Default : use threads when more than one CPU, virtual or
real, is available.
writePreviewToFile
<writePreviewToFile type="string">filename</writePreviewToFile>
The encoder will save its reconstructed frames as
uncompressed I420. Will create and write an AVI file, if the
filename has .avi extension. This corresponds to the frames
shown in the "preview" window of the GUI RealProducer.
Default: off
exactPreview
<exactPreview type="bool">[true|false]</exactPreview>
Normally the encoder does not inloop B frames accurately,
since these are not used for future prediction. However,
with this option set to true, the frames will be inloop
deblocked just like the player/decoder will do.
Default: false
New Rate Control Options
rcEnableCurveCompression
<rcEnableCurveCompression type="bool">true</rcEnableCurveCompression>
Enables new curve compression based rate control This
disables all other RC modes, MSL and maxBitrate ignored
Still, include maxBitrate and MSL; needed for stream
properties
The new RC's goal is constant quality throughout the encode.
It works great at high bitrates, and is much more accurate
than the old rate control. For low bitrates, until more
advanced parameters are added, the old rate control, or an
external scaler is recommended. Specifically useful for low
bitrates would have been High bitrate scenes degradation (%)
and Low bitrate scenes improvement (%). These are not yet
implemented
Also, this constant quality is not the best solution for
highest overall or average PSNR. For my sample test clip, I
got a reduction of 0.3 dB average PSNR, but 6.5 dB better
minimum PSNR, corresponding to a huge visual improvement
When above params are added and used, this will help avg
PSNR
Other news about this RC, is that it allows 1st pass to be
run at the lowest possible complexity (50), with inloop
filter off This makes the 1st pass run even faster than
before
Since the analysis file is the same format as XviD uses, it
can be read, plotted, and analyzed with some of the same
tools. External scaler tools can be used as well Finally,
with this new RC, the 2nd pass can be re-run at different
target bitrates than the 1st pass.
WARNING: This rate control works only in 2-pass mode.
If you enable rcEnableCurveCompression, and run
a 1-pass encode, the encoder will run the 1st pass of
a 2-pass encode, and you will end up with a very large
output file. If you like, you can then run the 2nd
pass separately, using the rcPassNumber option below.
rcAnalysisFileName
<rcAnalysisFileName type="string">realvideo.pass</rcAnalysisFileName>
First pass analysis file, ASCII text, same format as XviD
This is possible, since all it contains are: frame types,
quants, MBs, frame sizes, (scalable and un-scalable part)
Can be read by XviD stats analysis tools, like this one :
http://atlas2.tgv.net/~media-video/forum2/viewtopic.php?t=3594
http://forum.doom9.org/showthread.php?s=&threadid=67639
An external scaler would add a last column (desired frame
size) The binary .stats format is not supported
rcLogFileName
<rcLogFileName type="string">realvideo.log</rcLogFileName>
Rate control log file from 2nd pass Useful only if problems
occur, and for the curious
rcTargetVideoSize
<rcTargetVideoSize type="uint">585728</rcTargetVideoSize>
Target filesize is kilobytes for /VIDEO ONLY/, over-rides
target bitrate If this option is used, rcSourceFrameRate is
not needed
rcKeyFrameBoost
<rcKeyFrameBoost type="uint">0</rcKeyFrameBoost>
Boost keyframes by rcKeyFrameBoost %
rcHighBitrateReduce
<rcHighBitrateReduce type="uint">0</rcHighBitrateReduce>
Reduce larger than average frames by rcHighBitrateReduce %
Usually good for average PSNR, and/or low/medium bitrate
streams, where the largest frames cost too many bits
compared to the PSNR achieved
rcLowBitrateBoost
<rcLowBitrateBoost type="uint">0</rcLowBitrateBoost>
Boost smaller than average frames by rcLowBitrateBoost %
rcPassNumber
<rcPassNumber type="uint">2</rcPassNumber>
Specify pass # to run, requires cmd line -dt or jobfile
enableTwoPass to 'false'. 2nd pass can be re-run with any
target bitrate changes, other parameters should be the same
When pass #1 is run by itself, Producer will appear to be
encoding normally, and also output a large RMVB, but it will
also output .pass file correctly.
Default: not used for 2-pass encodes.
Reference Quantizers
<rcPFrameRefQuant type="uint">6</rcPFrameRefQuant>
<rcBFrameRefQuant type="uint">10</rcBFrameRefQuant>
Quantizers to use for the 1st pass reference encoding Range
[0-30] Leave alone unless you know what you are doing Quants
do not correspond to MPEG-4 quants and do not scale the same
way either.
RC fine tuning
<rcOverFlowControlStrength type="uint">5</rcOverFlowControlStrength>
<rcMaxOverflowImprovement type="uint">50</rcMaxOverflowImprovement>
<rcMaxOverflowDegradation type="uint">50</rcMaxOverflowDegradation>
B Frames Control
maxConsecutiveBFrames
<maxConsecutiveBFrames type="uint">3</maxConsecutiveBFrames>
Leave B frame adaptivity ON, but sets the max number of B frames Only 3, 1, and
0 are allowed, due to current impl. restriction
Inloop filter options
inloopCutOffQuant
<inloopCutOffQuant type="uint">[0-30]</inloopCutOffQuant>
Inloop filter is turned off below this quant. Set to 0 to
always use inloop (this is the default, but in reality, the
default level is around 9 Set to 31, to completely disable
inloop postfilter When quant is below the threshold, the
encoder will skip the inloop filter, and put a bit in the
bitstream so the decoder will do the same. Use with caution
for low to medium bitrates. No inloop will lower PSNR as
well These quants do not correspond to MPEG-4 quants
Default: 0
inloopCutOffCompatible
<inloopCutOffCompatible type="bool">[true|false]</inloopCutOffCompatible>
Make bitstream 100% compatible with earlier*) decoders What
this means is that /key/frames will always be inloop
filtered with the default quant threshold. This is a bug in
old decoders, they always inloop filter keyframes. When set
to false, the threshold applies to all frame types. When an
old decoder tries to decode such a bitstream there will be a
very minor decoder mismatch, in most cases not visible. *:
RV8/9/10 decoders prior to RealPlayer 10 Gold
Default: false
inloopCutOffBUseRefQuant
<inloopCutOffBUseRefQuant type="bool">[true|false]</inloopCutOffBUseRefQuant>
If true, the threshold to enable the inloop filter for B
frames, will use the reference frame's quant. If false, the B
frame's quant is used.
Default: false
Inloop defaults for 'Sharp' setting in latest Producer
inloopCutOffQuant = 10
inloopCutOffCompatible = false
inloopCutOffBUseRefQuant = true
Audience
To use these options, include the following in the
videoStream section of the audience:
<videoStream>
<codecProperties type="bag">
<customProperty type="mytype">setting</customProperty>
</codecProperties>
</videoStream>
Registry
All the options also have their corresponding registry
equivalent. The registry settings are meant as an
alternative to enable features when using GUIs that do
not (yet, or will ever) support some or all the custom features.
For instance, when a new codec is used in GUI Helix Producer,
Adobe Premiere, or Vegas Video, neither of which supports
custom codec options. If you edit your audiences by hand anyway,
or use a GUI that supports the custom options you would like to
use, you do not need registry settings at all.
The location is HKEY_LOCAL_MACHINE\SOFTWARE\RealNetworks\RV9.
For type="uint", use DWORD. Remember to use convert between
decimal and hex. For type="bool" also use DWORD, where 1 is
true, and 0 is false. For type='string' use String. An
example registry file would for instance be:
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\RealNetworks\RV9]
"encoderComplexity"=dword:0000005a
"rcEnableCurveCompression"=dword:00000001
"rcAnalysisFileName"="\realvideo.pass"
"rcAnalysisLogFileName"="\realvideo.log"
Encoder general options
encoderComplexity
<encoderComplexity type="uint">[0-100]</encoderComplexity>
Set encoder complexity. This over-rides the setting passed
in from Producer.
100: Very High (95-100)
90 : High (85-94) ** Recommended
80 : Medium-High (78-84) ** 2nd Recommended
70 : Medium (70-77)
60 : Low (60-69)
50 : Very Low (50-59)
Default: 85
firstPassComplexity
<firstPassComplexity type="uint">[0-100]</firstPassComplexity>
Set encoder complexity to use for 1st pass in a 2-pass encode.
Default: Normally 65, or 50 when new
vbrUnconstrainedBitrate *) rate control is used.
*): This corresponds to the new rcEnableCurveCompression described below.
customPacketSize
<customPacketSize type="uint">[0-16000]</customPacketSize>
Force codec to use a certain packet (slice) size. Any number
can be specified, but larger than 16000 is not going to be
decodable by RealOne V2 and older, due to a bug in
interpreting the RM information.
Default : passed in from Producer (15000 for VBR with
bitrate greater than 450 kbps, otherwise 1352 or lower,
depending on bitrate)
calcPSNR
<calcPSNR type="bool">[true|false]</calcPSNR>
Enable or disable PSNR and other information being printed
in the rv9log.txt file
Default : false
enableRPR
<enableRPR type="bool">[true|false]</enableRPR>
Enable or disable the use of RPR (Reference Picture
Resampling) in the codec. Sometimes it may be desirable to
have the codec encode at the native resolution, no matter
how low the bitrate is. One good example is screen capture
video clips.
Default : true
enableAutoKeyFrames
<enableAutoKeyFrames type="bool">[true|false]</enableAutoKeyFrames>
Enable or disable the insertion of key frames at scene
changes. Since the encoder will have to re-encode the whole
frame, when it detects a scene change, this can be CPU
intensive for very high action sequences with frequent scene
changes.
Default : true, unless in Live mode under CPU duress.
noisyEdgeFilter
<noisyEdgeFilter type="bool">[true|false]</noisyEdgeFilter>
Enable or disable the noisy edge filter, i.e. the filter
that corrects single or double lines along the edge of the
video, resulting from bad capture or crop settings. The
noisy edge filter is bad for PSNR).
Default : true, unless calcPSNR is enabled.
useThreads
<useThreads type="bool">[true|false]</useThreads>
Enable or disable the use of threads in the encoder.
Default : use threads when more than one CPU, virtual or
real, is available.
writePreviewToFile
<writePreviewToFile type="string">filename</writePreviewToFile>
The encoder will save its reconstructed frames as
uncompressed I420. Will create and write an AVI file, if the
filename has .avi extension. This corresponds to the frames
shown in the "preview" window of the GUI RealProducer.
Default: off
exactPreview
<exactPreview type="bool">[true|false]</exactPreview>
Normally the encoder does not inloop B frames accurately,
since these are not used for future prediction. However,
with this option set to true, the frames will be inloop
deblocked just like the player/decoder will do.
Default: false
New Rate Control Options
rcEnableCurveCompression
<rcEnableCurveCompression type="bool">true</rcEnableCurveCompression>
Enables new curve compression based rate control This
disables all other RC modes, MSL and maxBitrate ignored
Still, include maxBitrate and MSL; needed for stream
properties
The new RC's goal is constant quality throughout the encode.
It works great at high bitrates, and is much more accurate
than the old rate control. For low bitrates, until more
advanced parameters are added, the old rate control, or an
external scaler is recommended. Specifically useful for low
bitrates would have been High bitrate scenes degradation (%)
and Low bitrate scenes improvement (%). These are not yet
implemented
Also, this constant quality is not the best solution for
highest overall or average PSNR. For my sample test clip, I
got a reduction of 0.3 dB average PSNR, but 6.5 dB better
minimum PSNR, corresponding to a huge visual improvement
When above params are added and used, this will help avg
PSNR
Other news about this RC, is that it allows 1st pass to be
run at the lowest possible complexity (50), with inloop
filter off This makes the 1st pass run even faster than
before
Since the analysis file is the same format as XviD uses, it
can be read, plotted, and analyzed with some of the same
tools. External scaler tools can be used as well Finally,
with this new RC, the 2nd pass can be re-run at different
target bitrates than the 1st pass.
WARNING: This rate control works only in 2-pass mode.
If you enable rcEnableCurveCompression, and run
a 1-pass encode, the encoder will run the 1st pass of
a 2-pass encode, and you will end up with a very large
output file. If you like, you can then run the 2nd
pass separately, using the rcPassNumber option below.
rcAnalysisFileName
<rcAnalysisFileName type="string">realvideo.pass</rcAnalysisFileName>
First pass analysis file, ASCII text, same format as XviD
This is possible, since all it contains are: frame types,
quants, MBs, frame sizes, (scalable and un-scalable part)
Can be read by XviD stats analysis tools, like this one :
http://atlas2.tgv.net/~media-video/forum2/viewtopic.php?t=3594
http://forum.doom9.org/showthread.php?s=&threadid=67639
An external scaler would add a last column (desired frame
size) The binary .stats format is not supported
rcLogFileName
<rcLogFileName type="string">realvideo.log</rcLogFileName>
Rate control log file from 2nd pass Useful only if problems
occur, and for the curious
rcTargetVideoSize
<rcTargetVideoSize type="uint">585728</rcTargetVideoSize>
Target filesize is kilobytes for /VIDEO ONLY/, over-rides
target bitrate If this option is used, rcSourceFrameRate is
not needed
rcKeyFrameBoost
<rcKeyFrameBoost type="uint">0</rcKeyFrameBoost>
Boost keyframes by rcKeyFrameBoost %
rcHighBitrateReduce
<rcHighBitrateReduce type="uint">0</rcHighBitrateReduce>
Reduce larger than average frames by rcHighBitrateReduce %
Usually good for average PSNR, and/or low/medium bitrate
streams, where the largest frames cost too many bits
compared to the PSNR achieved
rcLowBitrateBoost
<rcLowBitrateBoost type="uint">0</rcLowBitrateBoost>
Boost smaller than average frames by rcLowBitrateBoost %
rcPassNumber
<rcPassNumber type="uint">2</rcPassNumber>
Specify pass # to run, requires cmd line -dt or jobfile
enableTwoPass to 'false'. 2nd pass can be re-run with any
target bitrate changes, other parameters should be the same
When pass #1 is run by itself, Producer will appear to be
encoding normally, and also output a large RMVB, but it will
also output .pass file correctly.
Default: not used for 2-pass encodes.
Reference Quantizers
<rcPFrameRefQuant type="uint">6</rcPFrameRefQuant>
<rcBFrameRefQuant type="uint">10</rcBFrameRefQuant>
Quantizers to use for the 1st pass reference encoding Range
[0-30] Leave alone unless you know what you are doing Quants
do not correspond to MPEG-4 quants and do not scale the same
way either.
RC fine tuning
<rcOverFlowControlStrength type="uint">5</rcOverFlowControlStrength>
<rcMaxOverflowImprovement type="uint">50</rcMaxOverflowImprovement>
<rcMaxOverflowDegradation type="uint">50</rcMaxOverflowDegradation>
B Frames Control
maxConsecutiveBFrames
<maxConsecutiveBFrames type="uint">3</maxConsecutiveBFrames>
Leave B frame adaptivity ON, but sets the max number of B frames Only 3, 1, and
0 are allowed, due to current impl. restriction
Inloop filter options
inloopCutOffQuant
<inloopCutOffQuant type="uint">[0-30]</inloopCutOffQuant>
Inloop filter is turned off below this quant. Set to 0 to
always use inloop (this is the default, but in reality, the
default level is around 9 Set to 31, to completely disable
inloop postfilter When quant is below the threshold, the
encoder will skip the inloop filter, and put a bit in the
bitstream so the decoder will do the same. Use with caution
for low to medium bitrates. No inloop will lower PSNR as
well These quants do not correspond to MPEG-4 quants
Default: 0
inloopCutOffCompatible
<inloopCutOffCompatible type="bool">[true|false]</inloopCutOffCompatible>
Make bitstream 100% compatible with earlier*) decoders What
this means is that /key/frames will always be inloop
filtered with the default quant threshold. This is a bug in
old decoders, they always inloop filter keyframes. When set
to false, the threshold applies to all frame types. When an
old decoder tries to decode such a bitstream there will be a
very minor decoder mismatch, in most cases not visible. *:
RV8/9/10 decoders prior to RealPlayer 10 Gold
Default: false
inloopCutOffBUseRefQuant
<inloopCutOffBUseRefQuant type="bool">[true|false]</inloopCutOffBUseRefQuant>
If true, the threshold to enable the inloop filter for B
frames, will use the reference frame's quant. If false, the B
frame's quant is used.
Default: false
Inloop defaults for 'Sharp' setting in latest Producer
inloopCutOffQuant = 10
inloopCutOffCompatible = false
inloopCutOffBUseRefQuant = true