[FFmpeg-devel] [PATCH 1/3] doc/encoders/libx264: review and extend option description

[Stefano Sabatini]

Also, merge x264opts and x264-opts option docs to avoid duplication
and make it even more clearer they provide the same functionality.
---
 doc/encoders.texi | 66 ++++++++++++++++++++++++++---------------------
 1 file changed, 37 insertions(+), 29 deletions(-)

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 6f8f5e127e..947b0c3320 100644
--- a/doc/encoders.texi
+++ b/doc/encoders.texi
@@ -2418,6 +2418,10 @@ To get a more accurate and extensive documentation of the libx264
 options, invoke the command @command{x264 --fullhelp} or consult
 the libx264 documentation.
 
+In the list below, note that the @command{x264} option name is shown
+in parentheses after the libavcodec corresponding name, in case there
+is a direct mapping.
+
 @table @option
 @item b (@emph{bitrate})
 Set bitrate in bits/s. Note that FFmpeg's @option{b} option is
@@ -2425,17 +2429,19 @@ expressed in bits/s, while @command{x264}'s @option{bitrate} is in
 kilobits/s.
 
 @item bf (@emph{bframes})
+Number of B-frames between I and P-frames
 
 @item g (@emph{keyint})
+Maximum GOP size
 
 @item qmin (@emph{qpmin})
-Minimum quantizer scale.
+Minimum quantizer scale
 
 @item qmax (@emph{qpmax})
-Maximum quantizer scale.
+Maximum quantizer scale
 
 @item qdiff (@emph{qpstep})
-Maximum difference between quantizer scales.
+Maximum difference between quantizer scales
 
 @item qblur (@emph{qblur})
 Quantizer curve blur
@@ -2444,7 +2450,7 @@ Quantizer curve blur
 Quantizer curve compression factor
 
 @item refs (@emph{ref})
-Number of reference frames each P-frame can use. The range is from @var{0-16}.
+Number of reference frames each P-frame can use. The allowed range is @var{0-16}.
 
 @item sc_threshold (@emph{scenecut})
 Sets the threshold for the scene change detection.
@@ -2452,7 +2458,8 @@ Sets the threshold for the scene change detection.
 @item trellis (@emph{trellis})
 Performs Trellis quantization to increase efficiency. Enabled by default.
 
- at item nr  (@emph{nr})
+ at item nr (@emph{nr})
+Noise reduction
 
 @item me_range (@emph{merange})
 Maximum range of the motion search in pixels.
@@ -2533,6 +2540,7 @@ open GOP by setting it to @code{-cgop}. The result is similar to
 the behavior of @command{x264}'s @option{--open-gop} option.
 
 @item rc_init_occupancy (@emph{vbv-init})
+Initial VBV buffer occupancy
 
 @item preset (@emph{preset})
 Set the encoding preset.
@@ -2578,7 +2586,7 @@ Set AQ strength, reduce blocking and blurring in flat and textured areas.
 Use psychovisual optimizations when set to 1. When set to 0, it has the
 same effect as @command{x264}'s @option{--no-psy} option.
 
- at item psy-rd  (@emph{psy-rd})
+ at item psy-rd (@emph{psy-rd})
 Set strength of psychovisual optimization, in
 @var{psy-rd}:@var{psy-trellis} format.
 
@@ -2610,7 +2618,7 @@ to 1.
 
 @item avcintra-class (@emph{class})
 Configure the encoder to generate AVC-Intra.
-Valid values are 50,100 and 200
+Valid values are 50, 100 and 200
 
 @item bluray-compat (@emph{bluray-compat})
 Configure the encoder to be compatible with the bluray standard.
@@ -2661,8 +2669,8 @@ Set loop filter parameters, in @var{alpha}:@var{beta} form.
 Set fluctuations reduction in QP (before curve compression).
 
 @item partitions (@emph{partitions})
-Set partitions to consider as a comma-separated list of. Possible
-values in the list:
+Set partitions to consider as a comma-separated list of
+values. Possible values in the list:
 
 @table @samp
 @item p8x8
@@ -2718,19 +2726,33 @@ Variable bit rate.
 Constant bit rate (not allowed in MP4 container).
 @end table
 
- at item x264opts (N.A.)
-Set any x264 option, see @command{x264 --fullhelp} for a list.
+ at item x264opts @var{opts}
+ at item x264-params @var{opts}
+Override the x264 configuration using a :-separated list of key=value
+options.
 
-Argument is a list of @var{key}=@var{value} couples separated by
-":". In @var{filter} and @var{psy-rd} options that use ":" as a separator
-themselves, use "," instead. They accept it as well since long ago but this
-is kept undocumented for some reason.
+ at option{x264-param} is functionally the same as the @option{x264opts},
+but is duplicated for compatibility with the Libav fork.
+
+The argument for both options is a list of @var{key}=@var{value}
+couples separated by ":". In @var{filter} and @var{psy-rd} options
+that use ":" as a separator themselves, use "," instead. They accept
+it as well since long ago but this is kept undocumented for some
+reason.
+
+For example, the options might be provided as:
+ at example
+level=30:bframes=0:weightp=0:cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:no-fast-pskip=1:subq=6:8x8dct=0:trellis=0
+ at end example
 
 For example to specify libx264 encoding options with @command{ffmpeg}:
 @example
 ffmpeg -i foo.mpg -c:v libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
 @end example
 
+To get the complete list of the libx264 options, invoke the command
+ at command{x264 --fullhelp} or consult the libx264 documentation.
+
 @item a53cc @var{boolean}
 Import closed captions (which must be ATSC compatible format) into output.
 Only the mpeg2 and h264 decoders provide these. Default is 1 (on).
@@ -2741,20 +2763,6 @@ Import user data unregistered SEI if available into output. Default is 0 (off).
 @item mb_info @var{boolean}
 Set mb_info data through AVFrameSideData, only useful when used from the
 API. Default is 0 (off).
-
- at item x264-params (N.A.)
-Override the x264 configuration using a :-separated list of key=value
-parameters.
-
-This option is functionally the same as the @option{x264opts}, but is
-duplicated for compatibility with the Libav fork.
-
-For example to specify libx264 encoding options with @command{ffmpeg}:
- at example
-ffmpeg -i INPUT -c:v libx264 -x264-params level=30:bframes=0:weightp=0:\
-cabac=0:ref=1:vbv-maxrate=768:vbv-bufsize=2000:analyse=all:me=umh:\
-no-fast-pskip=1:subq=6:8x8dct=0:trellis=0 OUTPUT
- at end example
 @end table
 
 Encoding ffpresets for common usages are provided so they can be used with the
-- 
2.34.1