1 /* ----------------------------------------------------------------------------- 2 Software License for The Fraunhofer FDK AAC Codec Library for Android 3 4 Copyright 1995 - 2019 Fraunhofer-Gesellschaft zur Frderung 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 (at) 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, /*!< MPEG-4 / MPEG-D Dynamic Range Control (DRC): Scaling factor 745 for boosting gain values. Defines how the boosting DRC factors 746 (conveyed in the bitstream) will be applied to the decoded 747 signal. The valid values range from 0 (don't apply boost 748 factors) to 127 (fully apply boost factors). Default value is 0 749 for MPEG-4 DRC and 127 for MPEG-D DRC. */ 750 AAC_DRC_ATTENUATION_FACTOR = 0x0201, /*!< MPEG-4 / MPEG-D DRC: Scaling factor 751 for attenuating gain values. Same as 752 ::AAC_DRC_BOOST_FACTOR but for 753 attenuating DRC factors. */ 754 AAC_DRC_REFERENCE_LEVEL = 755 0x0202, /*!< MPEG-4 / MPEG-D DRC: Target reference level / decoder target 756 loudness.\n Defines the level below full-scale (quantized in 757 steps of 0.25dB) to which the output audio signal will be 758 normalized to by the DRC module.\n The parameter controls 759 loudness normalization for both MPEG-4 DRC and MPEG-D DRC. The 760 valid values range from 40 (-10 dBFS) to 127 (-31.75 dBFS).\n 761 Example values:\n 762 124 (-31 dBFS) for audio/video receivers (AVR) or other 763 devices allowing audio playback with high dynamic range,\n 96 764 (-24 dBFS) for TV sets or equivalent devices (default),\n 64 765 (-16 dBFS) for mobile devices where the dynamic range of audio 766 playback is restricted.\n Any value smaller than 0 switches off 767 loudness normalization and MPEG-4 DRC. */ 768 AAC_DRC_HEAVY_COMPRESSION = 769 0x0203, /*!< MPEG-4 DRC: En-/Disable DVB specific heavy compression (aka 770 RF mode). If set to 1, the decoder will apply the compression 771 values from the DVB specific ancillary data field. At the same 772 time the MPEG-4 Dynamic Range Control tool will be disabled. By 773 default, heavy compression is disabled. */ 774 AAC_DRC_DEFAULT_PRESENTATION_MODE = 775 0x0204, /*!< MPEG-4 DRC: Default presentation mode (DRC parameter 776 handling). \n Defines the handling of the DRC parameters boost 777 factor, attenuation factor and heavy compression, if no 778 presentation mode is indicated in the bitstream.\n For options, 779 see ::AAC_DRC_DEFAULT_PRESENTATION_MODE_OPTIONS.\n Default: 780 ::AAC_DRC_PARAMETER_HANDLING_DISABLED */ 781 AAC_DRC_ENC_TARGET_LEVEL = 782 0x0205, /*!< MPEG-4 DRC: Encoder target level for light (i.e. not heavy) 783 compression.\n If known, this declares the target reference 784 level that was assumed at the encoder for calculation of 785 limiting gains. The valid values range from 0 (full-scale) to 786 127 (31.75 dB below full-scale). This parameter is used only 787 with ::AAC_DRC_PARAMETER_HANDLING_ENABLED and ignored 788 otherwise.\n Default: 127 (worst-case assumption).\n */ 789 AAC_UNIDRC_SET_EFFECT = 0x0206, /*!< MPEG-D DRC: Request a DRC effect type for 790 selection of a DRC set.\n Supported indices 791 are:\n -1: DRC off. Completely disables 792 MPEG-D DRC.\n 0: None (default). Disables 793 MPEG-D DRC, but automatically enables DRC 794 if necessary to prevent clipping.\n 1: Late 795 night\n 2: Noisy environment\n 3: Limited 796 playback range\n 4: Low playback level\n 5: 797 Dialog enhancement\n 6: General 798 compression. Used for generally enabling 799 MPEG-D DRC without particular request.\n */ 800 AAC_UNIDRC_ALBUM_MODE = 801 0x0207, /*!< MPEG-D DRC: Enable album mode. 0: Disabled (default), 1: 802 Enabled.\n Disabled album mode leads to application of gain 803 sequences for fading in and out, if provided in the 804 bitstream.\n Enabled album mode makes use of dedicated album 805 loudness information, if provided in the bitstream.\n */ 806 AAC_QMF_LOWPOWER = 0x0300, /*!< Quadrature Mirror Filter (QMF) Bank processing 807 mode. \n -1: Use internal default. Implies MPEG 808 Surround partially complex accordingly. \n 0: 809 Use complex QMF data mode. \n 1: Use real (low 810 power) QMF data mode. \n */ 811 AAC_TPDEC_CLEAR_BUFFER = 812 0x0603 /*!< Clear internal bit stream buffer of transport layers. The 813 decoder will start decoding at new data passed after this event 814 and any previous data is discarded. */ 815 816 } AACDEC_PARAM; 817 818 /** 819 * \brief This structure gives information about the currently decoded audio 820 * data. All fields are read-only. 821 */ 822 typedef struct { 823 /* These five members are the only really relevant ones for the user. */ 824 INT sampleRate; /*!< The sample rate in Hz of the decoded PCM audio signal. */ 825 INT frameSize; /*!< The frame size of the decoded PCM audio signal. \n 826 Typically this is: \n 827 1024 or 960 for AAC-LC \n 828 2048 or 1920 for HE-AAC (v2) \n 829 512 or 480 for AAC-LD and AAC-ELD \n 830 768, 1024, 2048 or 4096 for USAC */ 831 INT numChannels; /*!< The number of output audio channels before the rendering 832 module, i.e. the original channel configuration. */ 833 AUDIO_CHANNEL_TYPE 834 *pChannelType; /*!< Audio channel type of each output audio channel. */ 835 UCHAR *pChannelIndices; /*!< Audio channel index for each output audio 836 channel. See ISO/IEC 13818-7:2005(E), 8.5.3.2 837 Explicit channel mapping using a 838 program_config_element() */ 839 /* Decoder internal members. */ 840 INT aacSampleRate; /*!< Sampling rate in Hz without SBR (from configuration 841 info) divided by a (ELD) downscale factor if present. */ 842 INT profile; /*!< MPEG-2 profile (from file header) (-1: not applicable (e. g. 843 MPEG-4)). */ 844 AUDIO_OBJECT_TYPE 845 aot; /*!< Audio Object Type (from ASC): is set to the appropriate value 846 for MPEG-2 bitstreams (e. g. 2 for AAC-LC). */ 847 INT channelConfig; /*!< Channel configuration (0: PCE defined, 1: mono, 2: 848 stereo, ... */ 849 INT bitRate; /*!< Instantaneous bit rate. */ 850 INT aacSamplesPerFrame; /*!< Samples per frame for the AAC core (from ASC) 851 divided by a (ELD) downscale factor if present. \n 852 Typically this is (with a downscale factor of 1): 853 \n 1024 or 960 for AAC-LC \n 512 or 480 for 854 AAC-LD and AAC-ELD */ 855 INT aacNumChannels; /*!< The number of audio channels after AAC core 856 processing (before PS or MPS processing). CAUTION: This 857 are not the final number of output channels! */ 858 AUDIO_OBJECT_TYPE extAot; /*!< Extension Audio Object Type (from ASC) */ 859 INT extSamplingRate; /*!< Extension sampling rate in Hz (from ASC) divided by 860 a (ELD) downscale factor if present. */ 861 862 UINT outputDelay; /*!< The number of samples the output is additionally 863 delayed by.the decoder. */ 864 UINT flags; /*!< Copy of internal flags. Only to be written by the decoder, 865 and only to be read externally. */ 866 867 SCHAR epConfig; /*!< epConfig level (from ASC): only level 0 supported, -1 868 means no ER (e. g. AOT=2, MPEG-2 AAC, etc.) */ 869 /* Statistics */ 870 INT numLostAccessUnits; /*!< This integer will reflect the estimated amount of 871 lost access units in case aacDecoder_DecodeFrame() 872 returns AAC_DEC_TRANSPORT_SYNC_ERROR. It will be 873 < 0 if the estimation failed. */ 874 875 INT64 numTotalBytes; /*!< This is the number of total bytes that have passed 876 through the decoder. */ 877 INT64 878 numBadBytes; /*!< This is the number of total bytes that were considered 879 with errors from numTotalBytes. */ 880 INT64 881 numTotalAccessUnits; /*!< This is the number of total access units that 882 have passed through the decoder. */ 883 INT64 numBadAccessUnits; /*!< This is the number of total access units that 884 were considered with errors from numTotalBytes. */ 885 886 /* Metadata */ 887 SCHAR drcProgRefLev; /*!< DRC program reference level. Defines the reference 888 level below full-scale. It is quantized in steps of 889 0.25dB. The valid values range from 0 (0 dBFS) to 127 890 (-31.75 dBFS). It is used to reflect the average 891 loudness of the audio in LKFS according to ITU-R BS 892 1770. If no level has been found in the bitstream the 893 value is -1. */ 894 SCHAR 895 drcPresMode; /*!< DRC presentation mode. According to ETSI TS 101 154, 896 this field indicates whether light (MPEG-4 Dynamic Range 897 Control tool) or heavy compression (DVB heavy 898 compression) dynamic range control shall take priority 899 on the outputs. For details, see ETSI TS 101 154, table 900 C.33. Possible values are: \n -1: No corresponding 901 metadata found in the bitstream \n 0: DRC presentation 902 mode not indicated \n 1: DRC presentation mode 1 \n 2: 903 DRC presentation mode 2 \n 3: Reserved */ 904 905 } CStreamInfo; 906 907 typedef struct AAC_DECODER_INSTANCE 908 *HANDLE_AACDECODER; /*!< Pointer to a AAC decoder instance. */ 909 910 #ifdef __cplusplus 911 extern "C" { 912 #endif 913 914 /** 915 * \brief Initialize ancillary data buffer. 916 * 917 * \param self AAC decoder handle. 918 * \param buffer Pointer to (external) ancillary data buffer. 919 * \param size Size of the buffer pointed to by buffer. 920 * \return Error code. 921 */ 922 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataInit(HANDLE_AACDECODER self, 923 UCHAR *buffer, int size); 924 925 /** 926 * \brief Get one ancillary data element. 927 * 928 * \param self AAC decoder handle. 929 * \param index Index of the ancillary data element to get. 930 * \param ptr Pointer to a buffer receiving a pointer to the requested 931 * ancillary data element. 932 * \param size Pointer to a buffer receiving the length of the requested 933 * ancillary data element. 934 * \return Error code. 935 */ 936 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_AncDataGet(HANDLE_AACDECODER self, 937 int index, UCHAR **ptr, 938 int *size); 939 940 /** 941 * \brief Set one single decoder parameter. 942 * 943 * \param self AAC decoder handle. 944 * \param param Parameter to be set. 945 * \param value Parameter value. 946 * \return Error code. 947 */ 948 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_SetParam(const HANDLE_AACDECODER self, 949 const AACDEC_PARAM param, 950 const INT value); 951 952 /** 953 * \brief Get free bytes inside decoder internal buffer. 954 * \param self Handle of AAC decoder instance. 955 * \param pFreeBytes Pointer to variable receiving amount of free bytes inside 956 * decoder internal buffer. 957 * \return Error code. 958 */ 959 LINKSPEC_H AAC_DECODER_ERROR 960 aacDecoder_GetFreeBytes(const HANDLE_AACDECODER self, UINT *pFreeBytes); 961 962 /** 963 * \brief Open an AAC decoder instance. 964 * \param transportFmt The transport type to be used. 965 * \param nrOfLayers Number of transport layers. 966 * \return AAC decoder handle. 967 */ 968 LINKSPEC_H HANDLE_AACDECODER aacDecoder_Open(TRANSPORT_TYPE transportFmt, 969 UINT nrOfLayers); 970 971 /** 972 * \brief Explicitly configure the decoder by passing a raw AudioSpecificConfig 973 * (ASC) or a StreamMuxConfig (SMC), contained in a binary buffer. This is 974 * required for MPEG-4 and Raw Packets file format bitstreams as well as for 975 * LATM bitstreams with no in-band SMC. If the transport format is LATM with or 976 * without LOAS, configuration is assumed to be an SMC, for all other file 977 * formats an ASC. 978 * 979 * \param self AAC decoder handle. 980 * \param conf Pointer to an unsigned char buffer containing the binary 981 * configuration buffer (either ASC or SMC). 982 * \param length Length of the configuration buffer in bytes. 983 * \return Error code. 984 */ 985 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_ConfigRaw(HANDLE_AACDECODER self, 986 UCHAR *conf[], 987 const UINT length[]); 988 989 /** 990 * \brief Submit raw ISO base media file format boxes to decoder for parsing 991 * (only some box types are recognized). 992 * 993 * \param self AAC decoder handle. 994 * \param buffer Pointer to an unsigned char buffer containing the binary box 995 * data (including size and type, can be a sequence of multiple boxes). 996 * \param length Length of the data in bytes. 997 * \return Error code. 998 */ 999 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_RawISOBMFFData(HANDLE_AACDECODER self, 1000 UCHAR *buffer, 1001 UINT length); 1002 1003 /** 1004 * \brief Fill AAC decoder's internal input buffer with bitstream data from the 1005 * external input buffer. The function only copies such data as long as the 1006 * decoder-internal input buffer is not full. So it grabs whatever it can from 1007 * pBuffer and returns information (bytesValid) so that at a subsequent call of 1008 * %aacDecoder_Fill(), the right position in pBuffer can be determined to grab 1009 * the next data. 1010 * 1011 * \param self AAC decoder handle. 1012 * \param pBuffer Pointer to external input buffer. 1013 * \param bufferSize Size of external input buffer. This argument is required 1014 * because decoder-internally we need the information to calculate the offset to 1015 * pBuffer, where the next available data is, which is then 1016 * fed into the decoder-internal buffer (as much as 1017 * possible). Our example framework implementation fills the 1018 * buffer at pBuffer again, once it contains no available valid bytes anymore 1019 * (meaning bytesValid equal 0). 1020 * \param bytesValid Number of bitstream bytes in the external bitstream buffer 1021 * that have not yet been copied into the decoder's internal bitstream buffer by 1022 * calling this function. The value is updated according to 1023 * the amount of newly copied bytes. 1024 * \return Error code. 1025 */ 1026 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_Fill(HANDLE_AACDECODER self, 1027 UCHAR *pBuffer[], 1028 const UINT bufferSize[], 1029 UINT *bytesValid); 1030 1031 #define AACDEC_CONCEAL \ 1032 1 /*!< Flag for aacDecoder_DecodeFrame(): Trigger the built-in error \ 1033 concealment module to generate a substitute signal for one lost frame. \ 1034 New input data will not be considered. */ 1035 #define AACDEC_FLUSH \ 1036 2 /*!< Flag for aacDecoder_DecodeFrame(): Flush all filterbanks to get all \ 1037 delayed audio without having new input data. Thus new input data will \ 1038 not be considered.*/ 1039 #define AACDEC_INTR \ 1040 4 /*!< Flag for aacDecoder_DecodeFrame(): Signal an input bit stream data \ 1041 discontinuity. Resync any internals as necessary. */ 1042 #define AACDEC_CLRHIST \ 1043 8 /*!< Flag for aacDecoder_DecodeFrame(): Clear all signal delay lines and \ 1044 history buffers. CAUTION: This can cause discontinuities in the output \ 1045 signal. */ 1046 1047 /** 1048 * \brief Decode one audio frame 1049 * 1050 * \param self AAC decoder handle. 1051 * \param pTimeData Pointer to external output buffer where the decoded PCM 1052 * samples will be stored into. 1053 * \param timeDataSize Size of external output buffer. 1054 * \param flags Bit field with flags for the decoder: \n 1055 * (flags & AACDEC_CONCEAL) == 1: Do concealment. \n 1056 * (flags & AACDEC_FLUSH) == 2: Discard input data. Flush 1057 * filter banks (output delayed audio). \n (flags & AACDEC_INTR) == 4: Input 1058 * data is discontinuous. Resynchronize any internals as 1059 * necessary. \n (flags & AACDEC_CLRHIST) == 8: Clear all signal delay lines and 1060 * history buffers. 1061 * \return Error code. 1062 */ 1063 LINKSPEC_H AAC_DECODER_ERROR aacDecoder_DecodeFrame(HANDLE_AACDECODER self, 1064 INT_PCM *pTimeData, 1065 const INT timeDataSize, 1066 const UINT flags); 1067 1068 /** 1069 * \brief De-allocate all resources of an AAC decoder instance. 1070 * 1071 * \param self AAC decoder handle. 1072 * \return void. 1073 */ 1074 LINKSPEC_H void aacDecoder_Close(HANDLE_AACDECODER self); 1075 1076 /** 1077 * \brief Get CStreamInfo handle from decoder. 1078 * 1079 * \param self AAC decoder handle. 1080 * \return Reference to requested CStreamInfo. 1081 */ 1082 LINKSPEC_H CStreamInfo *aacDecoder_GetStreamInfo(HANDLE_AACDECODER self); 1083 1084 /** 1085 * \brief Get decoder library info. 1086 * 1087 * \param info Pointer to an allocated LIB_INFO structure. 1088 * \return 0 on success. 1089 */ 1090 LINKSPEC_H INT aacDecoder_GetLibInfo(LIB_INFO *info); 1091 1092 #ifdef __cplusplus 1093 } 1094 #endif 1095 1096 #endif /* AACDECODER_LIB_H */ 1097
