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