1 2 /* ----------------------------------------------------------------------------------------------------------- 3 Software License for The Fraunhofer FDK AAC Codec Library for Android 4 5 � Copyright 1995 - 2012 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 (see \ref CommandLineUsage). For any other bitstream formats that are 148 usually applicable in streaming applications, the decoder itself will try to synchronize and parse the given 149 bitstream fragment using the FDK transport library. Hence, for streaming applications (without file access) 150 this step is not necessary. 151 152 -# Call aacDecoder_Open() to open and retrieve a handle to a new AAC decoder instance. 153 \dontinclude main.cpp 154 \skipline aacDecoder_Open 155 -# If out-of-band config data (Audio Specific Config (ASC) or Stream Mux Config (SMC)) is available, call 156 aacDecoder_ConfigRaw() to pass it to the decoder and before the decoding process starts. If this data is 157 not available in advance, the decoder will get it from the bitstream and configure itself while decoding 158 with aacDecoder_DecodeFrame(). 159 -# Begin decoding loop. 160 \skipline do { 161 -# Read data from bitstream file or stream into a client-supplied input buffer ("inBuffer" in main.cpp). 162 If it is very small like just 4, aacDecoder_DecodeFrame() will 163 repeatedly return ::AAC_DEC_NOT_ENOUGH_BITS until enough bits were fed by aacDecoder_Fill(). Only read data 164 when this buffer has completely been processed and is then empty. For file-based input execute 165 mpegFileRead_Read() or any other implementation with similar functionality. 166 -# Call aacDecoder_Fill() to fill the decoder's internal bitstream input buffer with the client-supplied 167 external bitstream input buffer. 168 \skipline aacDecoder_Fill 169 -# Call aacDecoder_DecodeFrame() which writes decoded PCM audio data to a client-supplied buffer. It is the 170 client's responsibility to allocate a buffer which is large enough to hold this output data. 171 \skipline aacDecoder_DecodeFrame 172 If the bitstream's configuration (number of channels, sample rate, frame size) is not known in advance, you may 173 call aacDecoder_GetStreamInfo() to retrieve a structure containing this information and then initialize an audio 174 output device. In the example main.cpp, if the number of channels or the sample rate has changed since program 175 start or since the previously decoded frame, the audio output device will be re-initialized. If WAVE file output 176 is chosen, a new WAVE file for each new configuration will be created. 177 \skipline aacDecoder_GetStreamInfo 178 -# Repeat steps 5 to 7 until no data to decode is available anymore, or if an error occured. 179 \skipline } while 180 -# Call aacDecoder_Close() to de-allocate all AAC decoder and transport layer structures. 181 \skipline aacDecoder_Close 182 183 \section BufferSystem Buffer System 184 185 There are three main buffers in an AAC decoder application. One external input buffer to hold bitstream 186 data from file I/O or elsewhere, one decoder-internal input buffer, and one to hold the decoded output 187 PCM sample data, whereas this output buffer may overlap with the external input buffer. 188 189 The external input buffer is set in the example framework main.cpp and its size is defined by ::IN_BUF_SIZE. 190 You may freely choose different sizes here. To feed the data to the decoder-internal input buffer, use the 191 function aacDecoder_Fill(). This function returns important information about how many bytes in the 192 external input buffer have not yet been copied into the internal input buffer (variable bytesValid). 193 Once the external buffer has been fully copied, it can be re-filled again. 194 In case you want to re-fill it when there are still unprocessed bytes (bytesValid is unequal 0), you 195 would have to additionally perform a memcpy(), so that just means unnecessary computational overhead 196 and therefore we recommend to re-fill the buffer only when bytesValid is 0. 197 198 \image latex dec_buffer.png "Lifecycle of the external input buffer" width=9cm 199 200 The size of the decoder-internal input buffer is set in tpdec_lib.h (see define ::TRANSPORTDEC_INBUF_SIZE). 201 You may choose a smaller size under the following considerations: 202 203 - each input channel requires 768 bytes 204 - the whole buffer must be of size 2^n 205 206 So for example a stereo decoder: 207 208 \f[ 209 TRANSPORTDEC\_INBUF\_SIZE = 2 * 768 = 1536 => 2048 210 \f] 211 212 tpdec_lib.h and TRANSPORTDEC_INBUF_SIZE are not part of the decoder's library interface. Therefore 213 only source-code clients may change this setting. If you received a library release, please ask us and 214 we can change this in order to meet your memory requirements. 215 216 \page OutputFormat Decoder audio output 217 218 \section OutputFormatObtaining Obtaining channel mapping information 219 220 The decoded audio output format is indicated by a set of variables of the CStreamInfo structure. 221 While the members sampleRate, frameSize and numChannels might be quite self explaining, 222 pChannelType and pChannelIndices might require some more detailed explanation. 223 224 These two arrays indicate what is each output channel supposed to be. Both array have 225 CStreamInfo::numChannels cells. Each cell of pChannelType indicates the channel type, described in 226 the enum ::AUDIO_CHANNEL_TYPE defined in FDK_audio.h. The cells of pChannelIndices indicate the sub index 227 among the channels starting with 0 among all channels of the same audio channel type. 228 229 The indexing scheme is the same as for MPEG-2/4. Thus indices are counted upwards starting from the front 230 direction (thus a center channel if any, will always be index 0). Then the indices count up, starting always 231 with the left side, pairwise from front toward back. For detailed explanation, please refer to 232 ISO/IEC 13818-7:2005(E), chapter 8.5.3.2. 233 234 In case a Program Config is included in the audio configuration, the channel mapping described within 235 it will be adopted. 236 237 In case of MPEG-D Surround the channel mapping will follow the same criteria described in ISO/IEC 13818-7:2005(E), 238 but adding corresponding top channels to the channel types front, side and back, in order to avoid any 239 loss of information. 240 241 \section OutputFormatChange Changing the audio output format 242 243 The channel interleaving scheme and the actual channel order can be changed at runtime through the 244 parameters ::AAC_PCM_OUTPUT_INTERLEAVED and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING. See the description of those 245 parameters and the decoder library function aacDecoder_SetParam() for more detail. 246 247 \section OutputFormatExample Channel mapping examples 248 249 The following examples illustrate the location of individual audio samples in the audio buffer that 250 is passed to aacDecoder_DecodeFrame() and the expected data in the CStreamInfo structure which can be obtained 251 by calling aacDecoder_GetStreamInfo(). 252 253 \subsection ExamplesStereo Stereo 254 255 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 0 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1, 256 a AAC-LC bit stream which has channelConfiguration = 2 in its audio specific config would lead 257 to the following values in CStreamInfo: 258 259 CStreamInfo::numChannels = 2 260 261 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT } 262 263 CStreamInfo::pChannelIndices = { 0, 1 } 264 265 Since ::AAC_PCM_OUTPUT_INTERLEAVED is set to 0, the audio channels will be located as contiguous blocks 266 in the output buffer as follows: 267 268 \verbatim 269 <left sample 0> <left sample 1> <left sample 2> ... <left sample N> 270 <right sample 0> <right sample 1> <right sample 2> ... <right sample N> 271 \endverbatim 272 273 Where N equals to CStreamInfo::frameSize . 274 275 \subsection ExamplesSurround Surround 5.1 276 277 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 1 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1, 278 a AAC-LC bit stream which has channelConfiguration = 6 in its audio specific config, would lead 279 to the following values in CStreamInfo: 280 281 CStreamInfo::numChannels = 6 282 283 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT, ::ACT_FRONT, ::ACT_LFE, ::ACT_BACK, ::ACT_BACK } 284 285 CStreamInfo::pChannelIndices = { 1, 2, 0, 0, 0, 1 } 286 287 Since ::AAC_PCM_OUTPUT_CHANNEL_MAPPING is 1, WAV file channel ordering will be used. For a 5.1 channel 288 scheme, thus the channels would be: front left, front right, center, LFE, surround left, surround right. 289 Thus the third channel is the center channel, receiving the index 0. The other front channels are 290 front left, front right being placed as first and second channels with indices 1 and 2 correspondingly. 291 There is only one LFE, placed as the fourth channel and index 0. Finally both surround 292 channels get the type definition ACT_BACK, and the indices 0 and 1. 293 294 Since ::AAC_PCM_OUTPUT_INTERLEAVED is set to 1, the audio channels will be placed in the output buffer 295 as follows: 296 297 \verbatim 298 <front left sample 0> <front right sample 0> 299 <center sample 0> <LFE sample 0> 300 <surround left sample 0> <surround right sample 0> 301 302 <front left sample 1> <front right sample 1> 303 <center sample 1> <LFE sample 1> 304 <surround left sample 1> <surround right sample 1> 305 306 ... 307 308 <front left sample N> <front right sample N> 309 <center sample N> <LFE sample N> 310 <surround left sample N> <surround right sample N> 311 \endverbatim 312 313 Where N equals to CStreamInfo::frameSize . 314 315 \subsection ExamplesArib ARIB coding mode 2/1 316 317 In case of ::AAC_PCM_OUTPUT_INTERLEAVED set to 1 and ::AAC_PCM_OUTPUT_CHANNEL_MAPPING set to 1, 318 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, 319 would lead to the following values in CStreamInfo: 320 321 CStreamInfo::numChannels = 3 322 323 CStreamInfo::pChannelType = { ::ACT_FRONT, ::ACT_FRONT,:: ACT_BACK } 324 325 CStreamInfo::pChannelIndices = { 0, 1, 0 } 326 327 The audio channels will be placed as follows in the audio output buffer: 328 329 \verbatim 330 <front left sample 0> <front right sample 0> <mid surround sample 0> 331 332 <front left sample 1> <front right sample 1> <mid surround sample 1> 333 334 ... 335 336 <front left sample N> <front right sample N> <mid surround sample N> 337 338 Where N equals to CStreamInfo::frameSize . 339 340 \endverbatim 341 342 */ 343 344 #ifndef AACDECODER_LIB_H 345 #define AACDECODER_LIB_H 346 347 #include "machine_type.h" 348 #include "FDK_audio.h" 349 350 #include "genericStds.h" 351 352 /** 353 * \brief AAC decoder error codes. 354 */ 355 typedef enum { 356 AAC_DEC_OK = 0x0000, /*!< No error occured. Output buffer is valid and error free. */ 357 AAC_DEC_OUT_OF_MEMORY = 0x0002, /*!< Heap returned NULL pointer. Output buffer is invalid. */ 358 AAC_DEC_UNKNOWN = 0x0005, /*!< Error condition is of unknown reason, or from a another module. Output buffer is invalid. */ 359 360 /* Synchronization errors. Output buffer is invalid. */ 361 aac_dec_sync_error_start = 0x1000, 362 AAC_DEC_TRANSPORT_SYNC_ERROR = 0x1001, /*!< The transport decoder had syncronisation problems. Do not exit decoding. Just feed new 363 bitstream data. */ 364 AAC_DEC_NOT_ENOUGH_BITS = 0x1002, /*!< The input buffer ran out of bits. */ 365 aac_dec_sync_error_end = 0x1FFF, 366 367 /* Initialization errors. Output buffer is invalid. */ 368 aac_dec_init_error_start = 0x2000, 369 AAC_DEC_INVALID_HANDLE = 0x2001, /*!< The handle passed to the function call was invalid (NULL). */ 370 AAC_DEC_UNSUPPORTED_AOT = 0x2002, /*!< The AOT found in the configuration is not supported. */ 371 AAC_DEC_UNSUPPORTED_FORMAT = 0x2003, /*!< The bitstream format is not supported. */ 372 AAC_DEC_UNSUPPORTED_ER_FORMAT = 0x2004, /*!< The error resilience tool format is not supported. */ 373 AAC_DEC_UNSUPPORTED_EPCONFIG = 0x2005, /*!< The error protection format is not supported. */ 374 AAC_DEC_UNSUPPORTED_MULTILAYER = 0x2006, /*!< More than one layer for AAC scalable is not supported. */ 375 AAC_DEC_UNSUPPORTED_CHANNELCONFIG = 0x2007, /*!< The channel configuration (either number or arrangement) is not supported. */ 376 AAC_DEC_UNSUPPORTED_SAMPLINGRATE = 0x2008, /*!< The sample rate specified in the configuration is not supported. */ 377 AAC_DEC_INVALID_SBR_CONFIG = 0x2009, /*!< The SBR configuration is not supported. */ 378 AAC_DEC_SET_PARAM_FAIL = 0x200A, /*!< The parameter could not be set. Either the value was out of range or the parameter does 379 not exist. */ 380 AAC_DEC_NEED_TO_RESTART = 0x200B, /*!< The decoder needs to be restarted, since the requiered configuration change cannot be 381 performed. */ 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_OUTPUT_CHANNELS = 0x0001, /*!< Number of PCM output channels (if different from encoded audio channels, downmixing or 434 upmixing is applied). \n 435 -1: Disable up-/downmixing. The decoder output contains the same number of channels as the 436 encoded bitstream. \n 437 1: The decoder performs a mono matrix mix-down if the encoded audio channels are greater 438 than one. Thus it ouputs always exact one channel. \n 439 2: The decoder performs a stereo matrix mix-down if the encoded audio channels are greater 440 than two. If the encoded audio channels are smaller than two the decoder duplicates the 441 output. Thus it ouputs always exact two channels. \n */ 442 AAC_PCM_DUAL_CHANNEL_OUTPUT_MODE = 0x0002, /*!< Defines how the decoder processes two channel signals: 443 0: Leave both signals as they are (default). 444 1: Create a dual mono output signal from channel 1. 445 2: Create a dual mono output signal from channel 2. 446 3: Create a dual mono output signal by mixing both channels (L' = R' = 0.5*Ch1 + 0.5*Ch2). */ 447 AAC_PCM_OUTPUT_CHANNEL_MAPPING = 0x0003, /*!< Output buffer channel ordering. 0: MPEG PCE style order, 1: WAV file channel order (default). */ 448 449 AAC_CONCEAL_METHOD = 0x0100, /*!< Error concealment: Processing method. \n 450 0: Spectral muting. \n 451 1: Noise substitution (see ::CONCEAL_NOISE). \n 452 2: Energy interpolation (adds additional signal delay of one frame, see ::CONCEAL_INTER). \n */ 453 454 AAC_DRC_BOOST_FACTOR = 0x0200, /*!< Dynamic Range Control: Scaling factor for boosting gain values. 455 Defines how the boosting DRC factors (conveyed in the bitstream) will be applied to the 456 decoded signal. The valid values range from 0 (don't apply boost factors) to 127 (fully 457 apply all boosting factors). */ 458 AAC_DRC_ATTENUATION_FACTOR = 0x0201, /*!< Dynamic Range Control: Scaling factor for attenuating gain values. Same as 459 AAC_DRC_BOOST_FACTOR but for attenuating DRC factors. */ 460 AAC_DRC_REFERENCE_LEVEL = 0x0202, /*!< Dynamic Range Control: Target reference level. Defines the level below full-scale 461 (quantized in steps of 0.25dB) to which the output audio signal will be normalized to by 462 the DRC module. The valid values range from 0 (full-scale) to 127 (31.75 dB below 463 full-scale). The value smaller than 0 switches off normalization. */ 464 AAC_DRC_HEAVY_COMPRESSION = 0x0203, /*!< Dynamic Range Control: En-/Disable DVB specific heavy compression (aka RF mode). 465 If set to 1, the decoder will apply the compression values from the DVB specific ancillary 466 data field. At the same time the MPEG-4 Dynamic Range Control tool will be disabled. By 467 default heavy compression is disabled. */ 468 469 AAC_QMF_LOWPOWER = 0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing mode. \n 470 -1: Use internal default. Implies MPEG Surround partially complex accordingly. \n 471 0: Use complex QMF data mode. \n 472 1: Use real (low power) QMF data mode. \n */ 473 474 AAC_MPEGS_ENABLE = 0x0500, /*!< MPEG Surround: Allow/Disable decoding of MPS content. Available only for decoders with MPEG 475 Surround support. */ 476 477 AAC_TPDEC_CLEAR_BUFFER = 0x0603 /*!< Clear internal bit stream buffer of transport layers. The decoder will start decoding 478 at new data passed after this event and any previous data is discarded. */ 479 480 } AACDEC_PARAM; 481 482 /** 483 * \brief This structure gives information about the currently decoded audio data. 484 * All fields are read-only. 485 */ 486 typedef struct 487 { 488 /* These three members are the only really relevant ones for the user. */ 489 INT sampleRate; /*!< The samplerate in Hz of the fully decoded PCM audio signal (after SBR processing). */ 490 INT frameSize; /*!< The frame size of the decoded PCM audio signal. \n 491 1024 or 960 for AAC-LC \n 492 2048 or 1920 for HE-AAC (v2) \n 493 512 or 480 for AAC-LD and AAC-ELD */ 494 INT numChannels; /*!< The number of output audio channels in the decoded and interleaved PCM audio signal. */ 495 AUDIO_CHANNEL_TYPE *pChannelType; /*!< Audio channel type of each output audio channel. */ 496 UCHAR *pChannelIndices; /*!< Audio channel index for each output audio channel. 497 See ISO/IEC 13818-7:2005(E), 8.5.3.2 Explicit channel mapping using a program_config_element() */ 498 /* Decoder internal members. */ 499 INT aacSampleRate; /*!< sampling rate in Hz without SBR (from configuration info). */ 500 INT profile; /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g. MPEG-4)). */ 501 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). */ 502 INT channelConfig; /*!< Channel configuration (0: PCE defined, 1: mono, 2: stereo, ... */ 503 INT bitRate; /*!< Instantaneous bit rate. */ 504 INT aacSamplesPerFrame; /*!< Samples per frame for the AAC core (from ASC). \n 505 1024 or 960 for AAC-LC \n 506 512 or 480 for AAC-LD and AAC-ELD */ 507 508 AUDIO_OBJECT_TYPE extAot; /*!< Extension Audio Object Type (from ASC) */ 509 INT extSamplingRate; /*!< Extension sampling rate in Hz (from ASC) */ 510 511 UINT flags; /*!< Copy if internal flags. Only to be written by the decoder, and only to be read externally. */ 512 513 SCHAR epConfig; /*!< epConfig level (from ASC): only level 0 supported, -1 means no ER (e. g. AOT=2, MPEG-2 AAC, etc.) */ 514 515 /* Statistics */ 516 INT numLostAccessUnits; /*!< This integer will reflect the estimated amount of lost access units in case aacDecoder_DecodeFrame() 517 returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be < 0 if the estimation failed. */ 518 519 UINT numTotalBytes; /*!< This is the number of total bytes that have passed through the decoder. */ 520 UINT numBadBytes; /*!< This is the number of total bytes that were considered with errors from numTotalBytes. */ 521 UINT numTotalAccessUnits; /*!< This is the number of total access units that have passed through the decoder. */ 522 UINT numBadAccessUnits; /*!< This is the number of total access units that were considered with errors from numTotalBytes. */ 523 524 } CStreamInfo; 525 526 527 typedef struct AAC_DECODER_INSTANCE *HANDLE_AACDECODER; 528 529 #ifdef __cplusplus 530 extern "C" 531 { 532 #endif 533 534 /** 535 * \brief Initialize ancillary data buffer. 536 * 537 * \param self AAC decoder handle. 538 * \param buffer Pointer to (external) ancillary data buffer. 539 * \param size Size of the buffer pointed to by buffer. 540 * \return Error code. 541 */ 542 LINKSPEC_H AAC_DECODER_ERROR 543 aacDecoder_AncDataInit ( HANDLE_AACDECODER self, 544 UCHAR *buffer, 545 int size ); 546 547 /** 548 * \brief Get one ancillary data element. 549 * 550 * \param self AAC decoder handle. 551 * \param index Index of the ancillary data element to get. 552 * \param ptr Pointer to a buffer receiving a pointer to the requested ancillary data element. 553 * \param size Pointer to a buffer receiving the length of the requested ancillary data element. 554 * \return Error code. 555 */ 556 LINKSPEC_H AAC_DECODER_ERROR 557 aacDecoder_AncDataGet ( HANDLE_AACDECODER self, 558 int index, 559 UCHAR **ptr, 560 int *size ); 561 562 /** 563 * \brief Set one single decoder parameter. 564 * 565 * \param self AAC decoder handle. 566 * \param param Parameter to be set. 567 * \param value Parameter value. 568 * \return Error code. 569 */ 570 LINKSPEC_H AAC_DECODER_ERROR 571 aacDecoder_SetParam ( const HANDLE_AACDECODER self, 572 const AACDEC_PARAM param, 573 const INT value ); 574 575 576 /** 577 * \brief Get free bytes inside decoder internal buffer 578 * \param self Handle of AAC decoder instance 579 * \param pFreeBytes Pointer to variable receving amount of free bytes inside decoder internal buffer 580 * \return Error code 581 */ 582 LINKSPEC_H AAC_DECODER_ERROR 583 aacDecoder_GetFreeBytes ( const HANDLE_AACDECODER self, 584 UINT *pFreeBytes); 585 586 /** 587 * \brief Open an AAC decoder instance 588 * \param transportFmt The transport type to be used 589 * \return AAC decoder handle 590 */ 591 LINKSPEC_H HANDLE_AACDECODER 592 aacDecoder_Open ( TRANSPORT_TYPE transportFmt, UINT nrOfLayers ); 593 594 /** 595 * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig (ASC) or a StreamMuxConfig (SMC), 596 * contained in a binary buffer. This is required for MPEG-4 and Raw Packets file format bitstreams 597 * as well as for LATM bitstreams with no in-band SMC. If the transport format is LATM with or without 598 * LOAS, configuration is assumed to be an SMC, for all other file formats an ASC. 599 * 600 * \param self AAC decoder handle. 601 * \param conf Pointer to an unsigned char buffer containing the binary configuration buffer (either ASC or SMC). 602 * \param length Length of the configuration buffer in bytes. 603 * \return Error code. 604 */ 605 LINKSPEC_H AAC_DECODER_ERROR 606 aacDecoder_ConfigRaw ( HANDLE_AACDECODER self, 607 UCHAR *conf[], 608 const UINT length[] ); 609 610 611 /** 612 * \brief Fill AAC decoder's internal input buffer with bitstream data from the external input buffer. 613 * The function only copies such data as long as the decoder-internal input buffer is not full. 614 * So it grabs whatever it can from pBuffer and returns information (bytesValid) so that at a 615 * subsequent call of %aacDecoder_Fill(), the right position in pBuffer can be determined to 616 * grab the next data. 617 * 618 * \param self AAC decoder handle. 619 * \param pBuffer Pointer to external input buffer. 620 * \param bufferSize Size of external input buffer. This argument is required because decoder-internally 621 * we need the information to calculate the offset to pBuffer, where the next 622 * available data is, which is then fed into the decoder-internal buffer (as much 623 * as possible). Our example framework implementation fills the buffer at pBuffer 624 * again, once it contains no available valid bytes anymore (meaning bytesValid equal 0). 625 * \param bytesValid Number of bitstream bytes in the external bitstream buffer that have not yet been 626 * copied into the decoder's internal bitstream buffer by calling this function. 627 * The value is updated according to the amount of newly copied bytes. 628 * \return Error code. 629 */ 630 LINKSPEC_H AAC_DECODER_ERROR 631 aacDecoder_Fill ( HANDLE_AACDECODER self, 632 UCHAR *pBuffer[], 633 const UINT bufferSize[], 634 UINT *bytesValid ); 635 636 #define AACDEC_CONCEAL 1 /*!< Flag for aacDecoder_DecodeFrame(): do not consider new input data. Do concealment. */ 637 #define AACDEC_FLUSH 2 /*!< Flag for aacDecoder_DecodeFrame(): Do not consider new input data. Flush filterbanks (output delayed audio). */ 638 #define AACDEC_INTR 4 /*!< Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data discontinuity. Resync any internals as necessary. */ 639 #define AACDEC_CLRHIST 8 /*!< Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and history buffers. 640 Caution: This can cause discontinuities in the output signal. */ 641 642 /** 643 * \brief Decode one audio frame 644 * 645 * \param self AAC decoder handle. 646 * \param pTimeData Pointer to external output buffer where the decoded PCM samples will be stored into. 647 * \param flags Bit field with flags for the decoder: \n 648 * (flags & AACDEC_CONCEAL) == 1: Do concealment. \n 649 * (flags & AACDEC_FLUSH) == 2: Discard input data. Flush filter banks (output delayed audio). \n 650 * (flags & AACDEC_INTR) == 4: Input data is discontinuous. Resynchronize any internals as necessary. 651 * \return Error code. 652 */ 653 LINKSPEC_H AAC_DECODER_ERROR 654 aacDecoder_DecodeFrame ( HANDLE_AACDECODER self, 655 INT_PCM *pTimeData, 656 const INT timeDataSize, 657 const UINT flags ); 658 659 /** 660 * \brief De-allocate all resources of an AAC decoder instance. 661 * 662 * \param self AAC decoder handle. 663 * \return void 664 */ 665 LINKSPEC_H void aacDecoder_Close ( HANDLE_AACDECODER self ); 666 667 /** 668 * \brief Get CStreamInfo handle from decoder. 669 * 670 * \param self AAC decoder handle. 671 * \return Reference to requested CStreamInfo. 672 */ 673 LINKSPEC_H CStreamInfo* aacDecoder_GetStreamInfo( HANDLE_AACDECODER self ); 674 675 /** 676 * \brief Get decoder library info. 677 * 678 * \param info Pointer to an allocated LIB_INFO structure. 679 * \return 0 on success 680 */ 681 LINKSPEC_H INT aacDecoder_GetLibInfo( LIB_INFO *info ); 682 683 684 #ifdef __cplusplus 685 } 686 #endif 687 688 #endif /* AACDECODER_LIB_H */ 689