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

[Stefano Sabatini]

On date Friday 2013-06-28 16:46:21 -0700, Timothy Gu encoded:
> ---
>  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}

I would avoid the @columnfractions MAGIC altogether, which has a poor
rendering in the HTML output (and thus I'd avoid it in
libmp3lame/lib264 docs as well).

What I suggest instead:
@item b (bitrate)

or if you prefer:
@item b (@emph{bitrate})

adopting the KISS principle.


> + at tab Comments
> +
> + at item @option{b}                 @tab @option{bitrate}

@item b ...

should be more consistent with the rest of the docs (check also HTML
output)

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

Simpler:

Set the bit rate in bits/s.  FFmpeg's @option{b} option is expressed
in bits/s, while @command{opusenc}'s @option{bitrate} in
kilobits/s.

> The default value in both encoders are
> +the same, which is 64k per mono stream, 96k per coupled pair.

I'd avoid this part, since this will result in wrong docs in case
either is updated (and I bet this will happen).

> +

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

Please stick either with "FFmpeg" or "libavcodec".

> +parentheses:
> +
> + at table @samp
> + at item off
> +(hard-cbr) Use constant bit rate encoding.


I'd put them on the same line: 
@item off (hard-cbr)

same below

> + at item on
> +(vbr) Use variable bit rate encoding (the default).
> + at item constrained
> +(cvbr) Use constrained variable bit rate encoding.
> + at end table
> +
> + at item @option{compression_level} @tab @option{comp}

> + at tab Set encoding algorithm complexity. Valid options are integers from 0-10.

integers in the 0-10 range.

[...]
-- 
FFmpeg = Furious and Fostering Mournful Pacific Empowered God