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

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Wed Oct 30 14:25:29 2013 +0100| [2acc525d786f0ee4b0a354858a5f146ce6580658] | committer: Stefano Sabatini

doc/encoders: add libfaac encoder documentation

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=2acc525d786f0ee4b0a354858a5f146ce6580658
---

 doc/encoders.texi |  111 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 2 deletions(-)

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 840d55e..d8583a5 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,113 @@ Selected by Encoder (default)
 
 @end table
 
+ at anchor{libfaac}
+ at section libfaac
+
+libfaac AAC (Advanced Audio Coding) encoder wrapper.
+
+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}.
+
+For more information see the libfaac project at
+ at url{http://www.audiocoding.com/faac.html/}.
+
+ 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 bit rate
+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.
+
+Note that libfaac does not support CBR (Constant Bit Rate) but only
+ABR (Average Bit Rate).
+
+If VBR mode is enabled this option is ignored.
+
+ at item ar (@emph{-R})
+Set audio sampling rate (in Hz).
+
+ at item ac (@emph{-c})
+Set the number of audio channels.
+
+ 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_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 number of lambda units.
+
+Only relevant when VBR mode is enabled with @code{flags +qscale}.  The
+value is converted to QP units by dividing it by @code{FF_QP2LAMBDA},
+and used to set the quality value used by libfaac. A reasonable range
+for the option value in QP units is [10-500], the higher the value the
+higher the quality.
+
+ at item q (@emph{-q})
+Enable VBR mode when set to a non-negative value, and set constant
+quality value as a double floating point value in QP units.
+
+The value sets the quality value used by libfaac. A reasonable range
+for the option value is [10-500], the higher the value the higher the
+quality.
+
+This option is valid only using the @command{ffmpeg} command-line
+tool. 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 128 kbps AAC in an M4A (MP4)
+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
+LTP AAC profile:
+ at example
+ffmpeg -i input.wav -c:a libfaac -profile:a aac_ltp -q:a 100 output.m4a
+ at end example
+ at end itemize
+
 @anchor{libfdk-aac-enc}
 @section libfdk_aac