From 2acc525d786f0ee4b0a354858a5f146ce6580658 Mon Sep 17 00:00:00 2001
From: Stefano Sabatini <stefasab@gmail.com>
Date: Wed, 30 Oct 2013 14:25:29 +0100
Subject: [PATCH] doc/encoders: add libfaac encoder documentation

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

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 840d55e5ab..d8583a52e2 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.
 
-@c todo @ref{libfaac}, @ref{libaacplus}
-See also @ref{libfdk-aac-enc,,the libfdk_aac section}.
+@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
 
+@anchor{libfaac}
+@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
+@code{--enable-libfaac --enable-nonfree}.
+
+This encoder is considered to be of higher quality with respect to the
+@ref{aacenc,,the native experimental FFmpeg AAC encoder}.
+
+For more information see the libfaac project at
+@url{http://www.audiocoding.com/faac.html/}.
+
+@subsection Options
+
+The following shared FFmpeg codec options are recognized.
+
+The following options are supported by the libfaac wrapper. The
+@command{faac}-equivalent of the options are listed in parentheses.
+
+@table @option
+@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.
+
+@item ar (@emph{-R})
+Set audio sampling rate (in Hz).
+
+@item ac (@emph{-c})
+Set the number of audio channels.
+
+@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.
+
+@item profile
+Set audio profile.
+
+The following profiles are recognized:
+@table @samp
+@item aac_main
+Main AAC (Main)
+
+@item aac_low
+Low Complexity AAC (LC)
+
+@item aac_ssr
+Scalable Sample Rate (SSR)
+
+@item aac_ltp
+Long Term Prediction (LTP)
+@end table
+
+If not specified it is set to @samp{aac_low}.
+
+@item flags +qscale
+Set constant quality VBR (Variable Bit Rate) mode.
+
+@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.
+
+@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}.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Use @command{ffmpeg} to convert an audio file to ABR 128 kbps AAC in an M4A (MP4)
+container:
+@example
+ffmpeg -i input.wav -codec:a libfaac -b:a 128k -output.m4a
+@end example
+
+@item
+Use @command{ffmpeg} to convert an audio file to VBR AAC, using the
+LTP AAC profile:
+@example
+ffmpeg -i input.wav -c:a libfaac -profile:a aac_ltp -q:a 100 output.m4a
+@end example
+@end itemize
+
 @anchor{libfdk-aac-enc}
 @section libfdk_aac