[FFmpeg-devel] [PATCH] doc/encoders: document libtheora encoder

[Stefano Sabatini]

On date Sunday 2012-11-11 14:17:12 +0100, Clément Bœsch encoded:
> On Sun, Nov 11, 2012 at 12:41:15PM +0100, Stefano Sabatini wrote:
> > ---
> >  doc/encoders.texi |   40 ++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 40 insertions(+)
> > 
> > diff --git a/doc/encoders.texi b/doc/encoders.texi
> > index a7a2761..121d07b 100644
> > --- a/doc/encoders.texi
> > +++ b/doc/encoders.texi
> > @@ -420,6 +420,46 @@ Selected by Encoder (default)
> >  A description of some of the currently available video encoders
> >  follows.
> >  
> > + at section libtheora
> > +
> > +Theora format supported through libtheora.
> > +
> > +Requires the presence of the libtheora headers and library during
> > +configuration.  You need to explicitly configure the build with
> > + at code{--enable-libtheora}.
> > +
> > + at subsection Options
> > +
> > +The following options are mapped to internal libtheora options which
> 
> The following /global/ options?

Changed.

> 
> > +affect the quality and the bitrate of the encoded stream. All the
> > +other global options are ignored.
> 
> Maybe "All the other global options /such as qmin or qmax/ ..." ?
> 
> But I'd better not say something such as this: at some point we might try
> to honor more avctx settings in the wrapper and forget to update this
> sentence. Maybe mitigate the sentence with "likely" or something.

I removed the sentence. In case a new mapping is added, we should
update the docs and bump micro.

> 
> > +
> > + at table @option
> > + at item b
> > +Set the video bitrate, only works if the @code{qscale} flag in
> > + at option{flags} is not enabled.
> > +
> > + at item flags
> > +Used to enable constant quality mode encoding through the
> > + at option{qscale} flag, and to enable the @code{pass1} and @code{pass2}
> > +modes. All the other values are ignored.
> > +
> > + at item g
> > +Set the GOP size.
> > +
> > + at 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].
> 

> Sounds like a more general global-quality-expression-for-libs would be
> welcome…

Unrelated.
 
> > +
> > +For example, to set maximum constant quality encoding with
> > + at command{ffmpeg}:
> > + at example
> > +ffmpeg -i INPUT -flags qscale -global_quality "10*QP2LAMBDA" -codec:v libtheora OUTPUT.ogg
> > + at end example
> > + at end table
> > +
> 
> And so -qscale option has no effect?…

-qscale was never an option. -flags qscale is required to force CQR
(constat quality rate) vs. CBR mode (constant bit rate) mode. The
alternative is to use -q:v 10 but I prefer to show a more explicit
option setting (which does not depend on the ffmpeg.c implementation).

Updated.
-- 
FFmpeg = Fabulous & Frightening Minimal Powered Extroverse Geek
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0005-doc-encoders-document-libtheora-encoder.patch
Type: text/x-diff
Size: 1831 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121111/553a10e7/attachment.bin>