M4MCS_API.h revision 3b25fdc4a33b53cfcf67315c2d42ad699b8cefe2
1/* 2 * Copyright (C) 2004-2011 NXP Software 3 * Copyright (C) 2011 The Android Open Source Project 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18/** 19 ****************************************************************************** 20 * @file M4MCS_API.h 21 * @brief Media Conversion Service public API. 22 * @note MCS allows transcoding a 3gp/mp4 file into a new 3gp/mp4 file changing the 23 * video and audio encoding settings. 24 * It is a straightforward and fully synchronous API. 25 ****************************************************************************** 26 */ 27 28#ifndef __M4MCS_API_H__ 29#define __M4MCS_API_H__ 30 31/** 32 * OSAL basic types and errors */ 33#include "M4OSA_Types.h" 34#include "M4OSA_Error.h" 35 36/** 37 * OSAL types for file access */ 38#include "M4OSA_FileReader.h" 39#include "M4OSA_FileWriter.h" 40 41/** 42 * Definition of M4_VersionInfo */ 43#include "M4TOOL_VersionInfo.h" 44 45/** 46 * Common definitions of video editing components */ 47#include "M4_VideoEditingCommon.h" 48 49#include "M4VD_HW_API.h" 50#include "M4VE_API.h" 51 52/** 53 * To enable external audio codecs registering*/ 54#include "M4AD_Common.h" 55#include "M4ENCODER_AudioCommon.h" 56 57#ifdef __cplusplus 58extern "C" { 59#endif 60 61/** 62 * Public type of the MCS context */ 63typedef M4OSA_Void* M4MCS_Context; 64 65 66/** 67 ****************************************************************************** 68 * enum M4MCS_MediaRendering 69 * @brief This enum defines different media rendering 70 ****************************************************************************** 71 */ 72typedef enum 73{ 74 M4MCS_kResizing = 0, /**< The media is resized, the aspect ratio can be 75 different from the original one. 76 All of the media is rendered */ 77 M4MCS_kCropping, /**< The media is cropped, the aspect ratio is the 78 same as the original one. 79 The media is not rendered entirely */ 80 M4MCS_kBlackBorders /**< Black borders are rendered in order to keep the 81 original aspect ratio. All the media is rendered */ 82} M4MCS_MediaRendering; 83 84 85/** 86 ****************************************************************************** 87 * struct M4MCS_ExternalProgress 88 * @brief This structure contains information provided to the external Effect functions 89 * @note The uiProgress value should be enough for most cases 90 ****************************************************************************** 91 */ 92typedef struct 93{ 94 M4OSA_UInt32 uiProgress; /**< Progress of the Effect from 0 to 1000 (one thousand) */ 95 M4OSA_UInt32 uiClipTime; /**< Current time, in milliseconds, 96 in the current clip time-line */ 97 M4OSA_UInt32 uiOutputTime; /**< Current time, in milliseconds, 98 in the output clip time-line */ 99 100} M4MCS_ExternalProgress; 101 102 103/** 104 ****************************************************************************** 105 * enum M4MCS_AudioEffectType 106 * @brief This enumeration defines the audio effect types of the MCS 107 ****************************************************************************** 108 */ 109typedef enum 110{ 111 M4MCS_kAudioEffectType_None = 0, 112 M4MCS_kAudioEffectType_FadeIn = 8, /**< Intended for begin effect */ 113 M4MCS_kAudioEffectType_FadeOut = 16, /**< Intended for end effect */ 114 M4MCS_kAudioEffectType_External = 256 115 116} M4MCS_AudioEffectType; 117 118 119/** 120 ****************************************************************************** 121 * prototype M4MCS_editAudioEffectFct 122 * @brief Audio effect functions implemented by the integrator 123 * must match this prototype. 124 * @note The function is provided with the original PCM data buffer and its size. 125 * Audio effect have to be applied on it. 126 * The progress of the effect is given, on a scale from 0 to 1000. 127 * When the effect function is called, all the buffers are valid and 128 * owned by the MCS. 129 * 130 * @param pFunctionContext (IN) The function context, previously set by the integrator 131 * @param pPCMdata (IN/OUT) valid PCM data buffer 132 * @param uiPCMsize (IN/OUT) PCM data buffer corresponding size 133 * @param pProgress (IN) Set of information about the audio effect progress. 134 * 135 * @return M4NO_ERROR: No error 136 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 137 ****************************************************************************** 138 */ 139typedef M4OSA_ERR (*M4MCS_editAudioEffectFct) 140( 141 M4OSA_Void *pFunctionContext, 142 M4OSA_Int16 *pPCMdata, 143 M4OSA_UInt32 uiPCMsize, 144 M4MCS_ExternalProgress *pProgress 145); 146 147 148/** 149 ****************************************************************************** 150 * struct M4MCS_EffectSettings 151 * @brief This structure defines an audio effect for the edition. 152 ****************************************************************************** 153 */ 154typedef struct 155{ 156 M4OSA_UInt32 uiStartTime; /**< In ms */ 157 M4OSA_UInt32 uiDuration; /**< In ms */ 158 M4MCS_editAudioEffectFct ExtAudioEffectFct; /**< External effect function */ 159 M4OSA_Void *pExtAudioEffectFctCtxt; /**< Context given to the external 160 effect function */ 161 M4MCS_AudioEffectType AudioEffectType; /**< None, FadeIn, FadeOut */ 162 163} M4MCS_EffectSettings; 164 165 166/** 167 ****************************************************************************** 168 * struct M4MCS_OutputParams 169 * @brief MCS Output parameters 170 * @note Following parameters are used for still picture inputs : 171 * - OutputFileType (must be set to M4VIDEOEDITING_kFileType_JPG) 172 * - bDiscardExif must be set to M4OSA_TRUE or M4OSA_FALSE 173 * - bAdjustOrientation must be set to M4OSA_TRUE or M4OSA_FALSE 174 * - (MediaRendering is not handled : output image resolution is always 175 set according to BestFit criteria) 176 * bDiscardExif and bAdjustOrientation are still picture only parameters 177 ****************************************************************************** 178 */ 179typedef struct 180{ 181 /**< Format of the output file */ 182 M4VIDEOEDITING_FileType OutputFileType; 183 /**< Output video compression format, see enum */ 184 M4VIDEOEDITING_VideoFormat OutputVideoFormat; 185 /**< Output frame size : QQVGA, QCIF or SQCIF */ 186 M4VIDEOEDITING_VideoFrameSize OutputVideoFrameSize; 187 /**< Targeted Output framerate, see enum */ 188 M4VIDEOEDITING_VideoFramerate OutputVideoFrameRate; 189 /**< Format of the audio in the stream */ 190 M4VIDEOEDITING_AudioFormat OutputAudioFormat; 191 /**< Sampling frequency of the audio in the stream */ 192 M4VIDEOEDITING_AudioSamplingFrequency OutputAudioSamplingFrequency; 193 /**< Set to M4OSA_TRUE if the output audio is mono */ 194 M4OSA_Bool bAudioMono; 195 /**< Output PCM file if not NULL */ 196 M4OSA_Char *pOutputPCMfile; 197 /**< To crop, resize, or render black borders*/ 198 M4MCS_MediaRendering MediaRendering; 199 /**< List of effects */ 200 M4MCS_EffectSettings *pEffects; 201 /**< Number of effects in the above list */ 202 M4OSA_UInt8 nbEffects; 203 204 /*--- STILL PICTURE ---*/ 205 /**< TRUE: Even if the input file contains an EXIF section, 206 the output file won't contain any EXIF section.*/ 207 M4OSA_Bool bDiscardExif ; 208 209 /**< =TRUE : picture must be rotated if Exif tags hold a rotation info 210 (and rotation info is set to 0)*/ 211 M4OSA_Bool bAdjustOrientation ; 212 /*--- STILL PICTURE ---*/ 213} M4MCS_OutputParams; 214 215/*--- STILL PICTURE ---*/ 216/** 217 ****************************************************************************** 218 * enum M4MCS_SPOutputResolution 219 * @brief Still picture specific : MCS output targeted file resolution 220 ****************************************************************************** 221 */ 222typedef enum 223{ 224 M4MCS_kResSameAsInput = 0x00, /*width x height*/ 225 M4MCS_kResQVGA = 0x01, /*320x240*/ 226 M4MCS_kResVGA = 0x02, /*640x480*/ 227 M4MCS_kResWQVGA = 0x03, /*400x240*/ 228 M4MCS_kResWVGA = 0x04, /*800x480*/ 229 M4MCS_kResXGA = 0x05, /*1024x768*/ 230 M4MCS_kResCustom = 0xFF /*Size is set via StillPictureCustomWidth/Height*/ 231} M4MCS_SPOutputResolution ; 232 233 234/** 235 ****************************************************************************** 236 * enum M4MCS_SPStrategy 237 * @brief Still picture specific : MCS strategy to configure the encoding parameters 238 ****************************************************************************** 239 */ 240typedef enum 241{ 242 M4MCS_kFileSizeOnlyFixed = 0x00, /*StillPictureResolution and 243 QualityFactor are ignored*/ 244 M4MCS_kFileSizeAndResFixed = 0x01, /*QualityFactor is ignored*/ 245 M4MCS_kQualityAndResFixed = 0x02 /*OutputFileSize is ignored*/ 246} M4MCS_SPStrategy ; 247 248 249/** 250 ****************************************************************************** 251 * enum M4MCS_SPCrop 252 * @brief Still picture specific : indicate whether cropping should be done 253 before changing the resolution 254 ****************************************************************************** 255 */ 256typedef enum 257{ 258 M4MCS_kNoCrop = 0x00, /*No Cropping is performed*/ 259 M4MCS_kCropBeforeResize = 0x01 /*Input image is cropped (before changing resolution)*/ 260} M4MCS_SPCrop ; 261 262/** 263 ****************************************************************************** 264 * enum M4MCS_ExifInfos 265 * @brief Still picture specific : The following structure contains all available exif field 266 ****************************************************************************** 267 */ 268typedef struct { 269 M4OSA_Char* ImageTitle; /* Image title */ 270 M4OSA_Char* EquipmentManufacturer; /* Image input equipment manufacturer */ 271 M4OSA_Char* EquipmentModel; /* Image input equipment model */ 272 M4OSA_Char* Software; /* Software used */ 273 M4OSA_Char* Artist; /* Artist */ 274 M4OSA_Char* Copyright; /* Copyright */ 275 M4OSA_Char* CreationDateTime; /* Creation date and time */ 276 M4OSA_UInt32 Orientation; /* Orientation of the picture */ 277 M4OSA_Char* LastChangeDateTime; /* Last Change date and time*/ 278 M4OSA_UInt32 PixelXDimension; /* Image width*/ 279 M4OSA_UInt32 PixelYDimension; /* Image Height*/ 280} M4MCS_ExifInfos; 281 282/*--- STILL PICTURE ---*/ 283 284/** 285 ****************************************************************************** 286 * struct M4MCS_EncodingParams 287 * @brief MCS file size, bitrate and cut parameters 288 * @note Following parameters are used for still picture inputs : 289 * - OutputFileSize 290 * - StillPictureResolution 291 * - QualityFactor 292 * - StillPictureStrategy 293 * - StillPictureCustomWidth/Height (if StillPictureResolution==M4MCS_kResCustom) 294 * Still picture only parameters : StillPictureResolution, QualityFactor, 295 * StillPictureStrategy and StillPictureCustomWidth/Height 296 ****************************************************************************** 297 */ 298typedef struct 299{ 300 M4VIDEOEDITING_Bitrate OutputVideoBitrate; /**< Targeted video bitrate */ 301 M4VIDEOEDITING_Bitrate OutputAudioBitrate; /**< Targeted audio bitrate */ 302 M4OSA_UInt32 BeginCutTime; /**< Beginning cut time in input file */ 303 M4OSA_UInt32 EndCutTime; /**< End cut time in input file */ 304 M4OSA_UInt32 OutputFileSize; /**< Expected resulting file size */ 305 M4OSA_UInt32 OutputVideoTimescale; /**< Optional parameter used to fix a 306 timescale during transcoding */ 307 308 /*--- STILL PICTURE ---*/ 309 M4OSA_Int32 QualityFactor ; /**< =-1 (undefined) or 0(lowest).. 310 50(best) : This parameter is the 311 quality indication for the JPEG output 312 file (if =-1 the MCS will set quality 313 automatically)*/ 314 M4MCS_SPStrategy StillPictureStrategy ; /**< Defines which input parameters 315 will be taken into account by MCS*/ 316 M4MCS_SPOutputResolution StillPictureResolution;/**< Desired output resolution for 317 a still picture file */ 318 /**< (only if Resolution==M4MCS_kResCustom) : Custom output image width */ 319 M4OSA_UInt32 StillPictureCustomWidth; 320 /**< (only if Resolution==M4MCS_kResCustom) : Custom output image height */ 321 M4OSA_UInt32 StillPictureCustomHeight; 322 /**< Indicate whether Crop should be performed */ 323 M4MCS_SPCrop StillPictureCrop; 324 /**< (only if cropping) X coordinate of topleft corner of the crop window */ 325 M4OSA_UInt32 StillPictureCrop_X; 326 /**< (only if cropping) Y coordinate of topleft corner of the crop window */ 327 M4OSA_UInt32 StillPictureCrop_Y; 328 /**< (only if cropping) Width of the crop window (in pixels) */ 329 M4OSA_UInt32 StillPictureCrop_W; 330 /**< (only if cropping) Height of the crop window (in pixels) */ 331 M4OSA_UInt32 StillPictureCrop_H; 332 /*--- STILL PICTURE ---*/ 333} M4MCS_EncodingParams; 334 335/** 336 ****************************************************************************** 337 * M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo); 338 * @brief Get the MCS version. 339 * @note Can be called anytime. Do not need any context. 340 * @param pVersionInfo (OUT) Pointer to a version info structure 341 * @return M4NO_ERROR: No error 342 * @return M4ERR_PARAMETER: pVersionInfo is M4OSA_NULL (If Debug Level >= 2) 343 ****************************************************************************** 344 */ 345M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo); 346 347/** 348 ****************************************************************************** 349 * M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct, 350 M4OSA_FileWriterPointer* pFileWritePtrFct); 351 * @brief Initializes the MCS (allocates an execution context). 352 * @note 353 * @param pContext (OUT) Pointer on the MCS context to allocate 354 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 355 * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions 356 * @return M4NO_ERROR: No error 357 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (If Debug Level >= 2) 358 * @return M4ERR_ALLOC: There is no more available memory 359 ****************************************************************************** 360 */ 361M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct, 362 M4OSA_FileWriterPointer* pFileWritePtrFct); 363 364/** 365 ****************************************************************************** 366 * M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, M4OSA_Void* pFileOut, 367 M4OSA_UInt32 uiMaxMetadataSize); 368 * @brief Set the MCS input and output files. 369 * @note It opens the input file, but the output file is not created yet. 370 * In case of still picture, four InputFileType are possible 371 * (M4VIDEOEDITING_kFileType_JPG/BMP/GIF/PNG 372 * If one of them is set, the OutputFileType SHALL be set to M4VIDEOEDITING_kFileType_JPG 373 * @param pContext (IN) MCS context 374 * @param pFileIn (IN) Input file to transcode (The type of this parameter 375 * (URL, pipe...) depends on the OSAL implementation). 376 * @param mediaType (IN) Container type (.3gp,.amr, ...) of input file. 377 * @param pFileOut (IN) Output file to create (The type of this parameter 378 * (URL, pipe...) depends on the OSAL implementation). 379 * @param pTempFile (IN) Temporary file for the constant memory writer to store 380 * metadata ("moov.bin"). 381 * @return M4NO_ERROR: No error 382 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 383 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 384 * @return M4ERR_ALLOC: There is no more available memory 385 * @return M4ERR_FILE_NOT_FOUND: The input file has not been found 386 * @return M4MCS_ERR_INVALID_INPUT_FILE: The input file is not a valid file, or is corrupted 387 * @return M4MCS_ERR_INPUT_FILE_CONTAINS_NO_SUPPORTED_STREAM: The input file contains no 388 * supported audio or video stream 389 ****************************************************************************** 390 */ 391M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, 392 M4VIDEOEDITING_FileType InputFileType, 393 M4OSA_Void* pFileOut, M4OSA_Void* pTempFile); 394 395/** 396 ****************************************************************************** 397 * M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress); 398 * @brief Perform one step of trancoding. 399 * @note 400 * @param pContext (IN) MCS context 401 * @param pProgress (OUT) Progress percentage (0 to 100) of the transcoding 402 * @note pProgress must be a valid address. 403 * @return M4NO_ERROR: No error 404 * @return M4ERR_PARAMETER: One of the parameters is M4OSA_NULL (debug only) 405 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 406 * @return M4MCS_WAR_TRANSCODING_DONE: Transcoding is over, user should now call M4MCS_close() 407 * @return M4MCS_ERR_AUDIO_CONVERSION_FAILED: The audio conversion (AAC to AMR-NB, MP3) failed 408 * @return M4MCS_ERR_INVALID_AAC_SAMPLING_FREQUENCY: The input file contains an AAC audio track 409 * with an invalid sampling frequency 410 * (should never happen) 411 * @return M4MCS_WAR_PICTURE_AUTO_RESIZE: Picture will be automatically resized to fit 412 * into requirements 413 ****************************************************************************** 414 */ 415M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress); 416 417/** 418 ****************************************************************************** 419 * M4OSA_ERR M4MCS_pause(M4MCS_Context pContext); 420 * @brief Pause the transcoding i.e. release the (external hardware) video decoder. 421 * @note This function is not needed if no hardware accelerators are used. 422 * In that case, pausing the MCS is simply achieved by temporarily suspending 423 * the M4MCS_step function calls. 424 * @param pContext (IN) MCS context 425 * @return M4NO_ERROR: No error 426 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 427 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 428 ****************************************************************************** 429 */ 430M4OSA_ERR M4MCS_pause(M4MCS_Context pContext); 431 432/** 433 ****************************************************************************** 434 * M4OSA_ERR M4MCS_resume(M4MCS_Context pContext); 435 * @brief Resume the transcoding after a pause (see M4MCS_pause). 436 * @note This function is not needed if no hardware accelerators are used. 437 * In that case, resuming the MCS is simply achieved by calling 438 * the M4MCS_step function. 439 * @param pContext (IN) MCS context 440 * @return M4NO_ERROR: No error 441 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 442 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 443 ****************************************************************************** 444 */ 445M4OSA_ERR M4MCS_resume(M4MCS_Context pContext); 446 447/** 448 ****************************************************************************** 449 * M4OSA_ERR M4MCS_close(M4MCS_Context pContext); 450 * @brief Finish the MCS transcoding. 451 * @note The output 3GPP file is ready to be played after this call 452 * @param pContext (IN) MCS context 453 * @return M4NO_ERROR: No error 454 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (If Debug Level >= 2) 455 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 456 ****************************************************************************** 457 */ 458M4OSA_ERR M4MCS_close(M4MCS_Context pContext); 459 460/** 461 ****************************************************************************** 462 * M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext); 463 * @brief Free all resources used by the MCS. 464 * @note The context is no more valid after this call 465 * @param pContext (IN) MCS context 466 * @return M4NO_ERROR: No error 467 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (If Debug Level >= 2) 468 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 469 ****************************************************************************** 470 */ 471M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext); 472 473/** 474 ****************************************************************************** 475 * M4OSA_ERR M4MCS_abort(M4MCS_Context pContext); 476 * @brief Finish the MCS transcoding and free all resources used by the MCS 477 * whatever the state is. 478 * @note The context is no more valid after this call 479 * @param pContext (IN) MCS context 480 * @return M4NO_ERROR: No error 481 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 482 ****************************************************************************** 483 */ 484M4OSA_ERR M4MCS_abort(M4MCS_Context pContext); 485 486/** 487 ****************************************************************************** 488 * M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext, 489 * M4VIDEOEDITING_ClipProperties* pFileProperties); 490 * @brief Retrieves the properties of the audio and video streams from the input file. 491 * @param pContext (IN) MCS context 492 * @param pProperties (OUT) Pointer on an allocated M4VIDEOEDITING_ClipProperties 493 structure which is filled with the input stream properties. 494 * @note The structure pProperties must be allocated and further de-allocated 495 by the application. The function must be called in the opened state. 496 * @return M4NO_ERROR: No error 497 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL 498 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 499 ****************************************************************************** 500 */ 501M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext, 502 M4VIDEOEDITING_ClipProperties *pFileProperties); 503 504/** 505 ****************************************************************************** 506 * M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams); 507 * @brief Set the MCS video output parameters. 508 * @note Must be called after M4MCS_open. Must be called before M4MCS_step. 509 * @param pContext (IN) MCS context 510 * @param pParams (IN/OUT) Transcoding parameters 511 * @return M4NO_ERROR: No error 512 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 513 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 514 * @return M4MCS_ERR_INVALID_VIDEO_FRAME_SIZE_FOR_H263 : Output video frame size parameter is 515 * incompatible with H263 encoding 516 * @return M4MCS_ERR_INVALID_VIDEO_FRAME_RATE_FOR_H263 : Output video frame size parameter is 517 * incompatible with H263 encoding 518 * @return M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FORMAT : Undefined output video format parameter 519 * @return M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE : Undefined output video frame size 520 * @return M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_RATE : Undefined output video frame rate 521 * @return M4MCS_ERR_UNDEFINED_OUTPUT_AUDIO_FORMAT : Undefined output audio format parameter 522 * @return M4MCS_ERR_DURATION_IS_NULL : Specified output parameters define a null duration stream 523 * (no audio and video) 524 ****************************************************************************** 525 */ 526M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams); 527 528/** 529 ****************************************************************************** 530 * M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates) 531 * @brief Set the values of the encoding parameters 532 * @note Must be called before M4MCS_checkParamsAndStart(). 533 * @param pContext (IN) MCS context 534 * @param pRates (IN) Transcoding parameters 535 * @return M4NO_ERROR: No error 536 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 537 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 538 * @return M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps) 539 * @return M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac, 540 * 12.2 for amr, 8 for mp3) 541 * @return M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals 542 * @return M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than 543 * the input clip duration 544 * @return M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time 545 * @return M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output 546 * file at given bitrates 547 * @return M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps) 548 * @return M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low 549 ****************************************************************************** 550 */ 551M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates); 552 553/** 554 ****************************************************************************** 555 * M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates) 556 * @brief Get the extended values of the encoding parameters 557 * @note Could be called after M4MCS_setEncodingParams. 558 * @param pContext (IN) MCS context 559 * @param pRates (OUT) Transcoding parameters 560 * @return M4NO_ERROR: No error 561 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 562 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 563 * @return M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Encoding settings would produce a 564 * null duration clip = encoding is impossible 565 ****************************************************************************** 566 */ 567M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates); 568 569/** 570 ****************************************************************************** 571 * M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext) 572 * @brief 573 * @note 574 * @param pContext (IN) MCS context 575 * @return M4NO_ERROR: No error 576 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 577 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 578 * @return M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps) 579 * @return M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac, 580 * 12.2 for amr, 8 for mp3) 581 * @return M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals 582 * @return M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than 583 * the input clip duration 584 * @return M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time 585 * @return M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output 586 * file at given bitrates 587 * @return M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps) 588 * @return M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low 589 ****************************************************************************** 590 */ 591M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext); 592 593/** 594 ****************************************************************************** 595 * M4OSA_ERR M4MCS_registerExternalVideoDecoder(M4MCS_Context pContext, 596 * M4VD_VideoType decoderType, 597 * M4VD_Interface* pDecoderInterface, 598 * M4OSA_Void* pUserData) 599 * @brief Registers an external Video decoder 600 * @note 601 * @param pContext (IN) MCS context 602 * @param decoderType (IN) Type of decoder (MPEG4 ...) 603 * @param pDecoderInterface (IN) Decoder interface 604 * @param pUserData (IN) Pointer on a user data to give to external decoder 605 * @return M4NO_ERROR: No error 606 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 607 * @return M4ERR_STATE: MCS is not in an appropriate state for this function to be called 608 ****************************************************************************** 609 */ 610M4OSA_ERR M4MCS_registerExternalVideoDecoder(M4MCS_Context pContext, 611 M4VD_VideoType decoderType, 612 M4VD_Interface* pDecoderInterface, 613 M4OSA_Void* pUserData); 614 615M4OSA_ERR M4MCS_registerExternalVideoEncoder(M4MCS_Context pContext, 616 M4VE_EncoderType encoderType, 617 M4VE_Interface* pEncoderInterface, 618 M4OSA_Void* pUserData); 619 620 621/** 622 ************************************************************************ 623 * M4OSA_ERR M4MCS_registerExternalAudioDecoder(M4MCS_Context pContext, 624 * M4AD_Type decoderType, 625 * M4AD_Interface *pDecoderInterface); 626 * @brief This function will register a specific external audio decoder. 627 * @note According to the decoderType, this function will store in the internal context 628 * the decoder interface. 629 * @param context (IN/OUT) MCS context. 630 * @param decoderType (IN) Audio decoder type 631 * @param pDecoderInterface (IN) Audio decoder interface. 632 * @return M4NO_ERROR: No error 633 * @return M4ERR_PARAMETER: A parameter is null, or the decoder type is invalid(in DEBUG only) 634 ************************************************************************ 635 */ 636M4OSA_ERR M4MCS_registerExternalAudioDecoder(M4MCS_Context pContext, 637 M4AD_Type decoderType, 638 M4AD_Interface *pDecoderInterface); 639 640 641/** 642 ****************************************************************************** 643 * M4OSA_ERR M4MCS_registerExternalAudioEncoder(M4MCS_Context pContext, 644 * M4ENCODER_AudioFormat mediaType, 645 * M4ENCODER_AudioGlobalInterface *pEncGlobalInterface) 646 * @brief This function will register a specific external audio encoder. 647 * @note According to the Mediatype, this function will store in the internal context 648 * the encoder interface. 649 * @param pContext: (IN) Execution context. 650 * @param mediaType: (IN) The media type. 651 * @param pEncGlobalInterface: (OUT) the encoder interface functions. 652 * @return M4NO_ERROR: there is no error 653 * @return M4ERR_PARAMETER: pContext or pEncGlobalInterface is M4OSA_NULL (debug only) 654 ****************************************************************************** 655 */ 656M4OSA_ERR M4MCS_registerExternalAudioEncoder(M4MCS_Context pContext, 657 M4ENCODER_AudioFormat MediaType, 658 M4ENCODER_AudioGlobalInterface *pEncGlobalInterface); 659 660 661#ifdef __cplusplus 662} 663#endif /* __cplusplus */ 664 665#endif /* __M4MCS_API_H__ */ 666 667