Home | History | Annotate | Download | only in include
      1 /* -----------------------------------------------------------------------------
      2 Software License for The Fraunhofer FDK AAC Codec Library for Android
      3 
      4  Copyright  1995 - 2019 Fraunhofer-Gesellschaft zur Frderung der angewandten
      5 Forschung e.V. All rights reserved.
      6 
      7  1.    INTRODUCTION
      8 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software
      9 that implements the MPEG Advanced Audio Coding ("AAC") encoding and decoding
     10 scheme for digital audio. This FDK AAC Codec software is intended to be used on
     11 a wide variety of Android devices.
     12 
     13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient
     14 general perceptual audio codecs. AAC-ELD is considered the best-performing
     15 full-bandwidth communications codec by independent studies and is widely
     16 deployed. AAC has been standardized by ISO and IEC as part of the MPEG
     17 specifications.
     18 
     19 Patent licenses for necessary patent claims for the FDK AAC Codec (including
     20 those of Fraunhofer) may be obtained through Via Licensing
     21 (www.vialicensing.com) or through the respective patent owners individually for
     22 the purpose of encoding or decoding bit streams in products that are compliant
     23 with the ISO/IEC MPEG audio standards. Please note that most manufacturers of
     24 Android devices already license these patent claims through Via Licensing or
     25 directly from the patent owners, and therefore FDK AAC Codec software may
     26 already be covered under those patent licenses when it is used for those
     27 licensed purposes only.
     28 
     29 Commercially-licensed AAC software libraries, including floating-point versions
     30 with enhanced sound quality, are also available from Fraunhofer. Users are
     31 encouraged to check the Fraunhofer website for additional applications
     32 information and documentation.
     33 
     34 2.    COPYRIGHT LICENSE
     35 
     36 Redistribution and use in source and binary forms, with or without modification,
     37 are permitted without payment of copyright license fees provided that you
     38 satisfy the following conditions:
     39 
     40 You must retain the complete text of this software license in redistributions of
     41 the FDK AAC Codec or your modifications thereto in source code form.
     42 
     43 You must retain the complete text of this software license in the documentation
     44 and/or other materials provided with redistributions of the FDK AAC Codec or
     45 your modifications thereto in binary form. You must make available free of
     46 charge copies of the complete source code of the FDK AAC Codec and your
     47 modifications thereto to recipients of copies in binary form.
     48 
     49 The name of Fraunhofer may not be used to endorse or promote products derived
     50 from this library without prior written permission.
     51 
     52 You may not charge copyright license fees for anyone to use, copy or distribute
     53 the FDK AAC Codec software or your modifications thereto.
     54 
     55 Your modified versions of the FDK AAC Codec must carry prominent notices stating
     56 that you changed the software and the date of any change. For modified versions
     57 of the FDK AAC Codec, the term "Fraunhofer FDK AAC Codec Library for Android"
     58 must be replaced by the term "Third-Party Modified Version of the Fraunhofer FDK
     59 AAC Codec Library for Android."
     60 
     61 3.    NO PATENT LICENSE
     62 
     63 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without
     64 limitation the patents of Fraunhofer, ARE GRANTED BY THIS SOFTWARE LICENSE.
     65 Fraunhofer provides no warranty of patent non-infringement with respect to this
     66 software.
     67 
     68 You may use this FDK AAC Codec software or modifications thereto only for
     69 purposes that are authorized by appropriate patent licenses.
     70 
     71 4.    DISCLAIMER
     72 
     73 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright
     74 holders and contributors "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
     75 including but not limited to the implied warranties of merchantability and
     76 fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
     77 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary,
     78 or consequential damages, including but not limited to procurement of substitute
     79 goods or services; loss of use, data, or profits, or business interruption,
     80 however caused and on any theory of liability, whether in contract, strict
     81 liability, or tort (including negligence), arising in any way out of the use of
     82 this software, even if advised of the possibility of such damage.
     83 
     84 5.    CONTACT INFORMATION
     85 
     86 Fraunhofer Institute for Integrated Circuits IIS
     87 Attention: Audio and Multimedia Departments - FDK AAC LL
     88 Am Wolfsmantel 33
     89 91058 Erlangen, Germany
     90 
     91 www.iis.fraunhofer.de/amm
     92 amm-info (at) iis.fraunhofer.de
     93 ----------------------------------------------------------------------------- */
     94 
     95 /**************************** AAC decoder library ******************************
     96 
     97    Author(s):   Manuel Jander
     98 
     99    Description:
    100 
    101 *******************************************************************************/
    102 
    103 #ifndef AACDECODER_LIB_H
    104 #define AACDECODER_LIB_H
    105 
    106 /**
    107  * \file   aacdecoder_lib.h
    108  * \brief  FDK AAC decoder library interface header file.
    109  *
    110 
    111 \page INTRO Introduction
    112 
    113 
    114 \section SCOPE Scope
    115 
    116 This document describes the high-level application interface and usage of the
    117 ISO/MPEG-2/4 AAC Decoder library developed by the Fraunhofer Institute for
    118 Integrated Circuits (IIS). Depending on the library configuration, decoding of
    119 AAC-LC (Low-Complexity), HE-AAC (High-Efficiency AAC v1 and v2), AAC-LD
    120 (Low-Delay) and AAC-ELD (Enhanced Low-Delay) is implemented.
    121 
    122 All references to SBR (Spectral Band Replication) are only applicable to HE-AAC
    123 and AAC-ELD configurations of the FDK library. All references to PS (Parametric
    124 Stereo) are only applicable to HE-AAC v2 decoder configuration of the library.
    125 
    126 \section DecoderBasics Decoder Basics
    127 
    128 This document can only give a rough overview about the ISO/MPEG-2, ISO/MPEG-4
    129 AAC audio and MPEG-D USAC coding standards. To understand all details referenced
    130 in this document, you are encouraged to read the following documents.
    131 
    132 - ISO/IEC 13818-7 (MPEG-2 AAC) Standard, defines the syntax of MPEG-2 AAC audio
    133 bitstreams.
    134 - ISO/IEC 14496-3 (MPEG-4 AAC, subpart 1 and 4) Standard, defines the syntax of
    135 MPEG-4 AAC audio bitstreams.
    136 - ISO/IEC 23003-3 (MPEG-D USAC), defines MPEG-D USAC unified speech and audio
    137 codec.
    138 - Lutzky, Schuller, Gayer, Krämer, Wabnik, "A guideline to audio codec
    139 delay", 116th AES Convention, May 8, 2004
    140 
    141 In short, MPEG Advanced Audio Coding is based on a time-to-frequency mapping of
    142 the signal. The signal is partitioned into overlapping time portions and
    143 transformed into frequency domain. The spectral components are then quantized
    144 and coded using a highly efficient coding scheme.\n Encoded MPEG-2 and MPEG-4
    145 AAC audio bitstreams are composed of frames. Contrary to MPEG-1/2 Layer-3 (mp3),
    146 the length of individual frames is not restricted to a fixed number of bytes,
    147 but can take any length between 1 and 768 bytes.
    148 
    149 In addition to the above mentioned frequency domain coding mode, MPEG-D USAC
    150 also employs a time domain Algebraic Code-Excited Linear Prediction (ACELP)
    151 speech coder core. This operating mode is selected by the encoder in order to
    152 achieve the optimum audio quality for different content type. Several
    153 enhancements allow achieving higher quality at lower bit rates compared to
    154 MPEG-4 HE-AAC.
    155 
    156 
    157 \page LIBUSE Library Usage
    158 
    159 
    160 \section InterfaceDescritpion API Description
    161 
    162 All API header files are located in the folder /include of the release package.
    163 The contents of each file is described in detail in this document. All header
    164 files are provided for usage in specific C/C++ programs. The main AAC decoder
    165 library API functions are located in aacdecoder_lib.h header file.
    166 
    167 In binary releases the decoder core resides in statically linkable libraries,
    168 for example libAACdec.a.
    169 
    170 
    171 \section Calling_Sequence Calling Sequence
    172 
    173 The following sequence is necessary for proper decoding of ISO/MPEG-2/4 AAC,
    174 HE-AAC v2, or MPEG-D USAC bitstreams. In the following description, input stream
    175 read and output write function details are left out, since they may be
    176 implemented in a variety of configurations depending on the user's specific
    177 requirements. The example implementation uses file-based input/output, and in
    178 such case one may call mpegFileRead_Open() to open an input file and to allocate
    179 memory for the required structures, and the corresponding mpegFileRead_Close()
    180 to close opened files and to de-allocate associated structures.
    181 mpegFileRead_Open() will attempt to detect the bitstream format and in case of
    182 MPEG-4 file format or Raw Packets file format (a proprietary Fraunhofer IIS file
    183 format suitable only for testing) it will read the Audio Specific Config data
    184 (ASC). An unsuccessful attempt to recognize the bitstream format requires the
    185 user to provide this information manually. For any other bitstream formats that
    186 are usually applicable in streaming applications, the decoder itself will try to
    187 synchronize and parse the given bitstream fragment using the FDK transport
    188 library. Hence, for streaming applications (without file access) this step is
    189 not necessary.
    190 
    191 
    192 -# Call aacDecoder_Open() to open and retrieve a handle to a new AAC decoder
    193 instance. \code aacDecoderInfo = aacDecoder_Open(transportType, nrOfLayers);
    194 \endcode
    195 -# If out-of-band config data (Audio Specific Config (ASC) or Stream Mux Config
    196 (SMC)) is available, call aacDecoder_ConfigRaw() to pass this data to the
    197 decoder before beginning the decoding process. If this data is not available in
    198 advance, the decoder will configure itself while decoding, during the
    199 aacDecoder_DecodeFrame() function call.
    200 -# Begin decoding loop.
    201 \code
    202 do {
    203 \endcode
    204 -# Read data from bitstream file or stream buffer in to the driver program
    205 working memory (a client-supplied input buffer "inBuffer" in framework). This
    206 buffer will be used to load AAC bitstream data to the decoder.  Only when all
    207 data in this buffer has been processed will the decoder signal an empty buffer.
    208 For file-based input, you may invoke mpegFileRead_Read() to acquire new
    209 bitstream data.
    210 -# Call aacDecoder_Fill() to fill the decoder's internal bitstream input buffer
    211 with the client-supplied bitstream input buffer. Note, if the data loaded in to
    212 the internal buffer is not sufficient to decode a frame,
    213 aacDecoder_DecodeFrame() will return ::AAC_DEC_NOT_ENOUGH_BITS until a
    214 sufficient amount of data is loaded in to the internal buffer. For streaming
    215 formats (ADTS, LOAS), it is acceptable to load more than one frame to the
    216 decoder. However, for RAW file format (Fraunhofer IIS proprietary format), only
    217 one frame may be loaded to the decoder per aacDecoder_DecodeFrame() call. For
    218 least amount of communication delay, fill and decode should be performed on a
    219 frame by frame basis. \code ErrorStatus = aacDecoder_Fill(aacDecoderInfo,
    220 inBuffer, bytesRead, bytesValid); \endcode
    221 -# Call aacDecoder_DecodeFrame(). This function decodes one frame and writes
    222 decoded PCM audio data to a client-supplied buffer. It is the client's
    223 responsibility to allocate a buffer which is large enough to hold the decoded
    224 output data. \code ErrorStatus = aacDecoder_DecodeFrame(aacDecoderInfo,
    225 TimeData, OUT_BUF_SIZE, flags); \endcode If the bitstream configuration (number
    226 of channels, sample rate, frame size) is not known a priori, you may call
    227 aacDecoder_GetStreamInfo() to retrieve a structure that contains this
    228 information. You may use this data to initialize an audio output device. In the
    229 example program, if the number of channels or the sample rate has changed since
    230 program start or the previously decoded frame, the audio output device is then
    231 re-initialized. If WAVE file output is chosen, a new WAVE file for each new
    232 stream configuration is be created. \code p_si =
    233 aacDecoder_GetStreamInfo(aacDecoderInfo); \endcode
    234 -# Repeat steps 5 to 7 until no data is available to decode any more, or in case
    235 of error. \code } while (bytesRead[0] > 0 || doFlush || doBsFlush ||
    236 forceContinue); \endcode
    237 -# Call aacDecoder_Close() to de-allocate all AAC decoder and transport layer
    238 structures. \code aacDecoder_Close(aacDecoderInfo); \endcode
    239 
    240 \image latex decode.png "Decode calling sequence" width=11cm
    241 
    242 \image latex change_source.png "Change data source sequence" width 5cm
    243 
    244 \image latex conceal.png "Error concealment sequence" width=14cm
    245 
    246 \subsection Error_Concealment_Sequence Error Concealment Sequence
    247 
    248 There are different strategies to handle bit stream errors. Depending on the
    249 system properties the product designer might choose to take different actions in
    250 case a bit error occurs. In many cases the decoder might be able to do
    251 reasonable error concealment without the need of any additional actions from the
    252 system. But in some cases its not even possible to know how many decoded PCM
    253 output samples are required to fill the gap due to the data error, then the
    254 software surrounding the decoder must deal with the situation. The most simple
    255 way would be to just stop audio playback and resume once enough bit stream data
    256 and/or buffered output samples are available. More sophisticated designs might
    257 also be able to deal with sender/receiver clock drifts or data drop outs by
    258 using a closed loop control of FIFO fulness levels. The chosen strategy depends
    259 on the final product requirements.
    260 
    261 The error concealment sequence diagram illustrates the general execution paths
    262 for error handling.
    263 
    264 The macro IS_OUTPUT_VALID(err) can be used to identify if the audio output
    265 buffer contains valid audio either from error free bit stream data or successful
    266 error concealment. In case the result is false, the decoder output buffer does
    267 not contain meaningful audio samples and should not be passed to any output as
    268 it is. Most likely in case that a continuous audio output PCM stream is
    269 required, the output buffer must be filled with audio data from the calling
    270 framework. This might be e.g. an appropriate number of samples all zero.
    271 
    272 If error code ::AAC_DEC_TRANSPORT_SYNC_ERROR is returned by the decoder, under
    273 some particular conditions it is possible to estimate lost frames due to the bit
    274 stream error. In that case the bit stream is required to have a constant
    275 bitrate, and compatible transport type. Audio samples for the lost frames can be
    276 obtained by calling aacDecoder_DecodeFrame() with flag ::AACDEC_CONCEAL set
    277 n-times where n is the count of lost frames. Please note that the decoder has to
    278 have encountered valid configuration data at least once to be able to generate
    279 concealed data, because at the minimum the sampling rate, frame size and amount
    280 of audio channels needs to be known.
    281 
    282 If it is not possible to get an estimation of lost frames then a constant
    283 fullness of the audio output buffer can be achieved by implementing different
    284 FIFO control techniques e.g. just stop taking of samples from the buffer to
    285 avoid underflow or stop filling new data to the buffer to avoid overflow. But
    286 this techniques are out of scope of this document.
    287 
    288 For a detailed description of a specific error code please refer also to
    289 ::AAC_DECODER_ERROR.
    290 
    291 \section BufferSystem Buffer System
    292 
    293 There are three main buffers in an AAC decoder application. One external input
    294 buffer to hold bitstream data from file I/O or elsewhere, one decoder-internal
    295 input buffer, and one to hold the decoded output PCM sample data. In resource
    296 limited applications, the output buffer may be reused as an external input
    297 buffer prior to the subsequence aacDecoder_Fill() function call.
    298 
    299 The external input buffer is set in the example program and its size is defined
    300 by ::IN_BUF_SIZE. You may freely choose different buffer sizes. To feed the data
    301 to the decoder-internal input buffer, use the function aacDecoder_Fill(). This
    302 function returns important information regarding the number of bytes in the
    303 external input buffer that have not yet been copied into the internal input
    304 buffer (variable bytesValid). Once the external buffer has been fully copied, it
    305 can be completely re-filled again. In case you wish to refill the buffer while
    306 there are unprocessed bytes (bytesValid is unequal 0), you should preserve the
    307 unconsumed data. However, we recommend to refill the buffer only when bytesValid
    308 returns 0.
    309 
    310 The bytesValid parameter is an input and output parameter to the FDK decoder. As
    311 an input, it signals how many valid bytes are available in the external buffer.
    312 After consumption of the external buffer using aacDecoder_Fill() function, the
    313 bytesValid parameter indicates if any of the bytes in the external buffer were
    314 not consumed.
    315 
    316 \image latex dec_buffer.png "Life cycle of the external input buffer" width=9cm
    317 
    318 \page OutputFormat Decoder audio output
    319 
    320 \section OutputFormatObtaining Obtaining channel mapping information
    321 
    322 The decoded audio output format is indicated by a set of variables of the
    323 CStreamInfo structure. While the struct members sampleRate, frameSize and
    324 numChannels might be self explanatory, pChannelType and pChannelIndices require
    325 some further explanation.
    326 
    327 These two arrays indicate the configuration of channel data within the output
    328 buffer. Both arrays have CStreamInfo::numChannels number of cells. Each cell of
    329 pChannelType indicates the channel type, which is described in the enum
    330 ::AUDIO_CHANNEL_TYPE (defined in FDK_audio.h). The cells of pChannelIndices
    331 indicate the sub index among the channels starting with 0 among channels of the
    332 same audio channel type.
    333 
    334 The indexing scheme is structured as defined in MPEG-2/4 Standards. Indices
    335 start from the front direction (a center channel if available, will always be
    336 index 0) and increment, starting with the left side, pairwise (e.g. L, R) and
    337 from front to back (Front L, Front R, Surround L, Surround R). For detailed
    338 explanation, please refer to ISO/IEC 13818-7:2005(E), chapter 8.5.3.2.
    339 
    340 In case a Program Config is included in the audio configuration, the channel
    341 mapping described within it will be adopted.
    342 
    343 In case of MPEG-D Surround the channel mapping will follow the same criteria
    344 described in ISO/IEC 13818-7:2005(E), but adding corresponding top channels (if
    345 available) to the channel types in order to avoid ambiguity. The examples below
    346 explain these aspects in detail.
    347 
    348 \section OutputFormatChange Changing the audio output format
    349 
    350 For MPEG-4 audio the channel order can be changed at runtime through the
    351 parameter
    352 ::AAC_PCM_OUTPUT_CHANNEL_MAPPING. See the description of those
    353 parameters and the decoder library function aacDecoder_SetParam() for more
    354 detail.
    355 
    356 \section OutputFormatExample Channel mapping examples
    357 
    358 The following examples illustrate the location of individual audio samples in
    359 the audio buffer that is passed to aacDecoder_DecodeFrame() and the expected
    360 data in the CStreamInfo structure which can be obtained by calling
    361 aacDecoder_GetStreamInfo().
    362 
    363 \subsection ExamplesStereo Stereo
    364 
    365 In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
    366 a AAC-LC bit stream which has channelConfiguration = 2 in its audio specific
    367 config would lead to the following values in CStreamInfo:
    368 
    369 CStreamInfo::numChannels = 2
    370 
    371 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT }
    372 
    373 CStreamInfo::pChannelIndices = { 0, 1 }
    374 
    375 The output buffer will be formatted as follows:
    376 
    377 \verbatim
    378   <left sample 0>  <left sample 1>  <left sample 2>  ... <left sample N>
    379   <right sample 0> <right sample 1> <right sample 2> ... <right sample N>
    380 \endverbatim
    381 
    382 Where N equals to CStreamInfo::frameSize .
    383 
    384 \subsection ExamplesSurround Surround 5.1
    385 
    386 In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
    387 a AAC-LC bit stream which has channelConfiguration = 6 in its audio specific
    388 config, would lead to the following values in CStreamInfo:
    389 
    390 CStreamInfo::numChannels = 6
    391 
    392 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_FRONT, ::ACT_LFE,
    393 ::ACT_BACK, ::ACT_BACK }
    394 
    395 CStreamInfo::pChannelIndices = { 1, 2, 0, 0, 0, 1 }
    396 
    397 Since ::AAC_PCM_OUTPUT_CHANNEL_MAPPING is 1, WAV file channel ordering will be
    398 used. For a 5.1 channel scheme, thus the channels would be: front left, front
    399 right, center, LFE, surround left, surround right. Thus the third channel is the
    400 center channel, receiving the index 0. The other front channels are front left,
    401 front right being placed as first and second channels with indices 1 and 2
    402 correspondingly. There is only one LFE, placed as the fourth channel and index
    403 0. Finally both surround channels get the type definition ACT_BACK, and the
    404 indices 0 and 1.
    405 
    406 The output buffer will be formatted as follows:
    407 
    408 \verbatim
    409 <front left sample 0> <front right sample 0>
    410 <center sample 0> <LFE sample 0>
    411 <surround left sample 0> <surround right sample 0>
    412 
    413 <front left sample 1> <front right sample 1>
    414 <center sample 1> <LFE sample 1>
    415 <surround left sample 1> <surround right sample 1>
    416 
    417 ...
    418 
    419 <front left sample N> <front right sample N>
    420 <center sample N> <LFE sample N>
    421 <surround left sample N> <surround right sample N>
    422 \endverbatim
    423 
    424 Where N equals to CStreamInfo::frameSize .
    425 
    426 \subsection ExamplesArib ARIB coding mode 2/1
    427 
    428 In case of ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
    429 in case of a ARIB bit stream using coding mode 2/1 as described in ARIB STD-B32
    430 Part 2 Version 2.1-E1, page 61, would lead to the following values in
    431 CStreamInfo:
    432 
    433 CStreamInfo::numChannels = 3
    434 
    435 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_BACK }
    436 
    437 CStreamInfo::pChannelIndices = { 0, 1, 0 }
    438 
    439 The audio channels will be placed as follows in the audio output buffer:
    440 
    441 \verbatim
    442 <front left sample 0> <front right sample 0>  <mid surround sample 0>
    443 
    444 <front left sample 1> <front right sample 1> <mid surround sample 1>
    445 
    446 ...
    447 
    448 <front left sample N> <front right sample N> <mid surround sample N>
    449 
    450 Where N equals to CStreamInfo::frameSize .
    451 
    452 \endverbatim
    453 
    454 */
    455 
    456 #include "machine_type.h"
    457 #include "FDK_audio.h"
    458 
    459 #include "genericStds.h"
    460 /**
    461  * \brief  AAC decoder error codes.
    462  */
    463 typedef enum {
    464   AAC_DEC_OK =
    465       0x0000, /*!< No error occurred. Output buffer is valid and error free. */
    466   AAC_DEC_OUT_OF_MEMORY =
    467       0x0002, /*!< Heap returned NULL pointer. Output buffer is invalid. */
    468   AAC_DEC_UNKNOWN =
    469       0x0005, /*!< Error condition is of unknown reason, or from a another
    470                  module. Output buffer is invalid. */
    471 
    472   /* Synchronization errors. Output buffer is invalid. */
    473   aac_dec_sync_error_start = 0x1000,
    474   AAC_DEC_TRANSPORT_SYNC_ERROR = 0x1001, /*!< The transport decoder had
    475                                             synchronization problems. Do not
    476                                             exit decoding. Just feed new
    477                                               bitstream data. */
    478   AAC_DEC_NOT_ENOUGH_BITS = 0x1002, /*!< The input buffer ran out of bits. */
    479   aac_dec_sync_error_end = 0x1FFF,
    480 
    481   /* Initialization errors. Output buffer is invalid. */
    482   aac_dec_init_error_start = 0x2000,
    483   AAC_DEC_INVALID_HANDLE =
    484       0x2001, /*!< The handle passed to the function call was invalid (NULL). */
    485   AAC_DEC_UNSUPPORTED_AOT =
    486       0x2002, /*!< The AOT found in the configuration is not supported. */
    487   AAC_DEC_UNSUPPORTED_FORMAT =
    488       0x2003, /*!< The bitstream format is not supported.  */
    489   AAC_DEC_UNSUPPORTED_ER_FORMAT =
    490       0x2004, /*!< The error resilience tool format is not supported. */
    491   AAC_DEC_UNSUPPORTED_EPCONFIG =
    492       0x2005, /*!< The error protection format is not supported. */
    493   AAC_DEC_UNSUPPORTED_MULTILAYER =
    494       0x2006, /*!< More than one layer for AAC scalable is not supported. */
    495   AAC_DEC_UNSUPPORTED_CHANNELCONFIG =
    496       0x2007, /*!< The channel configuration (either number or arrangement) is
    497                  not supported. */
    498   AAC_DEC_UNSUPPORTED_SAMPLINGRATE = 0x2008, /*!< The sample rate specified in
    499                                                 the configuration is not
    500                                                 supported. */
    501   AAC_DEC_INVALID_SBR_CONFIG =
    502       0x2009, /*!< The SBR configuration is not supported. */
    503   AAC_DEC_SET_PARAM_FAIL = 0x200A,  /*!< The parameter could not be set. Either
    504                                        the value was out of range or the
    505                                        parameter does  not exist. */
    506   AAC_DEC_NEED_TO_RESTART = 0x200B, /*!< The decoder needs to be restarted,
    507                                        since the required configuration change
    508                                        cannot be performed. */
    509   AAC_DEC_OUTPUT_BUFFER_TOO_SMALL =
    510       0x200C, /*!< The provided output buffer is too small. */
    511   aac_dec_init_error_end = 0x2FFF,
    512 
    513   /* Decode errors. Output buffer is valid but concealed. */
    514   aac_dec_decode_error_start = 0x4000,
    515   AAC_DEC_TRANSPORT_ERROR =
    516       0x4001, /*!< The transport decoder encountered an unexpected error. */
    517   AAC_DEC_PARSE_ERROR = 0x4002, /*!< Error while parsing the bitstream. Most
    518                                    probably it is corrupted, or the system
    519                                    crashed. */
    520   AAC_DEC_UNSUPPORTED_EXTENSION_PAYLOAD =
    521       0x4003, /*!< Error while parsing the extension payload of the bitstream.
    522                  The extension payload type found is not supported. */
    523   AAC_DEC_DECODE_FRAME_ERROR = 0x4004, /*!< The parsed bitstream value is out of
    524                                           range. Most probably the bitstream is
    525                                           corrupt, or the system crashed. */
    526   AAC_DEC_CRC_ERROR = 0x4005,          /*!< The embedded CRC did not match. */
    527   AAC_DEC_INVALID_CODE_BOOK = 0x4006,  /*!< An invalid codebook was signaled.
    528                                           Most probably the bitstream is corrupt,
    529                                           or the system  crashed. */
    530   AAC_DEC_UNSUPPORTED_PREDICTION =
    531       0x4007, /*!< Predictor found, but not supported in the AAC Low Complexity
    532                  profile. Most probably the bitstream is corrupt, or has a wrong
    533                  format. */
    534   AAC_DEC_UNSUPPORTED_CCE = 0x4008, /*!< A CCE element was found which is not
    535                                        supported. Most probably the bitstream is
    536                                        corrupt, or has a wrong format. */
    537   AAC_DEC_UNSUPPORTED_LFE = 0x4009, /*!< A LFE element was found which is not
    538                                        supported. Most probably the bitstream is
    539                                        corrupt, or has a wrong format. */
    540   AAC_DEC_UNSUPPORTED_GAIN_CONTROL_DATA =
    541       0x400A, /*!< Gain control data found but not supported. Most probably the
    542                  bitstream is corrupt, or has a wrong format. */
    543   AAC_DEC_UNSUPPORTED_SBA =
    544       0x400B, /*!< SBA found, but currently not supported in the BSAC profile.
    545                */
    546   AAC_DEC_TNS_READ_ERROR = 0x400C, /*!< Error while reading TNS data. Most
    547                                       probably the bitstream is corrupt or the
    548                                       system crashed. */
    549   AAC_DEC_RVLC_ERROR =
    550       0x400D, /*!< Error while decoding error resilient data. */
    551   aac_dec_decode_error_end = 0x4FFF,
    552   /* Ancillary data errors. Output buffer is valid. */
    553   aac_dec_anc_data_error_start = 0x8000,
    554   AAC_DEC_ANC_DATA_ERROR =
    555       0x8001, /*!< Non severe error concerning the ancillary data handling. */
    556   AAC_DEC_TOO_SMALL_ANC_BUFFER = 0x8002,  /*!< The registered ancillary data
    557                                              buffer is too small to receive the
    558                                              parsed data. */
    559   AAC_DEC_TOO_MANY_ANC_ELEMENTS = 0x8003, /*!< More than the allowed number of
    560                                              ancillary data elements should be
    561                                              written to buffer. */
    562   aac_dec_anc_data_error_end = 0x8FFF
    563 
    564 } AAC_DECODER_ERROR;
    565 
    566 /** Macro to identify initialization errors. Output buffer is invalid. */
    567 #define IS_INIT_ERROR(err)                                                    \
    568   ((((err) >= aac_dec_init_error_start) && ((err) <= aac_dec_init_error_end)) \
    569        ? 1                                                                    \
    570        : 0)
    571 /** Macro to identify decode errors. Output buffer is valid but concealed. */
    572 #define IS_DECODE_ERROR(err)                 \
    573   ((((err) >= aac_dec_decode_error_start) && \
    574     ((err) <= aac_dec_decode_error_end))     \
    575        ? 1                                   \
    576        : 0)
    577 /**
    578  * Macro to identify if the audio output buffer contains valid samples after
    579  * calling aacDecoder_DecodeFrame(). Output buffer is valid but can be
    580  * concealed.
    581  */
    582 #define IS_OUTPUT_VALID(err) (((err) == AAC_DEC_OK) || IS_DECODE_ERROR(err))
    583 
    584 /*! \enum  AAC_MD_PROFILE
    585  *  \brief The available metadata profiles which are mostly related to downmixing. The values define the arguments
    586  *         for the use with parameter ::AAC_METADATA_PROFILE.
    587  */
    588 typedef enum {
    589   AAC_MD_PROFILE_MPEG_STANDARD =
    590       0, /*!< The standard profile creates a mixdown signal based on the
    591             advanced downmix metadata (from a DSE). The equations and default
    592             values are defined in ISO/IEC 14496:3 Ammendment 4. Any other
    593             (legacy) downmix metadata will be ignored. No other parameter will
    594             be modified.         */
    595   AAC_MD_PROFILE_MPEG_LEGACY =
    596       1, /*!< This profile behaves identical to the standard profile if advanced
    597               downmix metadata (from a DSE) is available. If not, the
    598             matrix_mixdown information embedded in the program configuration
    599             element (PCE) will be applied. If neither is the case, the module
    600             creates a mixdown using the default coefficients as defined in
    601             ISO/IEC 14496:3 AMD 4. The profile can be used to support legacy
    602             digital TV (e.g. DVB) streams.           */
    603   AAC_MD_PROFILE_MPEG_LEGACY_PRIO =
    604       2, /*!< Similar to the ::AAC_MD_PROFILE_MPEG_LEGACY profile but if both
    605             the advanced (ISO/IEC 14496:3 AMD 4) and the legacy (PCE) MPEG
    606             downmix metadata are available the latter will be applied.
    607           */
    608   AAC_MD_PROFILE_ARIB_JAPAN =
    609       3 /*!< Downmix creation as described in ABNT NBR 15602-2. But if advanced
    610              downmix metadata (ISO/IEC 14496:3 AMD 4) is available it will be
    611              preferred because of the higher resolutions. In addition the
    612            metadata expiry time will be set to the value defined in the ARIB
    613            standard (see ::AAC_METADATA_EXPIRY_TIME).
    614          */
    615 } AAC_MD_PROFILE;
    616 
    617 /*! \enum  AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS
    618  *  \brief Options for handling of DRC parameters, if presentation mode is not indicated in bitstream
    619  */
    620 typedef enum {
    621   AAC_DRC_PARAMETER_HANDLING_DISABLED = -1, /*!< DRC parameter handling
    622                                                disabled, all parameters are
    623                                                applied as requested. */
    624   AAC_DRC_PARAMETER_HANDLING_ENABLED =
    625       0, /*!< Apply changes to requested DRC parameters to prevent clipping. */
    626   AAC_DRC_PRESENTATION_MODE_1_DEFAULT =
    627       1, /*!< Use DRC presentation mode 1 as default (e.g. for Nordig) */
    628   AAC_DRC_PRESENTATION_MODE_2_DEFAULT =
    629       2 /*!< Use DRC presentation mode 2 as default (e.g. for DTG DBook) */
    630 } AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS;
    631 
    632 /**
    633  * \brief AAC decoder setting parameters
    634  */
    635 typedef enum {
    636   AAC_PCM_DUAL_CHANNEL_OUTPUT_MODE =
    637       0x0002, /*!< Defines how the decoder processes two channel signals: \n
    638                    0: Leave both signals as they are (default). \n
    639                    1: Create a dual mono output signal from channel 1. \n
    640                    2: Create a dual mono output signal from channel 2. \n
    641                    3: Create a dual mono output signal by mixing both channels
    642                  (L' = R' = 0.5*Ch1 + 0.5*Ch2). */
    643   AAC_PCM_OUTPUT_CHANNEL_MAPPING =
    644       0x0003, /*!< Output buffer channel ordering. 0: MPEG PCE style order, 1:
    645                  WAV file channel order (default). */
    646   AAC_PCM_LIMITER_ENABLE =
    647       0x0004,                           /*!< Enable signal level limiting. \n
    648                                              -1: Auto-config. Enable limiter for all
    649                                            non-lowdelay configurations by default. \n
    650                                               0: Disable limiter in general. \n
    651                                               1: Enable limiter always.
    652                                              It is recommended to call the decoder
    653                                            with a AACDEC_CLRHIST flag to reset all
    654                                            states when      the limiter switch is changed
    655                                            explicitly. */
    656   AAC_PCM_LIMITER_ATTACK_TIME = 0x0005, /*!< Signal level limiting attack time
    657                                            in ms. Default configuration is 15
    658                                            ms. Adjustable range from 1 ms to 15
    659                                            ms. */
    660   AAC_PCM_LIMITER_RELEAS_TIME = 0x0006, /*!< Signal level limiting release time
    661                                            in ms. Default configuration is 50
    662                                            ms. Adjustable time must be larger
    663                                            than 0 ms. */
    664   AAC_PCM_MIN_OUTPUT_CHANNELS =
    665       0x0011, /*!< Minimum number of PCM output channels. If higher than the
    666                  number of encoded audio channels, a simple channel extension is
    667                  applied (see note 4 for exceptions). \n -1, 0: Disable channel
    668                  extension feature. The decoder output contains the same number
    669                  of channels as the encoded bitstream. \n 1:    This value is
    670                  currently needed only together with the mix-down feature. See
    671                           ::AAC_PCM_MAX_OUTPUT_CHANNELS and note 2 below. \n
    672                     2:    Encoded mono signals will be duplicated to achieve a
    673                  2/0/0.0 channel output configuration. \n 6:    The decoder
    674                  tries to reorder encoded signals with less than six channels to
    675                  achieve a 3/0/2.1 channel output signal. Missing channels will
    676                  be filled with a zero signal. If reordering is not possible the
    677                  empty channels will simply be appended. Only available if
    678                  instance is configured to support multichannel output. \n 8:
    679                  The decoder tries to reorder encoded signals with less than
    680                  eight channels to achieve a 3/0/4.1 channel output signal.
    681                  Missing channels will be filled with a zero signal. If
    682                  reordering is not possible the empty channels will simply be
    683                           appended. Only available if instance is configured to
    684                  support multichannel output.\n NOTE: \n
    685                      1. The channel signaling (CStreamInfo::pChannelType and
    686                  CStreamInfo::pChannelIndices) will not be modified. Added empty
    687                  channels will be signaled with channel type
    688                         AUDIO_CHANNEL_TYPE::ACT_NONE. \n
    689                      2. If the parameter value is greater than that of
    690                  ::AAC_PCM_MAX_OUTPUT_CHANNELS both will be set to the same
    691                  value. \n
    692                      3. This parameter does not affect MPEG Surround processing.
    693                  \n
    694                      4. This parameter will be ignored if the number of encoded
    695                  audio channels is greater than 8. */
    696   AAC_PCM_MAX_OUTPUT_CHANNELS =
    697       0x0012, /*!< Maximum number of PCM output channels. If lower than the
    698                  number of encoded audio channels, downmixing is applied
    699                  accordingly (see note 5 for exceptions). If dedicated metadata
    700                  is available in the stream it will be used to achieve better
    701                  mixing results. \n -1, 0: Disable downmixing feature. The
    702                  decoder output contains the same number of channels as the
    703                  encoded bitstream. \n 1:    All encoded audio configurations
    704                  with more than one channel will be mixed down to one mono
    705                  output signal. \n 2:    The decoder performs a stereo mix-down
    706                  if the number encoded audio channels is greater than two. \n 6:
    707                  If the number of encoded audio channels is greater than six the
    708                  decoder performs a mix-down to meet the target output
    709                  configuration of 3/0/2.1 channels. Only available if instance
    710                  is configured to support multichannel output. \n 8:    This
    711                  value is currently needed only together with the channel
    712                  extension feature. See ::AAC_PCM_MIN_OUTPUT_CHANNELS and note 2
    713                  below. Only available if instance is configured to support
    714                  multichannel output. \n NOTE: \n
    715                      1. Down-mixing of any seven or eight channel configuration
    716                  not defined in ISO/IEC 14496-3 PDAM 4 is not supported by this
    717                  software version. \n
    718                      2. If the parameter value is greater than zero but smaller
    719                  than ::AAC_PCM_MIN_OUTPUT_CHANNELS both will be set to same
    720                  value. \n
    721                      3. The operating mode of the MPEG Surround module will be
    722                  set accordingly. \n
    723                      4. Setting this parameter with any value will disable the
    724                  binaural processing of the MPEG Surround module
    725                      5. This parameter will be ignored if the number of encoded
    726                  audio channels is greater than 8. */
    727   AAC_METADATA_PROFILE =
    728       0x0020, /*!< See ::AAC_MD_PROFILE for all available values. */
    729   AAC_METADATA_EXPIRY_TIME = 0x0021, /*!< Defines the time in ms after which all
    730                                         the bitstream associated meta-data (DRC,
    731                                         downmix coefficients, ...) will be reset
    732                                         to default if no update has been
    733                                         received. Negative values disable the
    734                                         feature. */
    735 
    736   AAC_CONCEAL_METHOD = 0x0100, /*!< Error concealment: Processing method. \n
    737                                     0: Spectral muting. \n
    738                                     1: Noise substitution (see ::CONCEAL_NOISE).
    739                                   \n 2: Energy interpolation (adds additional
    740                                   signal delay of one frame, see
    741                                   ::CONCEAL_INTER. only some AOTs are
    742                                   supported). \n */
    743   AAC_DRC_BOOST_FACTOR =
    744       0x0200, /*!< MPEG-4 / MPEG-D Dynamic Range Control (DRC): Scaling factor
    745                  for boosting gain values. Defines how the boosting DRC factors
    746                  (conveyed in the bitstream) will be applied to the decoded
    747                  signal. The valid values range from 0 (don't apply boost
    748                  factors) to 127 (fully apply boost factors). Default value is 0
    749                  for MPEG-4 DRC and 127 for MPEG-D DRC. */
    750   AAC_DRC_ATTENUATION_FACTOR = 0x0201, /*!< MPEG-4 / MPEG-D DRC: Scaling factor
    751                                           for attenuating gain values. Same as
    752                                             ::AAC_DRC_BOOST_FACTOR but for
    753                                           attenuating DRC factors. */
    754   AAC_DRC_REFERENCE_LEVEL =
    755       0x0202, /*!< MPEG-4 / MPEG-D DRC: Target reference level / decoder target
    756                  loudness.\n Defines the level below full-scale (quantized in
    757                  steps of 0.25dB) to which the output audio signal will be
    758                  normalized to by the DRC module.\n The parameter controls
    759                  loudness normalization for both MPEG-4 DRC and MPEG-D DRC. The
    760                  valid values range from 40 (-10 dBFS) to 127 (-31.75 dBFS).\n
    761                    Example values:\n
    762                    124 (-31 dBFS) for audio/video receivers (AVR) or other
    763                  devices allowing audio playback with high dynamic range,\n 96
    764                  (-24 dBFS) for TV sets or equivalent devices (default),\n 64
    765                  (-16 dBFS) for mobile devices where the dynamic range of audio
    766                  playback is restricted.\n Any value smaller than 0 switches off
    767                  loudness normalization and MPEG-4 DRC. */
    768   AAC_DRC_HEAVY_COMPRESSION =
    769       0x0203, /*!< MPEG-4 DRC: En-/Disable DVB specific heavy compression (aka
    770                  RF mode). If set to 1, the decoder will apply the compression
    771                  values from the DVB specific ancillary data field. At the same
    772                  time the MPEG-4 Dynamic Range Control tool will be disabled. By
    773                    default, heavy compression is disabled. */
    774   AAC_DRC_DEFAULT_PRESENTATION_MODE =
    775       0x0204, /*!< MPEG-4 DRC: Default presentation mode (DRC parameter
    776                  handling). \n Defines the handling of the DRC parameters boost
    777                  factor, attenuation factor and heavy compression, if no
    778                  presentation mode is indicated in the bitstream.\n For options,
    779                  see ::AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS.\n Default:
    780                  ::AAC_DRC_PARAMETER_HANDLING_DISABLED */
    781   AAC_DRC_ENC_TARGET_LEVEL =
    782       0x0205, /*!< MPEG-4 DRC: Encoder target level for light (i.e. not heavy)
    783                  compression.\n If known, this declares the target reference
    784                  level that was assumed at the encoder for calculation of
    785                  limiting gains. The valid values range from 0 (full-scale) to
    786                  127 (31.75 dB below full-scale). This parameter is used only
    787                  with ::AAC_DRC_PARAMETER_HANDLING_ENABLED and ignored
    788                  otherwise.\n Default: 127 (worst-case assumption).\n */
    789   AAC_UNIDRC_SET_EFFECT = 0x0206, /*!< MPEG-D DRC: Request a DRC effect type for
    790                                      selection of a DRC set.\n Supported indices
    791                                      are:\n -1: DRC off. Completely disables
    792                                      MPEG-D DRC.\n 0: None (default). Disables
    793                                      MPEG-D DRC, but automatically enables DRC
    794                                      if necessary to prevent clipping.\n 1: Late
    795                                      night\n 2: Noisy environment\n 3: Limited
    796                                      playback range\n 4: Low playback level\n 5:
    797                                      Dialog enhancement\n 6: General
    798                                      compression. Used for generally enabling
    799                                      MPEG-D DRC without particular request.\n */
    800   AAC_UNIDRC_ALBUM_MODE =
    801       0x0207, /*!<  MPEG-D DRC: Enable album mode. 0: Disabled (default), 1:
    802                  Enabled.\n Disabled album mode leads to application of gain
    803                  sequences for fading in and out, if provided in the
    804                  bitstream.\n Enabled album mode makes use of dedicated album
    805                  loudness information, if provided in the bitstream.\n */
    806   AAC_QMF_LOWPOWER = 0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing
    807                                 mode. \n -1: Use internal default. Implies MPEG
    808                                 Surround partially complex accordingly. \n 0:
    809                                 Use complex QMF data mode. \n 1: Use real (low
    810                                 power) QMF data mode. \n */
    811   AAC_TPDEC_CLEAR_BUFFER =
    812       0x0603 /*!< Clear internal bit stream buffer of transport layers. The
    813                 decoder will start decoding at new data passed after this event
    814                 and any previous data is discarded. */
    815 
    816 } AACDEC_PARAM;
    817 
    818 /**
    819  * \brief This structure gives information about the currently decoded audio
    820  * data. All fields are read-only.
    821  */
    822 typedef struct {
    823   /* These five members are the only really relevant ones for the user. */
    824   INT sampleRate; /*!< The sample rate in Hz of the decoded PCM audio signal. */
    825   INT frameSize;  /*!< The frame size of the decoded PCM audio signal. \n
    826                        Typically this is: \n
    827                        1024 or 960 for AAC-LC \n
    828                        2048 or 1920 for HE-AAC (v2) \n
    829                        512 or 480 for AAC-LD and AAC-ELD \n
    830                        768, 1024, 2048 or 4096 for USAC  */
    831   INT numChannels; /*!< The number of output audio channels before the rendering
    832                       module, i.e. the original channel configuration. */
    833   AUDIO_CHANNEL_TYPE
    834   *pChannelType; /*!< Audio channel type of each output audio channel. */
    835   UCHAR *pChannelIndices; /*!< Audio channel index for each output audio
    836                              channel. See ISO/IEC 13818-7:2005(E), 8.5.3.2
    837                              Explicit channel mapping using a
    838                              program_config_element() */
    839   /* Decoder internal members. */
    840   INT aacSampleRate; /*!< Sampling rate in Hz without SBR (from configuration
    841                         info) divided by a (ELD) downscale factor if present. */
    842   INT profile; /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g.
    843                   MPEG-4)).               */
    844   AUDIO_OBJECT_TYPE
    845   aot; /*!< Audio Object Type (from ASC): is set to the appropriate value
    846           for MPEG-2 bitstreams (e. g. 2 for AAC-LC). */
    847   INT channelConfig; /*!< Channel configuration (0: PCE defined, 1: mono, 2:
    848                         stereo, ...                       */
    849   INT bitRate;       /*!< Instantaneous bit rate.                   */
    850   INT aacSamplesPerFrame;   /*!< Samples per frame for the AAC core (from ASC)
    851                                divided by a (ELD) downscale factor if present. \n
    852                                  Typically this is (with a downscale factor of 1):
    853                                \n   1024 or 960 for AAC-LC \n   512 or 480 for
    854                                AAC-LD   and AAC-ELD         */
    855   INT aacNumChannels;       /*!< The number of audio channels after AAC core
    856                                processing (before PS or MPS processing).       CAUTION: This
    857                                are not the final number of output channels! */
    858   AUDIO_OBJECT_TYPE extAot; /*!< Extension Audio Object Type (from ASC)   */
    859   INT extSamplingRate; /*!< Extension sampling rate in Hz (from ASC) divided by
    860                           a (ELD) downscale factor if present. */
    861 
    862   UINT outputDelay; /*!< The number of samples the output is additionally
    863                        delayed by.the decoder. */
    864   UINT flags; /*!< Copy of internal flags. Only to be written by the decoder,
    865                  and only to be read externally. */
    866 
    867   SCHAR epConfig; /*!< epConfig level (from ASC): only level 0 supported, -1
    868                      means no ER (e. g. AOT=2, MPEG-2 AAC, etc.)  */
    869   /* Statistics */
    870   INT numLostAccessUnits; /*!< This integer will reflect the estimated amount of
    871                              lost access units in case aacDecoder_DecodeFrame()
    872                                returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be
    873                              < 0 if the estimation failed. */
    874 
    875   INT64 numTotalBytes; /*!< This is the number of total bytes that have passed
    876                           through the decoder. */
    877   INT64
    878   numBadBytes; /*!< This is the number of total bytes that were considered
    879                   with errors from numTotalBytes. */
    880   INT64
    881   numTotalAccessUnits;     /*!< This is the number of total access units that
    882                               have passed through the decoder. */
    883   INT64 numBadAccessUnits; /*!< This is the number of total access units that
    884                               were considered with errors from numTotalBytes. */
    885 
    886   /* Metadata */
    887   SCHAR drcProgRefLev; /*!< DRC program reference level. Defines the reference
    888                           level below full-scale. It is quantized in steps of
    889                           0.25dB. The valid values range from 0 (0 dBFS) to 127
    890                           (-31.75 dBFS). It is used to reflect the average
    891                           loudness of the audio in LKFS according to ITU-R BS
    892                           1770. If no level has been found in the bitstream the
    893                           value is -1. */
    894   SCHAR
    895   drcPresMode; /*!< DRC presentation mode. According to ETSI TS 101 154,
    896                   this field indicates whether   light (MPEG-4 Dynamic Range
    897                   Control tool) or heavy compression (DVB heavy
    898                   compression)   dynamic range control shall take priority
    899                   on the outputs.   For details, see ETSI TS 101 154, table
    900                   C.33. Possible values are: \n   -1: No corresponding
    901                   metadata found in the bitstream \n   0: DRC presentation
    902                   mode not indicated \n   1: DRC presentation mode 1 \n   2:
    903                   DRC presentation mode 2 \n   3: Reserved */
    904 
    905 } CStreamInfo;
    906 
    907 typedef struct AAC_DECODER_INSTANCE
    908     *HANDLE_AACDECODER; /*!< Pointer to a AAC decoder instance. */
    909 
    910 #ifdef __cplusplus
    911 extern "C" {
    912 #endif
    913 
    914 /**
    915  * \brief Initialize ancillary data buffer.
    916  *
    917  * \param self    AAC decoder handle.
    918  * \param buffer  Pointer to (external) ancillary data buffer.
    919  * \param size    Size of the buffer pointed to by buffer.
    920  * \return        Error code.
    921  */
    922 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataInit(HANDLE_AACDECODER self,
    923                                                     UCHAR *buffer, int size);
    924 
    925 /**
    926  * \brief Get one ancillary data element.
    927  *
    928  * \param self   AAC decoder handle.
    929  * \param index  Index of the ancillary data element to get.
    930  * \param ptr    Pointer to a buffer receiving a pointer to the requested
    931  * ancillary data element.
    932  * \param size   Pointer to a buffer receiving the length of the requested
    933  * ancillary data element.
    934  * \return       Error code.
    935  */
    936 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataGet(HANDLE_AACDECODER self,
    937                                                    int index, UCHAR **ptr,
    938                                                    int *size);
    939 
    940 /**
    941  * \brief Set one single decoder parameter.
    942  *
    943  * \param self   AAC decoder handle.
    944  * \param param  Parameter to be set.
    945  * \param value  Parameter value.
    946  * \return       Error code.
    947  */
    948 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_SetParam(const HANDLE_AACDECODER self,
    949                                                  const AACDEC_PARAM param,
    950                                                  const INT value);
    951 
    952 /**
    953  * \brief              Get free bytes inside decoder internal buffer.
    954  * \param self         Handle of AAC decoder instance.
    955  * \param pFreeBytes   Pointer to variable receiving amount of free bytes inside
    956  * decoder internal buffer.
    957  * \return             Error code.
    958  */
    959 LINKSPEC_H AAC_DECODER_ERROR
    960 aacDecoder_GetFreeBytes(const HANDLE_AACDECODER self, UINT *pFreeBytes);
    961 
    962 /**
    963  * \brief               Open an AAC decoder instance.
    964  * \param transportFmt  The transport type to be used.
    965  * \param nrOfLayers    Number of transport layers.
    966  * \return              AAC decoder handle.
    967  */
    968 LINKSPEC_H HANDLE_AACDECODER aacDecoder_Open(TRANSPORT_TYPE transportFmt,
    969                                              UINT nrOfLayers);
    970 
    971 /**
    972  * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig
    973  * (ASC) or a StreamMuxConfig (SMC), contained in a binary buffer. This is
    974  * required for MPEG-4 and Raw Packets file format bitstreams as well as for
    975  * LATM bitstreams with no in-band SMC. If the transport format is LATM with or
    976  * without LOAS, configuration is assumed to be an SMC, for all other file
    977  * formats an ASC.
    978  *
    979  * \param self    AAC decoder handle.
    980  * \param conf    Pointer to an unsigned char buffer containing the binary
    981  * configuration buffer (either ASC or SMC).
    982  * \param length  Length of the configuration buffer in bytes.
    983  * \return        Error code.
    984  */
    985 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_ConfigRaw(HANDLE_AACDECODER self,
    986                                                   UCHAR *conf[],
    987                                                   const UINT length[]);
    988 
    989 /**
    990  * \brief Submit raw ISO base media file format boxes to decoder for parsing
    991  * (only some box types are recognized).
    992  *
    993  * \param self    AAC decoder handle.
    994  * \param buffer  Pointer to an unsigned char buffer containing the binary box
    995  * data (including size and type, can be a sequence of multiple boxes).
    996  * \param length  Length of the data in bytes.
    997  * \return        Error code.
    998  */
    999 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_RawISOBMFFData(HANDLE_AACDECODER self,
   1000                                                        UCHAR *buffer,
   1001                                                        UINT length);
   1002 
   1003 /**
   1004  * \brief Fill AAC decoder's internal input buffer with bitstream data from the
   1005  * external input buffer. The function only copies such data as long as the
   1006  * decoder-internal input buffer is not full. So it grabs whatever it can from
   1007  * pBuffer and returns information (bytesValid) so that at a subsequent call of
   1008  * %aacDecoder_Fill(), the right position in pBuffer can be determined to grab
   1009  * the next data.
   1010  *
   1011  * \param self        AAC decoder handle.
   1012  * \param pBuffer     Pointer to external input buffer.
   1013  * \param bufferSize  Size of external input buffer. This argument is required
   1014  * because decoder-internally we need the information to calculate the offset to
   1015  * pBuffer, where the next available data is, which is then
   1016  * fed into the decoder-internal buffer (as much as
   1017  * possible). Our example framework implementation fills the
   1018  * buffer at pBuffer again, once it contains no available valid bytes anymore
   1019  * (meaning bytesValid equal 0).
   1020  * \param bytesValid  Number of bitstream bytes in the external bitstream buffer
   1021  * that have not yet been copied into the decoder's internal bitstream buffer by
   1022  * calling this function. The value is updated according to
   1023  * the amount of newly copied bytes.
   1024  * \return            Error code.
   1025  */
   1026 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_Fill(HANDLE_AACDECODER self,
   1027                                              UCHAR *pBuffer[],
   1028                                              const UINT bufferSize[],
   1029                                              UINT *bytesValid);
   1030 
   1031 #define AACDEC_CONCEAL                                                        \
   1032   1 /*!< Flag for aacDecoder_DecodeFrame(): Trigger the built-in error        \
   1033        concealment module to generate a substitute signal for one lost frame. \
   1034        New input data will not be considered. */
   1035 #define AACDEC_FLUSH                                                         \
   1036   2 /*!< Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all \
   1037        delayed audio without having new input data. Thus new input data will \
   1038        not be considered.*/
   1039 #define AACDEC_INTR                                                         \
   1040   4 /*!< Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data \
   1041        discontinuity. Resync any internals as necessary. */
   1042 #define AACDEC_CLRHIST                                                        \
   1043   8 /*!< Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and  \
   1044        history buffers. CAUTION: This can cause discontinuities in the output \
   1045        signal. */
   1046 
   1047 /**
   1048  * \brief               Decode one audio frame
   1049  *
   1050  * \param self          AAC decoder handle.
   1051  * \param pTimeData     Pointer to external output buffer where the decoded PCM
   1052  * samples will be stored into.
   1053  * \param timeDataSize  Size of external output buffer.
   1054  * \param flags         Bit field with flags for the decoder: \n
   1055  *                      (flags & AACDEC_CONCEAL) == 1: Do concealment. \n
   1056  *                      (flags & AACDEC_FLUSH) == 2: Discard input data. Flush
   1057  * filter banks (output delayed audio). \n (flags & AACDEC_INTR) == 4: Input
   1058  * data is discontinuous. Resynchronize any internals as
   1059  * necessary. \n (flags & AACDEC_CLRHIST) == 8: Clear all signal delay lines and
   1060  * history buffers.
   1061  * \return              Error code.
   1062  */
   1063 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_DecodeFrame(HANDLE_AACDECODER self,
   1064                                                     INT_PCM *pTimeData,
   1065                                                     const INT timeDataSize,
   1066                                                     const UINT flags);
   1067 
   1068 /**
   1069  * \brief       De-allocate all resources of an AAC decoder instance.
   1070  *
   1071  * \param self  AAC decoder handle.
   1072  * \return      void.
   1073  */
   1074 LINKSPEC_H void aacDecoder_Close(HANDLE_AACDECODER self);
   1075 
   1076 /**
   1077  * \brief       Get CStreamInfo handle from decoder.
   1078  *
   1079  * \param self  AAC decoder handle.
   1080  * \return      Reference to requested CStreamInfo.
   1081  */
   1082 LINKSPEC_H CStreamInfo *aacDecoder_GetStreamInfo(HANDLE_AACDECODER self);
   1083 
   1084 /**
   1085  * \brief       Get decoder library info.
   1086  *
   1087  * \param info  Pointer to an allocated LIB_INFO structure.
   1088  * \return      0 on success.
   1089  */
   1090 LINKSPEC_H INT aacDecoder_GetLibInfo(LIB_INFO *info);
   1091 
   1092 #ifdef __cplusplus
   1093 }
   1094 #endif
   1095 
   1096 #endif /* AACDECODER_LIB_H */
   1097