[FFmpeg-devel] [PATCH] doc/encoder: particially rewrite and reformat libx264 docs

[Timothy Gu]

Formats are defined by ml thread "[PATCH] doc/encoders: Add libopus
encoder doc" (06-28-2013)
http://thread.gmane.org/gmane.comp.video.ffmpeg.devel/165368/

Also merge the two options section (Mapping and Private options).
---
 doc/encoders.texi | 382 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 257 insertions(+), 125 deletions(-)

diff --git a/doc/encoders.texi b/doc/encoders.texi
index fb47586..aa3dfc8 100644
--- a/doc/encoders.texi
+++ b/doc/encoders.texi
@@ -885,166 +885,300 @@ interlacing (MBAFF), lossless mode, psy optimizations for detail retention
 The FFmpeg wrapper provides a mapping for most of them using global options
 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.
+a list of key=value tuples as accepted by @code{x264_param_parse} function.
 
- 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 @code{libx264} wrapper. The
+ at command{x264}-equivalent options or values are listed in parentheses for easy
+migration. However, if their option or argument names are the same, the
+ at command{x264}-equivalent options are 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 are documented here. For the
+documentation of the undocumented generic options, @ref{Codec Options}.
+
+To get a more accurate and extensive documentation of the libx264 options,
+for example default behaviors, invoke the command @samp{x264 --full-help}.
 
- 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}
-Use fast settings when encoding first pass.
- at item -crf @var{float}
-Select the quality for constant quality mode.
- at item -crf_max @var{float}
-In CRF mode, prevents VBV from lowering quality beyond this point.
- at item -qp @var{integer}
-Constant quantization parameter rate control method.
- at item -aq-mode @var{integer}
-AQ method
+ at item b (@emph{bitrate})
+Set bitrate in bits/s. Note that FFmpeg's @option{b} option is expressed in
+bits/s, while @command{x264}'s @option{bitrate} in kilobits/s.
+
+ 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
+decreasing order of speed:
+
+ at table @samp
+ at item dia
+ at item epzs (@emph{dia})
+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 (See below)
+Set entropy encoder. Possible values:
+
+ at table @samp
+ at item ac
+Enable CABAC.
+
+ at item vlc (Or everything else)
+Enable CAVLC and disable CABAC. It generates the same
+effect as @command{x264}'s @emph{--no-cabac} option.
+ at end table
+
+ at item cmp (See below)
+Set full pixel motion estimation comparation algorithm.
 Possible values:
+
 @table @samp
- at item none
+ at item chroma
+Enable chroma in motion estimation.
+
+ at item sad (Or everything else)
+Ignore chroma in motion estimation. It generates the same
+effect as @command{x264}'s @emph{--no-chroma-me} option.
+ at end table
+
+ 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 (See below)
+Set encoding flags. It can be used to disable closed GOP and
+enable open GOP by setting it to @samp{-cgop}. The result is
+similar to the behavior of @command{x264}'s @emph{--open-gop}
+option.
+
+ at item rc_init_occupancy (@emph{vbv-init})
+
+ at item preset
+Set the encoding preset.
+
+ at item tune
+Set tuning of the encoding params.
+
+ at item profile
+Set profile restrictions.
+
+ at item fastfirstpass (See below)
+Enable fast settings when encoding first pass, when set to 1.
+When set to 0, it has the same effect of @command{x264}'s
+ at emph{--slow-firstpass} option.
 
- at item variance
+ at item crf
+Set the quality for constant quality mode.
+
+ at item crf_max (@emph{crf-max})
+In CRF mode, prevents VBV from lowering quality beyond this point.
+
+ at item qp
+Set constant quantization rate control method parameter.
+
+ at item aq-mode
+Set AQ method. Possible values:
+
+ at table @samp
+ at item none (@emph{0})
+Disabled.
+
+ 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}
-AQ strength, reduces blocking and blurring in flat and textured areas.
- at item -psy @var{integer}
-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}
-Number of frames to look ahead for frametype and ratecontrol.
- at item -weightb @var{integer}
-Weighted prediction for B-frames.
- at item -weightp @var{integer}
-Weighted prediction analysis method.
 
-Possible values:
- at table @samp
- at item none
+ at item aq-strength
+Set AQ strength, reduces blocking and blurring in flat and textured areas.
 
- at item simple
+ at item psy (See below)
+Use psychovisual optimizations when set to 1. When set to 0, it has the
+same effect as @command{x264}'s @emph{--no-psy} option.
 
- at item smart
+ at item psy-rd
+Set strength of psychovisual optimization, in
+<@var{psy-rd}>:<@var{psy-trellis}> format.
+
+ at item rc-lookahead
+Set number of frames to look ahead for frametype and ratecontrol.
+
+ at item weightb (See below)
+Enable weighted prediction for B-frames when set to 1. When set to 0,
+it has the same effect as @command{x264}'s @emph{--no-weightb} option.
 
+ at item weightp
+Set weighted prediction method for P-frames. Possible values:
+
+ at table @samp
+ at item none (@emph{0})
+Disabled
+ at item simple
+Enable only weighted refs
+ at item smart
+Enable both weighted refs and duplicates
 @end table
- at item -ssim @var{integer}
-Calculate and print SSIM stats.
- at item -intra-refresh @var{integer}
-Use Periodic Intra Refresh instead of IDR frames.
- at item -b-bias @var{integer}
-Influences how often B-frames are used.
- at item -b-pyramid @var{integer}
-Keep some B-frames as references.
 
-Possible values:
+ at item ssim
+Enable calculation and printing SSIM stats after the encoding.
+
+ at item intra-refresh
+Enable the use of Periodic Intra Refresh instead of IDR frames.
+
+ at item b-bias
+Set the influence on how often B-frames are used.
+
+ at item b-pyramid
+Set method for keeping of 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}
-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 mixed-refs (See below)
+Enable the use of one reference per partition, as opposed to one
+reference per macroblock when set to 1. When set to 0, it has the
+same effect as @command{x264}'s @emph{--no-mixed-refs} option.
+
+ at item 8x8dct (See below)
+Enable adaptive spatial transform (high profile 8x8 transform)
+when set to 1. When set to 0, it has the same effect as
+ at command{x264}'s @emph{--no-8x8dct} option.
+
+ at item fast-pskip (See below)
+Enable early SKIP detection on P-frames when set to 1. When set
+to 0, it has the same effect as @command{x264}'s
+ at emph{--no-fast-pskip} option.
+
+ at item aud
+Enable use of access unit delimiters when set to 1.
+
+ at item mbtree (See below)
+Enable use macroblock tree ratecontrol when set to 1. When set
+to 0, it has the same effect as @command{x264}'s
+ at emph{--no-mbtree} option.
+
+ 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
+Set partitions to consider as a comma-separated list of. Possible
+values in the list:
+
 @table @samp
+ at item p8x8
+8x8 P-frame partition.
+ at item p4x4
+4x4 P-frame partition.
+ at item b8x8
+4x4 B-frame partition.
+ at item i8x8
+8x8 I-frame partition.
+ at item i4x4
+4x4 I-frame partition.
+(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})
+Set 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 +1188,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}
-
- 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).
 
 @section png
 
-- 
1.8.1.2