[FFmpeg-devel] [PATCH] encoders.texi: update libvpx documentation

Stefano Sabatini stefasab at gmail.com
Fri Jun 12 14:58:31 CEST 2015


On date Wednesday 2015-06-10 20:58:33 -0700, James Zern encoded:
> modeled after the libx264 section.
> ---
>  doc/encoders.texi | 163 ++++++++++++++++++++++++++++++------------------------
>  1 file changed, 92 insertions(+), 71 deletions(-)
> 
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 753e683..e0ad13e 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -1416,113 +1416,134 @@ You need to explicitly configure the build with @code{--enable-libvpx}.
>  
>  @subsection Options
>  
> -Mapping from FFmpeg to libvpx options with conversion notes in parentheses.
> +The following options are supported by the libvpx wrapper. The
> + at command{vpxenc}-equivalent options or values are listed in parentheses
> +for easy migration.
>  
> - at table @option
> +To reduce the duplication of documentation, only the private options
> +and some others requiring special attention are documented here. For
> +the documentation of the undocumented generic options, see
> + at ref{codec-options,,the Codec Options chapter}.
>  
> - at item threads
> -g_threads

> +To get more documentation of the libvpx options, invoke the command
> + at command{ffmpeg -h encoder=libvpx}, @command{ffmpeg -h encoder=libvpx-vp9} or
> + at command{vpxenc --help}. Further information is available in the libvpx API
> +documentation.
>  
> - at item profile
> -g_profile
> + at table @option
>  
> - at item vb
> -rc_target_bitrate
> + at item b (@emph{target-bitrate})
> +Set bitrate in bits/s. Note that FFmpeg's @option{b} option is
> +expressed in bits/s, while @command{vpxenc}'s @option{target-bitrate} is in
> +kilobits/s.
>  
> - at item g
> -kf_max_dist
> + at item g (@emph{kf-max-dist})
>  
> - at item keyint_min
> -kf_min_dist
> + at item keyint_min (@emph{kf-min-dist})
>  
> - at item qmin
> -rc_min_quantizer
> + at item qmin (@emph{min-q})
>  
> - at item qmax
> -rc_max_quantizer
> + at item qmax (@emph{max-q})
>  
> - at item bufsize, vb
> -rc_buf_sz
> - at code{(bufsize * 1000 / vb)}
> + at item bufsize (@emph{buf-sz}, @emph{buf-optimal-sz})
> +Set ratecontrol buffer size (in bits). Note @command{vpxenc}'s options are
> +specified in milliseconds, the libvpx wrapper converts this value as follows:
> + at code{buf-sz = bufsize * 1000 / bitrate},
> + at code{buf-optimal-sz = bufsize * 1000 / bitrate * 5 / 6}.
>  
> -rc_buf_optimal_sz
> - at code{(bufsize * 1000 / vb * 5 / 6)}
> + at item rc_init_occupancy (@emph{buf-initial-sz})
> +Set number of bits which should be loaded into the rc buffer before decoding
> +starts. Note @command{vpxenc}'s option is specified in milliseconds, the libvpx
> +wrapper converts this value as follows:
> + at code{rc_init_occupancy * 1000 / bitrate}.
>  
> - at item rc_init_occupancy, vb
> -rc_buf_initial_sz
> - at code{(rc_init_occupancy * 1000 / vb)}
> + at item undershoot-pct
> +Datarate undershoot (min) percentage of the target bitrate.
>  
> - at item rc_buffer_aggressivity
> -rc_undershoot_pct
> + at item overshoot-pct
> +Datarate overshoot (max) percentage of the target bitrate.
>  
> - at item skip_threshold
> -rc_dropframe_thresh
> + at item skip_threshold (@emph{drop-frame})
>  
> - at item qcomp
> -rc_2pass_vbr_bias_pct
> + at item qcomp (@emph{bias-pct})
>  
> - at item maxrate, vb
> -rc_2pass_vbr_maxsection_pct
> - at code{(maxrate * 100 / vb)}
> + at item maxrate (@emph{maxsection-pct})
> +GOP max bitrate in bits/s. Note @command{vpxenc}'s option is specified as a
> +percentage of the target bitrate, the libvpx wrapper converts this value as
> +follows: @code{(maxrate * 100 / bitrate)}.
>  
> - at item minrate, vb
> -rc_2pass_vbr_minsection_pct
> - at code{(minrate * 100 / vb)}
> + at item minrate (@emph{minsection-pct})
> +GOP min bitrate in bits/s. Note @command{vpxenc}'s option is specified as a
> +percentage of the target bitrate, the libvpx wrapper converts this value as
> +follows: @code{(minrate * 100 / bitrate)}.
>  
> - at item minrate, maxrate, vb
> - at code{VPX_CBR}
> - at code{(minrate == maxrate == vb)}
> + at item minrate, maxrate, b @emph{end-usage=cbr}
> + at code{(minrate == maxrate == bitrate)}.
>  
> - at item crf
> - at code{VPX_CQ}, @code{VP8E_SET_CQ_LEVEL}
> + at item crf (@emph{end-usage=cq}, @emph{cq-level})
>  
> - at item quality
> + at item quality, deadline (@emph{deadline})
>  @table @option
>  @item @var{best}
> - at code{VPX_DL_BEST_QUALITY}
> +Use best quality deadline. Poorly named and quite slow, this option should be
> +avoided as it may give worse quality output than good.
>  @item @var{good}
> - at code{VPX_DL_GOOD_QUALITY}
> +Use good quality deadline. This is a good trade-off between speed and quality
> +when used with the @option{cpu-used} option.
>  @item @var{realtime}
> - at code{VPX_DL_REALTIME}
> +Use realtime quality deadline.
>  @end table
>  
> - at item speed
> - at code{VP8E_SET_CPUUSED}
> + at item speed, cpu-used (@emph{cpu-used})

> +Quality/Speed ratio modifier.

Nit: Set quality/speed ...

In general, a verbal form is favored ("Set number of foos in the bar.",
rather than "number of foos in the bar").

>  
> - at item nr
> - at code{VP8E_SET_NOISE_SENSITIVITY}
> + at item nr (@emph{noise-sensitivity})
>  
> - at item mb_threshold
> - at code{VP8E_SET_STATIC_THRESHOLD}
> + at item static-thresh

> +A change threshold on blocks below which they will be skipped by the encoder.

Nit: Set a change threshold ...


> - at item slices
> - at code{VP8E_SET_TOKEN_PARTITIONS}
> + at item slices (@emph{token-parts})
> +Note that FFmpeg's @option{slices} option gives the total number of partitions,
> +while @command{vpxenc}'s @option{token-parts} is given as
> + at code{log2(partitions)}.
>  
>  @item max-intra-rate
> - at code{VP8E_SET_MAX_INTRA_BITRATE_PCT}
> +Maximum I-frame bitrate (pct) 0=unlimited.

Set maximum ...

Also
Maximum I-frame bitrate (pct) 0=unlimited.
is not a meaningful English sentence, add something like:

A value of 0 means unlimited.

(I don't know what "pct" is).

>  
>  @item force_key_frames
>  @code{VPX_EFLAG_FORCE_KF}
>  
>  @item Alternate reference frame related
>  @table @option
> - at item vp8flags altref
> - at code{VP8E_SET_ENABLEAUTOALTREF}
> - at item @var{arnr_max_frames}
> - at code{VP8E_SET_ARNR_MAXFRAMES}
> - at item @var{arnr_type}
> - at code{VP8E_SET_ARNR_TYPE}
> - at item @var{arnr_strength}
> - at code{VP8E_SET_ARNR_STRENGTH}
> - at item @var{rc_lookahead}
> -g_lag_in_frames
> - at end table
> -
> - at item vp8flags error_resilient
> -g_error_resilient
> -
> - at item aq_mode
> - at code{VP9E_SET_AQ_MODE}
> + at item auto-alt-ref
> +Enable use of alternate reference frames (2-pass only).

> + at item arnr-max-frames
> +altref noise reduction max frame count.

Set altref ...

> + at item arnr-type
> +altref noise reduction filter type: backward, forward, centered.

Set altref ...

> + at item arnr-strength
> +altref noise reduction filter strength.

Set altref ...

> + at item rc-lookahead, lag-in-frames (@emph{lag-in-frames})
> +Set number of frames to look ahead for frametype and ratecontrol.
> + at end table
> +
> + at item error-resilient
> +Enable error resiliency features.
> +
> + at item VP9-specific options
> + at table @option

> + at item lossless
> +Lossless mode.

Set lossless mode?

> + at item tile-columns
> +Number of tile columns to use, log2.

Set number of tile columns to use. What "log2" means in this context?

> + at item tile-rows
> +Number of tile rows to use, log2.

Ditto

> + at item frame-parallel
> +Enable frame parallel decodability features.
> + at item aq-mode

> +Adaptive quantization mode (0: off (default), 1: variance 2: complexity, 3:
> +cyclic refresh).

Set adaptive ...

LGTM otherwise, thanks.
-- 
FFmpeg = Friendly and Forgiving Multimedia Pitiless Easy Gymnast


More information about the ffmpeg-devel mailing list