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

[Gyan Doshi]

On 2023-08-26 06:40 am, Stefano Sabatini wrote:
> 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}.

Allowed is implicit in the statement. Also, most statements of range 
don't contain allow so prefer to keep it consistent.

>   @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.

There is a difference, in that x264opts accepts boolean args without a 
value.

> +
> +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.

May want to make it clear that x264 refers to the standalone CLI tool.

Regards,
Gyan


> +
>   @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