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 /**************************** PCM utility library ****************************** 96 97 Author(s): Christian Griebel 98 99 Description: 100 101 *******************************************************************************/ 102 103 /** 104 * \file pcmdmx_lib.h 105 * \brief FDK PCM audio mixdown library interface header file. 106 107 \page INTRO Introduction 108 109 110 \section SCOPE Scope 111 112 This document describes the high-level application interface and usage of the 113 FDK PCM audio mixdown module library developed by the Fraunhofer Institute for 114 Integrated Circuits (IIS). Depending on the library configuration, the module 115 can manipulate the number of audio channels of a given PCM signal. It can 116 create for example a two channel stereo audio signal from a given multi-channel 117 configuration (e.g. 5.1 channels). 118 119 120 \page ABBREV List of abbreviations 121 122 \li \b AAC - Advanced Audio Coding\n 123 Is an audio coding standard for lossy digital audio compression standardized 124 by ISO and IEC, as part of the MPEG-2 (ISO/IEC 13818-7:2006) and MPEG-4 125 (ISO/IEC 14496-3:2009) specifications. 126 127 \li \b DSE - Data Stream Element\n 128 A syntactical element of the MPEG-2/4 Advanced Audio Coding bitstream 129 standardized in ISO/IEC 14496-3:2009. It can convey any kind of data associated 130 to one program. 131 132 \li \b PCE - Program Config Element\n 133 A syntactical element of the MPEG-2/4 Advanced Audio Coding bitstream 134 standardized in ISO/IEC 14496-3:2009 that can define the stream configuration 135 for a single program. In addition it can comprise simple downmix meta data. 136 137 */ 138 139 #ifndef PCMDMX_LIB_H 140 #define PCMDMX_LIB_H 141 142 #include "machine_type.h" 143 #include "common_fix.h" 144 #include "FDK_audio.h" 145 #include "FDK_bitstream.h" 146 147 /** 148 * \enum PCMDMX_ERROR 149 * 150 * Error codes that can be returned by module interface functions. 151 */ 152 typedef enum { 153 PCMDMX_OK = 0x0, /*!< No error happened. */ 154 PCMDMX_UNSUPPORTED = 155 0x1, /*!< The requested feature/service is unavailable. This can 156 occur if the module was built for a wrong configuration. */ 157 pcm_dmx_fatal_error_start, 158 PCMDMX_OUT_OF_MEMORY, /*!< Not enough memory to set up an instance of the 159 module. */ 160 pcm_dmx_fatal_error_end, 161 162 PCMDMX_INVALID_HANDLE, /*!< The given instance handle is not valid. */ 163 PCMDMX_INVALID_ARGUMENT, /*!< One of the parameters handed over is invalid. */ 164 PCMDMX_INVALID_CH_CONFIG, /*!< The given channel configuration is not 165 supported and thus no processing was performed. 166 */ 167 PCMDMX_INVALID_MODE, /*!< The set configuration/mode is not applicable. */ 168 PCMDMX_UNKNOWN_PARAM, /*!< The handed parameter is not known/supported. */ 169 PCMDMX_UNABLE_TO_SET_PARAM, /*!< Unable to set the specific parameter. Most 170 probably the value ist out of range. 171 */ 172 PCMDMX_CORRUPT_ANC_DATA, /*!< The read ancillary data was corrupt. */ 173 PCMDMX_OUTPUT_BUFFER_TOO_SMALL /*!< The size of pcm output buffer is too 174 small. */ 175 176 } PCMDMX_ERROR; 177 178 /** Macro to identify fatal errors. */ 179 #define PCMDMX_IS_FATAL_ERROR(err) \ 180 ((((err) >= pcm_dmx_fatal_error_start) && \ 181 ((err) <= pcm_dmx_fatal_error_end)) \ 182 ? 1 \ 183 : 0) 184 185 /** 186 * \enum PCMDMX_PARAM 187 * 188 * Modules dynamic runtime parameters that can be handed to function 189 * pcmDmx_SetParam() and pcmDmx_GetParam(). 190 */ 191 typedef enum { 192 DMX_PROFILE_SETTING = 193 0x01, /*!< Defines which equations, coefficients and default/ 194 fallback values used for downmixing. See 195 ::DMX_PROFILE_TYPE type for details. */ 196 DMX_BS_DATA_EXPIRY_FRAME = 197 0x10, /*!< The number of frames without new metadata that 198 have to go by before the bitstream data expires. 199 The value 0 disables expiry. */ 200 DMX_BS_DATA_DELAY = 201 0x11, /*!< The number of delay frames of the output samples 202 compared to the bitstream data. */ 203 MIN_NUMBER_OF_OUTPUT_CHANNELS = 204 0x20, /*!< The minimum number of output channels. For all 205 input configurations that have less than the given 206 channels the module will modify the output 207 automatically to obtain the given number of output 208 channels. Mono signals will be duplicated. If more 209 than two output channels are desired the module 210 just adds empty channels. The parameter value must 211 be either -1, 0, 1, 2, 6 or 8. If the value is 212 greater than zero and exceeds the value of 213 parameter ::MAX_NUMBER_OF_OUTPUT_CHANNELS the 214 latter will be set to the same value. Both values 215 -1 and 0 disable the feature. */ 216 MAX_NUMBER_OF_OUTPUT_CHANNELS = 217 0x21, /*!< The maximum number of output channels. For all 218 input configurations that have more than the given 219 channels the module will apply a mixdown 220 automatically to obtain the given number of output 221 channels. The value must be either -1, 0, 1, 2, 6 222 or 8. If it's greater than zero and lower or equal 223 than the value of ::MIN_NUMBER_OF_OUTPUT_CHANNELS 224 parameter the latter will be set to the same value. 225 The values -1 and 0 disable the feature. */ 226 DMX_DUAL_CHANNEL_MODE = 227 0x30, /*!< Downmix mode for two channel audio data. See type 228 ::DUAL_CHANNEL_MODE for details. */ 229 DMX_PSEUDO_SURROUND_MODE = 230 0x31 /*!< Defines how module handles pseudo surround 231 compatible signals. See ::PSEUDO_SURROUND_MODE 232 type for details. */ 233 } PCMDMX_PARAM; 234 235 /** 236 * \enum DMX_PROFILE_TYPE 237 * 238 * Valid value list for parameter ::DMX_PROFILE_SETTING. 239 */ 240 typedef enum { 241 DMX_PRFL_STANDARD = 242 0x0, /*!< The standard profile creates mixdown signals based on 243 the advanced downmix metadata (from a DSE), equations 244 and default values defined in ISO/IEC 14496:3 245 Ammendment 4. Any other (legacy) downmix metadata will 246 be ignored. */ 247 DMX_PRFL_MATRIX_MIX = 248 0x1, /*!< This profile behaves just as the standard profile if 249 advanced downmix metadata (from a DSE) is available. If 250 not, the matrix_mixdown information embedded in the 251 program configuration element (PCE) will be applied. If 252 neither is the case the module creates a mixdown using 253 the default coefficients defined in MPEG-4 Ammendment 4. 254 The profile can be used e.g. to support legacy digital 255 TV (e.g. DVB) streams. */ 256 DMX_PRFL_FORCE_MATRIX_MIX = 257 0x2, /*!< Similar to the ::DMX_PRFL_MATRIX_MIX profile but if both 258 the advanced (DSE) and the legacy (PCE) MPEG downmix 259 metadata are available the latter will be applied. */ 260 DMX_PRFL_ARIB_JAPAN = 261 0x3 /*!< Downmix creation as described in ABNT NBR 15602-2. But 262 if advanced downmix metadata is available it will be 263 prefered. */ 264 } DMX_PROFILE_TYPE; 265 266 /** 267 * \enum PSEUDO_SURROUND_MODE 268 * 269 * Valid value list for parameter ::DMX_PSEUDO_SURROUND_MODE. 270 */ 271 typedef enum { 272 NEVER_DO_PS_DMX = 273 -1, /*!< Ignore any metadata and do never create a pseudo surround 274 compatible downmix. (Default) */ 275 AUTO_PS_DMX = 0, /*!< Create a pseudo surround compatible downmix only if 276 signalled in bitstreams meta data. */ 277 FORCE_PS_DMX = 278 1 /*!< Always create a pseudo surround compatible downmix. 279 CAUTION: This can lead to excessive signal cancellations 280 and signal level differences for non-compatible signals. */ 281 } PSEUDO_SURROUND_MODE; 282 283 /** 284 * \enum DUAL_CHANNEL_MODE 285 * 286 * Valid value list for parameter ::DMX_DUAL_CHANNEL_MODE. 287 */ 288 typedef enum { 289 STEREO_MODE = 0x0, /*!< Leave stereo signals as they are. */ 290 CH1_MODE = 0x1, /*!< Create a dual mono output signal from channel 1. */ 291 CH2_MODE = 0x2, /*!< Create a dual mono output signal from channel 2. */ 292 MIXED_MODE = 0x3 /*!< Create a dual mono output signal by mixing the two 293 channels. */ 294 } DUAL_CHANNEL_MODE; 295 296 #define DMX_PCM FIXP_DBL 297 #define DMX_PCMF FIXP_DBL 298 #define DMX_PCM_BITS DFRACT_BITS 299 #define FX_DMX2FX_PCM(x) FX_DBL2FX_PCM((FIXP_DBL)(x)) 300 301 /* ------------------------ * 302 * MODULES INTERFACE: * 303 * ------------------------ */ 304 typedef struct PCM_DMX_INSTANCE *HANDLE_PCM_DOWNMIX; 305 306 /*! \addtogroup pcmDmxResetFlags Modules reset flags 307 * Macros that can be used as parameter for function pcmDmx_Reset() to specify 308 * which parts of the module shall be reset. 309 * @{ 310 * 311 * \def PCMDMX_RESET_PARAMS 312 * Only reset the user specific parameters that have been modified with 313 * pcmDmx_SetParam(). 314 * 315 * \def PCMDMX_RESET_BS_DATA 316 * Delete the meta data that has been fed with the appropriate interface 317 * functions. 318 * 319 * \def PCMDMX_RESET_FULL 320 * Reset the complete module instance to the state after pcmDmx_Open() had been 321 * called. 322 */ 323 #define PCMDMX_RESET_PARAMS (1) 324 #define PCMDMX_RESET_BS_DATA (2) 325 #define PCMDMX_RESET_FULL (PCMDMX_RESET_PARAMS | PCMDMX_RESET_BS_DATA) 326 /*! @} */ 327 328 #ifdef __cplusplus 329 extern "C" { 330 #endif 331 332 /** Open and initialize an instance of the PCM downmix module 333 * @param[out] pSelf Pointer to a buffer receiving the handle of the new 334 *instance. 335 * @returns Returns an error code of type ::PCMDMX_ERROR. 336 **/ 337 PCMDMX_ERROR pcmDmx_Open(HANDLE_PCM_DOWNMIX *pSelf); 338 339 /** Set one parameter for a single instance of the PCM downmix module. 340 * @param[in] self Handle of PCM downmix instance. 341 * @param[in] param Parameter to be set. Can be one from the ::PCMDMX_PARAM 342 *list. 343 * @param[in] value Parameter value. 344 * @returns Returns an error code of type ::PCMDMX_ERROR. 345 **/ 346 PCMDMX_ERROR pcmDmx_SetParam(HANDLE_PCM_DOWNMIX self, const PCMDMX_PARAM param, 347 const INT value); 348 349 /** Get one parameter value of a single PCM downmix module instance. 350 * @param[in] self Handle of PCM downmix module instance. 351 * @param[in] param Parameter to query. Can be one from the ::PCMDMX_PARAM 352 *list. 353 * @param[out] pValue Pointer to buffer receiving the parameter value. 354 * @returns Returns an error code of type ::PCMDMX_ERROR. 355 **/ 356 PCMDMX_ERROR pcmDmx_GetParam(HANDLE_PCM_DOWNMIX self, const PCMDMX_PARAM param, 357 INT *const pValue); 358 359 /** \cond 360 * Extract relevant downmix meta-data directly from a given bitstream. The 361 *function can handle both data specified in ETSI TS 101 154 or ISO/IEC 362 *14496-3:2009/Amd.4:2013. 363 * @param[in] self Handle of PCM downmix instance. 364 * @param[in] hBitStream Handle of FDK bitstream buffer. 365 * @param[in] ancDataBits Length of ancillary data in bits. 366 * @param[in] isMpeg2 Flag indicating wheter the ancillary data is from a 367 *MPEG-1/2 or a MPEG-4 stream. 368 * @returns Returns an error code of type ::PCMDMX_ERROR. 369 **/ 370 PCMDMX_ERROR pcmDmx_Parse(HANDLE_PCM_DOWNMIX self, 371 HANDLE_FDK_BITSTREAM hBitStream, UINT ancDataBits, 372 int isMpeg2); 373 /** \endcond */ 374 375 /** Read from a given ancillary data buffer and extract the relevant downmix 376 *meta-data. The function can handle both data specified in ETSI TS 101 154 or 377 *ISO/IEC 14496-3:2009/Amd.4:2013. 378 * @param[in] self Handle of PCM downmix instance. 379 * @param[in] pAncDataBuf Pointer to ancillary buffer holding the data. 380 * @param[in] ancDataBytes Size of ancillary data in bytes. 381 * @param[in] isMpeg2 Flag indicating wheter the ancillary data is from a 382 *MPEG-1/2 or a MPEG-4 stream. 383 * @returns Returns an error code of type ::PCMDMX_ERROR. 384 **/ 385 PCMDMX_ERROR pcmDmx_ReadDvbAncData(HANDLE_PCM_DOWNMIX self, UCHAR *pAncDataBuf, 386 UINT ancDataBytes, int isMpeg2); 387 388 /** Set the matrix mixdown information extracted from the PCE of an AAC 389 *bitstream. 390 * @param[in] self Handle of PCM downmix instance. 391 * @param[in] matrixMixdownPresent Matrix mixdown index present flag extracted 392 *from PCE. 393 * @param[in] matrixMixdownIdx The 2 bit matrix mixdown index extracted 394 *from PCE. 395 * @param[in] pseudoSurroundEnable The pseudo surround enable flag extracted 396 *from PCE. 397 * @returns Returns an error code of type 398 *::PCMDMX_ERROR. 399 **/ 400 PCMDMX_ERROR pcmDmx_SetMatrixMixdownFromPce(HANDLE_PCM_DOWNMIX self, 401 int matrixMixdownPresent, 402 int matrixMixdownIdx, 403 int pseudoSurroundEnable); 404 405 /** Reset the module. 406 * @param[in] self Handle of PCM downmix instance. 407 * @param[in] flags Flags telling which parts of the module shall be reset. 408 * See \ref pcmDmxResetFlags for details. 409 * @returns Returns an error code of type ::PCMDMX_ERROR. 410 **/ 411 PCMDMX_ERROR pcmDmx_Reset(HANDLE_PCM_DOWNMIX self, UINT flags); 412 413 /** Create a mixdown, bypass or extend the output signal depending on the 414 *modules settings and the respective given input configuration. 415 * 416 * \param[in] self Handle of PCM downmix module instance. 417 * \param[in,out] pPcmBuf Pointer to time buffer with PCM samples. 418 * \param[in] pcmBufSize Size of pPcmBuf buffer. 419 * \param[in] frameSize The I/O block size which is the number of samples per channel. 420 * \param[in,out] nChannels Pointer to buffer that holds the number of input channels and 421 * where the amount of output channels is written 422 *to. 423 * \param[in] fInterleaved Input and output samples are processed interleaved. 424 * \param[in,out] channelType Array were the corresponding channel type for each output audio 425 * channel is stored into. 426 * \param[in,out] channelIndices Array were the corresponding channel type index for each output 427 * audio channel is stored into. 428 * \param[in] mapDescr Pointer to a FDK channel mapping descriptor that contains the 429 * channel mapping to be used. 430 * \param[out] pDmxOutScale Pointer on a field receiving the scale factor that has to be 431 * applied on all samples afterwards. If the 432 *handed pointer is NULL the final scaling is done internally. 433 * @returns Returns an error code of type ::PCMDMX_ERROR. 434 **/ 435 PCMDMX_ERROR pcmDmx_ApplyFrame(HANDLE_PCM_DOWNMIX self, DMX_PCM *pPcmBuf, 436 const int pcmBufSize, UINT frameSize, 437 INT *nChannels, INT fInterleaved, 438 AUDIO_CHANNEL_TYPE channelType[], 439 UCHAR channelIndices[], 440 const FDK_channelMapDescr *const mapDescr, 441 INT *pDmxOutScale); 442 443 /** Close an instance of the PCM downmix module. 444 * @param[in,out] pSelf Pointer to a buffer containing the handle of the 445 *instance. 446 * @returns Returns an error code of type ::PCMDMX_ERROR. 447 **/ 448 PCMDMX_ERROR pcmDmx_Close(HANDLE_PCM_DOWNMIX *pSelf); 449 450 /** Get library info for this module. 451 * @param[out] info Pointer to an allocated LIB_INFO structure. 452 * @returns Returns an error code of type ::PCMDMX_ERROR. 453 */ 454 PCMDMX_ERROR pcmDmx_GetLibInfo(LIB_INFO *info); 455 456 #ifdef __cplusplus 457 } 458 #endif 459 460 #endif /* PCMDMX_LIB_H */ 461