Include patched FDK-AAC in the repository

The initial idea was to get the DAB+ patch into upstream, but since
that follows the android source releases, there is no place for a custom
DAB+ patch there.

So instead of having to maintain a patched fdk-aac that has to have the
same .so version as the distribution package on which it is installed,
we prefer having a separate fdk-aac-dab library to avoid collision.

At that point, there's no reason to keep fdk-aac in a separate
repository, as odr-audioenc is the only tool that needs DAB+ encoding
support. Including it here simplifies installation, and makes it
consistent with toolame-dab, also shipped in this repository.

DAB+ decoding support (needed by ODR-SourceCompanion, dablin, etisnoop,
welle.io and others) can be done using upstream FDK-AAC.

3 files changed, 872 insertions, 0 deletions

diff --git a/fdk-aac/libPCMutils/include/limiter.h b/fdk-aac/libPCMutils/include/limiter.h
new file mode 100644
index 0000000..fab7226
--- /dev/null
+++ b/fdk-aac/libPCMutils/include/limiter.h
@@ -0,0 +1,281 @@
+/* -----------------------------------------------------------------------------
+Software License for The Fraunhofer FDK AAC Codec Library for Android
+
+© Copyright  1995 - 2018 Fraunhofer-Gesellschaft zur Förderung der angewandten
+Forschung e.V. All rights reserved.
+
+ 1.    INTRODUCTION
+The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
+that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
+scheme for digital audio. This FDK AAC Codec software is intended to be used on
+a wide variety of Android devices.
+
+AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
+general perceptual audio codecs. AAC-ELD is considered the best-performing
+full-bandwidth communications codec by independent studies and is widely
+deployed. AAC has been standardized by ISO and IEC as part of the MPEG
+specifications.
+
+Patent licenses for necessary patent claims for the FDK AAC Codec (including
+those of Fraunhofer) may be obtained through Via Licensing
+(www.vialicensing.com) or through the respective patent owners individually for
+the purpose of encoding or decoding bit streams in products that are compliant
+with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
+Android devices already license these patent claims through Via Licensing or
+directly from the patent owners, and therefore FDK AAC Codec software may
+already be covered under those patent licenses when it is used for those
+licensed purposes only.
+
+Commercially-licensed AAC software libraries, including floating-point versions
+with enhanced sound quality, are also available from Fraunhofer. Users are
+encouraged to check the Fraunhofer website for additional applications
+information and documentation.
+
+2.    COPYRIGHT LICENSE
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted without payment of copyright license fees provided that you
+satisfy the following conditions:
+
+You must retain the complete text of this software license in redistributions of
+the FDK AAC Codec or your modifications thereto in source code form.
+
+You must retain the complete text of this software license in the documentation
+and/or other materials provided with redistributions of the FDK AAC Codec or
+your modifications thereto in binary form. You must make available free of
+charge copies of the complete source code of the FDK AAC Codec and your
+modifications thereto to recipients of copies in binary form.
+
+The name of Fraunhofer may not be used to endorse or promote products derived
+from this library without prior written permission.
+
+You may not charge copyright license fees for anyone to use, copy or distribute
+the FDK AAC Codec software or your modifications thereto.
+
+Your modified versions of the FDK AAC Codec must carry prominent notices stating
+that you changed the software and the date of any change. For modified versions
+of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
+must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
+AAC Codec Library for Android."
+
+3.    NO PATENT LICENSE
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
+limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
+Fraunhofer provides no warranty of patent non-infringement with respect to this
+software.
+
+You may use this FDK AAC Codec software or modifications thereto only for
+purposes that are authorized by appropriate patent licenses.
+
+4.    DISCLAIMER
+
+This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
+holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
+including but not limited to the implied warranties of merchantability and
+fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
+or consequential damages, including but not limited to procurement of substitute
+goods or services; loss of use, data, or profits, or business interruption,
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort (including negligence), arising in any way out of the use of
+this software, even if advised of the possibility of such damage.
+
+5.    CONTACT INFORMATION
+
+Fraunhofer Institute for Integrated Circuits IIS
+Attention: Audio and Multimedia Departments - FDK AAC LL
+Am Wolfsmantel 33
+91058 Erlangen, Germany
+
+www.iis.fraunhofer.de/amm
+amm-info@iis.fraunhofer.de
+----------------------------------------------------------------------------- */
+
+/**************************** PCM utility library ******************************
+
+   Author(s):   Matthias Neusinger
+
+   Description: Hard limiter for clipping prevention
+
+*******************************************************************************/
+
+#ifndef LIMITER_H
+#define LIMITER_H
+
+#include "common_fix.h"
+#include "FDK_audio.h"
+
+#define TDL_ATTACK_DEFAULT_MS (15)  /* default attack  time in ms */
+#define TDL_RELEASE_DEFAULT_MS (50) /* default release time in ms */
+
+#define TDL_GAIN_SCALING (15) /* scaling of gain value. */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct TDLimiter {
+  unsigned int attack;
+  FIXP_DBL attackConst, releaseConst;
+  unsigned int attackMs, releaseMs, maxAttackMs;
+  FIXP_DBL threshold;
+  unsigned int channels, maxChannels;
+  UINT sampleRate, maxSampleRate;
+  FIXP_DBL cor, max;
+  FIXP_DBL* maxBuf;
+  FIXP_DBL* delayBuf;
+  unsigned int maxBufIdx, delayBufIdx;
+  FIXP_DBL smoothState0;
+  FIXP_DBL minGain;
+
+  FIXP_DBL additionalGainPrev;
+  FIXP_DBL additionalGainFilterState;
+  FIXP_DBL additionalGainFilterState1;
+};
+
+typedef enum {
+  TDLIMIT_OK = 0,
+  TDLIMIT_UNKNOWN = -1,
+
+  __error_codes_start = -100,
+
+  TDLIMIT_INVALID_HANDLE,
+  TDLIMIT_INVALID_PARAMETER,
+
+  __error_codes_end
+} TDLIMITER_ERROR;
+
+struct TDLimiter;
+typedef struct TDLimiter* TDLimiterPtr;
+
+#define PCM_LIM LONG
+#define FIXP_DBL2PCM_LIM(x) (x)
+#define PCM_LIM2FIXP_DBL(x) (x)
+#define PCM_LIM_BITS 32
+#define FIXP_PCM_LIM FIXP_DBL
+
+#define SAMPLE_BITS_LIM DFRACT_BITS
+
+/******************************************************************************
+ * pcmLimiter_Reset                                                            *
+ * limiter: limiter handle                                                     *
+ * returns: error code                                                         *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_Reset(TDLimiterPtr limiter);
+
+/******************************************************************************
+ * pcmLimiter_Destroy                                                          *
+ * limiter: limiter handle                                                     *
+ * returns: error code                                                         *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_Destroy(TDLimiterPtr limiter);
+
+/******************************************************************************
+ * pcmLimiter_GetDelay                                                         *
+ * limiter: limiter handle                                                     *
+ * returns: exact delay caused by the limiter in samples per channel           *
+ ******************************************************************************/
+unsigned int pcmLimiter_GetDelay(TDLimiterPtr limiter);
+
+/******************************************************************************
+ * pcmLimiter_GetMaxGainReduction                                              *
+ * limiter: limiter handle                                                     *
+ * returns: maximum gain reduction in last processed block in dB               *
+ ******************************************************************************/
+INT pcmLimiter_GetMaxGainReduction(TDLimiterPtr limiter);
+
+/******************************************************************************
+ * pcmLimiter_SetNChannels                                                     *
+ * limiter:   limiter handle                                                   *
+ * nChannels: number of channels ( <= maxChannels specified on create)         *
+ * returns:   error code                                                       *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_SetNChannels(TDLimiterPtr limiter,
+                                        unsigned int nChannels);
+
+/******************************************************************************
+ * pcmLimiter_SetSampleRate                                                    *
+ * limiter:    limiter handle                                                  *
+ * sampleRate: sampling rate in Hz ( <= maxSampleRate specified on create)     *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_SetSampleRate(TDLimiterPtr limiter, UINT sampleRate);
+
+/******************************************************************************
+ * pcmLimiter_SetAttack                                                        *
+ * limiter:    limiter handle                                                  *
+ * attackMs:   attack time in ms ( <= maxAttackMs specified on create)         *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_SetAttack(TDLimiterPtr limiter,
+                                     unsigned int attackMs);
+
+/******************************************************************************
+ * pcmLimiter_SetRelease                                                       *
+ * limiter:    limiter handle                                                  *
+ * releaseMs:  release time in ms                                              *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_SetRelease(TDLimiterPtr limiter,
+                                      unsigned int releaseMs);
+
+/******************************************************************************
+ * pcmLimiter_GetLibInfo                                                       *
+ * info:       pointer to an allocated and initialized LIB_INFO structure      *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_GetLibInfo(LIB_INFO* info);
+
+#ifdef __cplusplus
+}
+#endif
+
+/******************************************************************************
+ * pcmLimiter_Create                                                           *
+ * maxAttackMs:   maximum and initial attack/lookahead time in milliseconds    *
+ * releaseMs:     release time in milliseconds (90% time constant)             *
+ * threshold:     limiting threshold                                           *
+ * maxChannels:   maximum and initial number of channels                       *
+ * maxSampleRate: maximum and initial sampling rate in Hz                      *
+ * returns:       limiter handle                                               *
+ ******************************************************************************/
+TDLimiterPtr pcmLimiter_Create(unsigned int maxAttackMs, unsigned int releaseMs,
+                               FIXP_DBL threshold, unsigned int maxChannels,
+                               UINT maxSampleRate);
+
+/******************************************************************************
+ * pcmLimiter_SetThreshold                                                     *
+ * limiter:    limiter handle                                                  *
+ * threshold:  limiter threshold                                               *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_SetThreshold(TDLimiterPtr limiter,
+                                        FIXP_DBL threshold);
+
+/******************************************************************************
+ * pcmLimiter_Apply                                                            *
+ * limiter:    limiter handle                                                  *
+ * pGain :     pointer to gains to be applied to the signal before limiting,   *
+ *             which are downscaled by TDL_GAIN_SCALING bit.                   *
+ *             These gains are delayed by gain_delay, and smoothed.            *
+ *             Smoothing is done by a butterworth lowpass filter with a cutoff *
+ *             frequency which is fixed with respect to the sampling rate.     *
+ *             It is a substitute for the smoothing due to windowing and       *
+ *             overlap/add, if a gain is applied in frequency domain.          *
+ * gain_scale: pointer to scaling exponents to be applied to the signal before *
+ *             limiting, without delay and without smoothing                   *
+ * gain_size:  number of elements in pGain, currently restricted to 1          *
+ * gain_delay: delay [samples] with which the gains in pGain shall be applied  *
+ *             gain_delay <= nSamples                                          *
+ * samples:    input/output buffer containing interleaved samples              *
+ *             precision of output will be DFRACT_BITS-TDL_GAIN_SCALING bits   *
+ * nSamples:   number of samples per channel                                   *
+ * returns:    error code                                                      *
+ ******************************************************************************/
+TDLIMITER_ERROR pcmLimiter_Apply(TDLimiterPtr limiter, PCM_LIM* samplesIn,
+                                 INT_PCM* samplesOut, FIXP_DBL* pGain,
+                                 const INT* gain_scale, const UINT gain_size,
+                                 const UINT gain_delay, const UINT nSamples);
+
+#endif /* #ifndef LIMITER_H */
diff --git a/fdk-aac/libPCMutils/include/pcm_utils.h b/fdk-aac/libPCMutils/include/pcm_utils.h
new file mode 100644
index 0000000..073bcfc
--- /dev/null
+++ b/fdk-aac/libPCMutils/include/pcm_utils.h
@@ -0,0 +1,131 @@
+/* -----------------------------------------------------------------------------
+Software License for The Fraunhofer FDK AAC Codec Library for Android
+
+© Copyright  1995 - 2018 Fraunhofer-Gesellschaft zur Förderung der angewandten
+Forschung e.V. All rights reserved.
+
+ 1.    INTRODUCTION
+The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
+that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
+scheme for digital audio. This FDK AAC Codec software is intended to be used on
+a wide variety of Android devices.
+
+AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
+general perceptual audio codecs. AAC-ELD is considered the best-performing
+full-bandwidth communications codec by independent studies and is widely
+deployed. AAC has been standardized by ISO and IEC as part of the MPEG
+specifications.
+
+Patent licenses for necessary patent claims for the FDK AAC Codec (including
+those of Fraunhofer) may be obtained through Via Licensing
+(www.vialicensing.com) or through the respective patent owners individually for
+the purpose of encoding or decoding bit streams in products that are compliant
+with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
+Android devices already license these patent claims through Via Licensing or
+directly from the patent owners, and therefore FDK AAC Codec software may
+already be covered under those patent licenses when it is used for those
+licensed purposes only.
+
+Commercially-licensed AAC software libraries, including floating-point versions
+with enhanced sound quality, are also available from Fraunhofer. Users are
+encouraged to check the Fraunhofer website for additional applications
+information and documentation.
+
+2.    COPYRIGHT LICENSE
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted without payment of copyright license fees provided that you
+satisfy the following conditions:
+
+You must retain the complete text of this software license in redistributions of
+the FDK AAC Codec or your modifications thereto in source code form.
+
+You must retain the complete text of this software license in the documentation
+and/or other materials provided with redistributions of the FDK AAC Codec or
+your modifications thereto in binary form. You must make available free of
+charge copies of the complete source code of the FDK AAC Codec and your
+modifications thereto to recipients of copies in binary form.
+
+The name of Fraunhofer may not be used to endorse or promote products derived
+from this library without prior written permission.
+
+You may not charge copyright license fees for anyone to use, copy or distribute
+the FDK AAC Codec software or your modifications thereto.
+
+Your modified versions of the FDK AAC Codec must carry prominent notices stating
+that you changed the software and the date of any change. For modified versions
+of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
+must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
+AAC Codec Library for Android."
+
+3.    NO PATENT LICENSE
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
+limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
+Fraunhofer provides no warranty of patent non-infringement with respect to this
+software.
+
+You may use this FDK AAC Codec software or modifications thereto only for
+purposes that are authorized by appropriate patent licenses.
+
+4.    DISCLAIMER
+
+This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
+holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
+including but not limited to the implied warranties of merchantability and
+fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
+or consequential damages, including but not limited to procurement of substitute
+goods or services; loss of use, data, or profits, or business interruption,
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort (including negligence), arising in any way out of the use of
+this software, even if advised of the possibility of such damage.
+
+5.    CONTACT INFORMATION
+
+Fraunhofer Institute for Integrated Circuits IIS
+Attention: Audio and Multimedia Departments - FDK AAC LL
+Am Wolfsmantel 33
+91058 Erlangen, Germany
+
+www.iis.fraunhofer.de/amm
+amm-info@iis.fraunhofer.de
+----------------------------------------------------------------------------- */
+
+/**************************** PCM utility library ******************************
+
+   Author(s):   Alfonso Pino Garcia
+
+   Description: Functions that perform (de)interleaving combined with format
+change
+
+*******************************************************************************/
+
+#if !defined(PCM_UTILS_H)
+#define PCM_UTILS_H
+
+#include "common_fix.h"
+
+void FDK_interleave(const FIXP_DBL *RESTRICT pIn, LONG *RESTRICT pOut,
+                    const UINT channels, const UINT frameSize,
+                    const UINT length);
+void FDK_interleave(const FIXP_DBL *RESTRICT pIn, SHORT *RESTRICT pOut,
+                    const UINT channels, const UINT frameSize,
+                    const UINT length);
+void FDK_interleave(const FIXP_SGL *RESTRICT pIn, SHORT *RESTRICT pOut,
+                    const UINT channels, const UINT frameSize,
+                    const UINT length);
+
+void FDK_deinterleave(const LONG *RESTRICT pIn, SHORT *RESTRICT pOut,
+                      const UINT channels, const UINT frameSize,
+                      const UINT length);
+void FDK_deinterleave(const LONG *RESTRICT pIn, LONG *RESTRICT pOut,
+                      const UINT channels, const UINT frameSize,
+                      const UINT length);
+void FDK_deinterleave(const SHORT *RESTRICT pIn, SHORT *RESTRICT pOut,
+                      const UINT channels, const UINT frameSize,
+                      const UINT length);
+void FDK_deinterleave(const SHORT *RESTRICT pIn, LONG *RESTRICT pOut,
+                      const UINT channels, const UINT frameSize,
+                      const UINT length);
+#endif /* !defined(PCM_UTILS_H) */
diff --git a/fdk-aac/libPCMutils/include/pcmdmx_lib.h b/fdk-aac/libPCMutils/include/pcmdmx_lib.h
new file mode 100644
index 0000000..d37a851
--- /dev/null
+++ b/fdk-aac/libPCMutils/include/pcmdmx_lib.h
@@ -0,0 +1,460 @@
+/* -----------------------------------------------------------------------------
+Software License for The Fraunhofer FDK AAC Codec Library for Android
+
+© Copyright  1995 - 2018 Fraunhofer-Gesellschaft zur Förderung der angewandten
+Forschung e.V. All rights reserved.
+
+ 1.    INTRODUCTION
+The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
+that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
+scheme for digital audio. This FDK AAC Codec software is intended to be used on
+a wide variety of Android devices.
+
+AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
+general perceptual audio codecs. AAC-ELD is considered the best-performing
+full-bandwidth communications codec by independent studies and is widely
+deployed. AAC has been standardized by ISO and IEC as part of the MPEG
+specifications.
+
+Patent licenses for necessary patent claims for the FDK AAC Codec (including
+those of Fraunhofer) may be obtained through Via Licensing
+(www.vialicensing.com) or through the respective patent owners individually for
+the purpose of encoding or decoding bit streams in products that are compliant
+with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
+Android devices already license these patent claims through Via Licensing or
+directly from the patent owners, and therefore FDK AAC Codec software may
+already be covered under those patent licenses when it is used for those
+licensed purposes only.
+
+Commercially-licensed AAC software libraries, including floating-point versions
+with enhanced sound quality, are also available from Fraunhofer. Users are
+encouraged to check the Fraunhofer website for additional applications
+information and documentation.
+
+2.    COPYRIGHT LICENSE
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted without payment of copyright license fees provided that you
+satisfy the following conditions:
+
+You must retain the complete text of this software license in redistributions of
+the FDK AAC Codec or your modifications thereto in source code form.
+
+You must retain the complete text of this software license in the documentation
+and/or other materials provided with redistributions of the FDK AAC Codec or
+your modifications thereto in binary form. You must make available free of
+charge copies of the complete source code of the FDK AAC Codec and your
+modifications thereto to recipients of copies in binary form.
+
+The name of Fraunhofer may not be used to endorse or promote products derived
+from this library without prior written permission.
+
+You may not charge copyright license fees for anyone to use, copy or distribute
+the FDK AAC Codec software or your modifications thereto.
+
+Your modified versions of the FDK AAC Codec must carry prominent notices stating
+that you changed the software and the date of any change. For modified versions
+of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
+must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
+AAC Codec Library for Android."
+
+3.    NO PATENT LICENSE
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
+limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
+Fraunhofer provides no warranty of patent non-infringement with respect to this
+software.
+
+You may use this FDK AAC Codec software or modifications thereto only for
+purposes that are authorized by appropriate patent licenses.
+
+4.    DISCLAIMER
+
+This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
+holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
+including but not limited to the implied warranties of merchantability and
+fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
+or consequential damages, including but not limited to procurement of substitute
+goods or services; loss of use, data, or profits, or business interruption,
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort (including negligence), arising in any way out of the use of
+this software, even if advised of the possibility of such damage.
+
+5.    CONTACT INFORMATION
+
+Fraunhofer Institute for Integrated Circuits IIS
+Attention: Audio and Multimedia Departments - FDK AAC LL
+Am Wolfsmantel 33
+91058 Erlangen, Germany
+
+www.iis.fraunhofer.de/amm
+amm-info@iis.fraunhofer.de
+----------------------------------------------------------------------------- */
+
+/**************************** PCM utility library ******************************
+
+   Author(s):   Christian Griebel
+
+   Description:
+
+*******************************************************************************/
+
+/**
+ * \file   pcmdmx_lib.h
+ * \brief  FDK PCM audio mixdown library interface header file.
+
+ \page INTRO Introduction
+
+
+ \section SCOPE Scope
+
+ This document describes the high-level application interface and usage of the
+ FDK PCM audio mixdown module library developed by the Fraunhofer Institute for
+ Integrated Circuits (IIS). Depending on the library configuration, the module
+ can manipulate the number of audio channels of a given PCM signal. It can
+ create for example a two channel stereo audio signal from a given multi-channel
+ configuration (e.g. 5.1 channels).
+
+
+ \page ABBREV List of abbreviations
+
+  \li \b AAC - Advanced Audio Coding\n
+    Is an audio coding standard for lossy digital audio compression standardized
+ by ISO and IEC, as part of the MPEG-2 (ISO/IEC 13818-7:2006) and MPEG-4
+ (ISO/IEC 14496-3:2009) specifications.
+
+  \li \b DSE - Data Stream Element\n
+    A syntactical element of the MPEG-2/4 Advanced Audio Coding bitstream
+ standardized in ISO/IEC 14496-3:2009. It can convey any kind of data associated
+ to one program.
+
+  \li \b PCE - Program Config Element\n
+    A syntactical element of the MPEG-2/4 Advanced Audio Coding bitstream
+ standardized in ISO/IEC 14496-3:2009 that can define the stream configuration
+ for a single program. In addition it can comprise simple downmix meta data.
+
+ */
+
+#ifndef PCMDMX_LIB_H
+#define PCMDMX_LIB_H
+
+#include "machine_type.h"
+#include "common_fix.h"
+#include "FDK_audio.h"
+#include "FDK_bitstream.h"
+
+/**
+ *  \enum  PCMDMX_ERROR
+ *
+ *  Error codes that can be returned by module interface functions.
+ */
+typedef enum {
+  PCMDMX_OK = 0x0, /*!< No error happened. */
+  PCMDMX_UNSUPPORTED =
+      0x1, /*!< The requested feature/service is unavailable. This can
+                occur if the module was built for a wrong configuration.  */
+  pcm_dmx_fatal_error_start,
+  PCMDMX_OUT_OF_MEMORY, /*!< Not enough memory to set up an instance of the
+                           module.    */
+  pcm_dmx_fatal_error_end,
+
+  PCMDMX_INVALID_HANDLE,   /*!< The given instance handle is not valid.   */
+  PCMDMX_INVALID_ARGUMENT, /*!< One of the parameters handed over is invalid. */
+  PCMDMX_INVALID_CH_CONFIG, /*!< The given channel configuration is not
+                               supported and thus no processing was performed.
+                             */
+  PCMDMX_INVALID_MODE,  /*!< The set configuration/mode is not applicable.  */
+  PCMDMX_UNKNOWN_PARAM, /*!< The handed parameter is not known/supported. */
+  PCMDMX_UNABLE_TO_SET_PARAM, /*!< Unable to set the specific parameter. Most
+                                 probably the    value ist out of range.
+                               */
+  PCMDMX_CORRUPT_ANC_DATA,    /*!< The read ancillary data was corrupt.       */
+  PCMDMX_OUTPUT_BUFFER_TOO_SMALL /*!< The size of pcm output buffer is too
+                                    small.               */
+
+} PCMDMX_ERROR;
+
+/** Macro to identify fatal errors. */
+#define PCMDMX_IS_FATAL_ERROR(err)          \
+  ((((err) >= pcm_dmx_fatal_error_start) && \
+    ((err) <= pcm_dmx_fatal_error_end))     \
+       ? 1                                  \
+       : 0)
+
+/**
+ *  \enum  PCMDMX_PARAM
+ *
+ *  Modules dynamic runtime parameters that can be handed to function
+ * pcmDmx_SetParam() and pcmDmx_GetParam().
+ */
+typedef enum {
+  DMX_PROFILE_SETTING =
+      0x01, /*!< Defines which equations, coefficients and default/
+                 fallback values used for downmixing. See
+                 ::DMX_PROFILE_TYPE type for details.             */
+  DMX_BS_DATA_EXPIRY_FRAME =
+      0x10, /*!< The number of frames without new metadata that
+                 have to go by before the bitstream data expires.
+                 The value 0 disables expiry.                     */
+  DMX_BS_DATA_DELAY =
+      0x11, /*!< The number of delay frames of the output samples
+                 compared to the bitstream data.                  */
+  MIN_NUMBER_OF_OUTPUT_CHANNELS =
+      0x20, /*!< The minimum number of output channels. For all
+                 input configurations that have less than the given
+                 channels the module will modify the output
+                 automatically to obtain the given number of output
+                 channels. Mono signals will be duplicated. If more
+                 than two output channels are desired the module
+                 just adds empty channels. The parameter value must
+                 be either -1, 0, 1, 2, 6 or 8. If the value is
+                 greater than zero and exceeds the value of
+                 parameter ::MAX_NUMBER_OF_OUTPUT_CHANNELS the
+                 latter will be set to the same value. Both values
+                 -1 and 0 disable the feature.                    */
+  MAX_NUMBER_OF_OUTPUT_CHANNELS =
+      0x21, /*!< The maximum number of output channels. For all
+                 input configurations that have more than the given
+                 channels the module will apply a mixdown
+                 automatically to obtain the given number of output
+                 channels. The value must be either -1, 0, 1, 2, 6
+                 or 8. If it's greater than zero and lower or equal
+                 than the value of ::MIN_NUMBER_OF_OUTPUT_CHANNELS
+                 parameter the latter will be set to the same value.
+                 The values -1 and 0 disable the feature.         */
+  DMX_DUAL_CHANNEL_MODE =
+      0x30, /*!< Downmix mode for two channel audio data. See type
+                 ::DUAL_CHANNEL_MODE for details.                 */
+  DMX_PSEUDO_SURROUND_MODE =
+      0x31 /*!< Defines how module handles pseudo surround
+                compatible signals. See ::PSEUDO_SURROUND_MODE
+                type for details.                                */
+} PCMDMX_PARAM;
+
+/**
+ *  \enum  DMX_PROFILE_TYPE
+ *
+ *  Valid value list for parameter ::DMX_PROFILE_SETTING.
+ */
+typedef enum {
+  DMX_PRFL_STANDARD =
+      0x0, /*!< The standard profile creates mixdown signals based on
+                the advanced downmix metadata (from a DSE), equations
+                and default values defined in ISO/IEC 14496:3
+                Ammendment 4. Any other (legacy) downmix metadata will
+                be ignored.                                            */
+  DMX_PRFL_MATRIX_MIX =
+      0x1, /*!< This profile behaves just as the standard profile if
+                advanced downmix metadata (from a DSE) is available. If
+                not, the matrix_mixdown information embedded in the
+                program configuration element (PCE) will be applied. If
+                neither is the case the module creates a mixdown using
+                the default coefficients defined in MPEG-4 Ammendment 4.
+                The profile can be used e.g. to support legacy digital
+                TV (e.g. DVB) streams.                                 */
+  DMX_PRFL_FORCE_MATRIX_MIX =
+      0x2, /*!< Similar to the ::DMX_PRFL_MATRIX_MIX profile but if both
+                the advanced (DSE) and the legacy (PCE) MPEG downmix
+                metadata are available the latter will be applied.     */
+  DMX_PRFL_ARIB_JAPAN =
+      0x3 /*!< Downmix creation as described in ABNT NBR 15602-2. But
+               if advanced downmix metadata is available it will be
+               prefered.                                              */
+} DMX_PROFILE_TYPE;
+
+/**
+ *  \enum PSEUDO_SURROUND_MODE
+ *
+ *  Valid value list for parameter ::DMX_PSEUDO_SURROUND_MODE.
+ */
+typedef enum {
+  NEVER_DO_PS_DMX =
+      -1, /*!< Ignore any metadata and do never create a pseudo surround
+               compatible downmix. (Default)                             */
+  AUTO_PS_DMX = 0, /*!< Create a pseudo surround compatible downmix only if
+                        signalled in bitstreams meta data. */
+  FORCE_PS_DMX =
+      1 /*!< Always create a pseudo surround compatible downmix.
+             CAUTION: This can lead to excessive signal cancellations
+             and signal level differences for non-compatible signals.  */
+} PSEUDO_SURROUND_MODE;
+
+/**
+ *  \enum DUAL_CHANNEL_MODE
+ *
+ *  Valid value list for parameter ::DMX_DUAL_CHANNEL_MODE.
+ */
+typedef enum {
+  STEREO_MODE = 0x0, /*!< Leave stereo signals as they are. */
+  CH1_MODE = 0x1,    /*!< Create a dual mono output signal from channel 1.    */
+  CH2_MODE = 0x2,    /*!< Create a dual mono output signal from channel 2.    */
+  MIXED_MODE = 0x3   /*!< Create a dual mono output signal by mixing the two
+                          channels.   */
+} DUAL_CHANNEL_MODE;
+
+#define DMX_PCM FIXP_DBL
+#define DMX_PCMF FIXP_DBL
+#define DMX_PCM_BITS DFRACT_BITS
+#define FX_DMX2FX_PCM(x) FX_DBL2FX_PCM((FIXP_DBL)(x))
+
+/* ------------------------ *
+ *     MODULES INTERFACE:   *
+ * ------------------------ */
+typedef struct PCM_DMX_INSTANCE *HANDLE_PCM_DOWNMIX;
+
+/*! \addtogroup pcmDmxResetFlags Modules reset flags
+ *  Macros that can be used as parameter for function pcmDmx_Reset() to specify
+ * which parts of the module shall be reset.
+ *  @{
+ *
+ *  \def  PCMDMX_RESET_PARAMS
+ *  Only reset the user specific parameters that have been modified with
+ * pcmDmx_SetParam().
+ *
+ *  \def  PCMDMX_RESET_BS_DATA
+ *  Delete the meta data that has been fed with the appropriate interface
+ * functions.
+ *
+ *  \def  PCMDMX_RESET_FULL
+ *  Reset the complete module instance to the state after pcmDmx_Open() had been
+ * called.
+ */
+#define PCMDMX_RESET_PARAMS (1)
+#define PCMDMX_RESET_BS_DATA (2)
+#define PCMDMX_RESET_FULL (PCMDMX_RESET_PARAMS | PCMDMX_RESET_BS_DATA)
+/*! @} */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Open and initialize an instance of the PCM downmix module
+ * @param[out] pSelf  Pointer to a buffer receiving the handle of the new
+ *instance.
+ * @returns           Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_Open(HANDLE_PCM_DOWNMIX *pSelf);
+
+/** Set one parameter for a single instance of the PCM downmix module.
+ * @param[in] self   Handle of PCM downmix instance.
+ * @param[in] param  Parameter to be set. Can be one from the ::PCMDMX_PARAM
+ *list.
+ * @param[in] value  Parameter value.
+ * @returns          Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_SetParam(HANDLE_PCM_DOWNMIX self, const PCMDMX_PARAM param,
+                             const INT value);
+
+/** Get one parameter value of a single PCM downmix module instance.
+ * @param[in]  self    Handle of PCM downmix module instance.
+ * @param[in]  param   Parameter to query. Can be one from the ::PCMDMX_PARAM
+ *list.
+ * @param[out] pValue  Pointer to buffer receiving the parameter value.
+ * @returns            Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_GetParam(HANDLE_PCM_DOWNMIX self, const PCMDMX_PARAM param,
+                             INT *const pValue);
+
+/** \cond
+ *  Extract relevant downmix meta-data directly from a given bitstream. The
+ *function can handle both data specified in ETSI TS 101 154 or ISO/IEC
+ *14496-3:2009/Amd.4:2013.
+ * @param[in] self         Handle of PCM downmix instance.
+ * @param[in] hBitStream   Handle of FDK bitstream buffer.
+ * @param[in] ancDataBits  Length of ancillary data in bits.
+ * @param[in] isMpeg2      Flag indicating wheter the ancillary data is from a
+ *MPEG-1/2 or a MPEG-4 stream.
+ * @returns                Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_Parse(HANDLE_PCM_DOWNMIX self,
+                          HANDLE_FDK_BITSTREAM hBitStream, UINT ancDataBits,
+                          int isMpeg2);
+/** \endcond */
+
+/** Read from a given ancillary data buffer and extract the relevant downmix
+ *meta-data. The function can handle both data specified in ETSI TS 101 154 or
+ *ISO/IEC 14496-3:2009/Amd.4:2013.
+ * @param[in] self          Handle of PCM downmix instance.
+ * @param[in] pAncDataBuf   Pointer to ancillary buffer holding the data.
+ * @param[in] ancDataBytes  Size of ancillary data in bytes.
+ * @param[in] isMpeg2       Flag indicating wheter the ancillary data is from a
+ *MPEG-1/2 or a MPEG-4 stream.
+ * @returns                 Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_ReadDvbAncData(HANDLE_PCM_DOWNMIX self, UCHAR *pAncDataBuf,
+                                   UINT ancDataBytes, int isMpeg2);
+
+/** Set the matrix mixdown information extracted from the PCE of an AAC
+ *bitstream.
+ * @param[in] self                  Handle of PCM downmix instance.
+ * @param[in] matrixMixdownPresent  Matrix mixdown index present flag extracted
+ *from PCE.
+ * @param[in] matrixMixdownIdx      The 2 bit matrix mixdown index extracted
+ *from PCE.
+ * @param[in] pseudoSurroundEnable  The pseudo surround enable flag extracted
+ *from PCE.
+ * @returns                         Returns an error code of type
+ *::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_SetMatrixMixdownFromPce(HANDLE_PCM_DOWNMIX self,
+                                            int matrixMixdownPresent,
+                                            int matrixMixdownIdx,
+                                            int pseudoSurroundEnable);
+
+/** Reset the module.
+ * @param[in] self   Handle of PCM downmix instance.
+ * @param[in] flags  Flags telling which parts of the module shall be reset.
+ *                   See \ref pcmDmxResetFlags for details.
+ * @returns          Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_Reset(HANDLE_PCM_DOWNMIX self, UINT flags);
+
+/** Create a mixdown, bypass or extend the output signal depending on the
+ *modules settings and the respective given input configuration.
+ *
+ * \param[in]     self            Handle of PCM downmix module instance.
+ * \param[in,out] pPcmBuf         Pointer to time buffer with PCM samples.
+ * \param[in]     pcmBufSize      Size of pPcmBuf buffer.
+ * \param[in]     frameSize       The I/O block size which is the number of samples per channel.
+ * \param[in,out] nChannels       Pointer to buffer that holds the number of input channels and
+ *                                where the amount of output channels is written
+ *to.
+ * \param[in]     fInterleaved    Input and output samples are processed interleaved.
+ * \param[in,out] channelType     Array were the corresponding channel type for each output audio
+ *                                channel is stored into.
+ * \param[in,out] channelIndices  Array were the corresponding channel type index for each output
+ *                                audio channel is stored into.
+ * \param[in]     mapDescr        Pointer to a FDK channel mapping descriptor that contains the
+ *                                channel mapping to be used.
+ * \param[out]    pDmxOutScale    Pointer on a field receiving the scale factor that has to be
+ *                                applied on all samples afterwards. If the
+ *handed pointer is NULL the final scaling is done internally.
+ * @returns                       Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_ApplyFrame(HANDLE_PCM_DOWNMIX self, DMX_PCM *pPcmBuf,
+                               const int pcmBufSize, UINT frameSize,
+                               INT *nChannels, INT fInterleaved,
+                               AUDIO_CHANNEL_TYPE channelType[],
+                               UCHAR channelIndices[],
+                               const FDK_channelMapDescr *const mapDescr,
+                               INT *pDmxOutScale);
+
+/** Close an instance of the PCM downmix module.
+ * @param[in,out] pSelf  Pointer to a buffer containing the handle of the
+ *instance.
+ * @returns              Returns an error code of type ::PCMDMX_ERROR.
+ **/
+PCMDMX_ERROR pcmDmx_Close(HANDLE_PCM_DOWNMIX *pSelf);
+
+/** Get library info for this module.
+ * @param[out] info  Pointer to an allocated LIB_INFO structure.
+ * @returns          Returns an error code of type ::PCMDMX_ERROR.
+ */
+PCMDMX_ERROR pcmDmx_GetLibInfo(LIB_INFO *info);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PCMDMX_LIB_H */