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
77extern "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