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

[Timothy Gu]

On Jul 16, 2013 11:17 AM, "Stefano Sabatini" <stefasab at gmail.com> wrote:
>
> Subject nit: do not capitalize, also avoid weird formatting
> doc/encoders: partially rewrite and reformat libx264 docs

OK

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

OK.

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

OK

>
> > + 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 her
>
>
> > +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?

I'll change it to @item

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

What do you suggest then?

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

I already said this in the beginning.

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

Will post the new patch later.

Timothy