[FFmpeg-devel] [PATCH] doc/encoders: add libfaac encoder documentation

[Stefano Sabatini]

On date Wednesday 2013-10-30 19:53:29 -0700, Timothy Gu encoded:
> On Oct 30, 2013 6:26 AM, "Stefano Sabatini" <stefasab at gmail.com> wrote:
> >
> > ---
> >  doc/encoders.texi | 119
> +++++++++++++++++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 117 insertions(+), 2 deletions(-)
> >
> > diff --git a/doc/encoders.texi b/doc/encoders.texi
> > index 54157f0..a9d518a 100644
> > --- a/doc/encoders.texi
> > +++ b/doc/encoders.texi
> > @@ -38,8 +38,8 @@ As this encoder is experimental, unexpected behavior
> may exist from time to
> >  time. For a more stable AAC encoder, see @ref{libvo-aacenc}. However, be
> warned
> >  that it has a worse quality reported by some users.
> >
> > - at c todo @ref{libfaac}, @ref{libaacplus}
> > -See also @ref{libfdk-aac-enc,,the libfdk_aac section}.
> > + at c todo @ref{libaacplus}
> > +See also @ref{libfdk-aac-enc,,libfdk_aac} and @ref{libfaac}.
> >
> >  @subsection Options
> >
> > @@ -494,6 +494,121 @@ Selected by Encoder (default)
> >
> >  @end table
> >
> > + at anchor{libfaac}
> > + at section libfaac
> > +
> > +libfaac AAC (Advanced Audio Coding) encoder wrapper.
> > +
> 
> > +The libfdk-aac library is based on the Fraunhofer FDK AAC code from
> > +the Android project.
> 
> ???

copy&paste error

> 
> > +
> > +Requires the presence of the libfaac headers and library during
> > +configuration. You need to explicitly configure the build with
> > + at code{--enable-libfaac --enable-nonfree}.
> > +
> > +This encoder is considered to be of higher quality with respect to the
> > + at ref{aacenc,,the native experimental FFmpeg AAC encoder}.
> 

> ...with respect to aac and libvo-aacenc...but somehow worse compared to
> libfdk-aac.

I'd prefer to avoid multiple comparisons, reference documentation is
not the correct place for them, and it is hard to keep it updated in
case the comparison results change. Thus I only kept comparison with
the internal encoder.

Alternatively we could add a short section about AAC supported codecs
comparison, so to keep all the information in a single place.

> 
> > +
> > +For more information see the libfaac project at
> > + at url{http://sourceforge.net/projects/faac/}.
> 
> The real URL is http://www.audiocoding.com/faac.html

OK.
 
> > +
> > + at subsection Options
> > +
> > +The following shared FFmpeg codec options are recognized.
> > +
> > +The following options are supported by the libfaac wrapper. The
> > + at command{faac}-equivalent of the options are listed in parentheses.
> > +
> > + at table @option
> > + at item b (@emph{-b})
> > +Set bit rate in bits/s for ABR (Average Bit Rate) mode. If the bitrate
> 
> "bit rate" with space in between for consistency.
> 
> > +is not explicitly specified, it is automatically set to a suitable
> > +value depending on the selected profile. @command{faac} bitrate is
> > +expressed in kilobits/s.
> 
> @command{faac} @option{-b} option is expressed...
> 
> > +
> > +Note that libfaac does not support CBR (Constant Bit Rate) but only
> > +ABR (Average Bit Rate).
> > +
> > +In case VBR mode is enabled this option is ignored.
> 
> In case of

In case of VBR mode is enabled ...
sounds weird to me.

Changed to:
If VBR mode is enabled ...

> 
> > +
> > + at item ar (@emph{-R})
> > +Set audio sampling rate (in Hz).
> > +
> > + at item ac (@emph{-c})
> > +Set the number of audio channels.
> 
> Not sure if these two are necessary.

These are automatically set by ffmpeg, but should be set by the API
user.

> 
> > +
> > + at item cutoff (@emph{-C})
> > +Set cutoff frequency. If not specified (or explicitly set to 0) it
> > +will use a value automatically computed by the library. Default value
> > +is 0.
> > +
> > + at item profile
> > +Set audio profile.
> > +
> > +The following profiles are recognized:
> > + at table @samp
> > + at item aac_main
> > +Main AAC (Main)
> > +
> > + at item aac_low
> > +Low Complexity AAC (LC)
> > +
> 
> > + at item aac_he
> > +High Efficiency AAC (HE-AAC)
> 
> Faac doesn't support aac_he.

Oh, correct.

> > +
> > + at item aac_ssr
> > +Scalable Sample Rate (SSR)
> > +
> > + at item aac_ltp
> > +Long Term Prediction (LTP)
> > + at end table
> > +
> > +If not specified it is set to @samp{aac_low}.
> > +
> > + at item flags +qscale
> > +Set constant quality VBR (Variable Bit Rate) mode.
> > +
> > + at item global_quality
> > +Set quality in VBR mode as an integer.
> > +
> > +Only relevant when VBR mode is enabled with @code{flags +qscale}.
> > + at option{global_quality} is expressed in Lagrange units. To get the
> > +corresponding QP value you need to divide by the @code{FF_QP2LAMBDA}
> > +constant. The higher the value the higher the quality.
> > +
> > +Default value is 0.
> > +
> > + at item q (@emph{-q})
> > +Enable VBR mode, and set constant quality value as an integer.
> > +
> > +This option is valid only using the @command{ffmpeg} command-line
> > +tool. The value is expressed in QP units, the higher the value the
> > +higher the quality. A reasonable range for the option value is
> > +[10-500].
> 
> The valid range for...

Not exactly, since it will accept any non-negative value, but
reasonable quality starts with 10. I didn't check libfaac
documentation properly, I think this is already (much) better than
nothing.

> 
> > +
> > +Default value is 0.
> > +
> > +For library interface users, use @option{global_quality}.
> > + at end table
> > +
> > + at subsection Examples
> > +
> > + at itemize
> > + at item
> > +Use @command{ffmpeg} to convert an audio file to ABR 128kbps AAC in an
> M4A (MP4)
> 
> Nnnnnit: 128 kbps with space
> 
> > +container:
> > + at example
> > +ffmpeg -i input.wav -codec:a libfaac -b:a 128k -output.m4a
> > + at end example
> > +
> 
> > + at item
> > +Use @command{ffmpeg} to convert an audio file to VBR AAC, using the
> > +High-Efficiency AAC profile:
> > + at example
> > +ffmpeg -i input.wav -c:a libfaac -profile:a aac_he -q:a 100 output.m4a
> > + at end example
> > + at end itemize
> 
> Again, faac doesn't support HE.
> 

Updated.
-- 
FFmpeg = Fanciful & Frightening Marvellous Programmable Eager Gladiator
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0003-doc-encoders-add-libfaac-encoder-documentation.patch
Type: text/x-diff
Size: 4049 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20131031/65a26154/attachment.bin>