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 amm-info@iis.fraunhofer.de 93 ----------------------------------------------------------------------------- */ 94 95 /**************************** AAC decoder library ****************************** 96 97 Author(s): Manuel Jander 98 99 Description: 100 101 *******************************************************************************/ 102 103 #ifndef AACDECODER_LIB_H 104 #define AACDECODER_LIB_H 105 106 /** 107 * \file aacdecoder_lib.h 108 * \brief FDK AAC decoder library interface header file. 109 * 110 111 \page INTRO Introduction 112 113 114 \section SCOPE Scope 115 116 This document describes the high-level application interface and usage of the 117 ISO/MPEG-2/4 AAC Decoder library developed by the Fraunhofer Institute for 118 Integrated Circuits (IIS). Depending on the library configuration, decoding of 119 AAC-LC (Low-Complexity), HE-AAC (High-Efficiency AAC v1 and v2), AAC-LD 120 (Low-Delay) and AAC-ELD (Enhanced Low-Delay) is implemented. 121 122 All references to SBR (Spectral Band Replication) are only applicable to HE-AAC 123 and AAC-ELD configurations of the FDK library. All references to PS (Parametric 124 Stereo) are only applicable to HE-AAC v2 decoder configuration of the library. 125 126 \section DecoderBasics Decoder Basics 127 128 This document can only give a rough overview about the ISO/MPEG-2, ISO/MPEG-4 129 AAC audio and MPEG-D USAC coding standards. To understand all details referenced 130 in this document, you are encouraged to read the following documents. 131 132 - ISO/IEC 13818-7 (MPEG-2 AAC) Standard, defines the syntax of MPEG-2 AAC audio 133 bitstreams. 134 - ISO/IEC 14496-3 (MPEG-4 AAC, subpart 1 and 4) Standard, defines the syntax of 135 MPEG-4 AAC audio bitstreams. 136 - ISO/IEC 23003-3 (MPEG-D USAC), defines MPEG-D USAC unified speech and audio 137 codec. 138 - Lutzky, Schuller, Gayer, Krämer, Wabnik, "A guideline to audio codec 139 delay", 116th AES Convention, May 8, 2004 140 141 In short, MPEG Advanced Audio Coding is based on a time-to-frequency mapping of 142 the signal. The signal is partitioned into overlapping time portions and 143 transformed into frequency domain. The spectral components are then quantized 144 and coded using a highly efficient coding scheme.\n Encoded MPEG-2 and MPEG-4 145 AAC audio bitstreams are composed of frames. Contrary to MPEG-1/2 Layer-3 (mp3), 146 the length of individual frames is not restricted to a fixed number of bytes, 147 but can take any length between 1 and 768 bytes. 148 149 In addition to the above mentioned frequency domain coding mode, MPEG-D USAC 150 also employs a time domain Algebraic Code-Excited Linear Prediction (ACELP) 151 speech coder core. This operating mode is selected by the encoder in order to 152 achieve the optimum audio quality for different content type. Several 153 enhancements allow achieving higher quality at lower bit rates compared to 154 MPEG-4 HE-AAC. 155 156 157 \page LIBUSE Library Usage 158 159 160 \section InterfaceDescritpion API Description 161 162 All API header files are located in the folder /include of the release package. 163 The contents of each file is described in detail in this document. All header 164 files are provided for usage in specific C/C++ programs. The main AAC decoder 165 library API functions are located in aacdecoder_lib.h header file. 166 167 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 #include "genericStds.h" 435 /** 436 * \brief AAC decoder error codes. 437 */ 438 typedef enum { 439 AAC_DEC_OK = 440 0x0000, /*!< No error occurred. Output buffer is valid and error free. */ 441 AAC_DEC_OUT_OF_MEMORY = 442 0x0002, /*!< Heap returned NULL pointer. Output buffer is invalid. */ 443 AAC_DEC_UNKNOWN = 444 0x0005, /*!< Error condition is of unknown reason, or from a another 445 module. Output buffer is invalid. */ 446 447 /* Synchronization errors. Output buffer is invalid. */ 448 aac_dec_sync_error_start = 0x1000, 449 AAC_DEC_TRANSPORT_SYNC_ERROR = 0x1001, /*!< The transport decoder had 450 synchronization problems. Do not 451 exit decoding. Just feed new 452 bitstream data. */ 453 AAC_DEC_NOT_ENOUGH_BITS = 0x1002, /*!< The input buffer ran out of bits. */ 454 aac_dec_sync_error_end = 0x1FFF, 455 456 /* Initialization errors. Output buffer is invalid. */ 457 aac_dec_init_error_start = 0x2000, 458 AAC_DEC_INVALID_HANDLE = 459 0x2001, /*!< The handle passed to the function call was invalid (NULL). */ 460 AAC_DEC_UNSUPPORTED_AOT = 461 0x2002, /*!< The AOT found in the configuration is not supported. */ 462 AAC_DEC_UNSUPPORTED_FORMAT = 463 0x2003, /*!< The bitstream format is not supported. */ 464 AAC_DEC_UNSUPPORTED_ER_FORMAT = 465 0x2004, /*!< The error resilience tool format is not supported. */ 466 AAC_DEC_UNSUPPORTED_EPCONFIG = 467 0x2005, /*!< The error protection format is not supported. */ 468 AAC_DEC_UNSUPPORTED_MULTILAYER = 469 0x2006, /*!< More than one layer for AAC scalable is not supported. */ 470 AAC_DEC_UNSUPPORTED_CHANNELCONFIG = 471 0x2007, /*!< The channel configuration (either number or arrangement) is 472 not supported. */ 473 AAC_DEC_UNSUPPORTED_SAMPLINGRATE = 0x2008, /*!< The sample rate specified in 474 the configuration is not 475 supported. */ 476 AAC_DEC_INVALID_SBR_CONFIG = 477 0x2009, /*!< The SBR configuration is not supported. */ 478 AAC_DEC_SET_PARAM_FAIL = 0x200A, /*!< The parameter could not be set. Either 479 the value was out of range or the 480 parameter does not exist. */ 481 AAC_DEC_NEED_TO_RESTART = 0x200B, /*!< The decoder needs to be restarted, 482 since the required configuration change 483 cannot be performed. */ 484 AAC_DEC_OUTPUT_BUFFER_TOO_SMALL = 485 0x200C, /*!< The provided output buffer is too small. */ 486 aac_dec_init_error_end = 0x2FFF, 487 488 /* Decode errors. Output buffer is valid but concealed. */ 489 aac_dec_decode_error_start = 0x4000, 490 AAC_DEC_TRANSPORT_ERROR = 491 0x4001, /*!< The transport decoder encountered an unexpected error. */ 492 AAC_DEC_PARSE_ERROR = 0x4002, /*!< Error while parsing the bitstream. Most 493 probably it is corrupted, or the system 494 crashed. */ 495 AAC_DEC_UNSUPPORTED_EXTENSION_PAYLOAD = 496 0x4003, /*!< Error while parsing the extension payload of the bitstream. 497 The extension payload type found is not supported. */ 498 AAC_DEC_DECODE_FRAME_ERROR = 0x4004, /*!< The parsed bitstream value is out of 499 range. Most probably the bitstream is 500 corrupt, or the system crashed. */ 501 AAC_DEC_CRC_ERROR = 0x4005, /*!< The embedded CRC did not match. */ 502 AAC_DEC_INVALID_CODE_BOOK = 0x4006, /*!< An invalid codebook was signaled. 503 Most probably the bitstream is corrupt, 504 or the system crashed. */ 505 AAC_DEC_UNSUPPORTED_PREDICTION = 506 0x4007, /*!< Predictor found, but not supported in the AAC Low Complexity 507 profile. Most probably the bitstream is corrupt, or has a wrong 508 format. */ 509 AAC_DEC_UNSUPPORTED_CCE = 0x4008, /*!< A CCE element was found which is not 510 supported. Most probably the bitstream is 511 corrupt, or has a wrong format. */ 512 AAC_DEC_UNSUPPORTED_LFE = 0x4009, /*!< A LFE element was found which is not 513 supported. Most probably the bitstream is 514 corrupt, or has a wrong format. */ 515 AAC_DEC_UNSUPPORTED_GAIN_CONTROL_DATA = 516 0x400A, /*!< Gain control data found but not supported. Most probably the 517 bitstream is corrupt, or has a wrong format. */ 518 AAC_DEC_UNSUPPORTED_SBA = 519 0x400B, /*!< SBA found, but currently not supported in the BSAC profile. 520 */ 521 AAC_DEC_TNS_READ_ERROR = 0x400C, /*!< Error while reading TNS data. Most 522 probably the bitstream is corrupt or the 523 system crashed. */ 524 AAC_DEC_RVLC_ERROR = 525 0x400D, /*!< Error while decoding error resilient data. */ 526 aac_dec_decode_error_end = 0x4FFF, 527 /* Ancillary data errors. Output buffer is valid. */ 528 aac_dec_anc_data_error_start = 0x8000, 529 AAC_DEC_ANC_DATA_ERROR = 530 0x8001, /*!< Non severe error concerning the ancillary data handling. */ 531 AAC_DEC_TOO_SMALL_ANC_BUFFER = 0x8002, /*!< The registered ancillary data 532 buffer is too small to receive the 533 parsed data. */ 534 AAC_DEC_TOO_MANY_ANC_ELEMENTS = 0x8003, /*!< More than the allowed number of 535 ancillary data elements should be 536 written to buffer. */ 537 aac_dec_anc_data_error_end = 0x8FFF 538 539 } AAC_DECODER_ERROR; 540 541 /** Macro to identify initialization errors. Output buffer is invalid. */ 542 #define IS_INIT_ERROR(err) \ 543 ((((err) >= aac_dec_init_error_start) && ((err) <= aac_dec_init_error_end)) \ 544 ? 1 \ 545 : 0) 546 /** Macro to identify decode errors. Output buffer is valid but concealed. */ 547 #define IS_DECODE_ERROR(err) \ 548 ((((err) >= aac_dec_decode_error_start) && \ 549 ((err) <= aac_dec_decode_error_end)) \ 550 ? 1 \ 551 : 0) 552 /** 553 * Macro to identify if the audio output buffer contains valid samples after 554 * calling aacDecoder_DecodeFrame(). Output buffer is valid but can be 555 * concealed. 556 */ 557 #define IS_OUTPUT_VALID(err) (((err) == AAC_DEC_OK) || IS_DECODE_ERROR(err)) 558 559 /*! \enum AAC_MD_PROFILE 560 * \brief The available metadata profiles which are mostly related to downmixing. The values define the arguments 561 * for the use with parameter ::AAC_METADATA_PROFILE. 562 */ 563 typedef enum { 564 AAC_MD_PROFILE_MPEG_STANDARD = 565 0, /*!< The standard profile creates a mixdown signal based on the 566 advanced downmix metadata (from a DSE). The equations and default 567 values are defined in ISO/IEC 14496:3 Ammendment 4. Any other 568 (legacy) downmix metadata will be ignored. No other parameter will 569 be modified. */ 570 AAC_MD_PROFILE_MPEG_LEGACY = 571 1, /*!< This profile behaves identical to the standard profile if advanced 572 downmix metadata (from a DSE) is available. If not, the 573 matrix_mixdown information embedded in the program configuration 574 element (PCE) will be applied. If neither is the case, the module 575 creates a mixdown using the default coefficients as defined in 576 ISO/IEC 14496:3 AMD 4. The profile can be used to support legacy 577 digital TV (e.g. DVB) streams. */ 578 AAC_MD_PROFILE_MPEG_LEGACY_PRIO = 579 2, /*!< Similar to the ::AAC_MD_PROFILE_MPEG_LEGACY profile but if both 580 the advanced (ISO/IEC 14496:3 AMD 4) and the legacy (PCE) MPEG 581 downmix metadata are available the latter will be applied. 582 */ 583 AAC_MD_PROFILE_ARIB_JAPAN = 584 3 /*!< Downmix creation as described in ABNT NBR 15602-2. But if advanced 585 downmix metadata (ISO/IEC 14496:3 AMD 4) is available it will be 586 preferred because of the higher resolutions. In addition the 587 metadata expiry time will be set to the value defined in the ARIB 588 standard (see ::AAC_METADATA_EXPIRY_TIME). 589 */ 590 } AAC_MD_PROFILE; 591 592 /*! \enum AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS 593 * \brief Options for handling of DRC parameters, if presentation mode is not indicated in bitstream 594 */ 595 typedef enum { 596 AAC_DRC_PARAMETER_HANDLING_DISABLED = -1, /*!< DRC parameter handling 597 disabled, all parameters are 598 applied as requested. */ 599 AAC_DRC_PARAMETER_HANDLING_ENABLED = 600 0, /*!< Apply changes to requested DRC parameters to prevent clipping. */ 601 AAC_DRC_PRESENTATION_MODE_1_DEFAULT = 602 1, /*!< Use DRC presentation mode 1 as default (e.g. for Nordig) */ 603 AAC_DRC_PRESENTATION_MODE_2_DEFAULT = 604 2 /*!< Use DRC presentation mode 2 as default (e.g. for DTG DBook) */ 605 } AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS; 606 607 /** 608 * \brief AAC decoder setting parameters 609 */ 610 typedef enum { 611 AAC_PCM_DUAL_CHANNEL_OUTPUT_MODE = 612 0x0002, /*!< Defines how the decoder processes two channel signals: \n 613 0: Leave both signals as they are (default). \n 614 1: Create a dual mono output signal from channel 1. \n 615 2: Create a dual mono output signal from channel 2. \n 616 3: Create a dual mono output signal by mixing both channels 617 (L' = R' = 0.5*Ch1 + 0.5*Ch2). */ 618 AAC_PCM_OUTPUT_CHANNEL_MAPPING = 619 0x0003, /*!< Output buffer channel ordering. 0: MPEG PCE style order, 1: 620 WAV file channel order (default). */ 621 AAC_PCM_LIMITER_ENABLE = 622 0x0004, /*!< Enable signal level limiting. \n 623 -1: Auto-config. Enable limiter for all 624 non-lowdelay configurations by default. \n 625 0: Disable limiter in general. \n 626 1: Enable limiter always. 627 It is recommended to call the decoder 628 with a AACDEC_CLRHIST flag to reset all 629 states when the limiter switch is changed 630 explicitly. */ 631 AAC_PCM_LIMITER_ATTACK_TIME = 0x0005, /*!< Signal level limiting attack time 632 in ms. Default configuration is 15 633 ms. Adjustable range from 1 ms to 15 634 ms. */ 635 AAC_PCM_LIMITER_RELEAS_TIME = 0x0006, /*!< Signal level limiting release time 636 in ms. Default configuration is 50 637 ms. Adjustable time must be larger 638 than 0 ms. */ 639 AAC_PCM_MIN_OUTPUT_CHANNELS = 640 0x0011, /*!< Minimum number of PCM output channels. If higher than the 641 number of encoded audio channels, a simple channel extension is 642 applied (see note 4 for exceptions). \n -1, 0: Disable channel 643 extension feature. The decoder output contains the same number 644 of channels as the encoded bitstream. \n 1: This value is 645 currently needed only together with the mix-down feature. See 646 ::AAC_PCM_MAX_OUTPUT_CHANNELS and note 2 below. \n 647 2: Encoded mono signals will be duplicated to achieve a 648 2/0/0.0 channel output configuration. \n 6: The decoder 649 tries to reorder encoded signals with less than six channels to 650 achieve a 3/0/2.1 channel output signal. Missing channels will 651 be filled with a zero signal. If reordering is not possible the 652 empty channels will simply be appended. Only available if 653 instance is configured to support multichannel output. \n 8: 654 The decoder tries to reorder encoded signals with less than 655 eight channels to achieve a 3/0/4.1 channel output signal. 656 Missing channels will be filled with a zero signal. If 657 reordering is not possible the empty channels will simply be 658 appended. Only available if instance is configured to 659 support multichannel output.\n NOTE: \n 660 1. The channel signaling (CStreamInfo::pChannelType and 661 CStreamInfo::pChannelIndices) will not be modified. Added empty 662 channels will be signaled with channel type 663 AUDIO_CHANNEL_TYPE::ACT_NONE. \n 664 2. If the parameter value is greater than that of 665 ::AAC_PCM_MAX_OUTPUT_CHANNELS both will be set to the same 666 value. \n 667 3. This parameter will be ignored if the number of encoded 668 audio channels is greater than 8. */ 669 AAC_PCM_MAX_OUTPUT_CHANNELS = 670 0x0012, /*!< Maximum number of PCM output channels. If lower than the 671 number of encoded audio channels, downmixing is applied 672 accordingly (see note 5 for exceptions). If dedicated metadata 673 is available in the stream it will be used to achieve better 674 mixing results. \n -1, 0: Disable downmixing feature. The 675 decoder output contains the same number of channels as the 676 encoded bitstream. \n 1: All encoded audio configurations 677 with more than one channel will be mixed down to one mono 678 output signal. \n 2: The decoder performs a stereo mix-down 679 if the number encoded audio channels is greater than two. \n 6: 680 If the number of encoded audio channels is greater than six the 681 decoder performs a mix-down to meet the target output 682 configuration of 3/0/2.1 channels. Only available if instance 683 is configured to support multichannel output. \n 8: This 684 value is currently needed only together with the channel 685 extension feature. See ::AAC_PCM_MIN_OUTPUT_CHANNELS and note 2 686 below. Only available if instance is configured to support 687 multichannel output. \n NOTE: \n 688 1. Down-mixing of any seven or eight channel configuration 689 not defined in ISO/IEC 14496-3 PDAM 4 is not supported by this 690 software version. \n 691 2. If the parameter value is greater than zero but smaller 692 than ::AAC_PCM_MIN_OUTPUT_CHANNELS both will be set to same 693 value. \n 694 3. This parameter will be ignored if the number of encoded 695 audio channels is greater than 8. */ 696 AAC_METADATA_PROFILE = 697 0x0020, /*!< See ::AAC_MD_PROFILE for all available values. */ 698 AAC_METADATA_EXPIRY_TIME = 0x0021, /*!< Defines the time in ms after which all 699 the bitstream associated meta-data (DRC, 700 downmix coefficients, ...) will be reset 701 to default if no update has been 702 received. Negative values disable the 703 feature. */ 704 705 AAC_CONCEAL_METHOD = 0x0100, /*!< Error concealment: Processing method. \n 706 0: Spectral muting. \n 707 1: Noise substitution (see ::CONCEAL_NOISE). 708 \n 2: Energy interpolation (adds additional 709 signal delay of one frame, see 710 ::CONCEAL_INTER. only some AOTs are 711 supported). \n */ 712 AAC_DRC_BOOST_FACTOR = 713 0x0200, /*!< MPEG-4 / MPEG-D Dynamic Range Control (DRC): Scaling factor 714 for boosting gain values. Defines how the boosting DRC factors 715 (conveyed in the bitstream) will be applied to the decoded 716 signal. The valid values range from 0 (don't apply boost 717 factors) to 127 (fully apply boost factors). Default value is 0 718 for MPEG-4 DRC and 127 for MPEG-D DRC. */ 719 AAC_DRC_ATTENUATION_FACTOR = 0x0201, /*!< MPEG-4 / MPEG-D DRC: Scaling factor 720 for attenuating gain values. Same as 721 ::AAC_DRC_BOOST_FACTOR but for 722 attenuating DRC factors. */ 723 AAC_DRC_REFERENCE_LEVEL = 724 0x0202, /*!< MPEG-4 / MPEG-D DRC: Target reference level / decoder target 725 loudness.\n Defines the level below full-scale (quantized in 726 steps of 0.25dB) to which the output audio signal will be 727 normalized to by the DRC module.\n The parameter controls 728 loudness normalization for both MPEG-4 DRC and MPEG-D DRC. The 729 valid values range from 40 (-10 dBFS) to 127 (-31.75 dBFS).\n 730 Example values:\n 731 124 (-31 dBFS) for audio/video receivers (AVR) or other 732 devices allowing audio playback with high dynamic range,\n 96 733 (-24 dBFS) for TV sets or equivalent devices (default),\n 64 734 (-16 dBFS) for mobile devices where the dynamic range of audio 735 playback is restricted.\n Any value smaller than 0 switches off 736 loudness normalization and MPEG-4 DRC. */ 737 AAC_DRC_HEAVY_COMPRESSION = 738 0x0203, /*!< MPEG-4 DRC: En-/Disable DVB specific heavy compression (aka 739 RF mode). If set to 1, the decoder will apply the compression 740 values from the DVB specific ancillary data field. At the same 741 time the MPEG-4 Dynamic Range Control tool will be disabled. By 742 default, heavy compression is disabled. */ 743 AAC_DRC_DEFAULT_PRESENTATION_MODE = 744 0x0204, /*!< MPEG-4 DRC: Default presentation mode (DRC parameter 745 handling). \n Defines the handling of the DRC parameters boost 746 factor, attenuation factor and heavy compression, if no 747 presentation mode is indicated in the bitstream.\n For options, 748 see ::AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS.\n Default: 749 ::AAC_DRC_PARAMETER_HANDLING_DISABLED */ 750 AAC_DRC_ENC_TARGET_LEVEL = 751 0x0205, /*!< MPEG-4 DRC: Encoder target level for light (i.e. not heavy) 752 compression.\n If known, this declares the target reference 753 level that was assumed at the encoder for calculation of 754 limiting gains. The valid values range from 0 (full-scale) to 755 127 (31.75 dB below full-scale). This parameter is used only 756 with ::AAC_DRC_PARAMETER_HANDLING_ENABLED and ignored 757 otherwise.\n Default: 127 (worst-case assumption).\n */ 758 AAC_UNIDRC_SET_EFFECT = 0x0206, /*!< MPEG-D DRC: Request a DRC effect type for 759 selection of a DRC set.\n Supported indices 760 are:\n -1: DRC off. Completely disables 761 MPEG-D DRC.\n 0: None (default). Disables 762 MPEG-D DRC, but automatically enables DRC 763 if necessary to prevent clipping.\n 1: Late 764 night\n 2: Noisy environment\n 3: Limited 765 playback range\n 4: Low playback level\n 5: 766 Dialog enhancement\n 6: General 767 compression. Used for generally enabling 768 MPEG-D DRC without particular request.\n */ 769 AAC_UNIDRC_ALBUM_MODE = 770 0x0207, /*!< MPEG-D DRC: Enable album mode. 0: Disabled (default), 1: 771 Enabled.\n Disabled album mode leads to application of gain 772 sequences for fading in and out, if provided in the 773 bitstream.\n Enabled album mode makes use of dedicated album 774 loudness information, if provided in the bitstream.\n */ 775 AAC_QMF_LOWPOWER = 776 0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing mode. \n 777 -1: Use internal default. \n 778 0: Use complex QMF data mode. \n 779 1: Use real (low power) QMF data mode. \n */ 780 AAC_TPDEC_CLEAR_BUFFER = 781 0x0603 /*!< Clear internal bit stream buffer of transport layers. The 782 decoder will start decoding at new data passed after this event 783 and any previous data is discarded. */ 784 785 } AACDEC_PARAM; 786 787 /** 788 * \brief This structure gives information about the currently decoded audio 789 * data. All fields are read-only. 790 */ 791 typedef struct { 792 /* These five members are the only really relevant ones for the user. */ 793 INT sampleRate; /*!< The sample rate in Hz of the decoded PCM audio signal. */ 794 INT frameSize; /*!< The frame size of the decoded PCM audio signal. \n 795 Typically this is: \n 796 1024 or 960 for AAC-LC \n 797 2048 or 1920 for HE-AAC (v2) \n 798 512 or 480 for AAC-LD and AAC-ELD \n 799 768, 1024, 2048 or 4096 for USAC */ 800 INT numChannels; /*!< The number of output audio channels before the rendering 801 module, i.e. the original channel configuration. */ 802 AUDIO_CHANNEL_TYPE 803 *pChannelType; /*!< Audio channel type of each output audio channel. */ 804 UCHAR *pChannelIndices; /*!< Audio channel index for each output audio 805 channel. See ISO/IEC 13818-7:2005(E), 8.5.3.2 806 Explicit channel mapping using a 807 program_config_element() */ 808 /* Decoder internal members. */ 809 INT aacSampleRate; /*!< Sampling rate in Hz without SBR (from configuration 810 info) divided by a (ELD) downscale factor if present. */ 811 INT profile; /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g. 812 MPEG-4)). */ 813 AUDIO_OBJECT_TYPE 814 aot; /*!< Audio Object Type (from ASC): is set to the appropriate value 815 for MPEG-2 bitstreams (e. g. 2 for AAC-LC). */ 816 INT channelConfig; /*!< Channel configuration (0: PCE defined, 1: mono, 2: 817 stereo, ... */ 818 INT bitRate; /*!< Instantaneous bit rate. */ 819 INT aacSamplesPerFrame; /*!< Samples per frame for the AAC core (from ASC) 820 divided by a (ELD) downscale factor if present. \n 821 Typically this is (with a downscale factor of 1): 822 \n 1024 or 960 for AAC-LC \n 512 or 480 for 823 AAC-LD and AAC-ELD */ 824 INT aacNumChannels; /*!< The number of audio channels after AAC core 825 processing (before PS or MPS processing). CAUTION: This 826 are not the final number of output channels! */ 827 AUDIO_OBJECT_TYPE extAot; /*!< Extension Audio Object Type (from ASC) */ 828 INT extSamplingRate; /*!< Extension sampling rate in Hz (from ASC) divided by 829 a (ELD) downscale factor if present. */ 830 831 UINT outputDelay; /*!< The number of samples the output is additionally 832 delayed by.the decoder. */ 833 UINT flags; /*!< Copy of internal flags. Only to be written by the decoder, 834 and only to be read externally. */ 835 836 SCHAR epConfig; /*!< epConfig level (from ASC): only level 0 supported, -1 837 means no ER (e. g. AOT=2, MPEG-2 AAC, etc.) */ 838 /* Statistics */ 839 INT numLostAccessUnits; /*!< This integer will reflect the estimated amount of 840 lost access units in case aacDecoder_DecodeFrame() 841 returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be 842 < 0 if the estimation failed. */ 843 844 INT64 numTotalBytes; /*!< This is the number of total bytes that have passed 845 through the decoder. */ 846 INT64 847 numBadBytes; /*!< This is the number of total bytes that were considered 848 with errors from numTotalBytes. */ 849 INT64 850 numTotalAccessUnits; /*!< This is the number of total access units that 851 have passed through the decoder. */ 852 INT64 numBadAccessUnits; /*!< This is the number of total access units that 853 were considered with errors from numTotalBytes. */ 854 855 /* Metadata */ 856 SCHAR drcProgRefLev; /*!< DRC program reference level. Defines the reference 857 level below full-scale. It is quantized in steps of 858 0.25dB. The valid values range from 0 (0 dBFS) to 127 859 (-31.75 dBFS). It is used to reflect the average 860 loudness of the audio in LKFS according to ITU-R BS 861 1770. If no level has been found in the bitstream the 862 value is -1. */ 863 SCHAR 864 drcPresMode; /*!< DRC presentation mode. According to ETSI TS 101 154, 865 this field indicates whether light (MPEG-4 Dynamic Range 866 Control tool) or heavy compression (DVB heavy 867 compression) dynamic range control shall take priority 868 on the outputs. For details, see ETSI TS 101 154, table 869 C.33. Possible values are: \n -1: No corresponding 870 metadata found in the bitstream \n 0: DRC presentation 871 mode not indicated \n 1: DRC presentation mode 1 \n 2: 872 DRC presentation mode 2 \n 3: Reserved */ 873 INT outputLoudness; /*!< Audio output loudness in steps of -0.25 dB. Range: 0 874 (0 dBFS) to 231 (-57.75 dBFS).\n A value of -1 875 indicates that no loudness metadata is present.\n If 876 loudness normalization is active, the value corresponds 877 to the target loudness value set with 878 ::AAC_DRC_REFERENCE_LEVEL.\n If loudness normalization 879 is not active, the output loudness value corresponds to 880 the loudness metadata given in the bitstream.\n 881 Loudness metadata can originate from MPEG-4 DRC or 882 MPEG-D DRC. */ 883 884 } CStreamInfo; 885 886 typedef struct AAC_DECODER_INSTANCE 887 *HANDLE_AACDECODER; /*!< Pointer to a AAC decoder instance. */ 888 889 #ifdef __cplusplus 890 extern "C" { 891 #endif 892 893 /** 894 * \brief Initialize ancillary data buffer. 895 * 896 * \param self AAC decoder handle. 897 * \param buffer Pointer to (external) ancillary data buffer. 898 * \param size Size of the buffer pointed to by buffer. 899 * \return Error code. 900 */ 901 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataInit(HANDLE_AACDECODER self, 902 UCHAR *buffer, int size); 903 904 /** 905 * \brief Get one ancillary data element. 906 * 907 * \param self AAC decoder handle. 908 * \param index Index of the ancillary data element to get. 909 * \param ptr Pointer to a buffer receiving a pointer to the requested 910 * ancillary data element. 911 * \param size Pointer to a buffer receiving the length of the requested 912 * ancillary data element. 913 * \return Error code. 914 */ 915 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataGet(HANDLE_AACDECODER self, 916 int index, UCHAR **ptr, 917 int *size); 918 919 /** 920 * \brief Set one single decoder parameter. 921 * 922 * \param self AAC decoder handle. 923 * \param param Parameter to be set. 924 * \param value Parameter value. 925 * \return Error code. 926 */ 927 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_SetParam(const HANDLE_AACDECODER self, 928 const AACDEC_PARAM param, 929 const INT value); 930 931 /** 932 * \brief Get free bytes inside decoder internal buffer. 933 * \param self Handle of AAC decoder instance. 934 * \param pFreeBytes Pointer to variable receiving amount of free bytes inside 935 * decoder internal buffer. 936 * \return Error code. 937 */ 938 LINKSPEC_H AAC_DECODER_ERROR 939 aacDecoder_GetFreeBytes(const HANDLE_AACDECODER self, UINT *pFreeBytes); 940 941 /** 942 * \brief Open an AAC decoder instance. 943 * \param transportFmt The transport type to be used. 944 * \param nrOfLayers Number of transport layers. 945 * \return AAC decoder handle. 946 */ 947 LINKSPEC_H HANDLE_AACDECODER aacDecoder_Open(TRANSPORT_TYPE transportFmt, 948 UINT nrOfLayers); 949 950 /** 951 * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig 952 * (ASC) or a StreamMuxConfig (SMC), contained in a binary buffer. This is 953 * required for MPEG-4 and Raw Packets file format bitstreams as well as for 954 * LATM bitstreams with no in-band SMC. If the transport format is LATM with or 955 * without LOAS, configuration is assumed to be an SMC, for all other file 956 * formats an ASC. 957 * 958 * \param self AAC decoder handle. 959 * \param conf Pointer to an unsigned char buffer containing the binary 960 * configuration buffer (either ASC or SMC). 961 * \param length Length of the configuration buffer in bytes. 962 * \return Error code. 963 */ 964 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_ConfigRaw(HANDLE_AACDECODER self, 965 UCHAR *conf[], 966 const UINT length[]); 967 968 /** 969 * \brief Submit raw ISO base media file format boxes to decoder for parsing 970 * (only some box types are recognized). 971 * 972 * \param self AAC decoder handle. 973 * \param buffer Pointer to an unsigned char buffer containing the binary box 974 * data (including size and type, can be a sequence of multiple boxes). 975 * \param length Length of the data in bytes. 976 * \return Error code. 977 */ 978 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_RawISOBMFFData(HANDLE_AACDECODER self, 979 UCHAR *buffer, 980 UINT length); 981 982 /** 983 * \brief Fill AAC decoder's internal input buffer with bitstream data from the 984 * external input buffer. The function only copies such data as long as the 985 * decoder-internal input buffer is not full. So it grabs whatever it can from 986 * pBuffer and returns information (bytesValid) so that at a subsequent call of 987 * %aacDecoder_Fill(), the right position in pBuffer can be determined to grab 988 * the next data. 989 * 990 * \param self AAC decoder handle. 991 * \param pBuffer Pointer to external input buffer. 992 * \param bufferSize Size of external input buffer. This argument is required 993 * because decoder-internally we need the information to calculate the offset to 994 * pBuffer, where the next available data is, which is then 995 * fed into the decoder-internal buffer (as much as 996 * possible). Our example framework implementation fills the 997 * buffer at pBuffer again, once it contains no available valid bytes anymore 998 * (meaning bytesValid equal 0). 999 * \param bytesValid Number of bitstream bytes in the external bitstream buffer 1000 * that have not yet been copied into the decoder's internal bitstream buffer by 1001 * calling this function. The value is updated according to 1002 * the amount of newly copied bytes. 1003 * \return Error code. 1004 */ 1005 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_Fill(HANDLE_AACDECODER self, 1006 UCHAR *pBuffer[], 1007 const UINT bufferSize[], 1008 UINT *bytesValid); 1009 1010 /** Flag for aacDecoder_DecodeFrame(): Trigger the built-in error concealment 1011 * module to generate a substitute signal for one lost frame. New input data 1012 * will not be considered. 1013 */ 1014 #define AACDEC_CONCEAL 1 1015 /** Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all delayed 1016 * audio without having new input data. Thus new input data will not be 1017 * considered. 1018 */ 1019 #define AACDEC_FLUSH 2 1020 /** Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data 1021 * discontinuity. Resync any internals as necessary. 1022 */ 1023 #define AACDEC_INTR 4 1024 /** Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and history 1025 * buffers. CAUTION: This can cause discontinuities in the output signal. 1026 */ 1027 #define AACDEC_CLRHIST 8 1028 1029 /** 1030 * \brief Decode one audio frame 1031 * 1032 * \param self AAC decoder handle. 1033 * \param pTimeData Pointer to external output buffer where the decoded PCM 1034 * samples will be stored into. 1035 * \param timeDataSize Size of external output buffer in PCM samples. 1036 * \param flags Bit field with flags for the decoder: \n 1037 * (flags & AACDEC_CONCEAL) == 1: Do concealment. \n 1038 * (flags & AACDEC_FLUSH) == 2: Discard input data. Flush 1039 * filter banks (output delayed audio). \n (flags & AACDEC_INTR) == 4: Input 1040 * data is discontinuous. Resynchronize any internals as 1041 * necessary. \n (flags & AACDEC_CLRHIST) == 8: Clear all signal delay lines and 1042 * history buffers. 1043 * \return Error code. 1044 */ 1045 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_DecodeFrame(HANDLE_AACDECODER self, 1046 INT_PCM *pTimeData, 1047 const INT timeDataSize, 1048 const UINT flags); 1049 1050 /** 1051 * \brief De-allocate all resources of an AAC decoder instance. 1052 * 1053 * \param self AAC decoder handle. 1054 * \return void. 1055 */ 1056 LINKSPEC_H void aacDecoder_Close(HANDLE_AACDECODER self); 1057 1058 /** 1059 * \brief Get CStreamInfo handle from decoder. 1060 * 1061 * \param self AAC decoder handle. 1062 * \return Reference to requested CStreamInfo. 1063 */ 1064 LINKSPEC_H CStreamInfo *aacDecoder_GetStreamInfo(HANDLE_AACDECODER self); 1065 1066 /** 1067 * \brief Get decoder library info. 1068 * 1069 * \param info Pointer to an allocated LIB_INFO structure. 1070 * \return 0 on success. 1071 */ 1072 LINKSPEC_H INT aacDecoder_GetLibInfo(LIB_INFO *info); 1073 1074 #ifdef __cplusplus 1075 } 1076 #endif 1077 1078 #endif /* AACDECODER_LIB_H */ 1079