text: /* -----------------------------------------------------------------------------
  Software License for The Fraunhofer FDK AAC Codec Library for Android
  
  © Copyright  1995 - 2019 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
  ----------------------------------------------------------------------------- */
  
  /**************************** AAC decoder library ******************************
  
     Author(s):   Manuel Jander
  
     Description:
  
  *******************************************************************************/
  
  #ifndef AACDECODER_LIB_H
  #define AACDECODER_LIB_H
  
  /**
   * \file   aacdecoder_lib.h
   * \brief  FDK AAC decoder library interface header file.
   *
  
  \page INTRO Introduction
  
  
  \section SCOPE Scope
  
  This document describes the high-level application interface and usage of the
  ISO/MPEG-2/4 AAC Decoder library developed by the Fraunhofer Institute for
  Integrated Circuits (IIS). Depending on the library configuration, decoding of
  AAC-LC (Low-Complexity), HE-AAC (High-Efficiency AAC v1 and v2), AAC-LD
  (Low-Delay) and AAC-ELD (Enhanced Low-Delay) is implemented.
  
  All references to SBR (Spectral Band Replication) are only applicable to HE-AAC
  and AAC-ELD configurations of the FDK library. All references to PS (Parametric
  Stereo) are only applicable to HE-AAC v2 decoder configuration of the library.
  
  \section DecoderBasics Decoder Basics
  
  This document can only give a rough overview about the ISO/MPEG-2, ISO/MPEG-4
  AAC audio and MPEG-D USAC coding standards. To understand all details referenced
  in this document, you are encouraged to read the following documents.
  
  - ISO/IEC 13818-7 (MPEG-2 AAC) Standard, defines the syntax of MPEG-2 AAC audio
  bitstreams.
  - ISO/IEC 14496-3 (MPEG-4 AAC, subpart 1 and 4) Standard, defines the syntax of
  MPEG-4 AAC audio bitstreams.
  - ISO/IEC 23003-3 (MPEG-D USAC), defines MPEG-D USAC unified speech and audio
  codec.
  - Lutzky, Schuller, Gayer, Kr&auml;mer, Wabnik, "A guideline to audio codec
  delay", 116th AES Convention, May 8, 2004
  
  In short, MPEG Advanced Audio Coding is based on a time-to-frequency mapping of
  the signal. The signal is partitioned into overlapping time portions and
  transformed into frequency domain. The spectral components are then quantized
  and coded using a highly efficient coding scheme.\n Encoded MPEG-2 and MPEG-4
  AAC audio bitstreams are composed of frames. Contrary to MPEG-1/2 Layer-3 (mp3),
  the length of individual frames is not restricted to a fixed number of bytes,
  but can take any length between 1 and 768 bytes.
  
  In addition to the above mentioned frequency domain coding mode, MPEG-D USAC
  also employs a time domain Algebraic Code-Excited Linear Prediction (ACELP)
  speech coder core. This operating mode is selected by the encoder in order to
  achieve the optimum audio quality for different content type. Several
  enhancements allow achieving higher quality at lower bit rates compared to
  MPEG-4 HE-AAC.
  
  
  \page LIBUSE Library Usage
  
  
  \section InterfaceDescritpion API Description
  
  All API header files are located in the folder /include of the release package.
  The contents of each file is described in detail in this document. All header
  files are provided for usage in specific C/C++ programs. The main AAC decoder
  library API functions are located in aacdecoder_lib.h header file.
  
  
  \section Calling_Sequence Calling Sequence
  
  The following sequence is necessary for proper decoding of ISO/MPEG-2/4 AAC,
  HE-AAC v2, or MPEG-D USAC bitstreams. In the following description, input stream
  read and output write function details are left out, since they may be
  implemented in a variety of configurations depending on the user's specific
  requirements.
  
  
  -# Call aacDecoder_Open() to open and retrieve a handle to a new AAC decoder
  instance. \code aacDecoderInfo = aacDecoder_Open(transportType, nrOfLayers);
  \endcode
  -# If out-of-band config data (Audio Specific Config (ASC) or Stream Mux Config
  (SMC)) is available, call aacDecoder_ConfigRaw() to pass this data to the
  decoder before beginning the decoding process. If this data is not available in
  advance, the decoder will configure itself while decoding, during the
  aacDecoder_DecodeFrame() function call.
  -# Begin decoding loop.
  \code
  do {
  \endcode
  -# Read data from bitstream file or stream buffer in to the driver program
  working memory (a client-supplied input buffer "inBuffer" in framework). This
  buffer will be used to load AAC bitstream data to the decoder.  Only when all
  data in this buffer has been processed will the decoder signal an empty buffer.
  -# Call aacDecoder_Fill() to fill the decoder's internal bitstream input buffer
  with the client-supplied bitstream input buffer. Note, if the data loaded in to
  the internal buffer is not sufficient to decode a frame,
  aacDecoder_DecodeFrame() will return ::AAC_DEC_NOT_ENOUGH_BITS until a
  sufficient amount of data is loaded in to the internal buffer. For streaming
  formats (ADTS, LOAS), it is acceptable to load more than one frame to the
  decoder. However, for packed based formats, only one frame may be loaded to the
  decoder per aacDecoder_DecodeFrame() call. For least amount of communication
  delay, fill and decode should be performed on a frame by frame basis. \code
      ErrorStatus = aacDecoder_Fill(aacDecoderInfo, inBuffer, bytesRead,
  bytesValid); \endcode
  -# Call aacDecoder_DecodeFrame(). This function decodes one frame and writes
  decoded PCM audio data to a client-supplied buffer. It is the client's
  responsibility to allocate a buffer which is large enough to hold the decoded
  output data. \code ErrorStatus = aacDecoder_DecodeFrame(aacDecoderInfo,
  TimeData, OUT_BUF_SIZE, flags); \endcode If the bitstream configuration (number
  of channels, sample rate, frame size) is not known a priori, you may call
  aacDecoder_GetStreamInfo() to retrieve a structure that contains this
  information. You may use this data to initialize an audio output device. \code
      p_si = aacDecoder_GetStreamInfo(aacDecoderInfo);
  \endcode
  -# Repeat steps 5 to 7 until no data is available to decode any more, or in case
  of error. \code } while (bytesRead[0] > 0 || doFlush || doBsFlush ||
  forceContinue); \endcode
  -# Call aacDecoder_Close() to de-allocate all AAC decoder and transport layer
  structures. \code aacDecoder_Close(aacDecoderInfo); \endcode
  
  \image latex decode.png "Decode calling sequence" width=11cm
  
  \image latex change_source.png "Change data source sequence" width=5cm
  
  \image latex conceal.png "Error concealment sequence" width=14cm
  
  \subsection Error_Concealment_Sequence Error Concealment Sequence
  
  There are different strategies to handle bit stream errors. Depending on the
  system properties the product designer might choose to take different actions in
  case a bit error occurs. In many cases the decoder might be able to do
  reasonable error concealment without the need of any additional actions from the
  system. But in some cases its not even possible to know how many decoded PCM
  output samples are required to fill the gap due to the data error, then the
  software surrounding the decoder must deal with the situation. The most simple
  way would be to just stop audio playback and resume once enough bit stream data
  and/or buffered output samples are available. More sophisticated designs might
  also be able to deal with sender/receiver clock drifts or data drop outs by
  using a closed loop control of FIFO fulness levels. The chosen strategy depends
  on the final product requirements.
  
  The error concealment sequence diagram illustrates the general execution paths
  for error handling.
  
  The macro IS_OUTPUT_VALID(err) can be used to identify if the audio output
  buffer contains valid audio either from error free bit stream data or successful
  error concealment. In case the result is false, the decoder output buffer does
  not contain meaningful audio samples and should not be passed to any output as
  it is. Most likely in case that a continuous audio output PCM stream is
  required, the output buffer must be filled with audio data from the calling
  framework. This might be e.g. an appropriate number of samples all zero.
  
  If error code ::AAC_DEC_TRANSPORT_SYNC_ERROR is returned by the decoder, under
  some particular conditions it is possible to estimate lost frames due to the bit
  stream error. In that case the bit stream is required to have a constant
  bitrate, and compatible transport type. Audio samples for the lost frames can be
  obtained by calling aacDecoder_DecodeFrame() with flag ::AACDEC_CONCEAL set
  n-times where n is the count of lost frames. Please note that the decoder has to
  have encountered valid configuration data at least once to be able to generate
  concealed data, because at the minimum the sampling rate, frame size and amount
  of audio channels needs to be known.
  
  If it is not possible to get an estimation of lost frames then a constant
  fullness of the audio output buffer can be achieved by implementing different
  FIFO control techniques e.g. just stop taking of samples from the buffer to
  avoid underflow or stop filling new data to the buffer to avoid overflow. But
  this techniques are out of scope of this document.
  
  For a detailed description of a specific error code please refer also to
  ::AAC_DECODER_ERROR.
  
  \section BufferSystem Buffer System
  
  There are three main buffers in an AAC decoder application. One external input
  buffer to hold bitstream data from file I/O or elsewhere, one decoder-internal
  input buffer, and one to hold the decoded output PCM sample data. In resource
  limited applications, the output buffer may be reused as an external input
  buffer prior to the subsequence aacDecoder_Fill() function call.
  
  To feed the data to the decoder-internal input buffer, use the
  function aacDecoder_Fill(). This function returns important information
  regarding the number of bytes in the external input buffer that have not yet
  been copied into the internal input buffer (variable bytesValid). Once the
  external buffer has been fully copied, it can be completely re-filled again. In
  case you wish to refill the buffer while there are unprocessed bytes (bytesValid
  is unequal 0), you should preserve the unconsumed data. However, we recommend to
  refill the buffer only when bytesValid returns 0.
  
  The bytesValid parameter is an input and output parameter to the FDK decoder. As
  an input, it signals how many valid bytes are available in the external buffer.
  After consumption of the external buffer using aacDecoder_Fill() function, the
  bytesValid parameter indicates if any of the bytes in the external buffer were
  not consumed.
  
  \image latex dec_buffer.png "Life cycle of the external input buffer" width=9cm
  
  \page OutputFormat Decoder audio output
  
  \section OutputFormatObtaining Obtaining channel mapping information
  
  The decoded audio output format is indicated by a set of variables of the
  CStreamInfo structure. While the struct members sampleRate, frameSize and
  numChannels might be self explanatory, pChannelType and pChannelIndices require
  some further explanation.
  
  These two arrays indicate the configuration of channel data within the output
  buffer. Both arrays have CStreamInfo::numChannels number of cells. Each cell of
  pChannelType indicates the channel type, which is described in the enum
  ::AUDIO_CHANNEL_TYPE (defined in FDK_audio.h). The cells of pChannelIndices
  indicate the sub index among the channels starting with 0 among channels of the
  same audio channel type.
  
  The indexing scheme is structured as defined in MPEG-2/4 Standards. Indices
  start from the front direction (a center channel if available, will always be
  index 0) and increment, starting with the left side, pairwise (e.g. L, R) and
  from front to back (Front L, Front R, Surround L, Surround R). For detailed
  explanation, please refer to ISO/IEC 13818-7:2005(E), chapter 8.5.3.2.
  
  In case a Program Config is included in the audio configuration, the channel
  mapping described within it will be adopted.
  
  The examples below explain these aspects in detail.
  
  \section OutputFormatChange Changing the audio output format
  
  For MPEG-4 audio the channel order can be changed at runtime through the
  parameter
  ::AAC_PCM_OUTPUT_CHANNEL_MAPPING. See the description of those
  parameters and the decoder library function aacDecoder_SetParam() for more
  detail.
  
  \section OutputFormatExample Channel mapping examples
  
  The following examples illustrate the location of individual audio samples in
  the audio buffer that is passed to aacDecoder_DecodeFrame() and the expected
  data in the CStreamInfo structure which can be obtained by calling
  aacDecoder_GetStreamInfo().
  
  \subsection ExamplesStereo Stereo
  
  In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
  a AAC-LC bit stream which has channelConfiguration = 2 in its audio specific
  config would lead to the following values in CStreamInfo:
  
  CStreamInfo::numChannels = 2
  
  CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT }
  
  CStreamInfo::pChannelIndices = { 0, 1 }
  
  The output buffer will be formatted as follows:
  
  \verbatim
    <left sample 0>  <left sample 1>  <left sample 2>  ... <left sample N>
    <right sample 0> <right sample 1> <right sample 2> ... <right sample N>
  \endverbatim
  
  Where N equals to CStreamInfo::frameSize .
  
  \subsection ExamplesSurround Surround 5.1
  
  In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
  a AAC-LC bit stream which has channelConfiguration = 6 in its audio specific
  config, would lead to the following values in CStreamInfo:
  
  CStreamInfo::numChannels = 6
  
  CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_FRONT, ::ACT_LFE,
  ::ACT_BACK, ::ACT_BACK }
  
  CStreamInfo::pChannelIndices = { 1, 2, 0, 0, 0, 1 }
  
  Since ::AAC_PCM_OUTPUT_CHANNEL_MAPPING is 1, WAV file channel ordering will be
  used. For a 5.1 channel scheme, thus the channels would be: front left, front
  right, center, LFE, surround left, surround right. Thus the third channel is the
  center channel, receiving the index 0. The other front channels are front left,
  front right being placed as first and second channels with indices 1 and 2
  correspondingly. There is only one LFE, placed as the fourth channel and index
  0. Finally both surround channels get the type definition ACT_BACK, and the
  indices 0 and 1.
  
  The output buffer will be formatted as follows:
  
  \verbatim
  <front left sample 0> <front right sample 0>
  <center sample 0> <LFE sample 0>
  <surround left sample 0> <surround right sample 0>
  
  <front left sample 1> <front right sample 1>
  <center sample 1> <LFE sample 1>
  <surround left sample 1> <surround right sample 1>
  
  ...
  
  <front left sample N> <front right sample N>
  <center sample N> <LFE sample N>
  <surround left sample N> <surround right sample N>
  \endverbatim
  
  Where N equals to CStreamInfo::frameSize .
  
  \subsection ExamplesArib ARIB coding mode 2/1
  
  In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
  in case of a ARIB bit stream using coding mode 2/1 as described in ARIB STD-B32
  Part 2 Version 2.1-E1, page 61, would lead to the following values in
  CStreamInfo:
  
  CStreamInfo::numChannels = 3
  
  CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_BACK }
  
  CStreamInfo::pChannelIndices = { 0, 1, 0 }
  
  The audio channels will be placed as follows in the audio output buffer:
  
  \verbatim
  <front left sample 0> <front right sample 0>  <mid surround sample 0>
  
  <front left sample 1> <front right sample 1> <mid surround sample 1>
  
  ...
  
  <front left sample N> <front right sample N> <mid surround sample N>
  
  Where N equals to CStreamInfo::frameSize .
  
  \endverbatim
  
  */
  
  #include "machine_type.h"
  #include "FDK_audio.h"
  
  #include "genericStds.h"
  
  #define AACDECODER_LIB_VL0 3
  #define AACDECODER_LIB_VL1 2
  #define AACDECODER_LIB_VL2 0
  
  /**
   * \brief  AAC decoder error codes.
   */
  typedef enum {
    AAC_DEC_OK =
        0x0000, /*!< No error occurred. Output buffer is valid and error free. */
    AAC_DEC_OUT_OF_MEMORY =
        0x0002, /*!< Heap returned NULL pointer. Output buffer is invalid. */
    AAC_DEC_UNKNOWN =
        0x0005, /*!< Error condition is of unknown reason, or from a another
                   module. Output buffer is invalid. */
  
    /* Synchronization errors. Output buffer is invalid. */
    aac_dec_sync_error_start = 0x1000,
    AAC_DEC_TRANSPORT_SYNC_ERROR = 0x1001, /*!< The transport decoder had
                                              synchronization problems. Do not
                                              exit decoding. Just feed new
                                                bitstream data. */
    AAC_DEC_NOT_ENOUGH_BITS = 0x1002, /*!< The input buffer ran out of bits. */
    aac_dec_sync_error_end = 0x1FFF,
  
    /* Initialization errors. Output buffer is invalid. */
    aac_dec_init_error_start = 0x2000,
    AAC_DEC_INVALID_HANDLE =
        0x2001, /*!< The handle passed to the function call was invalid (NULL). */
    AAC_DEC_UNSUPPORTED_AOT =
        0x2002, /*!< The AOT found in the configuration is not supported. */
    AAC_DEC_UNSUPPORTED_FORMAT =
        0x2003, /*!< The bitstream format is not supported.  */
    AAC_DEC_UNSUPPORTED_ER_FORMAT =
        0x2004, /*!< The error resilience tool format is not supported. */
    AAC_DEC_UNSUPPORTED_EPCONFIG =
        0x2005, /*!< The error protection format is not supported. */
    AAC_DEC_UNSUPPORTED_MULTILAYER =
        0x2006, /*!< More than one layer for AAC scalable is not supported. */
    AAC_DEC_UNSUPPORTED_CHANNELCONFIG =
        0x2007, /*!< The channel configuration (either number or arrangement) is
                   not supported. */
    AAC_DEC_UNSUPPORTED_SAMPLINGRATE = 0x2008, /*!< The sample rate specified in
                                                  the configuration is not
                                                  supported. */
    AAC_DEC_INVALID_SBR_CONFIG =
        0x2009, /*!< The SBR configuration is not supported. */
    AAC_DEC_SET_PARAM_FAIL = 0x200A,  /*!< The parameter could not be set. Either
                                         the value was out of range or the
                                         parameter does  not exist. */
    AAC_DEC_NEED_TO_RESTART = 0x200B, /*!< The decoder needs to be restarted,
                                         since the required configuration change
                                         cannot be performed. */
    AAC_DEC_OUTPUT_BUFFER_TOO_SMALL =
        0x200C, /*!< The provided output buffer is too small. */
    aac_dec_init_error_end = 0x2FFF,
  
    /* Decode errors. Output buffer is valid but concealed. */
    aac_dec_decode_error_start = 0x4000,
    AAC_DEC_TRANSPORT_ERROR =
        0x4001, /*!< The transport decoder encountered an unexpected error. */
    AAC_DEC_PARSE_ERROR = 0x4002, /*!< Error while parsing the bitstream. Most
                                     probably it is corrupted, or the system
                                     crashed. */
    AAC_DEC_UNSUPPORTED_EXTENSION_PAYLOAD =
        0x4003, /*!< Error while parsing the extension payload of the bitstream.
                   The extension payload type found is not supported. */
    AAC_DEC_DECODE_FRAME_ERROR = 0x4004, /*!< The parsed bitstream value is out of
                                            range. Most probably the bitstream is
                                            corrupt, or the system crashed. */
    AAC_DEC_CRC_ERROR = 0x4005,          /*!< The embedded CRC did not match. */
    AAC_DEC_INVALID_CODE_BOOK = 0x4006,  /*!< An invalid codebook was signaled.
                                            Most probably the bitstream is corrupt,
                                            or the system  crashed. */
    AAC_DEC_UNSUPPORTED_PREDICTION =
        0x4007, /*!< Predictor found, but not supported in the AAC Low Complexity
                   profile. Most probably the bitstream is corrupt, or has a wrong
                   format. */
    AAC_DEC_UNSUPPORTED_CCE = 0x4008, /*!< A CCE element was found which is not
                                         supported. Most probably the bitstream is
                                         corrupt, or has a wrong format. */
    AAC_DEC_UNSUPPORTED_LFE = 0x4009, /*!< A LFE element was found which is not
                                         supported. Most probably the bitstream is
                                         corrupt, or has a wrong format. */
    AAC_DEC_UNSUPPORTED_GAIN_CONTROL_DATA =
        0x400A, /*!< Gain control data found but not supported. Most probably the
                   bitstream is corrupt, or has a wrong format. */
    AAC_DEC_UNSUPPORTED_SBA =
        0x400B, /*!< SBA found, but currently not supported in the BSAC profile.
                 */
    AAC_DEC_TNS_READ_ERROR = 0x400C, /*!< Error while reading TNS data. Most
                                        probably the bitstream is corrupt or the
                                        system crashed. */
    AAC_DEC_RVLC_ERROR =
        0x400D, /*!< Error while decoding error resilient data. */
    aac_dec_decode_error_end = 0x4FFF,
    /* Ancillary data errors. Output buffer is valid. */
    aac_dec_anc_data_error_start = 0x8000,
    AAC_DEC_ANC_DATA_ERROR =
        0x8001, /*!< Non severe error concerning the ancillary data handling. */
    AAC_DEC_TOO_SMALL_ANC_BUFFER = 0x8002,  /*!< The registered ancillary data
                                               buffer is too small to receive the
                                               parsed data. */
    AAC_DEC_TOO_MANY_ANC_ELEMENTS = 0x8003, /*!< More than the allowed number of
                                               ancillary data elements should be
                                               written to buffer. */
    aac_dec_anc_data_error_end = 0x8FFF
  
  } AAC_DECODER_ERROR;
  
  /** Macro to identify initialization errors. Output buffer is invalid. */
  #define IS_INIT_ERROR(err)                                                    \
    ((((err) >= aac_dec_init_error_start) && ((err) <= aac_dec_init_error_end)) \
         ? 1                                                                    \
         : 0)
  /** Macro to identify decode errors. Output buffer is valid but concealed. */
  #define IS_DECODE_ERROR(err)                 \
    ((((err) >= aac_dec_decode_error_start) && \
      ((err) <= aac_dec_decode_error_end))     \
         ? 1                                   \
         : 0)
  /**
   * Macro to identify if the audio output buffer contains valid samples after
   * calling aacDecoder_DecodeFrame(). Output buffer is valid but can be
   * concealed.
   */
  #define IS_OUTPUT_VALID(err) (((err) == AAC_DEC_OK) || IS_DECODE_ERROR(err))
  
  /*! \enum  AAC_MD_PROFILE
   *  \brief The available metadata profiles which are mostly related to downmixing. The values define the arguments
   *         for the use with parameter ::AAC_METADATA_PROFILE.
   */
  typedef enum {
    AAC_MD_PROFILE_MPEG_STANDARD =
        0, /*!< The standard profile creates a mixdown signal based on the
              advanced downmix metadata (from a DSE). The equations and default
              values are defined in ISO/IEC 14496:3 Ammendment 4. Any other
              (legacy) downmix metadata will be ignored. No other parameter will
              be modified.         */
    AAC_MD_PROFILE_MPEG_LEGACY =
        1, /*!< This profile behaves identical to 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 as defined in
              ISO/IEC 14496:3 AMD 4. The profile can be used to support legacy
              digital TV (e.g. DVB) streams.           */
    AAC_MD_PROFILE_MPEG_LEGACY_PRIO =
        2, /*!< Similar to the ::AAC_MD_PROFILE_MPEG_LEGACY profile but if both
              the advanced (ISO/IEC 14496:3 AMD 4) and the legacy (PCE) MPEG
              downmix metadata are available the latter will be applied.
            */
    AAC_MD_PROFILE_ARIB_JAPAN =
        3 /*!< Downmix creation as described in ABNT NBR 15602-2. But if advanced
               downmix metadata (ISO/IEC 14496:3 AMD 4) is available it will be
               preferred because of the higher resolutions. In addition the
             metadata expiry time will be set to the value defined in the ARIB
             standard (see ::AAC_METADATA_EXPIRY_TIME).
           */
  } AAC_MD_PROFILE;
  
  /*! \enum  AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS
   *  \brief Options for handling of DRC parameters, if presentation mode is not indicated in bitstream
   */
  typedef enum {
    AAC_DRC_PARAMETER_HANDLING_DISABLED = -1, /*!< DRC parameter handling
                                                 disabled, all parameters are
                                                 applied as requested. */
    AAC_DRC_PARAMETER_HANDLING_ENABLED =
        0, /*!< Apply changes to requested DRC parameters to prevent clipping. */
    AAC_DRC_PRESENTATION_MODE_1_DEFAULT =
        1, /*!< Use DRC presentation mode 1 as default (e.g. for Nordig) */
    AAC_DRC_PRESENTATION_MODE_2_DEFAULT =
        2 /*!< Use DRC presentation mode 2 as default (e.g. for DTG DBook) */
  } AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS;
  
  /**
   * \brief AAC decoder setting parameters
   */
  typedef enum {
    AAC_PCM_DUAL_CHANNEL_OUTPUT_MODE =
        0x0002, /*!< Defines how the decoder processes two channel signals: \n
                     0: Leave both signals as they are (default). \n
                     1: Create a dual mono output signal from channel 1. \n
                     2: Create a dual mono output signal from channel 2. \n
                     3: Create a dual mono output signal by mixing both channels
                   (L' = R' = 0.5*Ch1 + 0.5*Ch2). */
    AAC_PCM_OUTPUT_CHANNEL_MAPPING =
        0x0003, /*!< Output buffer channel ordering. 0: MPEG PCE style order, 1:
                   WAV file channel order (default). */
    AAC_PCM_LIMITER_ENABLE =
        0x0004,                           /*!< Enable signal level limiting. \n
                                               -1: Auto-config. Enable limiter for all
                                             non-lowdelay configurations by default. \n
                                                0: Disable limiter in general. \n
                                                1: Enable limiter always.
                                               It is recommended to call the decoder
                                             with a AACDEC_CLRHIST flag to reset all
                                             states when      the limiter switch is changed
                                             explicitly. */
    AAC_PCM_LIMITER_ATTACK_TIME = 0x0005, /*!< Signal level limiting attack time
                                             in ms. Default configuration is 15
                                             ms. Adjustable range from 1 ms to 15
                                             ms. */
    AAC_PCM_LIMITER_RELEAS_TIME = 0x0006, /*!< Signal level limiting release time
                                             in ms. Default configuration is 50
                                             ms. Adjustable time must be larger
                                             than 0 ms. */
    AAC_PCM_MIN_OUTPUT_CHANNELS =
        0x0011, /*!< Minimum number of PCM output channels. If higher than the
                   number of encoded audio channels, a simple channel extension is
                   applied (see note 4 for exceptions). \n -1, 0: Disable channel
                   extension feature. The decoder output contains the same number
                   of channels as the encoded bitstream. \n 1:    This value is
                   currently needed only together with the mix-down feature. See
                            ::AAC_PCM_MAX_OUTPUT_CHANNELS and note 2 below. \n
                      2:    Encoded mono signals will be duplicated to achieve a
                   2/0/0.0 channel output configuration. \n 6:    The decoder
                   tries to reorder encoded signals with less than six channels to
                   achieve a 3/0/2.1 channel output signal. Missing channels will
                   be filled with a zero signal. If reordering is not possible the
                   empty channels will simply be appended. Only available if
                   instance is configured to support multichannel output. \n 8:
                   The decoder tries to reorder encoded signals with less than
                   eight channels to achieve a 3/0/4.1 channel output signal.
                   Missing channels will be filled with a zero signal. If
                   reordering is not possible the empty channels will simply be
                            appended. Only available if instance is configured to
                   support multichannel output.\n NOTE: \n
                       1. The channel signaling (CStreamInfo::pChannelType and
                   CStreamInfo::pChannelIndices) will not be modified. Added empty
                   channels will be signaled with channel type
                          AUDIO_CHANNEL_TYPE::ACT_NONE. \n
                       2. If the parameter value is greater than that of
                   ::AAC_PCM_MAX_OUTPUT_CHANNELS both will be set to the same
                   value. \n
                       3. This parameter will be ignored if the number of encoded
                   audio channels is greater than 8. */
    AAC_PCM_MAX_OUTPUT_CHANNELS =
        0x0012, /*!< Maximum number of PCM output channels. If lower than the
                   number of encoded audio channels, downmixing is applied
                   accordingly (see note 5 for exceptions). If dedicated metadata
                   is available in the stream it will be used to achieve better
                   mixing results. \n -1, 0: Disable downmixing feature. The
                   decoder output contains the same number of channels as the
                   encoded bitstream. \n 1:    All encoded audio configurations
                   with more than one channel will be mixed down to one mono
                   output signal. \n 2:    The decoder performs a stereo mix-down
                   if the number encoded audio channels is greater than two. \n 6:
                   If the number of encoded audio channels is greater than six the
                   decoder performs a mix-down to meet the target output
                   configuration of 3/0/2.1 channels. Only available if instance
                   is configured to support multichannel output. \n 8:    This
                   value is currently needed only together with the channel
                   extension feature. See ::AAC_PCM_MIN_OUTPUT_CHANNELS and note 2
                   below. Only available if instance is configured to support
                   multichannel output. \n NOTE: \n
                       1. Down-mixing of any seven or eight channel configuration
                   not defined in ISO/IEC 14496-3 PDAM 4 is not supported by this
                   software version. \n
                       2. If the parameter value is greater than zero but smaller
                   than ::AAC_PCM_MIN_OUTPUT_CHANNELS both will be set to same
                   value. \n
                       3. This parameter will be ignored if the number of encoded
                   audio channels is greater than 8. */
    AAC_METADATA_PROFILE =
        0x0020, /*!< See ::AAC_MD_PROFILE for all available values. */
    AAC_METADATA_EXPIRY_TIME = 0x0021, /*!< Defines the time in ms after which all
                                          the bitstream associated meta-data (DRC,
                                          downmix coefficients, ...) will be reset
                                          to default if no update has been
                                          received. Negative values disable the
                                          feature. */
  
    AAC_CONCEAL_METHOD = 0x0100, /*!< Error concealment: Processing method. \n
                                      0: Spectral muting. \n
                                      1: Noise substitution (see ::CONCEAL_NOISE).
                                    \n 2: Energy interpolation (adds additional
                                    signal delay of one frame, see
                                    ::CONCEAL_INTER. only some AOTs are
                                    supported). \n */
    AAC_DRC_BOOST_FACTOR =
        0x0200, /*!< MPEG-4 / MPEG-D Dynamic Range Control (DRC): Scaling factor
                   for boosting gain values. Defines how the boosting DRC factors
                   (conveyed in the bitstream) will be applied to the decoded
                   signal. The valid values range from 0 (don't apply boost
                   factors) to 127 (fully apply boost factors). Default value is 0
                   for MPEG-4 DRC and 127 for MPEG-D DRC. */
    AAC_DRC_ATTENUATION_FACTOR = 0x0201, /*!< MPEG-4 / MPEG-D DRC: Scaling factor
                                            for attenuating gain values. Same as
                                              ::AAC_DRC_BOOST_FACTOR but for
                                            attenuating DRC factors. */
    AAC_DRC_REFERENCE_LEVEL =
        0x0202, /*!< MPEG-4 / MPEG-D DRC: Target reference level / decoder target
                   loudness.\n Defines the level below full-scale (quantized in
                   steps of 0.25dB) to which the output audio signal will be
                   normalized to by the DRC module.\n The parameter controls
                   loudness normalization for both MPEG-4 DRC and MPEG-D DRC. The
                   valid values range from 40 (-10 dBFS) to 127 (-31.75 dBFS).\n
                     Example values:\n
                     124 (-31 dBFS) for audio/video receivers (AVR) or other
                   devices allowing audio playback with high dynamic range,\n 96
                   (-24 dBFS) for TV sets or equivalent devices (default),\n 64
                   (-16 dBFS) for mobile devices where the dynamic range of audio
                   playback is restricted.\n Any value smaller than 0 switches off
                   loudness normalization and MPEG-4 DRC. */
    AAC_DRC_HEAVY_COMPRESSION =
        0x0203, /*!< MPEG-4 DRC: En-/Disable DVB specific heavy compression (aka
                   RF mode). If set to 1, the decoder will apply the compression
                   values from the DVB specific ancillary data field. At the same
                   time the MPEG-4 Dynamic Range Control tool will be disabled. By
                     default, heavy compression is disabled. */
    AAC_DRC_DEFAULT_PRESENTATION_MODE =
        0x0204, /*!< MPEG-4 DRC: Default presentation mode (DRC parameter
                   handling). \n Defines the handling of the DRC parameters boost
                   factor, attenuation factor and heavy compression, if no
                   presentation mode is indicated in the bitstream.\n For options,
                   see ::AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS.\n Default:
                   ::AAC_DRC_PARAMETER_HANDLING_DISABLED */
    AAC_DRC_ENC_TARGET_LEVEL =
        0x0205, /*!< MPEG-4 DRC: Encoder target level for light (i.e. not heavy)
                   compression.\n If known, this declares the target reference
                   level that was assumed at the encoder for calculation of
                   limiting gains. The valid values range from 0 (full-scale) to
                   127 (31.75 dB below full-scale). This parameter is used only
                   with ::AAC_DRC_PARAMETER_HANDLING_ENABLED and ignored
                   otherwise.\n Default: 127 (worst-case assumption).\n */
    AAC_UNIDRC_SET_EFFECT = 0x0206, /*!< MPEG-D DRC: Request a DRC effect type for
                                       selection of a DRC set.\n Supported indices
                                       are:\n -1: DRC off. Completely disables
                                       MPEG-D DRC.\n 0: None (default). Disables
                                       MPEG-D DRC, but automatically enables DRC
                                       if necessary to prevent clipping.\n 1: Late
                                       night\n 2: Noisy environment\n 3: Limited
                                       playback range\n 4: Low playback level\n 5:
                                       Dialog enhancement\n 6: General
                                       compression. Used for generally enabling
                                       MPEG-D DRC without particular request.\n */
    AAC_UNIDRC_ALBUM_MODE =
        0x0207, /*!<  MPEG-D DRC: Enable album mode. 0: Disabled (default), 1:
                   Enabled.\n Disabled album mode leads to application of gain
                   sequences for fading in and out, if provided in the
                   bitstream.\n Enabled album mode makes use of dedicated album
                   loudness information, if provided in the bitstream.\n */
    AAC_QMF_LOWPOWER =
        0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing mode. \n
                     -1: Use internal default. \n
                      0: Use complex QMF data mode. \n
                      1: Use real (low power) QMF data mode. \n */
    AAC_TPDEC_CLEAR_BUFFER =
        0x0603 /*!< Clear internal bit stream buffer of transport layers. The
                  decoder will start decoding at new data passed after this event
                  and any previous data is discarded. */
  
  } AACDEC_PARAM;
  
  /**
   * \brief This structure gives information about the currently decoded audio
   * data. All fields are read-only.
   */
  typedef struct {
    /* These five members are the only really relevant ones for the user. */
    INT sampleRate; /*!< The sample rate in Hz of the decoded PCM audio signal. */
    INT frameSize;  /*!< The frame size of the decoded PCM audio signal. \n
                         Typically this is: \n
                         1024 or 960 for AAC-LC \n
                         2048 or 1920 for HE-AAC (v2) \n
                         512 or 480 for AAC-LD and AAC-ELD \n
                         768, 1024, 2048 or 4096 for USAC  */
    INT numChannels; /*!< The number of output audio channels before the rendering
                        module, i.e. the original channel configuration. */
    AUDIO_CHANNEL_TYPE
    *pChannelType; /*!< Audio channel type of each output audio channel. */
    UCHAR *pChannelIndices; /*!< Audio channel index for each output audio
                               channel. See ISO/IEC 13818-7:2005(E), 8.5.3.2
                               Explicit channel mapping using a
                               program_config_element() */
    /* Decoder internal members. */
    INT aacSampleRate; /*!< Sampling rate in Hz without SBR (from configuration
                          info) divided by a (ELD) downscale factor if present. */
    INT profile; /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g.
                    MPEG-4)).               */
    AUDIO_OBJECT_TYPE
    aot; /*!< Audio Object Type (from ASC): is set to the appropriate value
            for MPEG-2 bitstreams (e. g. 2 for AAC-LC). */
    INT channelConfig; /*!< Channel configuration (0: PCE defined, 1: mono, 2:
                          stereo, ...                       */
    INT bitRate;       /*!< Instantaneous bit rate.                   */
    INT aacSamplesPerFrame;   /*!< Samples per frame for the AAC core (from ASC)
                                 divided by a (ELD) downscale factor if present. \n
                                   Typically this is (with a downscale factor of 1):
                                 \n   1024 or 960 for AAC-LC \n   512 or 480 for
                                 AAC-LD   and AAC-ELD         */
    INT aacNumChannels;       /*!< The number of audio channels after AAC core
                                 processing (before PS or MPS processing).       CAUTION: This
                                 are not the final number of output channels! */
    AUDIO_OBJECT_TYPE extAot; /*!< Extension Audio Object Type (from ASC)   */
    INT extSamplingRate; /*!< Extension sampling rate in Hz (from ASC) divided by
                            a (ELD) downscale factor if present. */
  
    UINT outputDelay; /*!< The number of samples the output is additionally
                         delayed by.the decoder. */
    UINT flags; /*!< Copy of internal flags. Only to be written by the decoder,
                   and only to be read externally. */
  
    SCHAR epConfig; /*!< epConfig level (from ASC): only level 0 supported, -1
                       means no ER (e. g. AOT=2, MPEG-2 AAC, etc.)  */
    /* Statistics */
    INT numLostAccessUnits; /*!< This integer will reflect the estimated amount of
                               lost access units in case aacDecoder_DecodeFrame()
                                 returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be
                               < 0 if the estimation failed. */
  
    INT64 numTotalBytes; /*!< This is the number of total bytes that have passed
                            through the decoder. */
    INT64
    numBadBytes; /*!< This is the number of total bytes that were considered
                    with errors from numTotalBytes. */
    INT64
    numTotalAccessUnits;     /*!< This is the number of total access units that
                                have passed through the decoder. */
    INT64 numBadAccessUnits; /*!< This is the number of total access units that
                                were considered with errors from numTotalBytes. */
  
    /* Metadata */
    SCHAR drcProgRefLev; /*!< DRC program reference level. Defines the reference
                            level below full-scale. It is quantized in steps of
                            0.25dB. The valid values range from 0 (0 dBFS) to 127
                            (-31.75 dBFS). It is used to reflect the average
                            loudness of the audio in LKFS according to ITU-R BS
                            1770. If no level has been found in the bitstream the
                            value is -1. */
    SCHAR
    drcPresMode;        /*!< DRC presentation mode. According to ETSI TS 101 154,
                           this field indicates whether   light (MPEG-4 Dynamic Range
                           Control tool) or heavy compression (DVB heavy
                           compression)   dynamic range control shall take priority
                           on the outputs.   For details, see ETSI TS 101 154, table
                           C.33. Possible values are: \n   -1: No corresponding
                           metadata found in the bitstream \n   0: DRC presentation
                           mode not indicated \n   1: DRC presentation mode 1 \n   2:
                           DRC presentation mode 2 \n   3: Reserved */
    INT outputLoudness; /*!< Audio output loudness in steps of -0.25 dB. Range: 0
                           (0 dBFS) to 231 (-57.75 dBFS).\n  A value of -1
                           indicates that no loudness metadata is present.\n  If
                           loudness normalization is active, the value corresponds
                           to the target loudness value set with
                           ::AAC_DRC_REFERENCE_LEVEL.\n  If loudness normalization
                           is not active, the output loudness value corresponds to
                           the loudness metadata given in the bitstream.\n
                             Loudness metadata can originate from MPEG-4 DRC or
                           MPEG-D DRC. */
  
  } CStreamInfo;
  
  typedef struct AAC_DECODER_INSTANCE
      *HANDLE_AACDECODER; /*!< Pointer to a AAC decoder instance. */
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * \brief Initialize ancillary data buffer.
   *
   * \param self    AAC decoder handle.
   * \param buffer  Pointer to (external) ancillary data buffer.
   * \param size    Size of the buffer pointed to by buffer.
   * \return        Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataInit(HANDLE_AACDECODER self,
                                                      UCHAR *buffer, int size);
  
  /**
   * \brief Get one ancillary data element.
   *
   * \param self   AAC decoder handle.
   * \param index  Index of the ancillary data element to get.
   * \param ptr    Pointer to a buffer receiving a pointer to the requested
   * ancillary data element.
   * \param size   Pointer to a buffer receiving the length of the requested
   * ancillary data element.
   * \return       Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataGet(HANDLE_AACDECODER self,
                                                     int index, UCHAR **ptr,
                                                     int *size);
  
  /**
   * \brief Set one single decoder parameter.
   *
   * \param self   AAC decoder handle.
   * \param param  Parameter to be set.
   * \param value  Parameter value.
   * \return       Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_SetParam(const HANDLE_AACDECODER self,
                                                   const AACDEC_PARAM param,
                                                   const INT value);
  
  /**
   * \brief              Get free bytes inside decoder internal buffer.
   * \param self         Handle of AAC decoder instance.
   * \param pFreeBytes   Pointer to variable receiving amount of free bytes inside
   * decoder internal buffer.
   * \return             Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR
  aacDecoder_GetFreeBytes(const HANDLE_AACDECODER self, UINT *pFreeBytes);
  
  /**
   * \brief               Open an AAC decoder instance.
   * \param transportFmt  The transport type to be used.
   * \param nrOfLayers    Number of transport layers.
   * \return              AAC decoder handle.
   */
  LINKSPEC_H HANDLE_AACDECODER aacDecoder_Open(TRANSPORT_TYPE transportFmt,
                                               UINT nrOfLayers);
  
  /**
   * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig
   * (ASC) or a StreamMuxConfig (SMC), contained in a binary buffer. This is
   * required for MPEG-4 and Raw Packets file format bitstreams as well as for
   * LATM bitstreams with no in-band SMC. If the transport format is LATM with or
   * without LOAS, configuration is assumed to be an SMC, for all other file
   * formats an ASC.
   *
   * \param self    AAC decoder handle.
   * \param conf    Pointer to an unsigned char buffer containing the binary
   * configuration buffer (either ASC or SMC).
   * \param length  Length of the configuration buffer in bytes.
   * \return        Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_ConfigRaw(HANDLE_AACDECODER self,
                                                    UCHAR *conf[],
                                                    const UINT length[]);
  
  /**
   * \brief Submit raw ISO base media file format boxes to decoder for parsing
   * (only some box types are recognized).
   *
   * \param self    AAC decoder handle.
   * \param buffer  Pointer to an unsigned char buffer containing the binary box
   * data (including size and type, can be a sequence of multiple boxes).
   * \param length  Length of the data in bytes.
   * \return        Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_RawISOBMFFData(HANDLE_AACDECODER self,
                                                         UCHAR *buffer,
                                                         UINT length);
  
  /**
   * \brief Fill AAC decoder's internal input buffer with bitstream data from the
   * external input buffer. The function only copies such data as long as the
   * decoder-internal input buffer is not full. So it grabs whatever it can from
   * pBuffer and returns information (bytesValid) so that at a subsequent call of
   * %aacDecoder_Fill(), the right position in pBuffer can be determined to grab
   * the next data.
   *
   * \param self        AAC decoder handle.
   * \param pBuffer     Pointer to external input buffer.
   * \param bufferSize  Size of external input buffer. This argument is required
   * because decoder-internally we need the information to calculate the offset to
   * pBuffer, where the next available data is, which is then
   * fed into the decoder-internal buffer (as much as
   * possible). Our example framework implementation fills the
   * buffer at pBuffer again, once it contains no available valid bytes anymore
   * (meaning bytesValid equal 0).
   * \param bytesValid  Number of bitstream bytes in the external bitstream buffer
   * that have not yet been copied into the decoder's internal bitstream buffer by
   * calling this function. The value is updated according to
   * the amount of newly copied bytes.
   * \return            Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_Fill(HANDLE_AACDECODER self,
                                               UCHAR *pBuffer[],
                                               const UINT bufferSize[],
                                               UINT *bytesValid);
  
  /** Flag for aacDecoder_DecodeFrame(): Trigger the built-in error concealment
   * module to generate a substitute signal for one lost frame. New input data
   * will not be considered.
   */
  #define AACDEC_CONCEAL 1
  /** Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all delayed
   * audio without having new input data. Thus new input data will not be
   * considered.
   */
  #define AACDEC_FLUSH 2
  /** Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data
   * discontinuity. Resync any internals as necessary.
   */
  #define AACDEC_INTR 4
  /** Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and history
   * buffers. CAUTION: This can cause discontinuities in the output signal.
   */
  #define AACDEC_CLRHIST 8
  
  /**
   * \brief               Decode one audio frame
   *
   * \param self          AAC decoder handle.
   * \param pTimeData     Pointer to external output buffer where the decoded PCM
   * samples will be stored into.
   * \param timeDataSize  Size of external output buffer.
   * \param flags         Bit field with flags for the decoder: \n
   *                      (flags & AACDEC_CONCEAL) == 1: Do concealment. \n
   *                      (flags & AACDEC_FLUSH) == 2: Discard input data. Flush
   * filter banks (output delayed audio). \n (flags & AACDEC_INTR) == 4: Input
   * data is discontinuous. Resynchronize any internals as
   * necessary. \n (flags & AACDEC_CLRHIST) == 8: Clear all signal delay lines and
   * history buffers.
   * \return              Error code.
   */
  LINKSPEC_H AAC_DECODER_ERROR aacDecoder_DecodeFrame(HANDLE_AACDECODER self,
                                                      INT_PCM *pTimeData,
                                                      const INT timeDataSize,
                                                      const UINT flags);
  
  /**
   * \brief       De-allocate all resources of an AAC decoder instance.
   *
   * \param self  AAC decoder handle.
   * \return      void.
   */
  LINKSPEC_H void aacDecoder_Close(HANDLE_AACDECODER self);
  
  /**
   * \brief       Get CStreamInfo handle from decoder.
   *
   * \param self  AAC decoder handle.
   * \return      Reference to requested CStreamInfo.
   */
  LINKSPEC_H CStreamInfo *aacDecoder_GetStreamInfo(HANDLE_AACDECODER self);
  
  /**
   * \brief       Get decoder library info.
   *
   * \param info  Pointer to an allocated LIB_INFO structure.
   * \return      0 on success.
   */
  LINKSPEC_H INT aacDecoder_GetLibInfo(LIB_INFO *info);
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* AACDECODER_LIB_H */
  