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