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