• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 
2 /* -----------------------------------------------------------------------------------------------------------
3 Software License for The Fraunhofer FDK AAC Codec Library for Android
4 
5 � Copyright  1995 - 2015 Fraunhofer-Gesellschaft zur F�rderung der angewandten Forschung e.V.
6   All rights reserved.
7 
8  1.    INTRODUCTION
9 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software that implements
10 the MPEG Advanced Audio Coding ("AAC") encoding and decoding scheme for digital audio.
11 This FDK AAC Codec software is intended to be used on a wide variety of Android devices.
12 
13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient general perceptual
14 audio codecs. AAC-ELD is considered the best-performing full-bandwidth communications codec by
15 independent studies and is widely deployed. AAC has been standardized by ISO and IEC as part
16 of the MPEG specifications.
17 
18 Patent licenses for necessary patent claims for the FDK AAC Codec (including those of Fraunhofer)
19 may be obtained through Via Licensing (www.vialicensing.com) or through the respective patent owners
20 individually for the purpose of encoding or decoding bit streams in products that are compliant with
21 the ISO/IEC MPEG audio standards. Please note that most manufacturers of Android devices already license
22 these patent claims through Via Licensing or directly from the patent owners, and therefore FDK AAC Codec
23 software may already be covered under those patent licenses when it is used for those licensed purposes only.
24 
25 Commercially-licensed AAC software libraries, including floating-point versions with enhanced sound quality,
26 are also available from Fraunhofer. Users are encouraged to check the Fraunhofer website for additional
27 applications information and documentation.
28 
29 2.    COPYRIGHT LICENSE
30 
31 Redistribution and use in source and binary forms, with or without modification, are permitted without
32 payment of copyright license fees provided that you satisfy the following conditions:
33 
34 You must retain the complete text of this software license in redistributions of the FDK AAC Codec or
35 your modifications thereto in source code form.
36 
37 You must retain the complete text of this software license in the documentation and/or other materials
38 provided with redistributions of the FDK AAC Codec or your modifications thereto in binary form.
39 You must make available free of charge copies of the complete source code of the FDK AAC Codec and your
40 modifications thereto to recipients of copies in binary form.
41 
42 The name of Fraunhofer may not be used to endorse or promote products derived from this library without
43 prior written permission.
44 
45 You may not charge copyright license fees for anyone to use, copy or distribute the FDK AAC Codec
46 software or your modifications thereto.
47 
48 Your modified versions of the FDK AAC Codec must carry prominent notices stating that you changed the software
49 and the date of any change. For modified versions of the FDK AAC Codec, the term
50 "Fraunhofer FDK AAC Codec Library for Android" must be replaced by the term
51 "Third-Party Modified Version of the Fraunhofer FDK AAC Codec Library for Android."
52 
53 3.    NO PATENT LICENSE
54 
55 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without limitation the patents of Fraunhofer,
56 ARE GRANTED BY THIS SOFTWARE LICENSE. Fraunhofer provides no warranty of patent non-infringement with
57 respect to this software.
58 
59 You may use this FDK AAC Codec software or modifications thereto only for purposes that are authorized
60 by appropriate patent licenses.
61 
62 4.    DISCLAIMER
63 
64 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright holders and contributors
65 "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, including but not limited to the implied warranties
66 of merchantability and fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
67 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary, or consequential damages,
68 including but not limited to procurement of substitute goods or services; loss of use, data, or profits,
69 or business interruption, however caused and on any theory of liability, whether in contract, strict
70 liability, or tort (including negligence), arising in any way out of the use of this software, even if
71 advised of the possibility of such damage.
72 
73 5.    CONTACT INFORMATION
74 
75 Fraunhofer Institute for Integrated Circuits IIS
76 Attention: Audio and Multimedia Departments - FDK AAC LL
77 Am Wolfsmantel 33
78 91058 Erlangen, Germany
79 
80 www.iis.fraunhofer.de/amm
81 amm-info@iis.fraunhofer.de
82 ----------------------------------------------------------------------------------------------------------- */
83 
84 /*****************************  MPEG-4 AAC Decoder  **************************
85 
86    Author(s):   Manuel Jander
87 
88 ******************************************************************************/
89 
90 /**
91  * \file   aacdecoder_lib.h
92  * \brief  FDK AAC decoder library interface header file.
93  *
94 
95 \page INTRO Introduction
96 
97 \section SCOPE Scope
98 
99 This document describes the high-level interface and usage of the ISO/MPEG-2/4 AAC Decoder
100 library developed by the Fraunhofer Institute for Integrated Circuits (IIS).
101 Depending on the library configuration, it implements decoding of AAC-LC (Low-Complexity),
102 HE-AAC (High-Efficiency AAC, v1 and v2), AAC-LD (Low-Delay) and AAC-ELD (Enhanced Low-Delay).
103 
104 All references to SBR (Spectral Band Replication) are only applicable to HE-AAC and AAC-ELD
105 versions of the library. All references to PS (Parametric Stereo) are only applicable to
106 HE-AAC v2 versions of the library.
107 
108 \section DecoderBasics Decoder Basics
109 
110 This document can only give a rough overview about the ISO/MPEG-2 and ISO/MPEG-4 AAC audio
111 coding standard. To understand all the terms in this document, you are encouraged to read
112 the following documents.
113 
114 - ISO/IEC 13818-7 (MPEG-2 AAC), which defines the syntax of MPEG-2 AAC audio bitstreams.
115 - ISO/IEC 14496-3 (MPEG-4 AAC, subpart 1 and 4), which defines the syntax of MPEG-4 AAC audio bitstreams.
116 - Lutzky, Schuller, Gayer, Krämer, Wabnik, "A guideline to audio codec delay", 116th AES Convention, May 8, 2004
117 
118 MPEG Advanced Audio Coding is based on a time-to-frequency mapping of the signal. The signal
119 is partitioned into overlapping portions and transformed into frequency domain. The spectral
120 components are then quantized and coded.\n
121 An MPEG2 or MPEG4 AAC audio bitstream is composed of frames. Contrary to MPEG-1/2 Layer-3 (mp3),
122 the length of individual frames is not restricted to a fixed number of bytes, but can take on
123 any length between 1 and 768 bytes.
124 
125 
126 \page LIBUSE Library Usage
127 
128 \section InterfaceDescritpion API Description
129 
130 All API header files are located in the folder /include of the release package. They are described in
131 detail in this document. All header files are provided for usage in C/C++ programs. The AAC decoder library
132 API functions are located at aacdecoder_lib.h.
133 
134 In binary releases the decoder core resides in statically linkable libraries called for example libAACdec.a,
135 (Linux) or FDK_aacDec_lib (Microsoft Visual C++).
136 
137 \section Calling_Sequence Calling Sequence
138 
139 For decoding of ISO/MPEG-2/4 AAC or HE-AAC v2 bitstreams the following sequence is mandatory. Input read
140 and output write functions as well as the corresponding open and close functions are left out, since they
141 may be implemented differently according to the user's specific requirements. The example implementation in
142 main.cpp uses file-based input/output, and in such case call mpegFileRead_Open() to open an input file and
143 to allocate memory for the required structures, and the corresponding mpegFileRead_Close() to close opened
144 files and to de-allocate associated structures. mpegFileRead_Open() tries to detect the bitstream format and
145 in case of MPEG-4 file format or Raw Packets file format (a Fraunhofer IIS proprietary format) reads the Audio
146 Specific Config data (ASC). An unsuccessful attempt to recognize the bitstream format requires the user to
147 provide this information manually. For any other bitstream formats that are usually applicable in streaming
148 applications, the decoder itself will try to synchronize and parse the given bitstream fragment using the
149 FDK transport library. Hence, for streaming applications (without file access) this step is not necessary.
150 
151 -# Call aacDecoder_Open() to open and retrieve a handle to a new AAC decoder instance.
152 \dontinclude main.cpp
153 \skipline aacDecoder_Open
154 -# If out-of-band config data (Audio Specific Config (ASC) or Stream Mux Config (SMC)) is available, call
155 aacDecoder_ConfigRaw() to pass it to the decoder and before the decoding process starts. If this data is
156 not available in advance, the decoder will get it from the bitstream  and configure itself while decoding
157 with aacDecoder_DecodeFrame().
158 -# Begin decoding loop.
159 \skipline do {
160 -# Read data from bitstream file or stream into a client-supplied input buffer ("inBuffer" in main.cpp).
161 If it is very small like just 4, aacDecoder_DecodeFrame() will
162 repeatedly return ::AAC_DEC_NOT_ENOUGH_BITS until enough bits were fed by aacDecoder_Fill(). Only read data
163 when this buffer has completely been processed and is then empty. For file-based input execute
164 mpegFileRead_Read() or any other implementation with similar functionality.
165 -# Call aacDecoder_Fill() to fill the decoder's internal bitstream input buffer with the client-supplied
166 external bitstream input buffer.
167 \skipline aacDecoder_Fill
168 -# Call aacDecoder_DecodeFrame() which writes decoded PCM audio data to a client-supplied buffer. It is the
169 client's responsibility to allocate a buffer which is large enough to hold this output data.
170 \skipline aacDecoder_DecodeFrame
171 If the bitstream's configuration (number of channels, sample rate, frame size) is not known in advance, you may
172 call aacDecoder_GetStreamInfo() to retrieve a structure containing this information and then initialize an audio
173 output device. In the example main.cpp, if the number of channels or the sample rate has changed since program
174 start or since the previously decoded frame, the audio output device will be re-initialized. If WAVE file output
175 is chosen, a new WAVE file for each new configuration will be created.
176 \skipline aacDecoder_GetStreamInfo
177 -# Repeat steps 5 to 7 until no data to decode is available anymore, or if an error occured.
178 \skipline } while
179 -# Call aacDecoder_Close() to de-allocate all AAC decoder and transport layer structures.
180 \skipline aacDecoder_Close
181 
182 \section BufferSystem Buffer System
183 
184 There are three main buffers in an AAC decoder application. One external input buffer to hold bitstream
185 data from file I/O or elsewhere, one decoder-internal input buffer, and one to hold the decoded output
186 PCM sample data, whereas this output buffer may overlap with the external input buffer.
187 
188 The external input buffer is set in the example framework main.cpp and its size is defined by ::IN_BUF_SIZE.
189 You may freely choose different sizes here. To feed the data to the decoder-internal input buffer, use the
190 function aacDecoder_Fill(). This function returns important information about how many bytes in the
191 external input buffer have not yet been copied into the internal input buffer (variable bytesValid).
192 Once the external buffer has been fully copied, it can be re-filled again.
193 In case you want to re-fill it when there are still unprocessed bytes (bytesValid is unequal 0), you
194 would have to additionally perform a memcpy(), so that just means unnecessary computational overhead
195 and therefore we recommend to re-fill the buffer only when bytesValid is 0.
196 
197 \image latex dec_buffer.png "Lifecycle of the external input buffer" width=9cm
198 
199 The size of the decoder-internal input buffer is set in tpdec_lib.h (see define ::TRANSPORTDEC_INBUF_SIZE).
200 You may choose a smaller size under the following considerations:
201 
202 - each input channel requires 768 bytes
203 - the whole buffer must be of size 2^n
204 
205 So for example a stereo decoder:
206 
207 \f[
208 TRANSPORTDEC\_INBUF\_SIZE = 2 * 768 = 1536 => 2048
209 \f]
210 
211 tpdec_lib.h and TRANSPORTDEC_INBUF_SIZE are not part of the decoder's library interface. Therefore
212 only source-code clients may change this setting. If you received a library release, please ask us and
213 we can change this in order to meet your memory requirements.
214 
215 \page OutputFormat Decoder audio output
216 
217 \section OutputFormatObtaining Obtaining channel mapping information
218 
219 The decoded audio output format is indicated by a set of variables of the CStreamInfo structure.
220 While the members sampleRate, frameSize and numChannels might be quite self explaining,
221 pChannelType and pChannelIndices might require some more detailed explanation.
222 
223 These two arrays indicate what is each output channel supposed to be. Both array have
224 CStreamInfo::numChannels cells. Each cell of pChannelType indicates the channel type, described in
225 the enum ::AUDIO_CHANNEL_TYPE defined in FDK_audio.h. The cells of pChannelIndices indicate the sub index
226 among the channels starting with 0 among all channels of the same audio channel type.
227 
228 The indexing scheme is the same as for MPEG-2/4. Thus indices are counted upwards starting from the front
229 direction (thus a center channel if any, will always be index 0). Then the indices count up, starting always
230 with the left side, pairwise from front toward back. For detailed explanation, please refer to
231 ISO/IEC 13818-7:2005(E), chapter 8.5.3.2.
232 
233 In case a Program Config is included in the audio configuration, the channel mapping described within
234 it will be adopted.
235 
236 In case of MPEG-D Surround the channel mapping will follow the same criteria described in ISO/IEC 13818-7:2005(E),
237 but adding corresponding top channels to the channel types front, side and back, in order to avoid any
238 loss of information.
239 
240 \section OutputFormatChange Changing the audio output format
241 
242 The channel interleaving scheme and the actual channel order can be changed at runtime through the
243 parameters ::AAC_PCM_OUTPUT_INTERLEAVED and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING. See the description of those
244 parameters and the decoder library function aacDecoder_SetParam() for more detail.
245 
246 \section OutputFormatExample Channel mapping examples
247 
248 The following examples illustrate the location of individual audio samples in the audio buffer that
249 is passed to aacDecoder_DecodeFrame() and the expected data in the CStreamInfo structure which can be obtained
250 by calling aacDecoder_GetStreamInfo().
251 
252 \subsection ExamplesStereo Stereo
253 
254 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 0 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
255 a AAC-LC bit stream which has channelConfiguration = 2 in its audio specific config would lead
256 to the following values in CStreamInfo:
257 
258 CStreamInfo::numChannels = 2
259 
260 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT }
261 
262 CStreamInfo::pChannelIndices = { 0, 1 }
263 
264 Since ::AAC_PCM_OUTPUT_INTERLEAVED is set to 0, the audio channels will be located as contiguous blocks
265 in the output buffer as follows:
266 
267 \verbatim
268   <left sample 0>  <left sample 1>  <left sample 2>  ... <left sample N>
269   <right sample 0> <right sample 1> <right sample 2> ... <right sample N>
270 \endverbatim
271 
272 Where N equals to CStreamInfo::frameSize .
273 
274 \subsection ExamplesSurround Surround 5.1
275 
276 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 1 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
277 a AAC-LC bit stream which has channelConfiguration = 6 in its audio specific config, would lead
278 to the following values in CStreamInfo:
279 
280 CStreamInfo::numChannels = 6
281 
282 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_FRONT, ::ACT_LFE, ::ACT_BACK, ::ACT_BACK }
283 
284 CStreamInfo::pChannelIndices = { 1, 2, 0, 0, 0, 1 }
285 
286 Since ::AAC_PCM_OUTPUT_CHANNEL_MAPPING is 1, WAV file channel ordering will be used. For a 5.1 channel
287 scheme, thus the channels would be: front left, front right, center, LFE, surround left, surround right.
288 Thus the third channel is the center channel, receiving the index 0. The other front channels are
289 front left, front right being placed as first and second channels with indices 1 and 2 correspondingly.
290 There is only one LFE, placed as the fourth channel and index 0. Finally both surround
291 channels get the type definition ACT_BACK, and the indices 0 and 1.
292 
293 Since ::AAC_PCM_OUTPUT_INTERLEAVED is set to 1, the audio channels will be placed in the output buffer
294 as follows:
295 
296 \verbatim
297 <front left sample 0> <front right sample 0>
298 <center sample 0> <LFE sample 0>
299 <surround left sample 0> <surround right sample 0>
300 
301 <front left sample 1> <front right sample 1>
302 <center sample 1> <LFE sample 1>
303 <surround left sample 1> <surround right sample 1>
304 
305 ...
306 
307 <front left sample N> <front right sample N>
308 <center sample N> <LFE sample N>
309 <surround left sample N> <surround right sample N>
310 \endverbatim
311 
312 Where N equals to CStreamInfo::frameSize .
313 
314 \subsection ExamplesArib ARIB coding mode 2/1
315 
316 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 1 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1,
317 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,
318 would lead to the following values in CStreamInfo:
319 
320 CStreamInfo::numChannels = 3
321 
322 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT,:: ACT_BACK }
323 
324 CStreamInfo::pChannelIndices = { 0, 1, 0 }
325 
326 The audio channels will be placed as follows in the audio output buffer:
327 
328 \verbatim
329 <front left sample 0> <front right sample 0>  <mid surround sample 0>
330 
331 <front left sample 1> <front right sample 1> <mid surround sample 1>
332 
333 ...
334 
335 <front left sample N> <front right sample N> <mid surround sample N>
336 
337 Where N equals to CStreamInfo::frameSize .
338 
339 \endverbatim
340 
341 */
342 
343 #ifndef AACDECODER_LIB_H
344 #define AACDECODER_LIB_H
345 
346 #include "machine_type.h"
347 #include "FDK_audio.h"
348 
349 #include "genericStds.h"
350 
351 /**
352  * \brief  AAC decoder error codes.
353  */
354 typedef enum {
355   AAC_DEC_OK                             = 0x0000,  /*!< No error occured. Output buffer is valid and error free. */
356   AAC_DEC_OUT_OF_MEMORY                  = 0x0002,  /*!< Heap returned NULL pointer. Output buffer is invalid. */
357   AAC_DEC_UNKNOWN                        = 0x0005,  /*!< Error condition is of unknown reason, or from a another module. Output buffer is invalid. */
358 
359   /* Synchronization errors. Output buffer is invalid. */
360   aac_dec_sync_error_start               = 0x1000,
361   AAC_DEC_TRANSPORT_SYNC_ERROR           = 0x1001,  /*!< The transport decoder had syncronisation problems. Do not exit decoding. Just feed new
362                                                          bitstream data. */
363   AAC_DEC_NOT_ENOUGH_BITS                = 0x1002,  /*!< The input buffer ran out of bits. */
364   aac_dec_sync_error_end                 = 0x1FFF,
365 
366   /* Initialization errors. Output buffer is invalid. */
367   aac_dec_init_error_start               = 0x2000,
368   AAC_DEC_INVALID_HANDLE                 = 0x2001,  /*!< The handle passed to the function call was invalid (NULL). */
369   AAC_DEC_UNSUPPORTED_AOT                = 0x2002,  /*!< The AOT found in the configuration is not supported. */
370   AAC_DEC_UNSUPPORTED_FORMAT             = 0x2003,  /*!< The bitstream format is not supported.  */
371   AAC_DEC_UNSUPPORTED_ER_FORMAT          = 0x2004,  /*!< The error resilience tool format is not supported. */
372   AAC_DEC_UNSUPPORTED_EPCONFIG           = 0x2005,  /*!< The error protection format is not supported. */
373   AAC_DEC_UNSUPPORTED_MULTILAYER         = 0x2006,  /*!< More than one layer for AAC scalable is not supported. */
374   AAC_DEC_UNSUPPORTED_CHANNELCONFIG      = 0x2007,  /*!< The channel configuration (either number or arrangement) is not supported. */
375   AAC_DEC_UNSUPPORTED_SAMPLINGRATE       = 0x2008,  /*!< The sample rate specified in the configuration is not supported. */
376   AAC_DEC_INVALID_SBR_CONFIG             = 0x2009,  /*!< The SBR configuration is not supported. */
377   AAC_DEC_SET_PARAM_FAIL                 = 0x200A,  /*!< The parameter could not be set. Either the value was out of range or the parameter does
378                                                          not exist. */
379   AAC_DEC_NEED_TO_RESTART                = 0x200B,  /*!< The decoder needs to be restarted, since the requiered configuration change cannot be
380                                                          performed. */
381   AAC_DEC_OUTPUT_BUFFER_TOO_SMALL        = 0x200C,  /*!< The provided output buffer is too small. */
382   aac_dec_init_error_end                 = 0x2FFF,
383 
384   /* Decode errors. Output buffer is valid but concealed. */
385   aac_dec_decode_error_start             = 0x4000,
386   AAC_DEC_TRANSPORT_ERROR                = 0x4001,  /*!< The transport decoder encountered an unexpected error. */
387   AAC_DEC_PARSE_ERROR                    = 0x4002,  /*!< Error while parsing the bitstream. Most probably it is corrupted, or the system crashed. */
388   AAC_DEC_UNSUPPORTED_EXTENSION_PAYLOAD  = 0x4003,  /*!< Error while parsing the extension payload of the bitstream. The extension payload type
389                                                          found is not supported. */
390   AAC_DEC_DECODE_FRAME_ERROR             = 0x4004,  /*!< The parsed bitstream value is out of range. Most probably the bitstream is corrupt, or
391                                                          the system crashed. */
392   AAC_DEC_CRC_ERROR                      = 0x4005,  /*!< The embedded CRC did not match. */
393   AAC_DEC_INVALID_CODE_BOOK              = 0x4006,  /*!< An invalid codebook was signalled. Most probably the bitstream is corrupt, or the system
394                                                          crashed. */
395   AAC_DEC_UNSUPPORTED_PREDICTION         = 0x4007,  /*!< Predictor found, but not supported in the AAC Low Complexity profile. Most probably the
396                                                          bitstream is corrupt, or has a wrong format. */
397   AAC_DEC_UNSUPPORTED_CCE                = 0x4008,  /*!< A CCE element was found which is not supported. Most probably the bitstream is corrupt, or
398                                                          has a wrong format. */
399   AAC_DEC_UNSUPPORTED_LFE                = 0x4009,  /*!< A LFE element was found which is not supported. Most probably the bitstream is corrupt, or
400                                                          has a wrong format. */
401   AAC_DEC_UNSUPPORTED_GAIN_CONTROL_DATA  = 0x400A,  /*!< Gain control data found but not supported. Most probably the bitstream is corrupt, or has
402                                                          a wrong format. */
403   AAC_DEC_UNSUPPORTED_SBA                = 0x400B,  /*!< SBA found, but currently not supported in the BSAC profile. */
404   AAC_DEC_TNS_READ_ERROR                 = 0x400C,  /*!< Error while reading TNS data. Most probably the bitstream is corrupt or the system
405                                                          crashed. */
406   AAC_DEC_RVLC_ERROR                     = 0x400D,  /*!< Error while decoding error resillient data. */
407   aac_dec_decode_error_end               = 0x4FFF,
408 
409   /* Ancillary data errors. Output buffer is valid. */
410   aac_dec_anc_data_error_start           = 0x8000,
411   AAC_DEC_ANC_DATA_ERROR                 = 0x8001,  /*!< Non severe error concerning the ancillary data handling. */
412   AAC_DEC_TOO_SMALL_ANC_BUFFER           = 0x8002,  /*!< The registered ancillary data buffer is too small to receive the parsed data. */
413   AAC_DEC_TOO_MANY_ANC_ELEMENTS          = 0x8003,  /*!< More than the allowed number of ancillary data elements should be written to buffer. */
414   aac_dec_anc_data_error_end             = 0x8FFF
415 
416 
417 } AAC_DECODER_ERROR;
418 
419 
420 /** Macro to identify initialization errors. */
421 #define IS_INIT_ERROR(err)   ( (((err)>=aac_dec_init_error_start)   && ((err)<=aac_dec_init_error_end))   ? 1 : 0)
422 /** Macro to identify decode errors. */
423 #define IS_DECODE_ERROR(err) ( (((err)>=aac_dec_decode_error_start) && ((err)<=aac_dec_decode_error_end)) ? 1 : 0)
424 /** Macro to identify if the audio output buffer contains valid samples after calling aacDecoder_DecodeFrame(). */
425 #define IS_OUTPUT_VALID(err) ( ((err) == AAC_DEC_OK) || IS_DECODE_ERROR(err) )
426 
427 /**
428  * \brief AAC decoder setting parameters
429  */
430 typedef enum
431 {
432   AAC_PCM_OUTPUT_INTERLEAVED              = 0x0000,  /*!< PCM output mode (1: interleaved (default); 0: not interleaved). */
433   AAC_PCM_DUAL_CHANNEL_OUTPUT_MODE        = 0x0002,  /*!< Defines how the decoder processes two channel signals: \n
434                                                           0: Leave both signals as they are (default). \n
435                                                           1: Create a dual mono output signal from channel 1. \n
436                                                           2: Create a dual mono output signal from channel 2. \n
437                                                           3: Create a dual mono output signal by mixing both channels (L' = R' = 0.5*Ch1 + 0.5*Ch2). */
438   AAC_PCM_OUTPUT_CHANNEL_MAPPING          = 0x0003,  /*!< Output buffer channel ordering. 0: MPEG PCE style order, 1: WAV file channel order (default). */
439   AAC_PCM_LIMITER_ENABLE                  = 0x0004,  /*!< Enable signal level limiting. \n
440                                                           -1: Auto-config. Enable limiter for all non-lowdelay configurations by default. \n
441                                                            0: Disable limiter in general. \n
442                                                            1: Enable limiter always.
443                                                           It is recommended to call the decoder with a AACDEC_CLRHIST flag to reset all states when
444                                                           the limiter switch is changed explicitly. */
445   AAC_PCM_LIMITER_ATTACK_TIME             = 0x0005,  /*!< Signal level limiting attack time in ms.
446                                                           Default confguration is 15 ms. Adjustable range from 1 ms to 15 ms. */
447   AAC_PCM_LIMITER_RELEAS_TIME             = 0x0006,  /*!< Signal level limiting release time in ms.
448                                                           Default configuration is 50 ms. Adjustable time must be larger than 0 ms. */
449   AAC_PCM_MIN_OUTPUT_CHANNELS             = 0x0011,  /*!< Minimum number of PCM output channels. If higher than the number of encoded audio channels,
450                                                           a simple channel extension is applied. \n
451                                                           -1, 0: Disable channel extenstion feature. The decoder output contains the same number of
452                                                                  channels as the encoded bitstream. \n
453                                                            1:    This value is currently needed only together with the mix-down feature. See
454                                                                  ::AAC_PCM_MAX_OUTPUT_CHANNELS and note 2 below. \n
455                                                            2:    Encoded mono signals will be duplicated to achieve a 2/0/0.0 channel output
456                                                                  configuration. \n
457                                                            6:    The decoder trys to reorder encoded signals with less than six channels to achieve
458                                                                  a 3/0/2.1 channel output signal. Missing channels will be filled with a zero signal.
459                                                                  If reordering is not possible the empty channels will simply be appended. Only
460                                                                  available if instance is configured to support multichannel output. \n
461                                                            8:    The decoder trys to reorder encoded signals with less than eight channels to
462                                                                  achieve a 3/0/4.1 channel output signal. Missing channels will be filled with a
463                                                                  zero signal. If reordering is not possible the empty channels will simply be
464                                                                  appended. Only available if instance is configured to support multichannel output.\n
465                                                           NOTE: \n
466                                                             1. The channel signalling (CStreamInfo::pChannelType and CStreamInfo::pChannelIndices)
467                                                                will not be modified. Added empty channels will be signalled with channel type
468                                                                AUDIO_CHANNEL_TYPE::ACT_NONE. \n
469                                                             2. If the parameter value is greater than that of ::AAC_PCM_MAX_OUTPUT_CHANNELS both will
470                                                                be set to the same value. \n
471                                                             3. This parameter does not affect MPEG Surround processing. */
472   AAC_PCM_MAX_OUTPUT_CHANNELS             = 0x0012,  /*!< Maximum number of PCM output channels. If lower than the number of encoded audio channels,
473                                                           downmixing is applied accordingly. If dedicated metadata is available in the stream it
474                                                           will be used to achieve better mixing results. \n
475                                                           -1, 0: Disable downmixing feature. The decoder output contains the same number of channels
476                                                                  as the encoded bitstream. \n
477                                                            1:    All encoded audio configurations with more than one channel will be mixed down to
478                                                                  one mono output signal. \n
479                                                            2:    The decoder performs a stereo mix-down if the number encoded audio channels is
480                                                                  greater than two. \n
481                                                            6:    If the number of encoded audio channels is greater than six the decoder performs a
482                                                                  mix-down to meet the target output configuration of 3/0/2.1 channels. Only
483                                                                  available if instance is configured to support multichannel output. \n
484                                                            8:    This value is currently needed only together with the channel extension feature.
485                                                                  See ::AAC_PCM_MIN_OUTPUT_CHANNELS and note 2 below. Only available if instance is
486                                                                  configured to support multichannel output. \n
487                                                           NOTE: \n
488                                                             1. Down-mixing of any seven or eight channel configuration not defined in ISO/IEC 14496-3
489                                                                PDAM 4 is not supported by this software version. \n
490                                                             2. If the parameter value is greater than zero but smaller than ::AAC_PCM_MIN_OUTPUT_CHANNELS
491                                                                both will be set to same value. \n
492                                                             3. The operating mode of the MPEG Surround module will be set accordingly. \n
493                                                             4. Setting this param with any value will disable the binaural processing of the MPEG
494                                                                Surround module (::AAC_MPEGS_BINAURAL_ENABLE=0). */
495 
496   AAC_CONCEAL_METHOD                      = 0x0100,  /*!< Error concealment: Processing method. \n
497                                                           0: Spectral muting. \n
498                                                           1: Noise substitution (see ::CONCEAL_NOISE). \n
499                                                           2: Energy interpolation (adds additional signal delay of one frame, see ::CONCEAL_INTER). \n */
500 
501   AAC_DRC_BOOST_FACTOR                    = 0x0200,  /*!< Dynamic Range Control: Scaling factor for boosting gain values.
502                                                           Defines how the boosting DRC factors (conveyed in the bitstream) will be applied to the
503                                                           decoded signal. The valid values range from 0 (don't apply boost factors) to 127 (fully
504                                                           apply all boosting factors). */
505   AAC_DRC_ATTENUATION_FACTOR              = 0x0201,  /*!< Dynamic Range Control: Scaling factor for attenuating gain values. Same as
506                                                           AAC_DRC_BOOST_FACTOR but for attenuating DRC factors. */
507   AAC_DRC_REFERENCE_LEVEL                 = 0x0202,  /*!< Dynamic Range Control: Target reference level. Defines the level below full-scale
508                                                           (quantized in steps of 0.25dB) to which the output audio signal will be normalized to by
509                                                           the DRC module. The valid values range from 0 (full-scale) to 127 (31.75 dB below
510                                                           full-scale). The value smaller than 0 switches off normalization. */
511   AAC_DRC_HEAVY_COMPRESSION               = 0x0203,  /*!< Dynamic Range Control: En-/Disable DVB specific heavy compression (aka RF mode).
512                                                           If set to 1, the decoder will apply the compression values from the DVB specific ancillary
513                                                           data field. At the same time the MPEG-4 Dynamic Range Control tool will be disabled. By
514                                                           default heavy compression is disabled. */
515 
516   AAC_QMF_LOWPOWER                        = 0x0300,  /*!< Quadrature Mirror Filter (QMF) Bank processing mode. \n
517                                                           -1: Use internal default. Implies MPEG Surround partially complex accordingly. \n
518                                                            0: Use complex QMF data mode. \n
519                                                            1: Use real (low power) QMF data mode. \n */
520 
521   AAC_MPEGS_ENABLE                        = 0x0500,  /*!< MPEG Surround: Allow/Disable decoding of MPS content. Available only for decoders with MPEG
522                                                           Surround support. */
523 
524   AAC_TPDEC_CLEAR_BUFFER                  = 0x0603   /*!< Clear internal bit stream buffer of transport layers. The decoder will start decoding
525                                                           at new data passed after this event and any previous data is discarded. */
526 
527 } AACDEC_PARAM;
528 
529 /**
530  * \brief This structure gives information about the currently decoded audio data.
531  *        All fields are read-only.
532  */
533 typedef struct
534 {
535   /* These five members are the only really relevant ones for the user.                                                            */
536   INT               sampleRate;          /*!< The samplerate in Hz of the fully decoded PCM audio signal (after SBR processing).   */
537   INT               frameSize;           /*!< The frame size of the decoded PCM audio signal. \n
538                                               1024 or 960 for AAC-LC \n
539                                               2048 or 1920 for HE-AAC (v2) \n
540                                               512 or 480 for AAC-LD and AAC-ELD                                                    */
541   INT               numChannels;         /*!< The number of output audio channels in the decoded and interleaved PCM audio signal. */
542   AUDIO_CHANNEL_TYPE *pChannelType;      /*!< Audio channel type of each output audio channel.                                     */
543   UCHAR             *pChannelIndices;    /*!< Audio channel index for each output audio channel.
544                                                See ISO/IEC 13818-7:2005(E), 8.5.3.2 Explicit channel mapping using a program_config_element() */
545   /* Decoder internal members. */
546   INT               aacSampleRate;       /*!< Sampling rate in Hz without SBR (from configuration info).                           */
547   INT               profile;             /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g. MPEG-4)).               */
548   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). */
549   INT               channelConfig;       /*!< Channel configuration (0: PCE defined, 1: mono, 2: stereo, ...                       */
550   INT               bitRate;             /*!< Instantaneous bit rate.                   */
551   INT               aacSamplesPerFrame;  /*!< Samples per frame for the AAC core (from ASC). \n
552                                               1024 or 960 for AAC-LC \n
553                                               512 or 480 for AAC-LD and AAC-ELD         */
554   INT               aacNumChannels;      /*!< The number of audio channels after AAC core processing (before PS or MPS processing).
555                                               CAUTION: This are not the final number of output channels! */
556   AUDIO_OBJECT_TYPE extAot;              /*!< Extension Audio Object Type (from ASC)   */
557   INT               extSamplingRate;     /*!< Extension sampling rate in Hz (from ASC) */
558 
559   UINT              outputDelay;         /*!< The number of samples the output is additionally delayed by the decoder. */
560 
561   UINT              flags;               /*!< Copy of internal flags. Only to be written by the decoder, and only to be read externally. */
562 
563   SCHAR             epConfig;            /*!< epConfig level (from ASC): only level 0 supported, -1 means no ER (e. g. AOT=2, MPEG-2 AAC, etc.)  */
564 
565   /* Statistics */
566   INT               numLostAccessUnits;  /*!< This integer will reflect the estimated amount of lost access units in case aacDecoder_DecodeFrame()
567                                               returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be < 0 if the estimation failed. */
568 
569   UINT              numTotalBytes;       /*!< This is the number of total bytes that have passed through the decoder. */
570   UINT              numBadBytes;         /*!< This is the number of total bytes that were considered with errors from numTotalBytes. */
571   UINT              numTotalAccessUnits; /*!< This is the number of total access units that have passed through the decoder. */
572   UINT              numBadAccessUnits;   /*!< This is the number of total access units that were considered with errors from numTotalBytes. */
573 
574   /* Metadata */
575   SCHAR             drcProgRefLev;       /*!< DRC program reference level. Defines the reference level below full-scale.
576                                               It is quantized in steps of 0.25dB. The valid values range from 0 (0 dBFS) to 127 (-31.75 dBFS).
577                                               It is used to reflect the average loudness of the audio in LKFS accoring to ITU-R BS 1770.
578                                               If no level has been found in the bitstream the value is -1. */
579   SCHAR             drcPresMode;         /*!< DRC presentation mode. According to ETSI TS 101 154, this field indicates whether
580                                               light (MPEG-4 Dynamic Range Control tool) or heavy compression (DVB heavy compression)
581                                               dynamic range control shall take priority on the outputs.
582                                               For details, see ETSI TS 101 154, table C.33. Possible values are: \n
583                                               -1: No corresponding metadata found in the bitstream \n
584                                                0: DRC presentation mode not indicated \n
585                                                1: DRC presentation mode 1 \n
586                                                2: DRC presentation mode 2 \n
587                                                3: Reserved */
588 
589 } CStreamInfo;
590 
591 
592 typedef struct AAC_DECODER_INSTANCE *HANDLE_AACDECODER;  /*!< Pointer to a AAC decoder instance. */
593 
594 #ifdef __cplusplus
595 extern "C"
596 {
597 #endif
598 
599 /**
600  * \brief Initialize ancillary data buffer.
601  *
602  * \param self    AAC decoder handle.
603  * \param buffer  Pointer to (external) ancillary data buffer.
604  * \param size    Size of the buffer pointed to by buffer.
605  * \return        Error code.
606  */
607 LINKSPEC_H AAC_DECODER_ERROR
608 aacDecoder_AncDataInit ( HANDLE_AACDECODER self,
609                          UCHAR            *buffer,
610                          int               size );
611 
612 /**
613  * \brief Get one ancillary data element.
614  *
615  * \param self   AAC decoder handle.
616  * \param index  Index of the ancillary data element to get.
617  * \param ptr    Pointer to a buffer receiving a pointer to the requested ancillary data element.
618  * \param size   Pointer to a buffer receiving the length of the requested ancillary data element.
619  * \return       Error code.
620  */
621 LINKSPEC_H AAC_DECODER_ERROR
622 aacDecoder_AncDataGet ( HANDLE_AACDECODER self,
623                         int               index,
624                         UCHAR           **ptr,
625                         int              *size );
626 
627 /**
628  * \brief Set one single decoder parameter.
629  *
630  * \param self   AAC decoder handle.
631  * \param param  Parameter to be set.
632  * \param value  Parameter value.
633  * \return       Error code.
634  */
635 LINKSPEC_H AAC_DECODER_ERROR
636 aacDecoder_SetParam ( const HANDLE_AACDECODER  self,
637                       const AACDEC_PARAM       param,
638                       const INT                value );
639 
640 
641 /**
642  * \brief              Get free bytes inside decoder internal buffer
643  * \param self    Handle of AAC decoder instance
644  * \param pFreeBytes Pointer to variable receving amount of free bytes inside decoder internal buffer
645  * \return             Error code
646  */
647 LINKSPEC_H AAC_DECODER_ERROR
648 aacDecoder_GetFreeBytes ( const HANDLE_AACDECODER  self,
649                                             UINT *pFreeBytes);
650 
651 /**
652  * \brief               Open an AAC decoder instance
653  * \param transportFmt  The transport type to be used
654  * \return              AAC decoder handle
655  */
656 LINKSPEC_H HANDLE_AACDECODER
657 aacDecoder_Open ( TRANSPORT_TYPE transportFmt, UINT nrOfLayers );
658 
659 /**
660  * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig (ASC) or a StreamMuxConfig (SMC),
661  *  contained in a binary buffer. This is required for MPEG-4 and Raw Packets file format bitstreams
662  *  as well as for LATM bitstreams with no in-band SMC. If the transport format is LATM with or without
663  *  LOAS, configuration is assumed to be an SMC, for all other file formats an ASC.
664  *
665  * \param self    AAC decoder handle.
666  * \param conf    Pointer to an unsigned char buffer containing the binary configuration buffer (either ASC or SMC).
667  * \param length  Length of the configuration buffer in bytes.
668  * \return        Error code.
669  */
670 LINKSPEC_H AAC_DECODER_ERROR
671 aacDecoder_ConfigRaw ( HANDLE_AACDECODER self,
672                        UCHAR            *conf[],
673                        const UINT        length[] );
674 
675 
676 /**
677  * \brief Fill AAC decoder's internal input buffer with bitstream data from the external input buffer.
678  *  The function only copies such data as long as the decoder-internal input buffer is not full.
679  *  So it grabs whatever it can from pBuffer and returns information (bytesValid) so that at a
680  *  subsequent call of %aacDecoder_Fill(), the right position in pBuffer can be determined to
681  *  grab the next data.
682  *
683  * \param self        AAC decoder handle.
684  * \param pBuffer     Pointer to external input buffer.
685  * \param bufferSize  Size of external input buffer. This argument is required because decoder-internally
686  *                    we need the information to calculate the offset to pBuffer, where the next
687  *                    available data is, which is then fed into the decoder-internal buffer (as much
688  *                    as possible). Our example framework implementation fills the buffer at pBuffer
689  *                    again, once it contains no available valid bytes anymore (meaning bytesValid equal 0).
690  * \param bytesValid  Number of bitstream bytes in the external bitstream buffer that have not yet been
691  *                    copied into the decoder's internal bitstream buffer by calling this function.
692  *                    The value is updated according to the amount of newly copied bytes.
693  * \return            Error code.
694  */
695 LINKSPEC_H AAC_DECODER_ERROR
696 aacDecoder_Fill ( HANDLE_AACDECODER  self,
697                   UCHAR             *pBuffer[],
698                   const UINT         bufferSize[],
699                   UINT              *bytesValid );
700 
701 #define AACDEC_CONCEAL  1 /*!< Flag for aacDecoder_DecodeFrame(): Trigger the built-in error concealment module \
702                                  to generate a substitute signal for one lost frame. New input data will not be
703                                  considered. */
704 #define AACDEC_FLUSH    2 /*!< Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all delayed audio \
705                                  without having new input data. Thus new input data will not be considered.*/
706 #define AACDEC_INTR     4 /*!< Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data discontinuity. \
707                                  Resync any internals as necessary. */
708 #define AACDEC_CLRHIST  8 /*!< Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and history buffers.\
709                                  CAUTION: This can cause discontinuities in the output signal. */
710 
711 /**
712  * \brief            Decode one audio frame
713  *
714  * \param self       AAC decoder handle.
715  * \param pTimeData  Pointer to external output buffer where the decoded PCM samples will be stored into.
716  * \param flags      Bit field with flags for the decoder: \n
717  *                   (flags & AACDEC_CONCEAL) == 1: Do concealment. \n
718  *                   (flags & AACDEC_FLUSH) == 2: Discard input data. Flush filter banks (output delayed audio). \n
719  *                   (flags & AACDEC_INTR) == 4: Input data is discontinuous. Resynchronize any internals as necessary.
720  * \return           Error code.
721  */
722 LINKSPEC_H AAC_DECODER_ERROR
723 aacDecoder_DecodeFrame ( HANDLE_AACDECODER  self,
724                          INT_PCM           *pTimeData,
725                          const INT          timeDataSize,
726                          const UINT         flags );
727 
728 /**
729  * \brief       De-allocate all resources of an AAC decoder instance.
730  *
731  * \param self  AAC decoder handle.
732  * \return      void
733  */
734 LINKSPEC_H void aacDecoder_Close ( HANDLE_AACDECODER self );
735 
736 /**
737  * \brief       Get CStreamInfo handle from decoder.
738  *
739  * \param self  AAC decoder handle.
740  * \return      Reference to requested CStreamInfo.
741  */
742 LINKSPEC_H CStreamInfo* aacDecoder_GetStreamInfo( HANDLE_AACDECODER self );
743 
744 /**
745  * \brief       Get decoder library info.
746  *
747  * \param info  Pointer to an allocated LIB_INFO structure.
748  * \return      0 on success
749  */
750 LINKSPEC_H INT aacDecoder_GetLibInfo( LIB_INFO *info );
751 
752 
753 #ifdef __cplusplus
754 }
755 #endif
756 
757 #endif /* AACDECODER_LIB_H */
758