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 /*********************** MPEG surround decoder library ************************* 96 97 Author(s): 98 99 Description: Space Decoder 100 101 *******************************************************************************/ 102 103 #ifndef SAC_DEC_LIB_H 104 #define SAC_DEC_LIB_H 105 106 #include "common_fix.h" 107 #include "FDK_audio.h" 108 #include "sac_dec_errorcodes.h" 109 #include "FDK_bitstream.h" 110 #include "FDK_qmf_domain.h" 111 112 #ifdef __cplusplus 113 extern "C" { 114 #endif /* __cplusplus */ 115 116 /** 117 * \brief MPEG Surround input data interface mode. 118 **/ 119 typedef enum { 120 SAC_INTERFACE_QMF = 121 0, /*!< Use QMF domain interface for the input downmix audio. */ 122 SAC_INTERFACE_TIME, /*!< Use time domain interface for the input downmix 123 audio. */ 124 SAC_INTERFACE_AUTO /*!< */ 125 } SAC_INPUT_CONFIG; 126 127 /** 128 * \brief MPEG Surround output mode. 129 **/ 130 typedef enum { 131 SACDEC_OUT_MODE_NORMAL = 132 0, /*!< Normal multi channel processing without output restrictions. */ 133 SACDEC_OUT_MODE_BINAURAL, /*!< Two channel output with binaural processsing. 134 */ 135 SACDEC_OUT_MODE_STEREO, /*!< Always two channel output mode. */ 136 SACDEC_OUT_MODE_6CHANNEL /*!< Always process with 5.1 channel output. */ 137 } SAC_DEC_OUTPUT_MODE; 138 139 /** 140 * \brief MPEG Surround binaural HRTF model. 141 * HRTF will be applied only in combination with upmixtype 142 *SAC_UPMIX_TYPE_BINAURAL. 143 **/ 144 typedef enum { 145 SAC_BINAURAL_HRTF_KEMAR = 0, 146 SAC_BINAURAL_HRTF_VAST, 147 SAC_BINAURAL_HRTF_MPSVT, 148 SAC_BINAURAL_SINGLE_HRTFS 149 } SAC_BINAURAL_HRTF_MODEL; 150 151 /** 152 * \brief MPEG Surround decoder instance available. 153 **/ 154 typedef enum { 155 SAC_INSTANCE_NOT_FULL_AVAILABLE = 156 0, /*!< MPEG Surround decoder instance not full available. */ 157 SAC_INSTANCE_FULL_AVAILABLE /*!< MPEG Surround decoder instance full 158 available. */ 159 } SAC_INSTANCE_AVAIL; 160 161 /** 162 * \brief MPEG Surround decoder dynamic parameters. 163 * 164 * Use mpegSurroundDecoder_SetParam() function to configure internal status of 165 * following parameters. 166 */ 167 typedef enum { 168 SACDEC_OUTPUT_MODE = 0x0001, /*!< Set MPEG Surround decoder output mode. See 169 SAC_DEC_OUTPUT_MODE. */ 170 SACDEC_BLIND_ENABLE = 171 0x0002, /*!< Multi channel output without MPEG Surround side info. */ 172 SACDEC_PARTIALLY_COMPLEX = 173 0x0003, /*!< Set partially complex flag for MPEG Surround. 174 0: Use complex valued QMF data. 175 1: Use real valued QMF data (low power mode) */ 176 SACDEC_INTERFACE = 177 0x0004, /*!< Select signal input interface for MPEG Surround. 178 Switch time interface off: 0 179 Switch time interface on: 1 */ 180 SACDEC_BS_DELAY = 0x0005, /*!< Select bit stream delay for MPEG Surround. 181 Switch bit stream delay off: 0 182 Switch bit stream delay on: 1 */ 183 SACDEC_BINAURAL_QUALITY = 184 0x0102, /*!< Set binaural quality for MPEG Surround binaural mode. 185 0: Low Complexity, 186 1: High Quality */ 187 SACDEC_BINAURAL_DISTANCE = 0x0103, /*!< Set perceived distance for binaural 188 playback (binaural mode only). The valid 189 values range from 0 to 100. Where 100 190 corresponds to the farthest perceived 191 distance. */ 192 SACDEC_BINAURAL_DIALOG_CLARITY = 193 0x0104, /*!< Set dialog clarity (for binaural playback). 194 The valid values range from 0 to 100. */ 195 SACDEC_BINAURAL_FRONT_ANGLE = 0x0105, /*!< Set angle between the virtual front 196 speaker pair (binaural mode only). 197 The valid range is from 0 to 180 198 angular degrees. */ 199 SACDEC_BINAURAL_BACK_ANGLE = 0x0106, /*!< Set angle between the virtual back 200 speaker pair (binaural mode only). The 201 valid range is from 0 to 180 angular 202 degrees. */ 203 SACDEC_BINAURAL_PRESET = 0x0107, /*!< Set a virtual speaker setup preset for 204 binaural playback (binaural mode only). 205 This meta-parameter implicitly modifies 206 the following parameters: 207 SACDEC_BINAURAL_DISTANCE, 208 SACDEC_BINAURAL_DIALOG_CLARITY, 209 SACDEC_BINAURAL_FRONT_ANGLE and 210 SACDEC_BINAURAL_BACK_ANGLE. 211 The following presets are available: 212 1: Dry room 213 2: Living room (default) 214 3: Cinema */ 215 216 SACDEC_BS_INTERRUPTION = 217 0x0200, /*!< If the given value is unequal to 0 hint the MPEG Surround 218 decoder that the next input data is discontinuous, because of 219 frame loss, seeking, etc. Announce the decoder that the 220 bitstream data was interrupted (fSync = 0). This will cause the 221 surround decoder not to parse any new bitstream data until a 222 new header with a valid Spatial Specific Config and a 223 independently decodable frame is found. Specially important 224 when the MPEG Surround data is split accross several frames 225 (for example in the case of AAC-LC downmix with 1024 226 framelength and 2048 surround frame length) and a discontinuity 227 in the bitstream data occurs. If fSync is 1, assume that MPEG 228 Surround data is in sync (out of band config for example). */ 229 SACDEC_CLEAR_HISTORY = 0x0201, /*!< If the given value is unequal to 0 clear 230 all internal states (delay lines, QMF 231 states, ...) of the MPEG Surround decoder. 232 This will cause a discontinuity in the audio 233 output signal. */ 234 235 SACDEC_CONCEAL_NUM_KEEP_FRAMES = 236 0x0301, /*!< Error concealment: The Number of frames the module keeps the 237 last spatial image before fading to the particular spatial 238 scenario starts. The default is 10 frames. */ 239 SACDEC_CONCEAL_FADE_OUT_SLOPE_LENGTH = 240 0x0302, /*!< Error concealment: Length of the slope (in frames) the module 241 creates to fade from the last spatial scenario to the 242 particular default scenario (downmix) in case of consecutive 243 errors. Default is 5. */ 244 SACDEC_CONCEAL_FADE_IN_SLOPE_LENGTH = 245 0x0303, /*!< Error concealment: Length of the slope (in frames) the module 246 creates to fade from the default spatial scenario (downmix) to 247 the current scenario after fade-out. Default parameter value 248 is 5. */ 249 SACDEC_CONCEAL_NUM_RELEASE_FRAMES = 250 0x0304 /*!< Error concealment: The number of error free frames before the 251 module starts fading from default to the current spatial 252 scenario. Default parameter value is 3 frames. */ 253 } SACDEC_PARAM; 254 255 #define PCM_MPS INT_PCM 256 257 /** 258 * \brief MPEG Surround decoder handle. 259 */ 260 typedef struct MpegSurroundDecoder CMpegSurroundDecoder; 261 262 /** 263 * \brief Check if the full MPEG Surround decoder instance is allocated. 264 * 265 * Check if the full MPEG Surround decoder instance is allocated. 266 * 267 * \param pMpegSurroundDecoder A pointer to a decoder stucture. 268 * 269 * \return SACDEC_ERROR error code 270 */ 271 SAC_INSTANCE_AVAIL 272 mpegSurroundDecoder_IsFullMpegSurroundDecoderInstanceAvailable( 273 CMpegSurroundDecoder *pMpegSurroundDecoder); 274 275 /** 276 * \brief Open one instance of the MPEG Surround decoder. 277 * 278 * Allocate one instance of decoder and input buffers. 279 * - Allocate decoder structure 280 * - Allocate input buffers (QMF/time/MPS data) 281 * 282 * \param pMpegSurroundDecoder A pointer to a decoder handle; filled on 283 * return. 284 * \param splitMemoryAllocation Allocate only outer layer of MPS decoder. Core 285 * part is reallocated later if needed. 286 * \param stereoConfigIndex USAC: Save memory by opening the MPS decoder 287 * for a specific stereoConfigIndex. (Needs optimization macros enabled.) 288 * \param pQmfDomain Pointer to QMF domain data structure. 289 * 290 * \return SACDEC_ERROR error code 291 */ 292 SACDEC_ERROR mpegSurroundDecoder_Open( 293 CMpegSurroundDecoder **pMpegSurroundDecoder, int stereoConfigIndex, 294 HANDLE_FDK_QMF_DOMAIN pQmfDomain); 295 296 /** 297 * \brief Init one instance of the MPEG Surround decoder. 298 * 299 * Init one instance of the MPEG Surround decoder 300 * 301 * \param pMpegSurroundDecoder A pointer to a decoder handle; 302 * 303 * \return SACDEC_ERROR error code 304 */ 305 SACDEC_ERROR mpegSurroundDecoder_Init( 306 CMpegSurroundDecoder *pMpegSurroundDecoder); 307 308 /** 309 * \brief Read and parse SpatialSpecificConfig. 310 * 311 * \param pMpegSurroundDecoder A pointer to a decoder handle. 312 * \param hBs bitstream handle config parsing data source. 313 * 314 * \return SACDEC_ERROR error code 315 */ 316 SACDEC_ERROR mpegSurroundDecoder_Config( 317 CMpegSurroundDecoder *pMpegSurroundDecoder, HANDLE_FDK_BITSTREAM hBs, 318 AUDIO_OBJECT_TYPE coreCodec, INT samplingRate, INT stereoConfigIndex, 319 INT coreSbrFrameLengthIndex, INT configBytes, const UCHAR configMode, 320 UCHAR *configChanged); 321 322 SACDEC_ERROR 323 mpegSurroundDecoder_ConfigureQmfDomain( 324 CMpegSurroundDecoder *pMpegSurroundDecoder, 325 SAC_INPUT_CONFIG sac_dec_interface, UINT coreSamplingRate, 326 AUDIO_OBJECT_TYPE coreCodec); 327 328 /** 329 * \brief Parse MPEG Surround data without header 330 * 331 * \param pMpegSurroundDecoder A MPEG Surrround decoder handle. 332 * \param hBs Bit stream handle data input source 333 * \param pMpsDataBits Pointer to number of valid bits in extension 334 * payload. Function updates mpsDataBits while parsing bitstream. 335 * \param fGlobalIndependencyFlag Global independency flag of current frame. 336 * 337 * \return Error code. 338 */ 339 int mpegSurroundDecoder_ParseNoHeader( 340 CMpegSurroundDecoder *pMpegSurroundDecoder, HANDLE_FDK_BITSTREAM hBs, 341 int *pMpsDataBits, int fGlobalIndependencyFlag); 342 343 /* #ifdef SACDEC_MPS_ENABLE */ 344 /** 345 * \brief Parse MPEG Surround data with header. Header is ancType, ancStart, 346 ancStop (4 bits total). Body is ancDataSegmentByte[i]. 347 * 348 * \param pMpegSurroundDecoder A MPEG Surrround decoder handle. 349 * \param hBs Bit stream handle data input source 350 * \param pMpsDataBits Pointer to number of valid bits in extension 351 payload. Function updates mpsDataBits while parsing bitstream. Needs to be a 352 multiple of 8 + 4 (4 bits header). 353 * \param coreCodec The audio object type of the core codec handling 354 the downmix input signal. 355 * \param sampleRate Samplerate of input downmix data. 356 * \param nChannels Amount of input channels. 357 * \param frameSize Amount of input samples. 358 * \param fGlobalIndependencyFlag Global independency flag of current frame. 359 * 360 * \return Error code. 361 */ 362 int mpegSurroundDecoder_Parse(CMpegSurroundDecoder *pMpegSurroundDecoder, 363 HANDLE_FDK_BITSTREAM hBs, int *pMpsDataBits, 364 AUDIO_OBJECT_TYPE coreCodec, int sampleRate, 365 int frameSize, int fGlobalIndependencyFlag); 366 /* #endif */ 367 368 /** 369 * \brief Apply MPEG Surround upmix. 370 * 371 * Process one downmix audio frame and decode one surround frame if it applies. 372 * Downmix framing can be different from surround framing, so depending on the 373 * frame size of the downmix audio data and the framing being used by the MPEG 374 * Surround decoder, it could be that only every second call, for example, of 375 * this function actually surround data was decoded. The returned value of 376 * frameSize will be zero, if no surround data was decoded. 377 * 378 * Decoding one MPEG Surround frame. Depending on interface configuration 379 * mpegSurroundDecoder_SetParam(self, SACDEC_INTERFACE, value), the QMF or time 380 * interface will be applied. External access to QMF buffer interface can be 381 * achieved by mpegSurroundDecoder_GetQmfBuffer() call before decode frame. 382 * While using time interface, pTimeData buffer will be shared as input and 383 * output buffer. 384 * 385 * \param pMpegSurroundDecoder A MPEG Surrround decoder handle. 386 * \param pTimeData Pointer to time buffer. Depending on interface 387 * configuration, the content of pTimeData is ignored, and the internal QMF 388 * buffer will be used as input data source. 389 * Otherwise, the MPEG Surround processing is applied to the timesignal 390 * pTimeData. For both variants, the resulting MPEG 391 * Surround signal is written into pTimeData. 392 * \param timeDataSize Size of pTimeData (available buffer size). 393 * \param timeDataFrameSize Frame size of input timedata 394 * \param nChannels Pointer where the amount of input channels is 395 * given and amount of output channels is returned. 396 * \param frameSize Pointer where the amount of output samples is 397 * returned into. 398 * \param channelType Array were the corresponding channel type for 399 * each output audio channel is stored into. 400 * \param channelIndices Array were the corresponding channel type index 401 * for each output audio channel is stored into. 402 * \param mapDescr Channep map descriptor for output channel mapping 403 * to be used (From MPEG PCE ordering to whatever is required). 404 * 405 * \return Error code. 406 */ 407 int mpegSurroundDecoder_Apply(CMpegSurroundDecoder *pMpegSurroundDecoder, 408 INT_PCM *input, PCM_MPS *pTimeData, 409 const int timeDataSize, int timeDataFrameSize, 410 int *nChannels, int *frameSize, int sampleRate, 411 AUDIO_OBJECT_TYPE coreCodec, 412 AUDIO_CHANNEL_TYPE channelType[], 413 UCHAR channelIndices[], 414 const FDK_channelMapDescr *const mapDescr); 415 416 /** 417 * \brief Deallocate a MPEG Surround decoder instance. 418 * \param pMpegSurroundDecoder A decoder handle. 419 * \return No return value. 420 */ 421 void mpegSurroundDecoder_Close(CMpegSurroundDecoder *pMpegSurroundDecoder); 422 423 /** 424 * \brief Free config dependent MPEG Surround memory. 425 * \param pMpegSurroundDecoder A decoder handle. 426 * \return error. 427 */ 428 SACDEC_ERROR mpegSurroundDecoder_FreeMem( 429 CMpegSurroundDecoder *pMpegSurroundDecoder); 430 431 /** 432 * \brief Set one single MPEG Surround decoder parameter. 433 * 434 * \param pMpegSurroundDecoder A MPEG Surrround decoder handle. Must not be 435 * NULL pointer. 436 * \param param Parameter to be set. See SACDEC_PARAM. 437 * \param value Parameter value. See SACDEC_PARAM. 438 * 439 * \return 0 on sucess, and non-zero on failure. 440 */ 441 SACDEC_ERROR mpegSurroundDecoder_SetParam( 442 CMpegSurroundDecoder *pMpegSurroundDecoder, const SACDEC_PARAM param, 443 const INT value); 444 445 /** 446 * \brief Retrieve MPEG Surround decoder library info and fill info list with all depending library infos. 447 * \param libInfo Pointer to library info list to be filled. 448 * \return 0 on sucess, and non-zero on failure. 449 **/ 450 int mpegSurroundDecoder_GetLibInfo(LIB_INFO *libInfo); 451 452 /** 453 * \brief Set one single MPEG Surround decoder parameter. 454 * 455 * \param pMpegSurroundDecoder A valid MPEG Surrround decoder handle. 456 * 457 * \return The additional signal delay caused by the module. 458 */ 459 UINT mpegSurroundDecoder_GetDelay(const CMpegSurroundDecoder *self); 460 461 /** 462 * \brief Get info on whether the USAC pseudo LR feature is active. 463 * 464 * \param pMpegSurroundDecoder A valid MPEG Surrround decoder handle. 465 * \param bsPseudoLr Pointer to return wether pseudo LR USAC feature 466 * is used. 467 * 468 * \return 0 on sucess, and non-zero on failure. 469 */ 470 SACDEC_ERROR mpegSurroundDecoder_IsPseudoLR( 471 CMpegSurroundDecoder *pMpegSurroundDecoder, int *bsPseudoLr); 472 473 #ifdef __cplusplus 474 } 475 #endif /* __cplusplus */ 476 477 #endif /* #ifndef SAC_DEC_LIB_H */ 478