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

[Timothy Gu]

---
 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
+
+ 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
+
+ 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
+disabled).
+ at end multitable
+
 @c man end AUDIO ENCODERS
 
 @chapter Video Encoders
-- 
1.8.1.2