[FFmpeg-devel] [PATCH] doc/encoders: Add libopus encoder doc

[Timothy Gu]

On Fri, Jun 28, 2013 at 4:46 PM, Timothy Gu <timothygu99 at gmail.com> wrote:
> ---
>  doc/encoders.texi | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 74 insertions(+)
>
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 7da6376..c3db780 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -629,6 +629,80 @@ Same as 3, but with extra processing enabled - corresponding to the wavpack
>
>  @end table
>
> + at section libopus
> +
> +libopus Opus Interactive Audio Codec encoder wrapper.
> +
> +Requires the presence of the libopus headers and library during
> +configuration. You need to explicitly configure the build with
> + at code{--enable-libopus}.
> +
> + at subsection Option Mapping
> +
> +Most libopus options are modeled after the @command{opusenc} utility from
> +opus-tools. The following is an option mapping chart describing options
> +supported by the libopus wrapper, and their @command{opusenc}-equivalent.
> +
> + at multitable @columnfractions .15 .15 .7
> + at headitem FFmpeg                 @tab @command{opusenc}
> + at tab Comments

I used another approach for option mapping formatting here. If you
don't like it, then I'll use the libmp3lame-style. If you like it,
then I can submit a patch to change everything into this style.

> +
> + at item @option{b}                 @tab @option{bitrate}
> + at tab Set the bit rate in bits/s. One thing to note is that FFmpeg's
> + at option{b} option is expressed in bits/s, while @command{opusenc}'s
> + at option{bitrate} in kilobits/s. The default value in both encoders are
> +the same, which is 64k per mono stream, 96k per coupled pair.
> +
> + at item @option{vbr}               @tab @option{vbr}, @option{hard-cbr}, and @option{cvbr}
> + at tab Set VBR mode. The libavcodec @option{vbr} option has the following
> +valid arguments, with the their @command{opusenc} equivalent in
> +parentheses:
> +
> + at table @samp
> + at item off
> +(hard-cbr) Use constant bit rate encoding.
> + at item on
> +(vbr) Use variable bit rate encoding (the default).
> + at item constrained
> +(cvbr) Use constrained variable bit rate encoding.
> + at end table

Same here, experimental formatting approach.

> +
> + at item @option{compression_level} @tab @option{comp}
> + at tab Set encoding algorithm complexity. Valid options are integers from 0-10.
> +0 gives the fastest encodes but lower quality, while 10 gives the
> +highest quality but slowest encoding. The default is 10.
> +
> + at item @option{frame_duration}    @tab @option{framesize}
> + at tab Set maximum frame size, or duration of a frame in milliseconds. The
> +argument must be exactly the following: 2.5, 5, 10, 20, 40, 60. Smaller
> +frame sizes achieve lower latency but less quality at a given bitrate.
> +Sizes greater than 20ms are only interesting at fairly low bitrates.
> +The default of FFmpeg is 10ms, but is 20ms in @command{opusenc}.
> +
> + at item @option{packet_loss}       @tab @option{expect-loss}
> + at tab Set expected packet loss percentage. The default is 0.
> +
> + at item @option{application}       @tab N.A.
> + at tab Set intended application type. Valid options are listed below:
> +
> + at table @samp
> + at item voip
> +Favor improved speech intelligibility.
> + at item audio
> +Favor faithfulness to the input (the default).
> + at item lowdelay
> +Restrict to only the lowest delay modes.
> + at end table
> +
> + at item @option{cutoff}            @tab N.A.
> + at tab Set cutoff bandwidth in Hz. The argument must be exactly one of the
> +following: 4000, 6000, 8000, 12000, or 20000, corresponding to
> + at code{OPUS_@/BANDWIDTH_@/NARROWBAND}, @code{OPUS_@/BANDWIDTH_@/MEDIUMBAND},
> + at code{OPUS_@/BANDWIDTH_@/WIDEBAND}, @code{OPUS_@/BANDWIDTH_@/SUPERWIDEBAND},
> +and @code{OPUS_@/BANDWIDTH_@/FULLBAND} respectively. The default is 0 (cutoff

I don't have a better idea here as to how to show the band things. If
you don't think this is necessary, then I'll delete it.

> +disabled).
> + at end multitable
> +
>  @c man end AUDIO ENCODERS
>
>  @chapter Video Encoders
> --
> 1.8.1.2
>