1 2 /* ----------------------------------------------------------------------------------------------------------- 3 Software License for The Fraunhofer FDK AAC Codec Library for Android 4 5 � Copyright 1995 - 2012 Fraunhofer-Gesellschaft zur F�rderung der angewandten Forschung e.V. 6 All rights reserved. 7 8 1. INTRODUCTION 9 The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software that implements 10 the MPEG Advanced Audio Coding ("AAC") encoding and decoding scheme for digital audio. 11 This FDK AAC Codec software is intended to be used on a wide variety of Android devices. 12 13 AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient general perceptual 14 audio codecs. AAC-ELD is considered the best-performing full-bandwidth communications codec by 15 independent studies and is widely deployed. AAC has been standardized by ISO and IEC as part 16 of the MPEG specifications. 17 18 Patent licenses for necessary patent claims for the FDK AAC Codec (including those of Fraunhofer) 19 may be obtained through Via Licensing (www.vialicensing.com) or through the respective patent owners 20 individually for the purpose of encoding or decoding bit streams in products that are compliant with 21 the ISO/IEC MPEG audio standards. Please note that most manufacturers of Android devices already license 22 these patent claims through Via Licensing or directly from the patent owners, and therefore FDK AAC Codec 23 software may already be covered under those patent licenses when it is used for those licensed purposes only. 24 25 Commercially-licensed AAC software libraries, including floating-point versions with enhanced sound quality, 26 are also available from Fraunhofer. Users are encouraged to check the Fraunhofer website for additional 27 applications information and documentation. 28 29 2. COPYRIGHT LICENSE 30 31 Redistribution and use in source and binary forms, with or without modification, are permitted without 32 payment of copyright license fees provided that you satisfy the following conditions: 33 34 You must retain the complete text of this software license in redistributions of the FDK AAC Codec or 35 your modifications thereto in source code form. 36 37 You must retain the complete text of this software license in the documentation and/or other materials 38 provided with redistributions of the FDK AAC Codec or your modifications thereto in binary form. 39 You must make available free of charge copies of the complete source code of the FDK AAC Codec and your 40 modifications thereto to recipients of copies in binary form. 41 42 The name of Fraunhofer may not be used to endorse or promote products derived from this library without 43 prior written permission. 44 45 You may not charge copyright license fees for anyone to use, copy or distribute the FDK AAC Codec 46 software or your modifications thereto. 47 48 Your modified versions of the FDK AAC Codec must carry prominent notices stating that you changed the software 49 and the date of any change. For modified versions of the FDK AAC Codec, the term 50 "Fraunhofer FDK AAC Codec Library for Android" must be replaced by the term 51 "Third-Party Modified Version of the Fraunhofer FDK AAC Codec Library for Android." 52 53 3. NO PATENT LICENSE 54 55 NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without limitation the patents of Fraunhofer, 56 ARE GRANTED BY THIS SOFTWARE LICENSE. Fraunhofer provides no warranty of patent non-infringement with 57 respect to this software. 58 59 You may use this FDK AAC Codec software or modifications thereto only for purposes that are authorized 60 by appropriate patent licenses. 61 62 4. DISCLAIMER 63 64 This FDK AAC Codec software is provided by Fraunhofer on behalf of the copyright holders and contributors 65 "AS IS" and WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, including but not limited to the implied warranties 66 of merchantability and fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 67 CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary, or consequential damages, 68 including but not limited to procurement of substitute goods or services; loss of use, data, or profits, 69 or business interruption, however caused and on any theory of liability, whether in contract, strict 70 liability, or tort (including negligence), arising in any way out of the use of this software, even if 71 advised of the possibility of such damage. 72 73 5. CONTACT INFORMATION 74 75 Fraunhofer Institute for Integrated Circuits IIS 76 Attention: Audio and Multimedia Departments - FDK AAC LL 77 Am Wolfsmantel 33 78 91058 Erlangen, Germany 79 80 www.iis.fraunhofer.de/amm 81 amm-info@iis.fraunhofer.de 82 ----------------------------------------------------------------------------------------------------------- */ 83 84 /************************** MPEG-4 Transport Decoder *********************** 85 86 Author(s): Manuel Jander 87 Description: MPEG Transport decoder 88 89 ******************************************************************************/ 90 91 #ifndef __TPDEC_LIB_H__ 92 #define __TPDEC_LIB_H__ 93 94 #include "tp_data.h" 95 96 #include "FDK_bitstream.h" 97 98 #define TRANSPORTDEC_INBUF_SIZE ( 8192 ) /*!< Size is in bytes. 99 Set the transport input buffer size carefully and 100 assure that it fulfills the requirements of the 101 supported transport format(s). */ 102 103 typedef enum { 104 TRANSPORTDEC_OK = 0, /*!< All fine. */ 105 106 /* Synchronization errors. Wait for new input data and try again. */ 107 tpdec_sync_error_start = 0x100, 108 TRANSPORTDEC_NOT_ENOUGH_BITS, /*!< Out of bits. Provide more bits and try again. */ 109 TRANSPORTDEC_SYNC_ERROR, /*!< No sync was found or sync got lost. Keep trying. */ 110 tpdec_sync_error_end, 111 112 /* Decode errors. Mostly caused due to bit errors. */ 113 tpdec_decode_error_start = 0x400, 114 TRANSPORTDEC_PARSE_ERROR, /*!< Bitstream data showed inconsistencies (wrong syntax). */ 115 TRANSPORTDEC_UNSUPPORTED_FORMAT, /*!< Unsupported format or feature found in the bitstream data. */ 116 TRANSPORTDEC_CRC_ERROR, /*!< CRC error encountered in bitstream data. */ 117 tpdec_decode_error_end, 118 119 /* Fatal errors. Stop immediately on one of these errors! */ 120 tpdec_fatal_error_start = 0x200, 121 TRANSPORTDEC_UNKOWN_ERROR, /*!< An unknown error occured. */ 122 TRANSPORTDEC_INVALID_PARAMETER, /*!< An invalid parameter was passed to a function. */ 123 TRANSPORTDEC_NEED_TO_RESTART, /*!< The decoder needs to be restarted, since the requiered 124 configuration change cannot be performed. */ 125 tpdec_fatal_error_end 126 127 } TRANSPORTDEC_ERROR; 128 129 130 /** Macro to identify decode errors. */ 131 #define TPDEC_IS_DECODE_ERROR(err) ( ((err>=tpdec_decode_error_start) && (err<=tpdec_decode_error_end)) ? 1 : 0) 132 /** Macro to identify fatal errors. */ 133 #define TPDEC_IS_FATAL_ERROR(err) ( ((err>=tpdec_fatal_error_start) && (err<=tpdec_fatal_error_end)) ? 1 : 0) 134 135 136 /** 137 * \brief Parameter identifiers for transportDec_SetParam() 138 */ 139 typedef enum { 140 TPDEC_PARAM_MINIMIZE_DELAY = 1, /** Delay minimization strategy. 0: none, 1: discard as many frames as possible. */ 141 TPDEC_PARAM_EARLY_CONFIG, /** Enable early config discovery. */ 142 TPDEC_PARAM_IGNORE_BUFFERFULLNESS, /** Ignore buffer fullness. */ 143 TPDEC_PARAM_SET_BITRATE, /** Set average bit rate for bit stream interruption frame misses estimation. */ 144 TPDEC_PARAM_RESET, /** Reset transport decoder instance status. */ 145 TPDEC_PARAM_BURST_PERIOD /** Set data reception burst period in mili seconds. */ 146 } TPDEC_PARAM; 147 148 /* ISO/IEC 14496-3 4.4.1.1 Table 4.2 Program config element */ 149 #define PC_FSB_CHANNELS_MAX 16 /* Front/Side/Back channels */ 150 #define PC_LFE_CHANNELS_MAX 4 151 #define PC_ASSOCDATA_MAX 8 152 #define PC_CCEL_MAX 16 /* CC elements */ 153 #define PC_COMMENTLENGTH 256 154 155 156 /*! 157 \brief Reset Program Config Element. 158 \param pPce Program Config Element structure. 159 \return void 160 */ 161 void CProgramConfig_Reset ( CProgramConfig *pPce ); 162 163 /*! 164 \brief Initialize Program Config Element. 165 \param pPce Program Config Element structure. 166 \return void 167 */ 168 void CProgramConfig_Init ( CProgramConfig *pPce ); 169 170 /*! 171 \brief Inquire state of present Program Config Element structure. 172 \param pPce Program Config Element structure. 173 \return 1 if the PCE structure is filled correct, 174 0 if no valid PCE present. 175 */ 176 int CProgramConfig_IsValid ( const CProgramConfig *pPce ); 177 178 #ifdef TP_PCE_ENABLE 179 /*! 180 \brief Read Program Config Element. 181 \param pPce Program Config Element structure. 182 \param bs Bitstream buffer to read from. 183 \param alignAnchor Align bitstream to alignAnchor bits after all read operations. 184 \return void 185 */ 186 void CProgramConfig_Read ( CProgramConfig *pPce, 187 HANDLE_FDK_BITSTREAM bs, 188 UINT alignAnchor ); 189 #endif /* TP_PCE_ENABLE */ 190 191 /** 192 * \brief Lookup and verify a given element. The decoder calls this 193 * method with every new element ID found in the bitstream. 194 * 195 * \param pPce A valid Program config structure. 196 * \param tag Tag of the current element to be looked up. 197 * \param channelIdx The current channel count of the decoder parser. 198 * \param chMapping Array to store the canonical channel mapping indexes. 199 * \param chType Array to store the audio channel type. 200 * \param chIndex Array to store the individual audio channel type index. 201 * \param elMapping Pointer where the canonical element index is stored. 202 * \param elType The element id of the current element to be looked up. 203 * 204 * \return Non-zero if the element belongs to the current program, zero 205 * if it does not. 206 */ 207 int CProgramConfig_LookupElement( 208 CProgramConfig *pPce, 209 const UINT channelConfig, 210 const UINT tag, 211 const UINT channelIdx, 212 UCHAR chMapping[], 213 AUDIO_CHANNEL_TYPE chType[], 214 UCHAR chIndex[], 215 UCHAR *elMapping, 216 MP4_ELEMENT_ID elList[], 217 MP4_ELEMENT_ID elType 218 ); 219 220 /** 221 * \brief Get table of elements in canonical order. 222 * \param pPce A valid program config structure. 223 * \param table An array where the element IDs are stored. 224 * \return Total element count including all SCE, CPE and LFE. 225 */ 226 int CProgramConfig_GetElementTable( const CProgramConfig *pPce, 227 MP4_ELEMENT_ID table[], 228 const INT elListSize ); 229 230 /** 231 * \brief Initialize a given AudioSpecificConfig structure. 232 * \param pAsc A pointer to an allocated CSAudioSpecificConfig struct. 233 * \return void 234 */ 235 void AudioSpecificConfig_Init(CSAudioSpecificConfig *pAsc); 236 237 /** 238 * \brief Parse a AudioSpecificConfig from a given bitstream handle. 239 * 240 * \param pAsc A pointer to an allocated CSAudioSpecificConfig struct. 241 * \param hBs Bitstream handle. 242 * \param fExplicitBackwardCompatible Do explicit backward compatibility parsing if set (flag). 243 * \param cb pointer to structure holding callback information 244 * 245 * \return Total element count including all SCE, CPE and LFE. 246 */ 247 TRANSPORTDEC_ERROR AudioSpecificConfig_Parse( 248 CSAudioSpecificConfig *pAsc, 249 HANDLE_FDK_BITSTREAM hBs, 250 int fExplicitBackwardCompatible, 251 CSTpCallBacks *cb 252 ); 253 254 /* CELP stuff */ 255 enum { 256 MPE = 0, 257 RPE = 1, 258 fs8KHz = 0, 259 fs16KHz = 1 260 }; 261 262 /* Defintion of flags that can be passed to transportDecOpen() */ 263 #define TP_FLAG_MPEG4 1 264 265 /* Capability flags */ 266 #define CAPF_TPDEC_ADIF 0x00001000 /**< Flag indicating support for ADIF transport format. */ 267 #define CAPF_TPDEC_ADTS 0x00002000 /**< Flag indicating support for ADTS transport format. */ 268 #define CAPF_TPDEC_LOAS 0x00004000 /**< Flag indicating support for LOAS transport format. */ 269 #define CAPF_TPDEC_LATM 0x00008000 /**< Flag indicating support for LATM transport format. */ 270 #define CAPF_TPDEC_RAWPACKETS 0x00010000 /**< Flag indicating support for raw packets transport format. */ 271 272 typedef struct TRANSPORTDEC *HANDLE_TRANSPORTDEC; 273 274 275 /** 276 * \brief Configure Transport Decoder via a binary coded AudioSpecificConfig or StreamMuxConfig. 277 * The previously requested configuration callback will be called as well. The buffer conf 278 * must containt a SMC in case of LOAS/LATM transport format, and an ASC elseways. 279 * 280 * \param hTp Handle of a transport decoder. 281 * \param conf UCHAR buffer of the binary coded config (ASC or SMC). 282 * \param length The length in bytes of the conf buffer. 283 * 284 * \return Error code. 285 */ 286 TRANSPORTDEC_ERROR transportDec_OutOfBandConfig( const HANDLE_TRANSPORTDEC hTp, 287 UCHAR *conf, 288 const UINT length, 289 const UINT layer ); 290 291 /** 292 * \brief Open Transport medium for reading. 293 * 294 * \param transportDecFmt Format of the transport decoder medium to be accessed. 295 * \param flags Transport decoder flags. Currently only TP_FLAG_MPEG4, which signals a 296 * MPEG4 capable decoder (relevant for ADTS only). 297 * 298 * \return A pointer to a valid and allocated HANDLE_TRANSPORTDEC or a null pointer on failure. 299 */ 300 HANDLE_TRANSPORTDEC transportDec_Open( TRANSPORT_TYPE transportDecFmt, 301 const UINT flags ); 302 303 /** 304 * \brief Register configuration change callback. 305 * \param hTp Handle of transport decoder. 306 * \param cbUpdateConfig Pointer to a callback function to handle audio config changes. 307 * \param user_data void pointer for user data passed to the callback as first parameter. 308 * \return 0 on success. 309 */ 310 int transportDec_RegisterAscCallback ( 311 HANDLE_TRANSPORTDEC hTp, 312 const cbUpdateConfig_t cbUpdateConfig, 313 void* user_data ); 314 315 /** 316 * \brief Register SSC parser callback. 317 * \param hTp Handle of transport decoder. 318 * \param cbUpdateConfig Pointer to a callback function to handle SSC parsing. 319 * \param user_data void pointer for user data passed to the callback as first parameter. 320 * \return 0 on success. 321 */ 322 int transportDec_RegisterSscCallback ( 323 HANDLE_TRANSPORTDEC hTp, 324 const cbSsc_t cbSscParse, 325 void* user_data ); 326 327 /** 328 * \brief Register SBR header parser callback. 329 * \param hTp Handle of transport decoder. 330 * \param cbUpdateConfig Pointer to a callback function to handle SBR header parsing. 331 * \param user_data void pointer for user data passed to the callback as first parameter. 332 * \return 0 on success. 333 */ 334 int transportDec_RegisterSbrCallback( HANDLE_TRANSPORTDEC hTpDec, const cbSbr_t cbSbr, void* user_data); 335 336 /** 337 * \brief Fill internal input buffer with bitstream data from the external input buffer. 338 * The function only copies such data as long as the decoder-internal input buffer is not full. 339 * So it grabs whatever it can from pBuffer and returns information (bytesValid) so that at a 340 * subsequent call of %transportDec_FillData(), the right position in pBuffer can be determined to 341 * grab the next data. 342 * 343 * \param hTp Handle of transportDec. 344 * \param pBuffer Pointer to external input buffer. 345 * \param bufferSize Size of external input buffer. This argument is required because decoder-internally 346 * we need the information to calculate the offset to pBuffer, where the next 347 * available data is, which is then fed into the decoder-internal buffer (as much 348 * as possible). Our example framework implementation fills the buffer at pBuffer 349 * again, once it contains no available valid bytes anymore (meaning bytesValid equal 0). 350 * \param bytesValid Number of bitstream bytes in the external bitstream buffer that have not yet been 351 * copied into the decoder's internal bitstream buffer by calling this function. 352 * The value is updated according to the amount of newly copied bytes. 353 * \param layer The layer the bitstream belongs to. 354 * \return Error code. 355 */ 356 TRANSPORTDEC_ERROR transportDec_FillData( 357 const HANDLE_TRANSPORTDEC hTp, 358 UCHAR *pBuffer, 359 const UINT bufferSize, 360 UINT *pBytesValid, 361 const INT layer ); 362 363 /** 364 * \brief Get transportDec bitstream handle. 365 * \param hTp Pointer to a transport decoder handle. 366 * \return HANDLE_FDK_BITSTREAM bitstream handle. 367 */ 368 HANDLE_FDK_BITSTREAM transportDec_GetBitstream ( const HANDLE_TRANSPORTDEC hTp, const UINT layer ); 369 370 /** 371 * \brief Get transport format. 372 * \param hTp Pointer to a transport decoder handle. 373 * \return The transport format. 374 */ 375 TRANSPORT_TYPE transportDec_GetFormat ( const HANDLE_TRANSPORTDEC hTp ); 376 377 /** 378 * \brief Get the current buffer fullness value. 379 * 380 * \param hTp Handle of a transport decoder. 381 * 382 * \return Buffer fullness 383 */ 384 INT transportDec_GetBufferFullness( const HANDLE_TRANSPORTDEC hTp ); 385 386 /** 387 * \brief Close and deallocate transportDec. 388 * \param phTp Pointer to a previously allocated transport decoder handle. 389 * \return void 390 */ 391 void transportDec_Close ( HANDLE_TRANSPORTDEC *phTp ); 392 393 /** 394 * \brief Read one access unit from the transportDec medium. 395 * \param hTp Handle of transportDec. 396 * \param length On return, this value is overwritten with the actual access unit length in bits. 397 * Set to -1 if length is unknown. 398 * \return Error code. 399 */ 400 TRANSPORTDEC_ERROR transportDec_ReadAccessUnit ( const HANDLE_TRANSPORTDEC hTp, const UINT layer ); 401 402 /** 403 * \brief Get the remaining amount of bits of the current access unit. The result 404 * can be below zero, meaning that too many bits have been read. 405 * \param hTp Handle of transportDec. 406 * \return amount of remaining bits. 407 */ 408 INT transportDec_GetAuBitsRemaining( const HANDLE_TRANSPORTDEC hTp, const UINT layer ); 409 410 /** 411 * \brief Get the total amount of bits of the current access unit. 412 * \param hTp Handle of transportDec. 413 * \return amount of total bits. 414 */ 415 INT transportDec_GetAuBitsTotal( const HANDLE_TRANSPORTDEC hTp, const UINT layer ); 416 417 /** 418 * \brief This function is required to be called when the decoder has finished parsing 419 * one Access Unit for bitstream housekeeping. 420 * \param hTp Transport Handle. 421 * \return Error code. 422 */ 423 TRANSPORTDEC_ERROR transportDec_EndAccessUnit ( const HANDLE_TRANSPORTDEC hTp ); 424 425 /** 426 * \brief Obtain the amount of missing access units if applicable in case of 427 * a bit stream synchronization error. Each time transportDec_ReadAccessUnit() 428 * returns TRANSPORTDEC_SYNC_ERROR this function can be called to retrieve an estimate 429 * of the amount of missing access units. This works only in case of constant average 430 * bit rate (has to be known) and if the parameter TPDEC_PARAM_SET_BITRATE has been set 431 * accordingly. 432 * \param hTp Transport Handle. 433 * \param pNAccessUnits pointer to a memory location where the estimated lost frame count will be stored into. 434 * \return Error code. 435 */ 436 TRANSPORTDEC_ERROR transportDec_GetMissingAccessUnitCount ( INT *pNAccessUnits, HANDLE_TRANSPORTDEC hTp ); 437 438 439 /** 440 * \brief Set a given setting. 441 * \param hTp Transport Handle. 442 * \param param Identifier of the parameter to be changed. 443 * \param value Value for the parameter to be changed. 444 * \return Error code. 445 */ 446 TRANSPORTDEC_ERROR transportDec_SetParam ( const HANDLE_TRANSPORTDEC hTp, 447 const TPDEC_PARAM param, 448 const INT value ); 449 450 /** 451 * \brief Get number of subframes (for LATM or ADTS) 452 * \param hTp Transport Handle. 453 * \return Number of ADTS/LATM subframes (return 1 for all other transport types). 454 */ 455 UINT transportDec_GetNrOfSubFrames(HANDLE_TRANSPORTDEC hTp); 456 457 458 /** 459 * \brief Get info structure of transport decoder library. 460 * \param info A pointer to an allocated LIB_INFO struct. 461 * \return Error code. 462 */ 463 TRANSPORTDEC_ERROR transportDec_GetLibInfo( LIB_INFO *info ); 464 465 /* ADTS CRC support */ 466 467 /** 468 * \brief Set current bitstream position as start of a new data region. 469 * \param hTp Transport handle. 470 * \param mBits Size in bits of the data region. Set to 0 if it should not be of a fixed size. 471 * \return Data region ID, which should be used when calling transportDec_CrcEndReg(). 472 */ 473 int transportDec_CrcStartReg ( const HANDLE_TRANSPORTDEC hTp, 474 const INT mBits ); 475 476 /** 477 * \brief Set end of data region. 478 * \param hTp Transport handle. 479 * \param reg Data region ID, opbtained from transportDec_CrcStartReg(). 480 * \return void 481 */ 482 void transportDec_CrcEndReg ( const HANDLE_TRANSPORTDEC hTp, 483 const INT reg ); 484 485 /** 486 * \brief Calculate ADTS crc and check if it is correct. The ADTS checksum is held internally. 487 * \param hTp Transport handle. 488 * \return Return TRANSPORTDEC_OK if the CRC is ok, or error if CRC is not correct. 489 */ 490 TRANSPORTDEC_ERROR transportDec_CrcCheck ( const HANDLE_TRANSPORTDEC hTp ); 491 492 493 #endif /* #ifndef __TPDEC_LIB_H__ */ 494