1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 /* 19 20 Name: PVMP4AudioDecoder_API.h 21 22 ------------------------------------------------------------------------------ 23 REVISION HISTORY 24 25 Description: Change buffer type to UChar 26 27 Description: Update comments 28 29 Description: Updated a comment that MT did not get around to 30 before the end of his contract. 31 32 Description: add a new API to decode audioSpecificConfig separately, the same 33 change has been made on 32-bits version (element \main\2) 34 35 Description: add a new API to reset history buffer, the same change has been 36 made on a 32-bits version(element \nd.e0352.wjin\1) 37 38 Who: Date: 39 Description: 40 41 ------------------------------------------------------------------------------ 42 INCLUDE DESCRIPTION 43 44 Main header file for the Packet Video MP4/AAC audio decoder library. The 45 constants, structures, and functions defined within this file, along with 46 a basic data types header file, is all that is needed to use and communicate 47 with the library. The internal data structures within the library are 48 purposely hidden. 49 50 ---* Need description of the input buffering. *------- 51 52 ---* Need an example of calling the library here *---- 53 54 ------------------------------------------------------------------------------ 55 REFERENCES 56 57 (Normally header files do not have a reference section) 58 59 ISO/EIC 14496-3:(1999) Document titled 60 ------------------------------------------------------------------------------ 61 */ 62 63 /*---------------------------------------------------------------------------- 64 ; CONTINUE ONLY IF NOT ALREADY DEFINED 65 ----------------------------------------------------------------------------*/ 66 #ifndef PVMP4AUDIODECODER_API_H 67 #define PVMP4AUDIODECODER_API_H 68 69 #include "pv_audio_type_defs.h" /* Basic data types used within the lib */ 70 71 #include "e_tmp4audioobjecttype.h" 72 73 /*---------------------------------------------------------------------------- 74 ; INCLUDES 75 ----------------------------------------------------------------------------*/ 76 #ifdef __cplusplus 77 extern "C" 78 { 79 #endif 80 81 /*---------------------------------------------------------------------------- 82 ; MACROS 83 ; Define module specific macros here 84 ----------------------------------------------------------------------------*/ 85 86 /*---------------------------------------------------------------------------- 87 ; DEFINES 88 ; Include all pre-processor statements here. 89 ----------------------------------------------------------------------------*/ 90 91 /* 92 * This constant is the guaranteed-to-work buffer size, specified in bytes, 93 * for the input buffer for 2 audio channels to decode one frame of data, 94 * as specified by the MPEG-2 or MPEG-4 standard. 95 * The standard, and this constant, do not take into account that lower 96 * bitrates will use less data per frame. Note that the number of bits 97 * used per frame is variable, and only that the average value will be the 98 * bit rate specified during encoding. The standard does not specify 99 * over how many frames the average must be maintained. 100 * 101 * The constant value is 6144 * 2 channels / 8 bits per byte 102 */ 103 104 105 #define PVMP4AUDIODECODER_INBUFSIZE 1536 106 107 /*---------------------------------------------------------------------------- 108 ; EXTERNAL VARIABLES REFERENCES 109 ; Declare variables used in this module but defined elsewhere 110 ----------------------------------------------------------------------------*/ 111 112 /*---------------------------------------------------------------------------- 113 ; SIMPLE TYPEDEF'S 114 ----------------------------------------------------------------------------*/ 115 116 /*---------------------------------------------------------------------------- 117 ; ENUMERATED TYPEDEF'S 118 ----------------------------------------------------------------------------*/ 119 /* 120 * This enumeration is used for the structure element outputFormat. It 121 * specifies how the output data is to be formatted. Presently only 16-bit 122 * PCM data is supported, and this enum informs how the single output 123 * buffer should be for two-channel stereo data. 124 * Grouped format stores all the left channel values, then right: 125 * "LLLL...LLRRRR...RR" 126 * Interleave format store left, then right audio samples: 127 * "LRLRLRLR...." 128 */ 129 typedef enum ePVMP4AudioDecoderOutputFormat 130 { 131 OUTPUTFORMAT_16PCM_GROUPED = 0, 132 OUTPUTFORMAT_16PCM_INTERLEAVED = 1 133 134 } tPVMP4AudioDecoderOutputFormat; 135 136 /* 137 * This enumeration holds the possible return values for the main decoder 138 * function, PVMP4AudioDecodeFrame. The plan was to easily distinguish 139 * whether an error was recoverable (streaming mode) or not. Presently no 140 * errors are recoverable, which is a result of not supporting ADTS in 141 * this release. 142 */ 143 typedef enum ePVMP4AudioDecoderErrorCode 144 { 145 MP4AUDEC_SUCCESS = 0, 146 MP4AUDEC_INVALID_FRAME = 10, 147 MP4AUDEC_INCOMPLETE_FRAME = 20, 148 MP4AUDEC_LOST_FRAME_SYNC = 30 /* Cannot happen since no ADTS */ 149 } tPVMP4AudioDecoderErrorCode; 150 151 152 /* 153 * This enumeration holds the possible return values for stream type 154 * being decoded 155 */ 156 typedef enum 157 { 158 AAC = 0, 159 AACPLUS, 160 ENH_AACPLUS 161 } STREAMTYPE; 162 163 /*---------------------------------------------------------------------------- 164 ; STRUCTURES TYPEDEF'S 165 ----------------------------------------------------------------------------*/ 166 /* 167 * This structure is used to communicate information in to and out of the 168 * AAC decoder. 169 */ 170 171 typedef struct 172 #ifdef __cplusplus 173 tPVMP4AudioDecoderExternal // To allow forward declaration of this struct in C++ 174 #endif 175 { 176 /* 177 * INPUT: 178 * Pointer to the input buffer that contains the encoded bistream data. 179 * The data is filled in such that the first bit transmitted is 180 * the most-significant bit (MSB) of the first array element. 181 * The buffer is accessed in a linear fashion for speed, and the number of 182 * bytes consumed varies frame to frame. 183 * The calling environment can change what is pointed to between calls to 184 * the decode function, library, as long as the inputBufferCurrentLength, 185 * and inputBufferUsedLength are updated too. Also, any remaining bits in 186 * the old buffer must be put at the beginning of the new buffer. 187 */ 188 UChar *pInputBuffer; 189 190 /* 191 * INPUT: 192 * Number of valid bytes in the input buffer, set by the calling 193 * function. After decoding the bitstream the library checks to 194 * see if it when past this value; it would be to prohibitive to 195 * check after every read operation. This value is not modified by 196 * the AAC library. 197 */ 198 Int inputBufferCurrentLength; 199 200 /* 201 * INPUT: 202 * The actual size of the buffer. 203 * This variable is not used by the library, but is used by the 204 * console test application. This parameter could be deleted 205 * if this value was passed into these function. The helper functions are 206 * not part of the library and are not used by the Common Audio Decoder 207 * Interface. 208 */ 209 Int inputBufferMaxLength; 210 211 /* 212 * INPUT: 213 * Enumerated value the output is to be interleaved left-right-left-right. 214 * For further information look at the comments for the enumeration. 215 */ 216 tPVMP4AudioDecoderOutputFormat outputFormat; 217 218 /* 219 * INPUT: (but what is pointed to is an output) 220 * Pointer to the output buffer to hold the 16-bit PCM audio samples. 221 * If the output is stereo, both left and right channels will be stored 222 * in this one buffer. Presently it must be of length of 2048 points. 223 * The format of the buffer is set by the parameter outputFormat. 224 */ 225 Int16 *pOutputBuffer; 226 227 /* 228 * INPUT: (but what is pointed to is an output) 229 * Pointer to the output buffer to hold the 16-bit PCM AAC-plus audio samples. 230 * If the output is stereo, both left and right channels will be stored 231 * in this one buffer. Presently it must be of length of 2048 points. 232 * The format of the buffer is set by the parameter outputFormat. 233 */ 234 Int16 *pOutputBuffer_plus; /* Used in AAC+ and enhanced AAC+ */ 235 236 /* 237 * INPUT: 238 * AAC Plus Upsampling Factor. Normally set to 2 when Spectrum Band 239 * Replication (SBR) is used 240 */ 241 Int32 aacPlusUpsamplingFactor; /* Used in AAC+ and enhanced AAC+ */ 242 243 /* 244 * INPUT: 245 * AAC Plus enabler. Deafaults to be ON, unless run time conditions 246 * require the SBR and PS tools disabled 247 */ 248 bool aacPlusEnabled; 249 /* 250 * INPUT: 251 * (Currently not being used inside the AAC library.) 252 * This flag is set to TRUE when the playback position has been changed, 253 * for example, rewind or fast forward. This informs the AAC library to 254 * take an appropriate action, which has yet to be determined. 255 */ 256 Bool repositionFlag; 257 258 /* 259 * INPUT: 260 * Number of requested output audio channels. This relieves the calling 261 * environment from having to perform stereo-to-mono or mono-to-stereo 262 * conversions. 263 */ 264 Int desiredChannels; 265 266 /* 267 * INPUT/OUTPUT: 268 * Number of elements used by the library, initially set to zero by 269 * the function PVMP4AudioDecoderInitLibrary, and modified by each 270 * call to PVMP4AudioDecodeFrame. 271 */ 272 Int inputBufferUsedLength; 273 274 /* 275 * INPUT/OUTPUT: 276 * Number of bits left over in the next buffer element, 277 * This value will always be zero, unless support for ADTS is added. 278 */ 279 Int32 remainderBits; 280 281 /* 282 * OUTPUT: 283 * The sampling rate decoded from the bitstream, in units of 284 * samples/second. For this release of the library this value does 285 * not change from frame to frame, but future versions will. 286 */ 287 Int32 samplingRate; 288 289 /* 290 * OUTPUT: 291 * This value is the bitrate in units of bits/second. IT 292 * is calculated using the number of bits consumed for the current frame, 293 * and then multiplying by the sampling_rate, divided by points in a frame. 294 * This value can changes frame to frame. 295 */ 296 Int32 bitRate; 297 298 /* 299 * OUTPUT: 300 * The number of channels decoded from the bitstream. The output data 301 * will have be the amount specified in the variable desiredChannels, 302 * this output is informative only, and can be ignored. 303 */ 304 Int encodedChannels; 305 306 /* 307 * OUTPUT: 308 * This value is the number of output PCM samples per channel. 309 * It is presently hard-coded to 1024, but may change in the future. 310 * It will not change frame to frame, and would take on 311 * one of these four values: 1024, 960, 512, or 480. If an error occurs 312 * do not rely on this value. 313 */ 314 Int frameLength; 315 316 /* 317 * This value is audio object type as defined in struct tMP4AudioObjectType 318 * in file e_tMP4AudioObjectType.h 319 */ 320 Int audioObjectType; 321 322 /* 323 * This value is extended audio object type as defined in struct tMP4AudioObjectType 324 * in file e_tMP4AudioObjectType.h. It carries the output Audio Object Type 325 */ 326 Int extendedAudioObjectType; 327 328 329 } tPVMP4AudioDecoderExternal; 330 331 /*---------------------------------------------------------------------------- 332 ; GLOBAL FUNCTION DEFINITIONS 333 ; Function Prototype declaration 334 ----------------------------------------------------------------------------*/ 335 336 OSCL_IMPORT_REF UInt32 PVMP4AudioDecoderGetMemRequirements(void); 337 338 OSCL_IMPORT_REF Int PVMP4AudioDecoderInitLibrary( 339 tPVMP4AudioDecoderExternal *pExt, 340 void *pMem); 341 342 OSCL_IMPORT_REF Int PVMP4AudioDecodeFrame( 343 tPVMP4AudioDecoderExternal *pExt, 344 void *pMem); 345 346 OSCL_IMPORT_REF Int PVMP4AudioDecoderConfig( 347 tPVMP4AudioDecoderExternal *pExt, 348 void *pMem); 349 350 OSCL_IMPORT_REF void PVMP4AudioDecoderResetBuffer( 351 void *pMem); 352 353 OSCL_IMPORT_REF void PVMP4AudioDecoderDisableAacPlus( 354 tPVMP4AudioDecoderExternal *pExt, 355 void *pMem); 356 357 Int PVMP4SetAudioConfig( 358 tPVMP4AudioDecoderExternal *pExt, 359 void *pMem, 360 Int upsamplingFactor, 361 Int samp_rate, 362 int num_ch, 363 tMP4AudioObjectType audioObjectType); 364 365 /*---------------------------------------------------------------------------- 366 ; END 367 ----------------------------------------------------------------------------*/ 368 369 #ifdef __cplusplus 370 } 371 #endif 372 373 374 #endif /* PVMP4AUDIODECODER_API_H */ 375 376 377
