1 2/* ----------------------------------------------------------------------------------------------------------- 3Software License for The Fraunhofer FDK AAC Codec Library for Android 4 5� Copyright 1995 - 2013 Fraunhofer-Gesellschaft zur F�rderung der angewandten Forschung e.V. 6 All rights reserved. 7 8 1. INTRODUCTION 9The Fraunhofer FDK AAC Codec Library for Android ("FDK AAC Codec") is software that implements 10the MPEG Advanced Audio Coding ("AAC") encoding and decoding scheme for digital audio. 11This FDK AAC Codec software is intended to be used on a wide variety of Android devices. 12 13AAC's HE-AAC and HE-AAC v2 versions are regarded as today's most efficient general perceptual 14audio codecs. AAC-ELD is considered the best-performing full-bandwidth communications codec by 15independent studies and is widely deployed. AAC has been standardized by ISO and IEC as part 16of the MPEG specifications. 17 18Patent licenses for necessary patent claims for the FDK AAC Codec (including those of Fraunhofer) 19may be obtained through Via Licensing (www.vialicensing.com) or through the respective patent owners 20individually for the purpose of encoding or decoding bit streams in products that are compliant with 21the ISO/IEC MPEG audio standards. Please note that most manufacturers of Android devices already license 22these patent claims through Via Licensing or directly from the patent owners, and therefore FDK AAC Codec 23software may already be covered under those patent licenses when it is used for those licensed purposes only. 24 25Commercially-licensed AAC software libraries, including floating-point versions with enhanced sound quality, 26are also available from Fraunhofer. Users are encouraged to check the Fraunhofer website for additional 27applications information and documentation. 28 292. COPYRIGHT LICENSE 30 31Redistribution and use in source and binary forms, with or without modification, are permitted without 32payment of copyright license fees provided that you satisfy the following conditions: 33 34You must retain the complete text of this software license in redistributions of the FDK AAC Codec or 35your modifications thereto in source code form. 36 37You must retain the complete text of this software license in the documentation and/or other materials 38provided with redistributions of the FDK AAC Codec or your modifications thereto in binary form. 39You must make available free of charge copies of the complete source code of the FDK AAC Codec and your 40modifications thereto to recipients of copies in binary form. 41 42The name of Fraunhofer may not be used to endorse or promote products derived from this library without 43prior written permission. 44 45You may not charge copyright license fees for anyone to use, copy or distribute the FDK AAC Codec 46software or your modifications thereto. 47 48Your modified versions of the FDK AAC Codec must carry prominent notices stating that you changed the software 49and 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 533. NO PATENT LICENSE 54 55NO EXPRESS OR IMPLIED LICENSES TO ANY PATENT CLAIMS, including without limitation the patents of Fraunhofer, 56ARE GRANTED BY THIS SOFTWARE LICENSE. Fraunhofer provides no warranty of patent non-infringement with 57respect to this software. 58 59You may use this FDK AAC Codec software or modifications thereto only for purposes that are authorized 60by appropriate patent licenses. 61 624. DISCLAIMER 63 64This 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 66of merchantability and fitness for a particular purpose. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 67CONTRIBUTORS BE LIABLE for any direct, indirect, incidental, special, exemplary, or consequential damages, 68including but not limited to procurement of substitute goods or services; loss of use, data, or profits, 69or business interruption, however caused and on any theory of liability, whether in contract, strict 70liability, or tort (including negligence), arising in any way out of the use of this software, even if 71advised of the possibility of such damage. 72 735. CONTACT INFORMATION 74 75Fraunhofer Institute for Integrated Circuits IIS 76Attention: Audio and Multimedia Departments - FDK AAC LL 77Am Wolfsmantel 33 7891058 Erlangen, Germany 79 80www.iis.fraunhofer.de/amm 81amm-info@iis.fraunhofer.de 82----------------------------------------------------------------------------------------------------------- */ 83 84/************************ FDK PCM up/downmixing module ********************* 85 86 Author(s): Christian Griebel 87 Description: Declares functions to interface with the PCM downmix processing 88 module. 89 90*******************************************************************************/ 91 92#ifndef _PCMUTILS_LIB_H_ 93#define _PCMUTILS_LIB_H_ 94 95#include "machine_type.h" 96#include "common_fix.h" 97#include "FDK_audio.h" 98#include "FDK_bitstream.h" 99 100 101/* ------------------------ * 102 * ERROR CODES: * 103 * ------------------------ */ 104typedef enum 105{ 106 PCMDMX_OK = 0x0, /*!< No error happened. */ 107 108 pcm_dmx_fatal_error_start, 109 PCMDMX_OUT_OF_MEMORY = 0x2, /*!< Not enough memory to set up an instance of the module. */ 110 PCMDMX_UNKNOWN = 0x5, /*!< Error condition is of unknown reason, or from a third 111 party module. */ 112 pcm_dmx_fatal_error_end, 113 114 PCMDMX_INVALID_HANDLE, /*!< The given instance handle is not valid. */ 115 PCMDMX_INVALID_ARGUMENT, /*!< One of the parameters handed over is invalid. */ 116 PCMDMX_INVALID_CH_CONFIG, /*!< The given channel configuration is not supported and thus 117 no processing was performed. */ 118 PCMDMX_INVALID_MODE, /*!< The set configuration/mode is not applicable. */ 119 PCMDMX_UNKNOWN_PARAM, /*!< The handed parameter is not known/supported. */ 120 PCMDMX_UNABLE_TO_SET_PARAM, /*!< Unable to set the specific parameter. Most probably the 121 value ist out of range. */ 122 PCMDMX_CORRUPT_ANC_DATA /*!< The read ancillary data was corrupt. */ 123 124} PCMDMX_ERROR; 125 126/** Macro to identify fatal errors. */ 127#define PCMDMX_IS_FATAL_ERROR(err) ( (((err)>=pcm_dmx_fatal_error_start) && ((err)<=pcm_dmx_fatal_error_end)) ? 1 : 0) 128 129/* ------------------------ * 130 * RUNTIME PARAMS: * 131 * ------------------------ */ 132typedef enum 133{ 134 DMX_BS_DATA_EXPIRY_FRAME, /*!< The number of frames without new metadata that have to go 135 by before the bitstream data expires. The value 0 disables 136 expiry. */ 137 DMX_BS_DATA_DELAY, /*!< The number of delay frames of the output samples compared 138 to the bitstream data. */ 139 MIN_NUMBER_OF_OUTPUT_CHANNELS, /*!< The minimum number of output channels. For all input 140 configurations that have less than the given channels the 141 module will modify the output automatically to obtain the 142 given number of output channels. Mono signals will be 143 duplicated. If more than two output channels are desired 144 the module just adds empty channels. The parameter value 145 must be either -1, 0, 1, 2, 6 or 8. If the value is 146 greater than zero and exceeds the value of parameter 147 MAX_NUMBER_OF_OUTPUT_CHANNELS the latter will be set to 148 the same value. Both values -1 and 0 disable the feature. */ 149 MAX_NUMBER_OF_OUTPUT_CHANNELS, /*!< The maximum number of output channels. For all input 150 configurations that have more than the given channels the 151 module will apply a mixdown automatically to obtain the 152 given number of output channels. The value must be either 153 -1, 0, 1, 2, 6 or 8. If it is greater than zero and lower 154 or equal than the value of MIN_NUMBER_OF_OUTPUT_CHANNELS 155 parameter the latter will be set to the same value. 156 The values -1 and 0 disable the feature. */ 157 DMX_DUAL_CHANNEL_MODE, /*!< Downmix mode for two channel audio data. */ 158 DMX_PSEUDO_SURROUND_MODE /*!< Defines how module handles pseudo surround compatible 159 signals. See PSEUDO_SURROUND_MODE type for details. */ 160} PCMDMX_PARAM; 161 162/* Parameter value types */ 163typedef enum 164{ 165 NEVER_DO_PS_DMX = -1, /*!< Never create a pseudo surround compatible downmix. */ 166 AUTO_PS_DMX = 0, /*!< Create a pseudo surround compatible downmix only if 167 signalled in bitstreams meta data. (Default) */ 168 FORCE_PS_DMX = 1 /*!< Always create a pseudo surround compatible downmix. 169 CAUTION: This can lead to excessive signal cancellations 170 and signal level differences for non-compatible signals. */ 171} PSEUDO_SURROUND_MODE; 172 173typedef enum 174{ 175 STEREO_MODE = 0x0, /*!< Leave stereo signals as they are. */ 176 CH1_MODE = 0x1, /*!< Create a dual mono output signal from channel 1. */ 177 CH2_MODE = 0x2, /*!< Create a dual mono output signal from channel 2. */ 178 MIXED_MODE = 0x3 /*!< Create a dual mono output signal by mixing the two 179 channels. */ 180} DUAL_CHANNEL_MODE; 181 182 183/* ------------------------ * 184 * MODULES INTERFACE: * 185 * ------------------------ */ 186typedef struct PCM_DMX_INSTANCE *HANDLE_PCM_DOWNMIX; 187 188/* Modules reset flags */ 189#define PCMDMX_RESET_PARAMS ( 1 ) 190#define PCMDMX_RESET_BS_DATA ( 2 ) 191#define PCMDMX_RESET_FULL ( PCMDMX_RESET_PARAMS | PCMDMX_RESET_BS_DATA ) 192 193#ifdef __cplusplus 194extern "C" 195{ 196#endif 197 198/** Open and initialize an instance of the PCM downmix module 199 * @param [out] Pointer to a buffer receiving the handle of the new instance. 200 * @returns Returns an error code. 201 **/ 202PCMDMX_ERROR pcmDmx_Open ( 203 HANDLE_PCM_DOWNMIX *pSelf 204 ); 205 206/** Set one parameter for one instance of the PCM downmix module. 207 * @param [in] Handle of PCM downmix instance. 208 * @param [in] Parameter to be set. 209 * @param [in] Parameter value. 210 * @returns Returns an error code. 211 **/ 212PCMDMX_ERROR pcmDmx_SetParam ( 213 HANDLE_PCM_DOWNMIX self, 214 const PCMDMX_PARAM param, 215 const INT value 216 ); 217 218/** Get one parameter value of one PCM downmix module instance. 219 * @param [in] Handle of PCM downmix module instance. 220 * @param [in] Parameter to be set. 221 * @param [out] Pointer to buffer receiving the parameter value. 222 * @returns Returns an error code. 223 **/ 224PCMDMX_ERROR pcmDmx_GetParam ( 225 HANDLE_PCM_DOWNMIX self, 226 const PCMDMX_PARAM param, 227 INT * const pValue 228 ); 229 230/** Read downmix meta-data directly from a given bitstream. 231 * @param [in] Handle of PCM downmix instance. 232 * @param [in] Handle of FDK bitstream buffer. 233 * @param [in] Length of ancillary data in bits. 234 * @param [in] Flag indicating wheter the ancillary data is from a MPEG-1/2 or an MPEG-4 stream. 235 * @returns Returns an error code. 236 **/ 237PCMDMX_ERROR pcmDmx_Parse ( 238 HANDLE_PCM_DOWNMIX self, 239 HANDLE_FDK_BITSTREAM hBitStream, 240 UINT ancDataBits, 241 int isMpeg2 242 ); 243 244/** Read downmix meta-data from a given data buffer. 245 * @param [in] Handle of PCM downmix instance. 246 * @param [in] Pointer to ancillary data buffer. 247 * @param [in] Size of ancillary data in bytes. 248 * @param [in] Flag indicating wheter the ancillary data is from a MPEG-1/2 or an MPEG-4 stream. 249 * @returns Returns an error code. 250 **/ 251PCMDMX_ERROR pcmDmx_ReadDvbAncData ( 252 HANDLE_PCM_DOWNMIX self, 253 UCHAR *pAncDataBuf, 254 UINT ancDataBytes, 255 int isMpeg2 256 ); 257 258/** Set the matrix mixdown information extracted from the PCE of an AAC bitstream. 259 * @param [in] Handle of PCM downmix instance. 260 * @param [in] Matrix mixdown index present flag extracted from PCE. 261 * @param [in] The 2 bit matrix mixdown index extracted from PCE. 262 * @param [in] The pseudo surround enable flag extracted from PCE. 263 * @returns Returns an error code. 264 **/ 265PCMDMX_ERROR pcmDmx_SetMatrixMixdownFromPce ( 266 HANDLE_PCM_DOWNMIX self, 267 int matrixMixdownPresent, 268 int matrixMixdownIdx, 269 int pseudoSurroundEnable 270 ); 271 272/** Reset the module. 273 * @param [in] Handle of PCM downmix instance. 274 * @param [in] Flags telling which parts of the module shall be reset. 275 * @returns Returns an error code. 276 **/ 277PCMDMX_ERROR pcmDmx_Reset ( 278 HANDLE_PCM_DOWNMIX self, 279 UINT flags 280 ); 281 282/** Create a mixdown, bypass or extend the output signal depending on the modules settings and the 283 * respective given input configuration. 284 * 285 * \param [in] Handle of PCM downmix module instance. 286 * \param [inout] Pointer to time buffer with decoded PCM samples. 287 * \param [in] The I/O block size which is the number of samples per channel. 288 * \param [inout] Pointer to buffer that holds the number of input channels and where the 289 * amount of output channels is written to. 290 * \param [in] Flag which indicates if output time data is writtern interleaved or as 291 * subsequent blocks. 292 * \param [inout] Array were the corresponding channel type for each output audio channel is 293 * stored into. 294 * \param [inout] Array were the corresponding channel type index for each output audio channel 295 * is stored into. 296 * \param [in] Array containing the output channel mapping to be used (from MPEG PCE ordering 297 * to whatever is required). 298 * \param [out] Pointer on a field receiving the scale factor that has to be applied on all 299 * samples afterwards. If the handed pointer is NULL the final scaling is done 300 * internally. 301 * @returns Returns an error code. 302 **/ 303PCMDMX_ERROR pcmDmx_ApplyFrame ( 304 HANDLE_PCM_DOWNMIX self, 305 INT_PCM *pPcmBuf, 306 UINT frameSize, 307 INT *nChannels, 308 int fInterleaved, 309 AUDIO_CHANNEL_TYPE channelType[], 310 UCHAR channelIndices[], 311 const UCHAR channelMapping[][8], 312 INT *pDmxOutScale 313 ); 314 315/** Close an instance of the PCM downmix module. 316 * @param [inout] Pointer to a buffer containing the handle of the instance. 317 * @returns Returns an error code. 318 **/ 319PCMDMX_ERROR pcmDmx_Close ( 320 HANDLE_PCM_DOWNMIX *pSelf 321 ); 322 323/** Get library info for this module. 324 * @param [out] Pointer to an allocated LIB_INFO structure. 325 * @returns Returns an error code. 326 */ 327PCMDMX_ERROR pcmDmx_GetLibInfo( LIB_INFO *info ); 328 329 330#ifdef __cplusplus 331} 332#endif 333 334#endif /* _PCMUTILS_LIB_H_ */ 335