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 ****************************************************************************** 19 * @file M4MP4W_Writer.h 20 * @brief Core MP4 writer interface 21 * @note This file declares the MP4 writer interface functions. 22 * The MP4 writer specific types are defined in file M4MP4W_Types.h 23 ****************************************************************************** 24 */ 25 #ifndef M4MP4W_WRITER_H 26 #define M4MP4W_WRITER_H 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 #include "NXPSW_CompilerSwitches.h" 33 34 #ifndef _M4MP4W_USE_CST_MEMORY_WRITER 35 36 /* includes */ 37 #include "M4OSA_Types.h" 38 #include "M4OSA_Error.h" 39 #include "M4OSA_FileWriter.h" 40 #include "M4OSA_FileReader.h" 41 #include "M4SYS_AccessUnit.h" 42 #include "M4MP4W_Types.h" 43 44 /** 45 ****************************************************************************** 46 * MP4W Errors & Warnings definition 47 ****************************************************************************** 48 */ 49 #define M4WAR_MP4W_OVERSIZE M4OSA_ERR_CREATE(M4_WAR, M4MP4_WRITER ,0x000001) 50 #define M4WAR_MP4W_NOT_EVALUABLE M4OSA_ERR_CREATE(M4_WAR, M4MP4_WRITER ,0x000002) 51 52 /** 53 ****************************************************************************** 54 * @brief Get MP4W version 55 * @param major (OUT) Pointer to the 'major' version number. 56 * @param minor (OUT) Pointer to the 'minor' version number. 57 * @param revision (OUT) Pointer to the 'revision' number. 58 * @return M4NO_ERROR: No error 59 * @return M4ERR_PARAMETER: At least one parameter is null 60 ****************************************************************************** 61 */ 62 M4OSA_ERR M4MP4W_getVersion(M4OSA_UInt8* major, 63 M4OSA_UInt8* minor, 64 M4OSA_UInt8* revision); 65 66 /** 67 ****************************************************************************** 68 * @brief Initiation of the MP4 file creation 69 * @param contextPtr (OUT) Pointer to the MP4 writer context to create. 70 * @param outputFileDescriptor (IN) Descriptor of the output file to open. 71 * @param fileWriterFunction (IN) Pointer to structure containing the set of 72 * OSAL file write functions. 73 * @param tempFileDescriptor (IN) Descriptor of the temporary file to open. 74 * @param fileReaderFunction (IN) Pointer to structure containing the set of 75 * OSAL file read functions. 76 * @return M4NO_ERROR: No error 77 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 78 * @return M4ERR_ALLOC: Memory allocation failed 79 ****************************************************************************** 80 */ 81 M4OSA_ERR M4MP4W_openWrite( M4OSA_Context* contextPtr, 82 void* outputFileDescriptor, 83 M4OSA_FileWriterPointer* fileWriterFunction, 84 void* tempFileDescriptor, 85 M4OSA_FileReadPointer* fileReaderFunction ); 86 87 /** 88 ****************************************************************************** 89 * @brief Add a new track 90 * @param context (IN/OUT) MP4 writer context. 91 * @param streamDescPtr (IN) Pointer to the structure containing the 92 parameters for the new track. 93 * @return M4NO_ERROR: No error 94 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 95 * @return M4ERR_ALLOC: Memory allocation failed 96 * @return M4ERR_STATE: Invalid state 97 * @return M4ERR_BAD_CONTEXT: An audio (resp.video) stream has already been added 98 * to this context while attempting to add another one, 99 * which is forbidden. 100 ****************************************************************************** 101 */ 102 M4OSA_ERR M4MP4W_addStream( M4OSA_Context context, 103 M4SYS_StreamDescription* streamDescPtr); 104 105 /** 106 ****************************************************************************** 107 * @brief Signal to the core MP4 writer that there is no more tracks to add 108 * @param context (IN/OUT) MP4 writer context. 109 * @return M4NO_ERROR: No error 110 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 111 * @return M4ERR_ALLOC: Memory allocation failed 112 * @return M4ERR_STATE: Invalid state 113 * @return M4ERR_BAD_CONTEXT: Audio size estimation is required but not two streams 114 * have been added. 115 ****************************************************************************** 116 */ 117 M4OSA_ERR M4MP4W_startWriting( M4OSA_Context context); 118 119 /** 120 ****************************************************************************** 121 * @brief Asks the core MP4 writer to initiate the access unit creation in 122 * the streamID track 123 * @param context (IN/OUT) MP4 writer context. 124 * @param streamID (IN) Stream ID of the track. 125 * @param auPtr (IN/OUT) Access unit. 126 * @return M4NO_ERROR: No error 127 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 128 * @return M4ERR_BAD_STREAM_ID:Unknown stream ID 129 * @return M4ERR_ALLOC: Memory allocation failed 130 * @return M4ERR_STATE: Invalid state 131 ****************************************************************************** 132 */ 133 M4OSA_ERR M4MP4W_startAU( M4OSA_Context context, 134 M4SYS_StreamID streamID, 135 M4SYS_AccessUnit* auPtr); 136 137 /** 138 ****************************************************************************** 139 * @brief Ask the core MP4 writer to write the access unit in the streamID track 140 * @note If M4MP4W_WAR_OVERSIZE is returned, M4MP4W_startAU must not be called anymore, 141 * but directly M4MP4W_closeWrite(). 142 * @param context (IN/OUT) MP4 writer context. 143 * @param streamID (IN) Stream ID of the track. 144 * @param auPtr (IN/OUT) Access unit. 145 * @return M4NO_ERROR: No error 146 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 147 * @return M4ERR_BAD_STREAM_ID: Unknown stream ID 148 * @return M4ERR_ALLOC: Memory allocation failed 149 * @return M4ERR_STATE: Invalid state 150 * @return M4WAR_MP4W_NOT_EVALUABLE: It is not possible to evaluate audio size if audio 151 * samples don't have a constant size. 152 * @return M4WAR_MP4W_OVERSIZE: Max file size was reached 153 ****************************************************************************** 154 */ 155 M4OSA_ERR M4MP4W_processAU( M4OSA_Context context, 156 M4SYS_StreamID streamID, 157 M4SYS_AccessUnit* auPtr); 158 159 /** 160 ****************************************************************************** 161 * @brief Close the MP4 file 162 * @note In previous versions of the MP4 writer, the M4MP4W_freeContext method 163 * was in the interface, which is not the case anymore. 164 * The context is now always deallocated in the M4MP4W_closeWrite function. 165 * @param context (IN/OUT) MP4 writer context. 166 * @return M4NO_ERROR: No error 167 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 168 ****************************************************************************** 169 */ 170 M4OSA_ERR M4MP4W_closeWrite( M4OSA_Context context); 171 172 /** 173 ****************************************************************************** 174 * @brief Ask the core MP4 writer to return the value associated with the optionID 175 * @param context (IN) MP4 writer context. 176 * @param option (IN) Option ID. 177 * @param valuePtr (OUT) Pointer to the option value. 178 * @return M4NO_ERROR: No error 179 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 180 * @return M4ERR_NOT_IMPLEMENTED: Not implemented in the current version 181 * @return M4ERR_BAD_OPTION_ID: Unknown optionID 182 * @return M4ERR_BAD_STREAM_ID: Bad stream ID in the option value 183 ****************************************************************************** 184 */ 185 M4OSA_ERR M4MP4W_getOption( M4OSA_Context context, 186 M4OSA_OptionID option, 187 M4OSA_DataOption *valuePtr); 188 189 /** 190 ****************************************************************************** 191 * @brief Ask the core MP4 writer to set the value associated with the optionID. 192 * @param context (IN/OUT) MP4 writer context. 193 * @param option (IN) Option ID. 194 * @param value (IN) Option value. 195 * @return M4NO_ERROR: No error 196 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 197 * @return M4ERR_NOT_IMPLEMENTED: Not implemented in the current version 198 * @return M4ERR_BAD_OPTION_ID: Unknown optionID 199 * @return M4ERR_BAD_STREAM_ID: Bad stream ID in the option value 200 * @return M4ERR_ALLOC: A memory allocation failed 201 ****************************************************************************** 202 */ 203 M4OSA_ERR M4MP4W_setOption( M4OSA_Context context, 204 M4OSA_OptionID option, 205 M4OSA_DataOption value); 206 207 /** 208 ****************************************************************************** 209 * @brief Ask the core MP4 writer to return its state. 210 * @note By selecting a specific streamID (not null), the caller can obtain 211 * the state of a specific stream. By using 0 as streamID the returned 212 * state is not stream specific. 213 * @param context (IN/OUT) MP4 writer context. 214 * @param context (IN) Pointer to the state enumeration. 215 * @param context (IN/OUT) streamID of the stream to retrieve the 216 * micro-state (0 for global state). 217 * @return M4NO_ERROR: No error 218 * @return M4ERR_BAD_STREAM_ID: Unknown stream ID 219 * @return M4ERR_PARAMETER: At least one parameter is null or incorrect 220 ****************************************************************************** 221 */ 222 M4OSA_ERR M4MP4W_getState( M4OSA_Context context, 223 M4MP4W_State* statePtr, 224 M4SYS_StreamID streamID); 225 226 /** 227 ****************************************************************************** 228 * @brief Get the currently expected file size 229 * @param context (IN/OUT) MP4 writer context. 230 * @return M4NO_ERROR: No error 231 * @return M4ERR_PARAMETER: At least one parameter is null 232 ****************************************************************************** 233 */ 234 M4OSA_ERR M4MP4W_getCurrentFileSize( M4OSA_Context context, 235 M4OSA_UInt32* currentFileSize); 236 237 #endif /* _M4MP4W_USE_CST_MEMORY_WRITER */ 238 239 #ifdef __cplusplus 240 } 241 #endif /* __cplusplus */ 242 243 244 #endif /*M4MP4W_WRITER_H*/ 245 246