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

[Stefano Sabatini]

---
 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.
+
+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://sourceforge.net/projects/faac/}.
+
+ 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
+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).
+
+In case 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_he
+High Efficiency AAC (HE-AAC)
+
+ 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].
+
+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)
+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
+
 @anchor{libfdk-aac-enc}
 @section libfdk_aac
 
-- 
1.8.1.2