[FFmpeg-devel] [PATCH] doc/encoder: (Almost a) Rewrite and reformat of libx264 doc

[Stefano Sabatini]

Subject nit: do not capitalize, also avoid weird formatting
doc/encoders: partially rewrite and reformat libx264 docs

On date Sunday 2013-07-14 14:55:54 -0700, Timothy Gu encoded:

> Formats are defined by ml thread "[PATCH] doc/encoders: Add libopus
> encoder doc"
> http://thread.gmane.org/gmane.comp.video.ffmpeg.devel/165368/

This is better referenced by mentioning the date of the thread, since
gmane addresses are not guaranteed to last forever.
 
> Also merged the two options section (Mapping and Private options).

merge

> ---
> 
> Will extend the reformatting to other codecs later.
> 
>  doc/encoders.texi | 319 +++++++++++++++++++++++++++++++++++-------------------
>  1 file changed, 206 insertions(+), 113 deletions(-)
> 
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index fb47586..bd65eba 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -887,164 +887,259 @@ that match those of the encoders and provides private options for the unique
>  encoder options. Additionally an expert override is provided to directly pass
>  a list of key=value tuples as accepted by x264_param_parse.
>  
> - at subsection Option Mapping
> + at subsection Options
>  
> -The following options are supported by the x264 wrapper, the x264-equivalent
> -options follow the FFmpeg ones.

> +The following options are supported by the @command{x264} wrapper. The

Note: I tend to favor the point of view of the library users, thus I'd
prefer "libx264 wrapper". This is also technically more correct, since
x264 the command makes use of libx264 the library.

> + at command{x264}-equivalent options or values are listed in parentheses for easy

> +migration. However, if their option or value names are the same, it is omitted.

The last sentence is confusing, what is "value names"? What is omitted?

> - at multitable @columnfractions .2 .2
> - at item b                 @tab bitrate
> -FFmpeg @code{b} option is expressed in bits/s, x264 @code{bitrate} in kilobits/s.
> - at item bf                @tab bframes
> -Maximum number of B-frames.
> - at item g                 @tab keyint
> -Maximum GOP size.
> - at item qmin              @tab qpmin
> - at item qmax              @tab qpmax
> - at item qdiff             @tab qpstep
> - at item qblur             @tab qblur
> - at item qcomp             @tab qcomp
> - at item refs              @tab ref
> - at item sc_threshold      @tab scenecut
> - at item trellis           @tab trellis
> - at item nr                @tab nr
> -Noise reduction.
> - at item me_range          @tab merange
> - at item me_method         @tab me
> - at item subq              @tab subme
> - at item b_strategy        @tab b-adapt
> - at item keyint_min        @tab keyint-min
> - at item coder             @tab cabac
> -Set coder to @code{ac} to use CABAC.
> - at item cmp               @tab chroma-me
> -Set to @code{chroma} to use chroma motion estimation.
> - at item threads           @tab threads
> - at item thread_type       @tab sliced_threads
> -Set to @code{slice} to use sliced threading instead of frame threading.
> - at item flags -cgop       @tab open-gop
> -Set @code{-cgop} to use recovery points to close GOPs.
> - at item rc_init_occupancy @tab vbv-init
> -Initial buffer occupancy.
> - at end multitable
> +To reduce the duplication of documentation, only the private options and some
> +others requiring special attention of this encoder is documented here. For the

requiring special attention are documented here


> +documentation of the undocumented options, please refer to the "Codec Options"

undocumented generic options, 

remove "please" since it adds no valuable information in this
context. Also since the section will always appear in the same manual,
you are authorized to use @ref to reference the section, and provide a
nice direct link to the mentioned section.

> +section earlier.


> +
> +For the most accurate and extensive documentation with argument formats, please
> +see the @command{x264} documentation by invoking @command{x264 --full-help}.

This sounds a bit awkward, what about:

To get a more accurate and extensive documentation of the libx264
options, invoke the command @command{...}.

>  
> - at subsection Private Options
>  @table @option
> - at item -preset @var{string}
> -Set the encoding preset (cf. x264 --fullhelp).
> - at item -tune @var{string}
> -Tune the encoding params (cf. x264 --fullhelp).
> - at item -profile @var{string}
> -Set profile restrictions (cf. x264 --fullhelp).
> - at item -fastfirstpass @var{integer}


> + at item b (@emph{bitrate})
> +FFmpeg's @option{b} option is expressed in bits/s, while @command{x264}'s
> + at option{bitrate} in kilobits/s.

Set bitrate ...

> +
> + at item bf (@emph{bframes})
> +
> + at item g (@emph{keyint})
> +
> + at item qmax (@emph{qpmax})
> +
> + at item qmin (@emph{qpmin})
> +
> + at item qdiff (@emph{qpstep})
> +
> + at item qblur
> +
> + at item qcomp
> +
> + at item refs (@emph{ref})
> +
> + at item sc_threshold (@emph{scenecut})
> +
> + at item trellis
> +
> + at item nr
> +
> + at item me_range (@emph{merange})
> +
> + at item me_method (@emph{me})
> +Set motion estimation method. Possible values in the

> +decreasingorder of speed:

itisnotallattached

> +
> + at table @samp
> + at item dia

> + at itemx epzs (@emph{dia})

Is @itemx properly supported by our renderers?


> +Diamond search, radius 1 (fastest). @samp{epzs} is an alias
> +for @samp{dia}.
> + at item hex
> +Hexagonal search, radius 2.
> + at item umh
> +Uneven multi-hexagon search.
> + at item esa
> +Exhaustive search.
> + at item tesa
> +Hadamard exhaustive search (slowest).
> + at end table
> +
> + at item subq (@emph{subme})
> +
> + at item b_strategy (@emph{b-adapt})
> +
> + at item keyint_min (@emph{min-keyint})
> +

> + at item coder (Opposite of @emph{no-cabac})

"opposite" is an overloaded term which should be avoided when you aim
at delivering an exact meaning.

> +Set entropy encoder. When set to @samp{ac}, CABAC is enabled.
> +
> + at item cmp (Opposite of @emph{no-chroma-me})

Same note on "opposite", you may add a separate entry for
no-chroma-me.

> +
> + at item threads
> +
> + at item thread_type (@emph{sliced_threads})
> +Set multithreading technique. Possible values:
> +
> + at table @samp
> + at item slice (@emph{sliced_threads})
> +Slice-based multithreading.
> + at item frame
> +Frame-based multithreading.
> + at end table
> +

> + at item flags (@emph{open-gop})
> +Set encoding flags. When set to @samp{-cgop}, closed GOP
> +is disabled and open GOP is used.

This is not an exact mapping, since flags is not the same as open-gop,
but flags -cgop is the same as open-gop 1. Thus you should mention
only the flags which are relevant for the x264 encoder (check
libtheora doc for an example).

> +
> + at item rc_init_occupancy (@emph{vbv-init})
> +
> + at item preset
> +Set the encoding preset.
> +
> + at item tune
> +Tune the encoding params.
> +
> + at item profile
> +Set profile restrictions.
> +
> + at item fastfirstpass (Opposite of @emph{slow-firstpass})
>  Use fast settings when encoding first pass.
> - at item -crf @var{float}
> +
> + at item crf
>  Select the quality for constant quality mode.
> - at item -crf_max @var{float}
> +
> + at item crf_max (@emph{crf-max})
>  In CRF mode, prevents VBV from lowering quality beyond this point.
> - at item -qp @var{integer}
> +
> + at item qp
>  Constant quantization parameter rate control method.
> - at item -aq-mode @var{integer}
> -AQ method
>  
> -Possible values:

> + at item aq-mode
> +AQ method. Possible values:

Set AQ

> +
>  @table @samp
> - at item none
> + at item none (@emph{0})
> +Disabled.
>  
> - at item variance
> + at item variance (@emph{1})
>  Variance AQ (complexity mask).
> - at item autovariance
> +
> + at item autovariance (@emph{2})
>  Auto-variance AQ (experimental).
> +
>  @end table
> - at item -aq-strength @var{float}
> +

> + at item aq-strength
>  AQ strength, reduces blocking and blurring in flat and textured areas.

Set 

here and below

> - at item -psy @var{integer}
> +
> + at item psy (Opposite of @emph{no-psy})
>  Use psychovisual optimizations.
> - at item -psy-rd @var{string}
> -Strength of psychovisual optimization, in <psy-rd>:<psy-trellis> format.
> - at item -rc-lookahead @var{integer}
> +
> + at item psy-rd
> +Strength of psychovisual optimization, in <@var{psy-rd}>:<@var{psy-trellis}> format.
> +
> + at item rc-lookahead
>  Number of frames to look ahead for frametype and ratecontrol.
> - at item -weightb @var{integer}
> +
> + at item weightb (Opposite of @{no-weightb})
>  Weighted prediction for B-frames.
> - at item -weightp @var{integer}
> -Weighted prediction analysis method.
>  
> -Possible values:
> - at table @samp
> - at item none
> + at item weightp
> +Weighted prediction for P-frames. Possible values:
>  
> + at table @samp
> + at item none (@emph{0})
> +Disabled
>  @item simple
> -
> +Enable only weighted refs
>  @item smart
> -
> +Enable both weighted refs and duplicates
>  @end table
> - at item -ssim @var{integer}
> +
> + at item ssim
>  Calculate and print SSIM stats.
> - at item -intra-refresh @var{integer}
> +
> + at item intra-refresh
>  Use Periodic Intra Refresh instead of IDR frames.
> - at item -b-bias @var{integer}
> +
> + at item b-bias
>  Influences how often B-frames are used.
> - at item -b-pyramid @var{integer}
> -Keep some B-frames as references.
>  
> -Possible values:
> + at item b-pyramid
> +Keep some B-frames as references. Possible values:
> +
>  @table @samp
>  @item none
> -
> +Disabled.
>  @item strict
>  Strictly hierarchical pyramid.
>  @item normal
>  Non-strict (not Blu-ray compatible).
>  @end table
> - at item -mixed-refs @var{integer}
> +
> + at item mixed-refs (Opposite of @emph{no-mixed-refs})
>  One reference per partition, as opposed to one reference per macroblock.
> - at item -8x8dct @var{integer}
> -High profile 8x8 transform.
> - at item -fast-pskip @var{integer}
> - at item -aud @var{integer}
> -Use access unit delimiters.
> - at item -mbtree @var{integer}
> -Use macroblock tree ratecontrol.
> - at item -deblock @var{string}
> -Loop filter parameters, in <alpha:beta> form.
> - at item -cplxblur @var{float}
> -Reduce fluctuations in QP (before curve compression).
> - at item -partitions @var{string}
> -A comma-separated list of partitions to consider, possible values: p8x8, p4x4, b8x8, i8x8, i4x4, none, all.
> - at item -direct-pred @var{integer}
> -Direct MV prediction mode
>  
> -Possible values:
> + at item 8x8dct (Opposite of @emph{no-8x8dct})
> +Enable adaptive spatial transform (high profile 8x8 transform)
> +when set to 1.
> +
> + at item fast-pskip (Opposite of @emph{no-fast-pskip})
> +Enable early SKIP detection on P-frames when set to 1.
> +
> + at item aud
> +Enable use of access unit delimiters when set to 1.
> +
> + at item mbtree (Opposite of @emph{no-mbtree})
> +Enable use macroblock tree ratecontrol when set to 1.
> +
> + at item deblock
> +Set loop filter parameters, in <@var{alpha}:@var{beta}> form.
> +
> + at item cplxblur
> +Set fluctuations reduction in QP (before curve compression).
> +
> + at item partitions
> +A comma-separated list of partitions to consider. Possible values:
> +
>  @table @samp
> + at item p8x8
> + at item p4x4
> + at item b8x8
> + at item i8x8
> + at item i4x4
> +(Enabling @samp{p4x4} requires @samp{p8x8} to be enabled. Enabling
> + at samp{i8x8} requires adaptive spatial transform (@option{8x8dct})
> +to be enabled.)
>  @item none
> +Do not consider any partitions.
> + at item all
> +Consider every partition.
> + at end table
>  
> - at item spatial
> + at item direct-pred (@emph{direct})
> +Direct MV prediction mode. Possible values:
>  
> + at table @samp
> + at item none
> +Disable MV prediction.
> + at item spatial
> +Enable spatial predicting.
>  @item temporal
> -
> +Enable temporal predicting.
>  @item auto
> -
> +Automatically decided.
>  @end table
> - at item -slice-max-size @var{integer}
> -Limit the size of each slice in bytes.
> - at item -stats @var{string}
> -Filename for 2 pass stats.
> - at item -nal-hrd @var{integer}
> -Signal HRD information (requires vbv-bufsize; cbr not allowed in .mp4).
>  
> + at item slice-max-size
> +Set the limit of the size of each slice in bytes. If not specified
> +but RTP payload size (@option{ps}) is specified, that is used.
> +
> + at item stats
> +Set the file name for multi-pass stats.
> +
> + at item nal-hrd
> +Set signal HRD information (requires @option{vbv-bufsize} to be set).
>  Possible values:
> +
>  @table @samp
>  @item none
> -
> +Disable HRD information signaling.
>  @item vbr
> -
> +Variable bit rate.
>  @item cbr
> -
> +Constant bit rate (not allowed in MP4 container).
>  @end table
>  
> - at item x264opts @var{options}
> -Allow to set any x264 option, see @code{x264 --fullhelp} for a list.
> + at item x264opts (N.A.)
> +Set any x264 option, see @command{x264 --fullhelp} for a list.
>  
> - at var{options} is a list of @var{key}=@var{value} couples separated by
> +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.
> @@ -1054,18 +1149,16 @@ For example to specify libx264 encoding options with @command{ffmpeg}:
>  ffmpeg -i foo.mpg -vcodec libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
>  @end example
>  

> -For more information about libx264 and the supported options see:
> - at url{http://www.videolan.org/developers/x264.html}
> -

why did you remove this?

> - at item -x264-params @var{string}
> + at item x264-params (N.A.)
>  Override the x264 configuration using a :-separated list of key=value parameters.
>  @example
> --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
> +ffmpeg -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
>  @end example
>  @end table
>  
> -Encoding avpresets for common usages are provided so they can be used with the
> -general presets system (e.g. passing the @code{-pre} option).
> +Encoding ffpresets for common usages are provided so they can be used with the
> +general presets system (e.g. passing the @option{pre} option).

-- 
FFmpeg = Fundamental and Fascinating Multimedia Portable Evil Ghost