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 encoder library ************************* 96 97 Author(s): Max Neuendorf 98 99 Description: Encoder Library Interface 100 Encoder API 101 102 *******************************************************************************/ 103 104 /**************************************************************************/ /** 105 \file 106 ******************************************************************************/ 107 108 #ifndef SACENC_LIB_H 109 #define SACENC_LIB_H 110 111 /* Includes ******************************************************************/ 112 #include "machine_type.h" 113 #include "FDK_audio.h" 114 115 #ifdef __cplusplus 116 extern "C" { 117 #endif 118 /* Defines *******************************************************************/ 119 120 /* Data Types ****************************************************************/ 121 122 /** 123 * Space encoder error codes. 124 */ 125 typedef enum { 126 SACENC_OK = 0x00000000, /*!< No error happened. All fine. */ 127 SACENC_INVALID_HANDLE = 128 0x00000080, /*!< Handle passed to function call was invalid. */ 129 SACENC_MEMORY_ERROR = 0x00000800, /*!< Memory allocation failed. */ 130 SACENC_INIT_ERROR = 0x00008000, /*!< General initialization error. */ 131 SACENC_ENCODE_ERROR = 132 0x00080000, /*!< The encoding process was interrupted by an unexpected 133 error. */ 134 SACENC_PARAM_ERROR = 0x00800000, /*!< Invalid runtime parameter. */ 135 SACENC_UNSUPPORTED_PARAMETER = 0x00800001, /*!< Parameter not available. */ 136 SACENC_INVALID_CONFIG = 0x00800002, /*!< Configuration not provided. */ 137 SACENC_UNKNOWN_ERROR = 0x08000000 /*!< Unknown error. */ 138 139 } FDK_SACENC_ERROR; 140 141 typedef enum { 142 SACENC_INVALID_MODE = 0, 143 SACENC_212 = 8, 144 SACENC_ESCAPE = 15 145 146 } MP4SPACEENC_MODE; 147 148 typedef enum { 149 SACENC_BANDS_INVALID = 0, 150 SACENC_BANDS_4 = 4, 151 SACENC_BANDS_5 = 5, 152 SACENC_BANDS_7 = 7, 153 SACENC_BANDS_9 = 9, 154 SACENC_BANDS_12 = 12, 155 SACENC_BANDS_15 = 15, 156 SACENC_BANDS_23 = 23 157 158 } MP4SPACEENC_BANDS_CONFIG; 159 160 typedef enum { 161 SACENC_QUANTMODE_INVALID = -1, 162 SACENC_QUANTMODE_FINE = 0, 163 SACENC_QUANTMODE_EBQ1 = 1, 164 SACENC_QUANTMODE_EBQ2 = 2, 165 SACENC_QUANTMODE_RSVD3 = 3 166 167 } MP4SPACEENC_QUANTMODE; 168 169 typedef enum { 170 SACENC_DMXGAIN_INVALID = -1, 171 SACENC_DMXGAIN_0_dB = 0, 172 SACENC_DMXGAIN_1_5_dB = 1, 173 SACENC_DMXGAIN_3_dB = 2, 174 SACENC_DMXGAIN_4_5_dB = 3, 175 SACENC_DMXGAIN_6_dB = 4, 176 SACENC_DMXGAIN_7_5_dB = 5, 177 SACENC_DMXGAIN_9_dB = 6, 178 SACENC_DMXGAIN_12_dB = 7 179 180 } MP4SPACEENC_DMX_GAIN; 181 182 /** 183 * \brief Space Encoder setting parameters. 184 * 185 * Use FDK_sacenc_setParam() function to configure the internal status of the 186 * following parameters. 187 */ 188 typedef enum { 189 SACENC_LOWDELAY, /*!< Configure lowdelay MPEG Surround. 190 - 0: Disable Lowdelay. (default) 191 - 1: Enable Lowdelay. 192 - 2: Enable Lowdelay including keep frame. */ 193 194 SACENC_ENC_MODE, /*!< Configure encoder tree mode. See ::MP4SPACEENC_MODE for 195 available values. */ 196 197 SACENC_SAMPLERATE, /*!< Configure encoder sampling rate. */ 198 199 SACENC_FRAME_TIME_SLOTS, /*!< Configure number of slots per spatial frame. */ 200 201 SACENC_PARAM_BANDS, /*!< Configure number of parameter bands. See 202 ::MP4SPACEENC_BANDS_CONFIG for available values. */ 203 204 SACENC_TIME_DOM_DMX, /*!< Configure time domain downmix. 205 - 0: No time domain downmix. (default) 206 - 1: Static time domain downmix. 207 - 2: Enhanced time domain downmix, stereo to mono 208 only. */ 209 210 SACENC_DMX_GAIN, /*!< Configure downmix gain. See ::MP4SPACEENC_DMX_GAIN for 211 available values. */ 212 213 SACENC_COARSE_QUANT, /*!< Use coarse parameter quantization. 214 - 0: No (default) 215 - 1: Yes */ 216 217 SACENC_QUANT_MODE, /*!< Configure quanitzation mode. See 218 ::MP4SPACEENC_QUANTMODE for available values. */ 219 220 SACENC_TIME_ALIGNMENT, /*!< Configure time alignment in samples. */ 221 222 SACENC_INDEPENDENCY_COUNT, /*!< Configure the independency count. (count == 0 223 means independencyFlag == 1) */ 224 225 SACENC_INDEPENDENCY_FACTOR, /*!< How often should we set the independency flag 226 */ 227 228 SACENC_NONE /*!< ------ */ 229 230 } SPACEENC_PARAM; 231 232 /** 233 * Describes Spatial Specific Config. 234 */ 235 typedef struct { 236 INT nSscSizeBits; /*!< Number of valid bits in pSsc buffer. */ 237 UCHAR *pSsc; /*!< SpatialSpecificConfig buffer in binary format. */ 238 239 } MPEG4SPACEENC_SSCBUF; 240 241 /** 242 * Provides some info about the encoder configuration. 243 */ 244 typedef struct { 245 INT nSampleRate; /*!< Configured sampling rate.*/ 246 INT nSamplesFrame; /*!< Frame length in samples. */ 247 INT nTotalInputChannels; /*!< Number of expected audio input channels. */ 248 INT nDmxDelay; /*!< Delay of the downmixed signal. */ 249 INT nCodecDelay; /*!< Delay of the whole en-/decoded signal, including 250 core-coder delay. */ 251 INT nDecoderDelay; /*!< Delay added by the MP4SPACE decoder. */ 252 INT nPayloadDelay; /*!< Delay of the payload. */ 253 INT nDiscardOutFrames; /*!< Number of dmx frames to discard for alignment with 254 bitstream. */ 255 256 MPEG4SPACEENC_SSCBUF 257 *pSscBuf; /*!< Pointer to Spatial Specific Config structure. */ 258 259 } MP4SPACEENC_INFO; 260 261 /** 262 * MPEG Surround encoder handle. 263 */ 264 typedef struct MP4SPACE_ENCODER *HANDLE_MP4SPACE_ENCODER; 265 266 /** 267 * Defines the input arguments for a FDK_sacenc_encode() call. 268 */ 269 typedef struct { 270 INT nInputSamples; /*!< Number of valid input audio samples (multiple of input 271 channels). */ 272 UINT inputBufferSizePerChannel; /*!< Size of input buffer (input audio 273 samples) per channel. */ 274 UINT isInputInterleaved; /*!< Indicates if input audio samples are represented 275 in blocks or interleaved: 276 - 0 : in blocks. 277 - 1 : interleaved. */ 278 279 } SACENC_InArgs; 280 281 /** 282 * Defines the output arguments for a FDK_sacenc_encode() call. 283 */ 284 typedef struct { 285 INT nOutputBits; /*!< Number of valid payload bits generated during 286 FDK_sacenc_encode(). */ 287 INT nOutputSamples; /*!< Number of valid output audio samples generated during 288 FDK_sacenc_encode(). */ 289 UINT nSamplesConsumed; /*!< Number of input audio samples consumed in 290 FDK_sacenc_encode(). */ 291 292 } SACENC_OutArgs; 293 294 /* Constants *****************************************************************/ 295 296 /* Function / Class Declarations *********************************************/ 297 298 /** 299 * \brief Opens a new instace of the MPEG Surround encoder. 300 * 301 * \param phMp4SpaceEnc Pointer to the encoder handle to be deallocated. 302 * 303 * \return 304 * - SACENC_OK, on success. 305 * - SACENC_INVALID_HANDLE, SACENC_MEMORY_ERROR, on failure. 306 */ 307 FDK_SACENC_ERROR FDK_sacenc_open(HANDLE_MP4SPACE_ENCODER *phMp4SpaceEnc); 308 309 /** 310 * \brief Finalizes opening process of MPEG Surround encoder. 311 * 312 * Shows, how many samples are needed as input 313 * 314 * \param hMp4SpaceEnc A valid MPEG Surround encoder handle. 315 * \param dmxDelay Downmix delay. 316 * 317 * \return 318 * - SACENC_OK, on success. 319 * - SACENC_INVALID_HANDLE, SACENC_INIT_ERROR, SACENC_INVALID_CONFIG, 320 * on failure. 321 */ 322 FDK_SACENC_ERROR FDK_sacenc_init(HANDLE_MP4SPACE_ENCODER hMp4SpaceEnc, 323 const INT dmxDelay); 324 325 /** 326 * \brief Close the MPEG Surround encoder instance. 327 * 328 * Deallocate encoder instance and free whole memory. 329 * 330 * \param phMp4SpaceEnc Pointer to the encoder handle to be deallocated. 331 * 332 * \return 333 * - SACENC_OK, on success. 334 * - SACENC_INVALID_HANDLE, on failure. 335 */ 336 FDK_SACENC_ERROR FDK_sacenc_close(HANDLE_MP4SPACE_ENCODER *phMp4SpaceEnc); 337 338 /** 339 * \brief MPEG surround parameter extraction, framwise. 340 * 341 * \param hMp4SpaceEnc A valid MPEG Surround encoder handle. 342 * 343 * \return 344 * - SACENC_OK, on success. 345 * - SACENC_INVALID_HANDLE, on failure. 346 */ 347 FDK_SACENC_ERROR FDK_sacenc_encode(const HANDLE_MP4SPACE_ENCODER hMp4SpaceEnc, 348 const FDK_bufDescr *inBufDesc, 349 const FDK_bufDescr *outBufDesc, 350 const SACENC_InArgs *inargs, 351 SACENC_OutArgs *outargs); 352 353 /** 354 * \brief Provides information on produced bitstream. 355 * 356 * \param hMp4SpaceEnc A valid MPEG Surround encoder handle. 357 * \param pInfo Pointer to an encoder info struct, filled on 358 * return. 359 * 360 * \return 361 * - SACENC_OK, on success. 362 * - SACENC_INVALID_HANDLE, on failure. 363 */ 364 FDK_SACENC_ERROR FDK_sacenc_getInfo(const HANDLE_MP4SPACE_ENCODER hMp4SpaceEnc, 365 MP4SPACEENC_INFO *const pInfo); 366 367 /** 368 * \brief Set one single MPEG Surround encoder parameter. 369 * 370 * This function allows configuration of all encoder parameters specified in 371 * ::SPACEENC_PARAM. Each parameter must be set with a separate function call. 372 * An internal validation of the configuration value range will be done. 373 * 374 * \param hMp4SpaceEnc A valid MPEG Surround encoder handle. 375 * \param param Parameter to be set. See ::SPACEENC_PARAM. 376 * \param value Parameter value. See parameter description in 377 * ::SPACEENC_PARAM. 378 * 379 * \return 380 * - SACENC_OK, on success. 381 * - SACENC_INVALID_HANDLE, SACENC_UNSUPPORTED_PARAMETER, 382 * SACENC_INVALID_CONFIG, on failure. 383 */ 384 FDK_SACENC_ERROR FDK_sacenc_setParam(HANDLE_MP4SPACE_ENCODER hMp4SpaceEnc, 385 const SPACEENC_PARAM param, 386 const UINT value); 387 388 /** 389 * \brief Get information about MPEG Surround encoder library build. 390 * 391 * Fill a given LIB_INFO structure with library version information. 392 * 393 * \param info Pointer to an allocated LIB_INFO struct. 394 * 395 * \return 396 * - SACENC_OK, on success. 397 * - SACENC_INVALID_HANDLE, SACENC_INIT_ERROR, on failure. 398 */ 399 FDK_SACENC_ERROR FDK_sacenc_getLibInfo(LIB_INFO *info); 400 401 #ifdef __cplusplus 402 } 403 #endif 404 405 #endif /* SACENC_LIB_H */ 406