[FFmpeg-cvslog] doc/encoders: document the libfdk-aac wrapper

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Tue Oct 29 21:50:09 2013 +0100| [d339e03fc3b889fe60cc1dd00cdd18cb68aaa2ab] | committer: Stefano Sabatini

doc/encoders: document the libfdk-aac wrapper

Partially based on the https://trac.ffmpeg.org/wiki/AACEncodingGuide
guide.

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

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

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 7825b9a..840d55e 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 Comment this out until somebody writes the respective documentation.
- at c See also @ref{libfaac}, @ref{libaacplus}, and @ref{libfdk-aac-enc}.
+ at c todo @ref{libfaac}, @ref{libaacplus}
+See also @ref{libfdk-aac-enc,,the libfdk_aac section}.
 
 @subsection Options
 
@@ -494,6 +494,171 @@ Selected by Encoder (default)
 
 @end table
 
+ at anchor{libfdk-aac-enc}
+ at section libfdk_aac
+
+libfdk-aac 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 libfdk-aac headers and library during
+configuration. You need to explicitly configure the build with
+ at code{--enable-libfdk-aac}. The library is also incompatible with GPL,
+so if you allow the use of GPL, you should configure with
+ at code{--enable-gpl --enable-nonfree --enable-libfdk-aac}.
+
+This encoder is considered to be of higher quality with respect to
+both @ref{aacenc,,the native experimental FFmpeg AAC encoder} and
+libfaac.
+
+For more information see the fdk-aac project at
+ at url{http://sourceforge.net/p/opencore-amr/fdk-aac/}.
+
+ at subsection Options
+
+The following options are mapped on the shared FFmpeg codec options.
+
+ at table @option
+ at item b
+Set bit rate in bits/s. If the bitrate is not explicitly specified, it
+is automatically set to a suitable value depending on the selected
+profile.
+
+In case VBR mode is enabled the option is ignored.
+
+ at item ar
+Set audio sampling rate (in Hz).
+
+ at item channels
+Set the number of audio channels.
+
+ at item flags +qscale
+Enable fixed quality, VBR (Variable Bit Rate) mode.
+Note that VBR is implicitely enabled when the @option{vbr} value is
+positive.
+
+ at item cutoff
+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_low
+Low Complexity AAC (LC)
+
+ at item aac_he
+High Efficiency AAC (HE-AAC)
+
+ at item aac_he_v2
+High Efficiency AAC version 2 (HE-AACv2)
+
+ at item aac_ld
+Low Delay AAC (LD)
+
+ at item aac_eld
+Enhanced Low Delay AAC (ELD)
+ at end table
+
+If not specified it is set to @samp{aac_low}.
+ at end table
+
+The following are private options of the libfdk_aac encoder.
+
+ at table @option
+ at item afterburner
+Enable afterburner feature if set to 1, disabled if set to 0. This
+improves the quality but also the required processing power.
+
+Default value is 1.
+
+ at item eld_sbr
+Enable SBR (Spectral Band Replication) for ELD if set to 1, disabled
+if set to 0.
+
+Default value is 0.
+
+ at item signaling
+Set SBR/PS signaling style.
+
+It can assume one of the following values:
+ at table @samp
+ at item default
+choose signaling implicitly (explicit hierarchical by default,
+implicit if global header is disabled)
+
+ at item implicit
+implicit backwards compatible signaling
+
+ at item explicit_sbr
+explicit SBR, implicit PS signaling
+
+ at item explicit_hierarchical
+explicit hierarchical signaling
+ at end table
+
+Default value is @samp{default}.
+
+ at item latm
+Output LATM/LOAS encapsulated data if set to 1, disabled if set to 0.
+
+Default value is 0.
+
+ at item header_period
+Set StreamMuxConfig and PCE repetition period (in frames) for sending
+in-band configuration buffers within LATM/LOAS transport layer.
+
+Must be a 16-bits non-negative integer.
+
+Default value is 0.
+
+ at item vbr
+Set VBR mode, from 1 to 5. 1 is lowest quality (though still pretty
+good) and 5 is highest quality. A value of 0 will disable VBR mode,
+and CBR (Constant Bit Rate) mode is enabled.
+
+Currently only the @samp{aac_low} profile supports VBR mode.
+
+VBR modes 1-5 correspond to roughly the following average bit rate:
+
+ at table @samp
+ at item 1
+32 kbps/channel
+ at item 2
+40 kbps/channel
+ at item 3
+48-56 kbps/channel
+ at item 4
+64 kbps/channel
+ at item 5
+about 80-96 kbps/channel
+ at end table
+
+Default value is 0.
+ at end table
+
+ at section Examples
+
+ at itemize
+ at item
+Use @command{ffmpeg} to convert an audio file to VBR AAC in an M4A (MP4)
+container:
+ at example
+ffmpeg -i input.wav -codec:a libfdk_aac -vbr 3 output.m4a
+ at end example
+
+ at item
+Use @command{ffmpeg} to convert an audio file to CBR 64k kbps AAC, using the
+High-Efficiency AAC profile:
+ at example
+ffmpeg -i input.wav -c:a libfdk_aac -profile:a aac_he -b:a 64k output.m4a
+ at end example
+ at end itemize
+
 @anchor{libmp3lame}
 @section libmp3lame