/* ------------------------------------------------------------------ * Copyright (C) 1998-2009 PacketVideo * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either * express or implied. * See the License for the specific language governing permissions * and limitations under the License. * ------------------------------------------------------------------- */ /* Name: PVMP4AudioDecoder_API.h ------------------------------------------------------------------------------ REVISION HISTORY Description: Change buffer type to UChar Description: Update comments Description: Updated a comment that MT did not get around to before the end of his contract. Description: add a new API to decode audioSpecificConfig separately, the same change has been made on 32-bits version (element \main\2) Description: add a new API to reset history buffer, the same change has been made on a 32-bits version(element \nd.e0352.wjin\1) Who: Date: Description: ------------------------------------------------------------------------------ INCLUDE DESCRIPTION Main header file for the Packet Video MP4/AAC audio decoder library. The constants, structures, and functions defined within this file, along with a basic data types header file, is all that is needed to use and communicate with the library. The internal data structures within the library are purposely hidden. ---* Need description of the input buffering. *------- ---* Need an example of calling the library here *---- ------------------------------------------------------------------------------ REFERENCES (Normally header files do not have a reference section) ISO/EIC 14496-3:(1999) Document titled ------------------------------------------------------------------------------ */ /*---------------------------------------------------------------------------- ; CONTINUE ONLY IF NOT ALREADY DEFINED ----------------------------------------------------------------------------*/ #ifndef PVMP4AUDIODECODER_API_H #define PVMP4AUDIODECODER_API_H #include "pv_audio_type_defs.h" /* Basic data types used within the lib */ #include "e_tmp4audioobjecttype.h" /*---------------------------------------------------------------------------- ; INCLUDES ----------------------------------------------------------------------------*/ #ifdef __cplusplus extern "C" { #endif /*---------------------------------------------------------------------------- ; MACROS ; Define module specific macros here ----------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------- ; DEFINES ; Include all pre-processor statements here. ----------------------------------------------------------------------------*/ /* * This constant is the guaranteed-to-work buffer size, specified in bytes, * for the input buffer for 2 audio channels to decode one frame of data, * as specified by the MPEG-2 or MPEG-4 standard. * The standard, and this constant, do not take into account that lower * bitrates will use less data per frame. Note that the number of bits * used per frame is variable, and only that the average value will be the * bit rate specified during encoding. The standard does not specify * over how many frames the average must be maintained. * * The constant value is 6144 * 2 channels / 8 bits per byte */ #define PVMP4AUDIODECODER_INBUFSIZE 1536 /*---------------------------------------------------------------------------- ; EXTERNAL VARIABLES REFERENCES ; Declare variables used in this module but defined elsewhere ----------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------- ; SIMPLE TYPEDEF'S ----------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------- ; ENUMERATED TYPEDEF'S ----------------------------------------------------------------------------*/ /* * This enumeration is used for the structure element outputFormat. It * specifies how the output data is to be formatted. Presently only 16-bit * PCM data is supported, and this enum informs how the single output * buffer should be for two-channel stereo data. * Grouped format stores all the left channel values, then right: * "LLLL...LLRRRR...RR" * Interleave format store left, then right audio samples: * "LRLRLRLR...." */ typedef enum ePVMP4AudioDecoderOutputFormat { OUTPUTFORMAT_16PCM_GROUPED = 0, OUTPUTFORMAT_16PCM_INTERLEAVED = 1 } tPVMP4AudioDecoderOutputFormat; /* * This enumeration holds the possible return values for the main decoder * function, PVMP4AudioDecodeFrame. The plan was to easily distinguish * whether an error was recoverable (streaming mode) or not. Presently no * errors are recoverable, which is a result of not supporting ADTS in * this release. */ typedef enum ePVMP4AudioDecoderErrorCode { MP4AUDEC_SUCCESS = 0, MP4AUDEC_INVALID_FRAME = 10, MP4AUDEC_INCOMPLETE_FRAME = 20, MP4AUDEC_LOST_FRAME_SYNC = 30 /* Cannot happen since no ADTS */ } tPVMP4AudioDecoderErrorCode; /* * This enumeration holds the possible return values for stream type * being decoded */ typedef enum { AAC = 0, AACPLUS, ENH_AACPLUS } STREAMTYPE; /*---------------------------------------------------------------------------- ; STRUCTURES TYPEDEF'S ----------------------------------------------------------------------------*/ /* * This structure is used to communicate information in to and out of the * AAC decoder. */ typedef struct #ifdef __cplusplus tPVMP4AudioDecoderExternal // To allow forward declaration of this struct in C++ #endif { /* * INPUT: * Pointer to the input buffer that contains the encoded bistream data. * The data is filled in such that the first bit transmitted is * the most-significant bit (MSB) of the first array element. * The buffer is accessed in a linear fashion for speed, and the number of * bytes consumed varies frame to frame. * The calling environment can change what is pointed to between calls to * the decode function, library, as long as the inputBufferCurrentLength, * and inputBufferUsedLength are updated too. Also, any remaining bits in * the old buffer must be put at the beginning of the new buffer. */ UChar *pInputBuffer; /* * INPUT: * Number of valid bytes in the input buffer, set by the calling * function. After decoding the bitstream the library checks to * see if it when past this value; it would be to prohibitive to * check after every read operation. This value is not modified by * the AAC library. */ Int inputBufferCurrentLength; /* * INPUT: * The actual size of the buffer. * This variable is not used by the library, but is used by the * console test application. This parameter could be deleted * if this value was passed into these function. The helper functions are * not part of the library and are not used by the Common Audio Decoder * Interface. */ Int inputBufferMaxLength; /* * INPUT: * Enumerated value the output is to be interleaved left-right-left-right. * For further information look at the comments for the enumeration. */ tPVMP4AudioDecoderOutputFormat outputFormat; /* * INPUT: (but what is pointed to is an output) * Pointer to the output buffer to hold the 16-bit PCM audio samples. * If the output is stereo, both left and right channels will be stored * in this one buffer. Presently it must be of length of 2048 points. * The format of the buffer is set by the parameter outputFormat. */ Int16 *pOutputBuffer; /* * INPUT: (but what is pointed to is an output) * Pointer to the output buffer to hold the 16-bit PCM AAC-plus audio samples. * If the output is stereo, both left and right channels will be stored * in this one buffer. Presently it must be of length of 2048 points. * The format of the buffer is set by the parameter outputFormat. */ Int16 *pOutputBuffer_plus; /* Used in AAC+ and enhanced AAC+ */ /* * INPUT: * AAC Plus Upsampling Factor. Normally set to 2 when Spectrum Band * Replication (SBR) is used */ Int32 aacPlusUpsamplingFactor; /* Used in AAC+ and enhanced AAC+ */ /* * INPUT: * AAC Plus enabler. Deafaults to be ON, unless run time conditions * require the SBR and PS tools disabled */ bool aacPlusEnabled; /* * INPUT: * (Currently not being used inside the AAC library.) * This flag is set to TRUE when the playback position has been changed, * for example, rewind or fast forward. This informs the AAC library to * take an appropriate action, which has yet to be determined. */ Bool repositionFlag; /* * INPUT: * Number of requested output audio channels. This relieves the calling * environment from having to perform stereo-to-mono or mono-to-stereo * conversions. */ Int desiredChannels; /* * INPUT/OUTPUT: * Number of elements used by the library, initially set to zero by * the function PVMP4AudioDecoderInitLibrary, and modified by each * call to PVMP4AudioDecodeFrame. */ Int inputBufferUsedLength; /* * INPUT/OUTPUT: * Number of bits left over in the next buffer element, * This value will always be zero, unless support for ADTS is added. */ Int32 remainderBits; /* * OUTPUT: * The sampling rate decoded from the bitstream, in units of * samples/second. For this release of the library this value does * not change from frame to frame, but future versions will. */ Int32 samplingRate; /* * OUTPUT: * This value is the bitrate in units of bits/second. IT * is calculated using the number of bits consumed for the current frame, * and then multiplying by the sampling_rate, divided by points in a frame. * This value can changes frame to frame. */ Int32 bitRate; /* * OUTPUT: * The number of channels decoded from the bitstream. The output data * will have be the amount specified in the variable desiredChannels, * this output is informative only, and can be ignored. */ Int encodedChannels; /* * OUTPUT: * This value is the number of output PCM samples per channel. * It is presently hard-coded to 1024, but may change in the future. * It will not change frame to frame, and would take on * one of these four values: 1024, 960, 512, or 480. If an error occurs * do not rely on this value. */ Int frameLength; /* * This value is audio object type as defined in struct tMP4AudioObjectType * in file e_tMP4AudioObjectType.h */ Int audioObjectType; /* * This value is extended audio object type as defined in struct tMP4AudioObjectType * in file e_tMP4AudioObjectType.h. It carries the output Audio Object Type */ Int extendedAudioObjectType; } tPVMP4AudioDecoderExternal; /*---------------------------------------------------------------------------- ; GLOBAL FUNCTION DEFINITIONS ; Function Prototype declaration ----------------------------------------------------------------------------*/ OSCL_IMPORT_REF UInt32 PVMP4AudioDecoderGetMemRequirements(void); OSCL_IMPORT_REF Int PVMP4AudioDecoderInitLibrary( tPVMP4AudioDecoderExternal *pExt, void *pMem); OSCL_IMPORT_REF Int PVMP4AudioDecodeFrame( tPVMP4AudioDecoderExternal *pExt, void *pMem); OSCL_IMPORT_REF Int PVMP4AudioDecoderConfig( tPVMP4AudioDecoderExternal *pExt, void *pMem); OSCL_IMPORT_REF void PVMP4AudioDecoderResetBuffer( void *pMem); OSCL_IMPORT_REF void PVMP4AudioDecoderDisableAacPlus( tPVMP4AudioDecoderExternal *pExt, void *pMem); Int PVMP4SetAudioConfig( tPVMP4AudioDecoderExternal *pExt, void *pMem, Int upsamplingFactor, Int samp_rate, int num_ch, tMP4AudioObjectType audioObjectType); /*---------------------------------------------------------------------------- ; END ----------------------------------------------------------------------------*/ #ifdef __cplusplus } #endif #endif /* PVMP4AUDIODECODER_API_H */