[FFmpeg-devel] [PATCH] doc/encoder: document the libfdk-aac wrapper

[Timothy Gu]

On Oct 29, 2013 1:51 PM, "Stefano Sabatini" <stefasab at gmail.com> wrote:
>
> Partially based on the https://trac.ffmpeg.org/wiki/AACEncodingGuide
> guide.
> ---
>  doc/encoders.texi | 148
+++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 146 insertions(+), 2 deletions(-)

I wanted to do that a long time ago. +1

>
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 67f2a39..a0a61f8 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,150 @@ Selected by Encoder (default)
>
>  @end table
>
> + at anchor{libfdk-aac-enc}

Unrelated to this patch: Should @node is better for these cases? (But don't
use node in this patch as it will mess up document structure)

> + at section libfdk_aac
> +
> +libfdk-aac AAC (Advanced Audio Coding) encoder wrapper.
> +
> +The library is based on the Fraunhofer FDK AAC code from Android
> +library.

Android is not a library.
...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 --enable-nonfree}.

fdk-aac itself is not non free, it's just incompatible to the GPL . You can
do ./configure --enable-libfdk-aac or ./configure --enable-gpl
--enable-nonfree --enable-libfdk-aac.

> +
> +This encoder is considered to be of higher quality with respect to
> + at ref{aacenc,,the native experimental FFmpeg AAC encoder}.

respect to both aac and libfaac.

> +
> +For more information see the fdk-aac project at
> + at url{https://github.com/mstorsjo/fdk-aac}.
> +
> +See also @ref{aacenc,,the native aac encoder section}.
> +
> + 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.
> +
> + at item ar
> +Set audio sampling rate (in Hz).
> +
> + 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 item flags +qscale
> +Enable fixed quality, VBR (Variable Bit Rate) mode.
> +Note that VBR is implicitely enabled when the @option{vbr} value is

Implicitly typo. (Extra E)

> +positive.
> +
> + at item global_quality
> +Set global quality when VBR mode is enabled. This is only used if
> + at option{vbr} is set to 0, and is interpreted as a @option{vbr} option
> +mode.
> + 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 1.

disabled if set to 0.

> +
> +For SBR in other configurations, use the @option{profile} option.

Isn't other profiles clearer in this context?

> +
> +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,

An idea of "still pretty good" should be added (avg bit rate).

> +and CBR (Constant Bit Rate) is enabled.
> +
> +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

Rest looks OK. Nice job!

Timothy