1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
/*
* Copyright (C) 2011 The Android Open Source Project
*
* 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.
*/
/**
******************************************************************************
* @file M4PTO3GPP_API.h
* @brief The Pictures to 3GPP Converter.
* @note M4PTO3GPP produces 3GPP compliant audio/video files
* from an AMR NB audio file and raw pictures into a MPEG-4/h263 3GPP file.
******************************************************************************
*/
#ifndef __M4PTO3GPP_API_H__
#define __M4PTO3GPP_API_H__
/**
* OSAL basic types and errors */
#include "M4OSA_Types.h"
#include "M4OSA_Error.h"
/**
* OSAL types for file access */
#include "M4OSA_FileReader.h"
#include "M4OSA_FileWriter.h"
/**
* Definition of M4_VersionInfo */
#include "M4TOOL_VersionInfo.h"
/**
* Definitions of M4VIFI_ImagePlane */
#include "M4VIFI_FiltersAPI.h"
/**
* Common definitions of video editing components */
#include "M4_VideoEditingCommon.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Public type of the M4PTO3GPP context */
typedef M4OSA_Void* M4PTO3GPP_Context;
/**
******************************************************************************
* enum M4PTO3GPP_ReplaceAudioMode
* @brief This enumeration defines the way the audio is managed if it is shorter than the video
******************************************************************************
*/
typedef enum
{
M4PTO3GPP_kAudioPaddingMode_None = 0, /**< Audio track is kept shorter than the video track*/
M4PTO3GPP_kAudioPaddingMode_Silence, /**< If audio is shorter, silence is added at the end*/
M4PTO3GPP_kAudioPaddingMode_Loop /**< If audio is shorter, loop back to the beginning
when the whole track has been processed */
} M4PTO3GPP_AudioPaddingMode;
/**
******************************************************************************
* struct M4PTO3GPP_OutputFileMaxSize
* @brief Defines the maximum size of the 3GPP file produced by the PTO3GPP
******************************************************************************
*/
typedef enum
{
M4PTO3GPP_k50_KB, /**< Output 3GPP file size is limited to 50 Kbytes */
M4PTO3GPP_k75_KB, /**< Output 3GPP file size is limited to 75 Kbytes */
M4PTO3GPP_k100_KB, /**< Output 3GPP file size is limited to 100 Kbytes */
M4PTO3GPP_k150_KB, /**< Output 3GPP file size is limited to 150 Kbytes */
M4PTO3GPP_k200_KB, /**< Output 3GPP file size is limited to 200 Kbytes */
M4PTO3GPP_k300_KB, /**< Output 3GPP file size is limited to 300 Kbytes */
M4PTO3GPP_k400_KB, /**< Output 3GPP file size is limited to 400 Kbytes */
M4PTO3GPP_k500_KB, /**< Output 3GPP file size is limited to 500 Kbytes */
M4PTO3GPP_kUNLIMITED=-1 /**< Output 3GPP file size is not limited */
} M4PTO3GPP_OutputFileMaxSize;
/**
******************************************************************************
* M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
* M4VIFI_ImagePlane* pImagePlanes, M4OSA_Double* pPictureDuration);
* @brief The integrator must implement a function following this prototype.
* Its goal is to feed the PTO3GPP with YUV420 pictures.
*
* @note This function is given to the PTO3GPP in the M4PTO3GPP_Params structure
* @param pContext (IN) The integrator own context
* @param pImagePlanes(IN/OUT) Pointer to an array of three valid image planes
* @param pPictureDuration(OUT) Duration of the returned picture
*
* @return M4NO_ERROR: No error
* @return M4PTO3GPP_WAR_LAST_PICTURE: The returned image is the last one
* @return M4ERR_PARAMETER: At least one of the function parameters is null (bebug only)
******************************************************************************
*/
typedef M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
M4VIFI_ImagePlane* pImagePlanes,
M4OSA_Double* pPictureDuration);
/**
******************************************************************************
* struct M4PTO3GPP_Params
* @brief M4PTO3GPP parameters definition
******************************************************************************
*/
typedef struct
{
/**< Output video compression format, H263 or MPEG4 */
M4VIDEOEDITING_VideoFormat OutputVideoFormat;
/**< Output frame size : SQCIF to VGA*/
M4VIDEOEDITING_VideoFrameSize OutputVideoFrameSize;
/**< Targeted Output bit-rate, see enum*/
M4VIDEOEDITING_Bitrate OutputVideoBitrate;
/**< Maximum size of the output 3GPP file, see enum */
M4PTO3GPP_OutputFileMaxSize OutputFileMaxSize;
/**< Callback function to be called by the PTO3GPP to get the input pictures*/
M4PTO3GPP_PictureCallbackFct* pPictureCallbackFct;
/**< Context to be given as third argument of the picture callback function call*/
M4OSA_Void* pPictureCallbackCtxt;
/**< File descriptor of the input audio track file */
M4OSA_Void* pInputAudioTrackFile;
/**< Format of the audio file */
M4VIDEOEDITING_FileType AudioFileFormat;
/**< Type of processing to apply when audio is shorter than video*/
M4PTO3GPP_AudioPaddingMode AudioPaddingMode;
/**< File descriptor of the output 3GPP file */
M4OSA_Void* pOutput3gppFile;
/**< File descriptor of the temporary file to store metadata ("moov.bin") */
M4OSA_Void* pTemporaryFile;
/**< Number of input YUV frames to encode */
M4OSA_UInt32 NbVideoFrames;
M4OSA_Int32 videoProfile;
M4OSA_Int32 videoLevel;
} M4PTO3GPP_Params;
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
* @brief Get the M4PTO3GPP version.
* @note Can be called anytime. Do not need any context.
* @param pVersionInfo (OUT) Pointer to a version info structure
* @return M4NO_ERROR: No error
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext);
* @brief Initializes the M4PTO3GPP (allocates an execution context).
* @note
* @param pContext (OUT) Pointer on the M4PTO3GPP context to allocate
* @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions
* @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_ALLOC: The context structure could not be allocated
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
M4OSA_FileWriterPointer* pFileWritePtrFct);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
* @brief Set the M4PTO3GPP input and output files.
* @note It opens the input file, but the output file may not be created yet.
* @param pContext (IN) M4PTO3GPP context
* @param pParams (IN) Pointer to the parameters for the PTO3GPP.
* @note The pointed structure can be de-allocated after this function returns because
* it is internally copied by the PTO3GPP
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
* @return M4ERR_ALLOC: There is no more available memory
* @return ERR_PTO3GPP_INVALID_VIDEO_FRAME_SIZE_FOR_H263 The output video frame
* size parameter is incompatible with H263 encoding
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FORMAT
* The output video format parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_BITRATE
* The output video bit-rate parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE
* The output video frame size parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_FILE_SIZE
* The output file size parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_AUDIO_PADDING
* The output audio padding parameter is undefined
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
* @brief Perform one step of trancoding.
* @note
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
* @return M4PTO3GPP_WAR_END_OF_PROCESSING: Encoding completed
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
* @brief Finish the M4PTO3GPP transcoding.
* @note The output 3GPP file is ready to be played after this call
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
* @brief Free all resources used by the M4PTO3GPP.
* @note The context is no more valid after this call
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __M4PTO3GPP_API_H__ */
|
