[FFmpeg-devel] [PATCH] doc/encoders: extend/clarify libtheora encoder documentation

[Stefano Sabatini]

---
 doc/encoders.texi | 52 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 38 insertions(+), 14 deletions(-)

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 7d54dae..550f229 100644
--- a/doc/encoders.texi
+++ b/doc/encoders.texi
@@ -1177,12 +1177,15 @@ follows.
 
 @section libtheora
 
-Theora format supported through libtheora.
+libtheora Theora encoder wrapper.
 
 Requires the presence of the libtheora headers and library during
 configuration. You need to explicitly configure the build with
 @code{--enable-libtheora}.
 
+For more informations about the libtheora project see
+ at url{http://www.theora.org/}.
+
 @subsection Options
 
 The following global options are mapped to internal libtheora options
@@ -1190,30 +1193,51 @@ which affect the quality and the bitrate of the encoded stream.
 
 @table @option
 @item b
-Set the video bitrate, only works if the @code{qscale} flag in
- at option{flags} is not enabled.
+Set the video bitrate in bit/s for CBR (Constant Bit Rate) mode.  In
+case VBR (Variable Bit Rate) mode is enabled this option is ignored.
 
 @item flags
-Used to enable constant quality mode encoding through the
+Used to enable constant quality mode (VBR) encoding through the
 @option{qscale} flag, and to enable the @code{pass1} and @code{pass2}
 modes.
 
 @item g
 Set the GOP size.
 
+ at item q
+Enable constant quality (VBR) mode, and set quality as a double
+floating point number. The value is expressed in QP units, is clipped
+in the [0-10] range, and then multiplied by 6.3 to get a value in the
+native libtheora range [0-63].
+
+This option is valid only using the @command{ffmpeg} command-line
+tool. For library interface users, use @option{global_quality}.
+
 @item global_quality
-Set the global quality in lambda units, only works if the
- at code{qscale} flag in @option{flags} is enabled. The value is clipped
-in the [0 - 10*@code{FF_QP2LAMBDA}] range, and then multiplied for 6.3
-to get a value in the native libtheora range [0-63]. A higher value
-corresponds to a higher quality.
-
-For example, to set maximum constant quality encoding with
- at command{ffmpeg}:
+Set the global quality as an integer in lambda units.
+
+The option is effective only if VBR mode is enabled with @code{flags
++qscale}. The value is converted in QP units by dividing it by
+ at code{FF_QP2LAMBDA}, clipped in the [0 - 10] range, and then
+multiplied by 6.3 to get a value in the native libtheora range
+[0-63]. A higher value corresponds to a higher quality.
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Set maximum constant quality (VBR) encoding with @command{ffmpeg}:
 @example
-ffmpeg -i INPUT -flags:v qscale -global_quality:v "10*QP2LAMBDA" -codec:v libtheora OUTPUT.ogg
+ffmpeg -i INPUT -codec:v libtheora -q:v 10 OUTPUT.ogg
 @end example
- at end table
+
+ at item
+Use @command{ffmpeg} to convert a CBR 1000kbps Theora video stream:
+ at example
+ffmpeg -i INPUT -codec:v libtheora -b:v 1000k OUTPUT.ogg
+ at end example
+ at end itemize
 
 @section libvpx
 
-- 
1.8.1.2