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 #ifndef __M4VSS3GPP_API_H__ 18 #define __M4VSS3GPP_API_H__ 19 20 /** 21 ****************************************************************************** 22 * @file M4VSS3GPP_API.h 23 * @brief Video Studio Service 3GPP public API. 24 * @note VSS allows editing 3GPP files. 25 * It is a straightforward and fully synchronous API. 26 ****************************************************************************** 27 */ 28 29 /** 30 * OSAL basic types and errors */ 31 #include "M4OSA_Types.h" 32 #include "M4OSA_Error.h" 33 34 /** 35 * OSAL types for file access */ 36 #include "M4OSA_FileReader.h" 37 #include "M4OSA_FileWriter.h" 38 39 /** 40 * Definition of M4_VersionInfo */ 41 #include "M4TOOL_VersionInfo.h" 42 43 /** 44 * Image planes definition */ 45 #include "M4VIFI_FiltersAPI.h" 46 47 /** 48 * Common definitions of video editing components */ 49 #include "M4_VideoEditingCommon.h" 50 #include "M4ENCODER_AudioCommon.h" 51 #include "M4AD_Common.h" 52 #include "M4DA_Types.h" 53 54 /** 55 * Extended API (xVSS) */ 56 #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 57 #include "M4VSS3GPP_Extended_API.h" 58 #endif 59 60 //#include "M4VD_HW_API.h" 61 //#include "M4VE_API.h" 62 63 64 #ifdef __cplusplus 65 extern "C" { 66 #endif 67 68 69 70 /** 71 ****************************************************************************** 72 ****************************************************************************** 73 ****************************************************************************** 74 * 75 * Edition Feature 76 * 77 ****************************************************************************** 78 ****************************************************************************** 79 ****************************************************************************** 80 */ 81 82 /** 83 * Public type of the VSS edit context */ 84 typedef M4OSA_Void* M4VSS3GPP_EditContext; 85 86 87 /** 88 ****************************************************************************** 89 * enum M4VSS3GPP_VideoEffectType 90 * @brief This enumeration defines the video effect types of the VSS3GPP 91 ****************************************************************************** 92 */ 93 typedef enum 94 { 95 M4VSS3GPP_kVideoEffectType_None = 0, /**< No video effect */ 96 M4VSS3GPP_kVideoEffectType_FadeFromBlack = 8, /**< Intended for begin effect */ 97 M4VSS3GPP_kVideoEffectType_FadeToBlack = 16, /**< Intended for end effect */ 98 M4VSS3GPP_kVideoEffectType_External = 256 /**< External effect function is used */ 99 /* reserved 256 + n */ /**< External effect number n */ 100 101 } M4VSS3GPP_VideoEffectType; 102 103 104 /** 105 ****************************************************************************** 106 * enum M4VSS3GPP_AudioEffectType 107 * @brief This enumeration defines the audio effect types of the VSS3GPP 108 ****************************************************************************** 109 */ 110 typedef enum 111 { 112 M4VSS3GPP_kAudioEffectType_None = 0, 113 M4VSS3GPP_kAudioEffectType_FadeIn = 8, /**< Intended for begin effect */ 114 M4VSS3GPP_kAudioEffectType_FadeOut = 16 /**< Intended for end effect */ 115 116 } M4VSS3GPP_AudioEffectType; 117 118 119 /** 120 ****************************************************************************** 121 * enum M4VSS3GPP_VideoTransitionType 122 * @brief This enumeration defines the video effect that can be applied during a transition. 123 ****************************************************************************** 124 */ 125 typedef enum 126 { 127 M4VSS3GPP_kVideoTransitionType_None = 0, 128 M4VSS3GPP_kVideoTransitionType_CrossFade = 1, 129 M4VSS3GPP_kVideoTransitionType_External = 256 130 /* reserved 256 + n */ /**< External transition number n */ 131 132 } M4VSS3GPP_VideoTransitionType; 133 134 135 /** 136 ****************************************************************************** 137 * enum M4VSS3GPP_AudioTransitionType 138 * @brief This enumeration defines the audio effect that can be applied during a transition. 139 ****************************************************************************** 140 */ 141 typedef enum 142 { 143 M4VSS3GPP_kAudioTransitionType_None = 0, 144 M4VSS3GPP_kAudioTransitionType_CrossFade 145 146 } M4VSS3GPP_AudioTransitionType; 147 148 149 /** 150 ****************************************************************************** 151 * struct M4VSS3GPP_ExternalProgress 152 * @brief This structure contains information provided to the external Effect 153 * and Transition functions 154 * @note The uiProgress value should be enough for most cases 155 ****************************************************************************** 156 */ 157 typedef struct 158 { 159 /**< Progress of the Effect or the Transition, from 0 to 1000 (one thousand) */ 160 M4OSA_UInt32 uiProgress; 161 /**< Index of the current clip (first clip in case of a Transition), from 0 to N */ 162 //M4OSA_UInt8 uiCurrentClip; 163 /**< Current time, in milliseconds, in the current clip time-line */ 164 M4OSA_UInt32 uiClipTime; 165 /**< Current time, in milliseconds, in the output clip time-line */ 166 M4OSA_UInt32 uiOutputTime; 167 M4OSA_Bool bIsLast; 168 169 } M4VSS3GPP_ExternalProgress; 170 171 172 /** 173 ************************************************************************ 174 * enum M4VSS3GPP_codecType 175 * @brief This enum defines the codec types used to create interfaces 176 * @note This enum is used internally by the VSS3GPP services to identify 177 * a currently supported codec interface. Each codec is 178 * registered with one of this type associated. 179 * When a codec instance is needed, this type is used to 180 * identify and retrieve its interface. 181 * This can be extended for other codecs. 182 ************************************************************************ 183 */ 184 typedef enum 185 { 186 /* Video Decoder Types */ 187 M4VSS3GPP_kVideoDecMPEG4 = 0, 188 M4VSS3GPP_kVideoDecH264, 189 190 /* Video Encoder Types */ 191 M4VSS3GPP_kVideoEncMPEG4, 192 M4VSS3GPP_kVideoEncH263, 193 M4VSS3GPP_kVideoEncH264, 194 195 /* Audio Decoder Types */ 196 M4VSS3GPP_kAudioDecAMRNB, 197 M4VSS3GPP_kAudioDecAAC, 198 M4VSS3GPP_kAudioDecMP3, 199 200 /* Audio Encoder Types */ 201 M4VSS3GPP_kAudioEncAMRNB, 202 M4VSS3GPP_kAudioEncAAC, 203 204 /* number of codecs, keep it as last enum entry, before invlaid type */ 205 M4VSS3GPP_kCodecType_NB, 206 /* invalid codec type */ 207 M4VSS3GPP_kCodecTypeInvalid = 255 208 209 } M4VSS3GPP_codecType; 210 211 212 /** 213 ****************************************************************************** 214 * prototype M4VSS3GPP_editVideoEffectFct 215 * @brief Begin and End video effect functions implemented by the integrator 216 * must match this prototype. 217 * @note The function is provided with the original image of the clip. 218 * It must apply the video effect to build the output image. 219 * The progress of the effect is given, on a scale from 0 to 1000. 220 * When the effect function is called, all the image plane structures 221 * and buffers are valid and owned by the VSS 3GPP. 222 * 223 * @param pFunctionContext (IN) The function context, previously set by the integrator 224 * @param pInputPlanes (IN) Input YUV420 image: pointer to an array of three valid 225 image planes (Y, U and V) 226 * @param pOutputPlanes (IN/OUT) Output (filtered) YUV420 image: pointer to an array 227 of three valid image planes (Y, U and V) 228 * @param pProgress (IN) Set of information about the video transition progress. 229 * @param uiExternalEffectId (IN) Which effect function should be used (for external effects) 230 * 231 * @return M4NO_ERROR: No error 232 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 233 ****************************************************************************** 234 */ 235 typedef M4OSA_ERR (*M4VSS3GPP_editVideoEffectFct) 236 ( 237 M4OSA_Void *pFunctionContext, 238 M4VIFI_ImagePlane *pInputPlanes, 239 M4VIFI_ImagePlane *pOutputPlanes, 240 M4VSS3GPP_ExternalProgress *pProgress, 241 M4OSA_UInt32 uiExternalEffectId 242 ); 243 244 245 /** 246 ****************************************************************************** 247 * prototype M4VSS3GPP_editVideoTransitionFct 248 * @brief External transition functions implemented by the integrator 249 * must match this prototype. 250 * @note The function is provided with the image of the first clip and 251 * the image of the second clip. It must build the output image 252 * from the two input images. 253 * The progress of the transition is given, on a scale from 0 to 1000. 254 * When the external function is called, all the image plane 255 * structures and buffers are valid and owned by the VSS 3GPP. 256 * 257 * @param pFunctionContext (IN) The function context, previously set by the integrator 258 * @param pClip1InputPlanes (IN) First input YUV420 image: pointer to an array of three 259 valid image planes (Y, U and V) 260 * @param pClip2InputPlanes (IN) Second input YUV420 image: pointer to an array of three 261 valid image planes (Y, U and V) 262 * @param pOutputPlanes (IN/OUT) Output (filtered) YUV420 image: pointer to an array 263 of three valid image planes (Y, U and V) 264 * @param pProgress (IN) Set of information about the video effect progress. 265 * @param uiExternalTransitionId (IN) Which transition function should be used 266 (for external transitions) 267 * 268 * @return M4NO_ERROR: No error 269 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 270 ****************************************************************************** 271 */ 272 typedef M4OSA_ERR (*M4VSS3GPP_editVideoTransitionFct) 273 ( 274 M4OSA_Void *pFunctionContext, 275 M4VIFI_ImagePlane *pClip1InputPlanes, 276 M4VIFI_ImagePlane *pClip2InputPlanes, 277 M4VIFI_ImagePlane *pOutputPlanes, 278 M4VSS3GPP_ExternalProgress *pProgress, 279 M4OSA_UInt32 uiExternalTransitionId 280 ); 281 282 283 /** 284 ****************************************************************************** 285 * struct M4VSS3GPP_EffectSettings 286 * @brief This structure defines an audio/video effect for the edition. 287 * @note Effect start time is relative to output clip. 288 ****************************************************************************** 289 */ 290 typedef struct 291 { 292 M4OSA_UInt32 uiStartTime; /**< In ms */ 293 M4OSA_UInt32 uiDuration; /**< In ms */ 294 M4VSS3GPP_VideoEffectType VideoEffectType; /**< None, FadeIn, FadeOut, etc. */ 295 M4VSS3GPP_editVideoEffectFct ExtVideoEffectFct; /**< External effect function */ 296 M4OSA_Void *pExtVideoEffectFctCtxt;/**< Context given to the external 297 effect function */ 298 M4VSS3GPP_AudioEffectType AudioEffectType; /**< None, FadeIn, FadeOut */ 299 300 #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 301 M4xVSS_EffectSettings xVSS; 302 #endif 303 304 } M4VSS3GPP_EffectSettings; 305 306 307 /** 308 ****************************************************************************** 309 * enum M4VSS3GPP_TransitionBehaviour 310 * @brief Transition behavior 311 ****************************************************************************** 312 */ 313 typedef enum 314 { 315 M4VSS3GPP_TransitionBehaviour_SpeedUp = 0, 316 M4VSS3GPP_TransitionBehaviour_Linear, 317 M4VSS3GPP_TransitionBehaviour_SpeedDown, 318 M4VSS3GPP_TransitionBehaviour_SlowMiddle, 319 M4VSS3GPP_TransitionBehaviour_FastMiddle 320 } M4VSS3GPP_TransitionBehaviour; 321 322 323 /** 324 ****************************************************************************** 325 * struct M4VSS3GPP_TransitionSettings 326 * @brief This structure defines the transition to be applied when assembling two clips. 327 ****************************************************************************** 328 */ 329 typedef struct 330 { 331 /**< Duration of the transition, in milliseconds (set to 0 to get no transition) */ 332 M4OSA_UInt32 uiTransitionDuration; 333 334 /**< Type of the video transition */ 335 M4VSS3GPP_VideoTransitionType VideoTransitionType; 336 337 /**< External transition video effect function */ 338 M4VSS3GPP_editVideoTransitionFct ExtVideoTransitionFct; 339 340 /**< Context of the external transition video effect function */ 341 M4OSA_Void *pExtVideoTransitionFctCtxt; 342 M4VSS3GPP_AudioTransitionType AudioTransitionType; /**< Type of the audio transition */ 343 M4VSS3GPP_TransitionBehaviour TransitionBehaviour; /**<Transition behaviour*/ 344 345 #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 346 M4xVSS_TransitionSettings xVSS; 347 #endif 348 349 } M4VSS3GPP_TransitionSettings; 350 351 352 /** 353 ****************************************************************************** 354 * struct M4VSS3GPP_ClipSettings 355 * @brief This structure defines an input clip for the edition. 356 * @note It also contains the settings for the cut and begin/end effects applied to the clip. 357 ****************************************************************************** 358 */ 359 typedef struct 360 { 361 M4OSA_Void *pFile; /**< Clip file descriptor */ 362 M4VIDEOEDITING_FileType FileType; /**< .3gp, .amr, .mp3 */ 363 M4OSA_UInt32 filePathSize; /**< Clip path size 364 (add because of UTF16 conversion)*/ 365 M4VIDEOEDITING_ClipProperties ClipProperties; /**< Clip analysis previously computed 366 with M4VSS3GPP_editAnalyseClip */ 367 M4OSA_UInt32 uiBeginCutTime; /**< Begin cut time, in milliseconds */ 368 M4OSA_UInt32 uiEndCutTime; /**< End cut time, in milliseconds */ 369 M4OSA_Bool bTranscodingRequired; 370 371 #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 372 M4xVSS_ClipSettings xVSS; 373 #endif 374 375 } M4VSS3GPP_ClipSettings; 376 377 378 /** 379 ****************************************************************************** 380 * struct M4VSS3GPP_EditSettings 381 * @brief This structure gathers all the information needed to define a complete 382 * edition operation 383 ****************************************************************************** 384 */ 385 typedef struct 386 { 387 /**< Number of element of the clip list pClipList */ 388 M4OSA_UInt8 uiClipNumber; 389 /**< The properties of this clip will be used as a reference for compatibility checking */ 390 M4OSA_UInt8 uiMasterClip; 391 /**< List of the input clips settings. Pointer to an array of uiClipNumber 392 clip settings pointers */ 393 M4VSS3GPP_ClipSettings **pClipList; 394 /**< List of the transition settings. Pointer to an array of uiClipNumber-1 395 transition settings pointers */ 396 M4VSS3GPP_TransitionSettings **pTransitionList; 397 M4VSS3GPP_EffectSettings *Effects; /**< List of effects */ 398 M4OSA_UInt8 nbEffects; /**< Number of effects in the above list */ 399 /**< Frame rate at which the modified video sections will be encoded */ 400 M4VIDEOEDITING_VideoFramerate videoFrameRate; 401 M4OSA_Void *pOutputFile; /**< Output 3GPP clip file descriptor */ 402 M4OSA_UInt32 uiOutputPathSize; /**< Output file path size*/ 403 /**< Temporary file to store metadata ("moov.bin") */ 404 M4OSA_Void *pTemporaryFile; 405 406 #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 407 M4xVSS_EditSettings xVSS; 408 #endif 409 M4OSA_Float PTVolLevel; 410 } M4VSS3GPP_EditSettings; 411 412 413 /** 414 ****************************************************************************** 415 * M4OSA_ERR M4VSS3GPP_editAnalyseClip() 416 * @brief This function allows checking if a clip is compatible with VSS 3GPP editing 417 * @note It also fills a ClipAnalysis structure, which can be used to check if two 418 * clips are compatible 419 * @param pClip (IN) File descriptor of the input 3GPP/MP3 clip file. 420 * @param pClipProperties (IN) Pointer to a valid ClipProperties structure. 421 * @param FileType (IN) Type of the input file (.3gp, .amr, .mp3) 422 * @return M4NO_ERROR: No error 423 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 424 * @return M4VSS3GPP_ERR_H263_PROFILE_NOT_SUPPORTED 425 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION 426 * @return M4VSS3GPP_ERR_AMR_EDITING_UNSUPPORTED 427 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_H263_PROFILE 428 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_PROFILE 429 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_RVLC 430 * @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT 431 * @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_VIDEO_STREAM_IN_FILE 432 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_AUDIO_FORMAT 433 * @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_STREAM_IN_FILE 434 ****************************************************************************** 435 */ 436 M4OSA_ERR M4VSS3GPP_editAnalyseClip(M4OSA_Void *pClip, M4VIDEOEDITING_FileType FileType, 437 M4VIDEOEDITING_ClipProperties *pClipProperties, 438 M4OSA_FileReadPointer *pFileReadPtrFct); 439 440 /** 441 ****************************************************************************** 442 * M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility() 443 * @brief This function allows checking if two clips are compatible with each other 444 * for VSS 3GPP editing assembly feature. 445 * @note 446 * @param pClip1Properties (IN) Clip analysis of the first clip 447 * @param pClip2Properties (IN) Clip analysis of the second clip 448 * @return M4NO_ERROR: No error 449 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 450 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION 451 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_PLATFORM 452 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FORMAT 453 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FRAME_SIZE 454 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_TIME_SCALE 455 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_DATA_PARTITIONING 456 * @return M4VSS3GPP_ERR_UNSUPPORTED_MP3_ASSEMBLY 457 * @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT 458 ****************************************************************************** 459 */ 460 M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility(M4VIDEOEDITING_ClipProperties *pClip1Properties, 461 M4VIDEOEDITING_ClipProperties *pClip2Properties); 462 463 /** 464 ****************************************************************************** 465 * M4OSA_ERR M4VSS3GPP_editInit() 466 * @brief Initializes the VSS 3GPP edit operation (allocates an execution context). 467 * @note 468 * @param pContext (OUT) Pointer on the VSS 3GPP edit context to allocate 469 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 470 * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions 471 * @return M4NO_ERROR: No error 472 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL 473 * @return M4ERR_ALLOC: There is no more available memory 474 ****************************************************************************** 475 */ 476 M4OSA_ERR M4VSS3GPP_editInit( 477 M4VSS3GPP_EditContext* pContext, 478 M4OSA_FileReadPointer* pFileReadPtrFct, 479 M4OSA_FileWriterPointer* pFileWritePtrFct ); 480 481 /** 482 ****************************************************************************** 483 * M4OSA_ERR M4VSS3GPP_editCreateClipSettings() 484 * @brief Allows filling a clip settings structure with default values 485 * 486 * @note WARNING: pClipSettings->pFile will be allocated in this function. 487 * 488 * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 489 * @param pFile (IN) Clip file name 490 * @param filePathSize (IN) Size of the clip path (needed for UTF16 conversion) 491 * @param nbEffects (IN) Nb of effect settings to allocate 492 * @return M4NO_ERROR: No error 493 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 494 ****************************************************************************** 495 */ 496 M4OSA_ERR M4VSS3GPP_editCreateClipSettings(M4VSS3GPP_ClipSettings *pClipSettings, 497 M4OSA_Void* pFile, M4OSA_UInt32 filePathSize, 498 M4OSA_UInt8 nbEffects); 499 500 /** 501 ****************************************************************************** 502 * M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings() 503 * @brief Duplicates a clip settings structure, performing allocations if required 504 * 505 * @param pClipSettingsDest (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 506 * @param pClipSettingsOrig (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 507 * @param bCopyEffects (IN) Flag to know if we have to duplicate effects (deprecated) 508 * @return M4NO_ERROR: No error 509 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 510 ****************************************************************************** 511 */ 512 M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings(M4VSS3GPP_ClipSettings *pClipSettingsDest, 513 M4VSS3GPP_ClipSettings *pClipSettingsOrig, 514 M4OSA_Bool bCopyEffects); 515 516 /** 517 ****************************************************************************** 518 * M4OSA_ERR M4VSS3GPP_editFreeClipSettings() 519 * @brief Free the pointers allocated in the ClipSetting structure (pFile, Effects). 520 * 521 * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 522 * @return M4NO_ERROR: No error 523 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 524 ****************************************************************************** 525 */ 526 M4OSA_ERR M4VSS3GPP_editFreeClipSettings(M4VSS3GPP_ClipSettings *pClipSettings); 527 528 /** 529 ****************************************************************************** 530 * M4OSA_ERR M4VSS3GPP_editOpen() 531 * @brief Set the VSS 3GPP input and output files, and set the settings. 532 * @note 533 * @param pContext (IN) VSS 3GPP edit context 534 * @param pSettings (IN) Edit settings 535 * @return M4NO_ERROR: No error 536 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 537 * @return M4ERR_STATE: VSS is not in an appropriate state for this function to be called 538 * @return M4ERR_ALLOC: There is no more available memory 539 ****************************************************************************** 540 */ 541 M4OSA_ERR M4VSS3GPP_editOpen(M4VSS3GPP_EditContext pContext, M4VSS3GPP_EditSettings *pSettings); 542 543 /** 544 ****************************************************************************** 545 * M4OSA_ERR M4VSS3GPP_editStep() 546 * @brief Perform one step of editing. 547 * @note 548 * @param pContext (IN) VSS 3GPP edit context 549 * @param pProgress (OUT) Progress percentage (0 to 100) of the editing operation 550 * @return M4NO_ERROR: No error 551 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 552 * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function to 553 * be called 554 * @return M4VSS3GPP_WAR_EDITING_DONE:Edition is done, user should now call M4VSS3GPP_editClose() 555 ****************************************************************************** 556 */ 557 M4OSA_ERR M4VSS3GPP_editStep(M4VSS3GPP_EditContext pContext, M4OSA_UInt8 *pProgress); 558 559 /** 560 ****************************************************************************** 561 * M4OSA_ERR M4VSS3GPP_editClose() 562 * @brief Finish the VSS 3GPP edit operation. 563 * @note The output 3GPP file is ready to be played after this call 564 * @param pContext (IN) VSS 3GPP edit context 565 * @return M4NO_ERROR: No error 566 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 567 * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function 568 * to be called 569 ****************************************************************************** 570 */ 571 M4OSA_ERR M4VSS3GPP_editClose(M4VSS3GPP_EditContext pContext); 572 573 /** 574 ****************************************************************************** 575 * M4OSA_ERR M4VSS3GPP_editCleanUp() 576 * @brief Free all resources used by the VSS 3GPP edit operation. 577 * @note The context is no more valid after this call 578 * @param pContext (IN) VSS 3GPP edit context 579 * @return M4NO_ERROR: No error 580 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 581 ****************************************************************************** 582 */ 583 M4OSA_ERR M4VSS3GPP_editCleanUp(M4VSS3GPP_EditContext pContext); 584 585 /** 586 ****************************************************************************** 587 ****************************************************************************** 588 ****************************************************************************** 589 * 590 * Audio Mixing Feature 591 * 592 ****************************************************************************** 593 ****************************************************************************** 594 ****************************************************************************** 595 */ 596 /** 597 * Public type of the VSS audio mixing context */ 598 typedef M4OSA_Void* M4VSS3GPP_AudioMixingContext; 599 600 601 /** 602 ****************************************************************************** 603 * struct M4VSS3GPP_AudioMixingSettings 604 * @brief This structure defines the settings of the audio mixing operation. 605 ****************************************************************************** 606 */ 607 typedef struct { 608 M4OSA_Void* pOriginalClipFile; /**< Input 3GPP clip file */ 609 M4OSA_Void* pAddedAudioTrackFile; /**< New audio track */ 610 M4VIDEOEDITING_FileType AddedAudioFileType; /**< File Format of the new audio file */ 611 M4OSA_UInt32 uiAddCts; /**< Time, in milliseconds, 612 at which the added audio track is inserted */ 613 M4OSA_UInt32 uiAddVolume; /**< Volume, in percentage, 614 of the added audio track */ 615 M4OSA_UInt32 uiBeginLoop; /**< Describes in milli-second the 616 start time of the loop */ 617 M4OSA_UInt32 uiEndLoop; /**< Describes in milli-second the end 618 time of the loop (0 means no loop) */ 619 M4OSA_Bool bRemoveOriginal; /**< If true, the original audio track 620 is not taken into account */ 621 M4OSA_Void* pOutputClipFile; /**< Output 3GPP clip file */ 622 M4OSA_Void* pTemporaryFile; /**< Temporary file to store metadata 623 ("moov.bin") */ 624 /**< The following parameters are optionnal. They are just used in case of MP3 replacement. */ 625 M4VIDEOEDITING_AudioSamplingFrequency outputASF; /**< Output sampling frequency */ 626 M4VIDEOEDITING_AudioFormat outputAudioFormat; /**< Output audio codec(AAC/AMR)*/ 627 M4VIDEOEDITING_Bitrate outputAudioBitrate; /**< Output audio bitrate */ 628 M4OSA_UInt8 outputNBChannels; /**< Output audio nb of channels */ 629 M4OSA_Bool b_DuckingNeedeed; 630 M4OSA_Int32 InDucking_threshold; 631 M4OSA_Float fBTVolLevel; 632 M4OSA_Float fPTVolLevel; 633 M4OSA_Float InDucking_lowVolume; 634 M4OSA_Bool bLoop; 635 M4OSA_UInt32 uiSamplingFrequency; 636 M4OSA_UInt32 uiNumChannels; 637 } M4VSS3GPP_AudioMixingSettings; 638 639 /** 640 ****************************************************************************** 641 * M4OSA_ERR M4VSS3GPP_audioMixingInit(M4VSS3GPP_AudioMixingContext* pContext, 642 * M4VSS3GPP_AudioMixingSettings* pSettings) 643 * @brief Initializes the VSS audio mixing operation (allocates an execution context). 644 * @note 645 * @param pContext (OUT) Pointer on the VSS audio mixing context to allocate 646 * @param pSettings (IN) Pointer to valid audio mixing settings 647 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 648 * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions 649 * @return M4NO_ERROR: No error 650 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 651 * @return M4ERR_ALLOC: There is no more available memory 652 ****************************************************************************** 653 */ 654 M4OSA_ERR M4VSS3GPP_audioMixingInit( 655 M4VSS3GPP_AudioMixingContext* pContext, 656 M4VSS3GPP_AudioMixingSettings* pSettings, 657 M4OSA_FileReadPointer* pFileReadPtrFct, 658 M4OSA_FileWriterPointer* pFileWritePtrFct ); 659 660 /** 661 ****************************************************************************** 662 * M4OSA_ERR M4VSS3GPP_audioMixingStep() 663 * @brief Perform one step of audio mixing. 664 * @note 665 * @param pContext (IN) VSS 3GPP audio mixing context 666 * @return M4NO_ERROR: No error 667 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 668 * @param pProgress (OUT) Progress percentage (0 to 100) 669 of the finalization operation 670 * @return M4ERR_STATE: VSS is not in an appropriate state for 671 this function to be called 672 * @return M4VSS3GPP_WAR_END_OF_AUDIO_MIXING: Audio mixing is over, user should 673 now call M4VSS3GPP_audioMixingCleanUp() 674 ****************************************************************************** 675 */ 676 M4OSA_ERR M4VSS3GPP_audioMixingStep(M4VSS3GPP_AudioMixingContext pContext, 677 M4OSA_UInt8 *pProgress); 678 679 /** 680 ****************************************************************************** 681 * M4OSA_ERR M4VSS3GPP_audioMixingCleanUp() 682 * @brief Free all resources used by the VSS audio mixing operation. 683 * @note The context is no more valid after this call 684 * @param pContext (IN) VSS 3GPP audio mixing context 685 * @return M4NO_ERROR: No error 686 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 687 ****************************************************************************** 688 */ 689 M4OSA_ERR M4VSS3GPP_audioMixingCleanUp(M4VSS3GPP_AudioMixingContext pContext); 690 691 692 /** 693 ****************************************************************************** 694 ****************************************************************************** 695 ****************************************************************************** 696 * 697 * Extract Picture Feature 698 * 699 ****************************************************************************** 700 ****************************************************************************** 701 ****************************************************************************** 702 */ 703 /** 704 * Public type of the VSS extract picture context */ 705 typedef M4OSA_Void* M4VSS3GPP_ExtractPictureContext; 706 707 /** 708 ****************************************************************************** 709 * struct M4VSS3GPP_ExtractPictureSettings 710 * @brief This structure defines the settings of the extract picture audio operation. 711 ****************************************************************************** 712 */ 713 typedef struct { 714 M4OSA_Void* pInputClipFile; /**< Input 3GPP clip file */ 715 M4OSA_Int32 iExtractionTime; /**< frame time (in ms) to be extracted */ 716 M4OSA_Void* pOutputYuvPic; /**< Output YUV picture name */ 717 } M4VSS3GPP_ExtractPictureSettings; 718 719 720 /****************************************************************************** 721 * M4OSA_ERR M4VSS3GPP_extractPictureInit() 722 * @brief Initializes the VSS extract picture operation (allocates an execution context). 723 * @note 724 * @param pContext (OUT) Pointer on the VSS extract picture context to allocate 725 * @param pSettings (IN) Pointer to valid extract picture settings 726 * @param pWidth (OUT) video stream width 727 * @param pHeight (OUT) video stream height 728 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 729 * @return M4NO_ERROR: No error 730 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 731 * @return M4ERR_ALLOC: There is no more available memory 732 * @return M4VSS3GPP_ERR_INVALID_CLIP1: The input clip is empty 733 ****************************************************************************** 734 */ 735 M4OSA_ERR M4VSS3GPP_extractPictureInit( 736 M4VSS3GPP_ExtractPictureContext* pContext, 737 M4VSS3GPP_ExtractPictureSettings* pSettings, 738 M4OSA_UInt32 *pWidth, 739 M4OSA_UInt32 *pHeight, 740 M4OSA_FileReadPointer* pFileReadPtrFct ); 741 742 /** 743 ****************************************************************************** 744 * M4OSA_ERR M4VSS3GPP_extractPictureStep() 745 * @brief Perform one step of picture extraction. 746 * @note 747 * @param pContext (IN) VSS extract picture context 748 * @return M4NO_ERROR: No error 749 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 750 * @param pDecPlanes (OUT) Plane in wich the extracted picture is copied 751 * @param pProgress (OUT) Progress percentage (0 to 100) 752 of the picture extraction 753 * @return M4ERR_STATE: VSS is not in an appropriate state for this 754 function to be called 755 * @return VSS_WAR_END_OF_EXTRACT_PICTURE: Picture extraction is over, user should now 756 call M4VSS3GPP_extractPictureCleanUp() 757 ****************************************************************************** 758 */ 759 M4OSA_ERR M4VSS3GPP_extractPictureStep(M4VSS3GPP_ExtractPictureContext pContext, 760 M4VIFI_ImagePlane *pDecPlanes, M4OSA_UInt8 *pProgress); 761 762 /** 763 ****************************************************************************** 764 * M4OSA_ERR M4VSS3GPP_extractPictureCleanUp() 765 * @brief Free all resources used by the VSS picture extraction. 766 * @note The context is no more valid after this call 767 * @param pContext (IN) VSS extract picture context 768 * @return M4NO_ERROR: No error 769 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 770 ****************************************************************************** 771 */ 772 M4OSA_ERR M4VSS3GPP_extractPictureCleanUp(M4VSS3GPP_ExtractPictureContext pContext); 773 774 /** 775 ****************************************************************************** 776 ****************************************************************************** 777 ****************************************************************************** 778 * 779 * Common features 780 * 781 ****************************************************************************** 782 ****************************************************************************** 783 ****************************************************************************** 784 */ 785 786 /** 787 ****************************************************************************** 788 * M4OSA_ERR M4VSS3GPP_GetVersion() 789 * @brief Get the VSS version. 790 * @note Can be called anytime. Do not need any context. 791 * @param pVersionInfo (OUT) Pointer to a version info structure 792 * @return M4NO_ERROR: No error 793 ****************************************************************************** 794 */ 795 M4OSA_ERR M4VSS3GPP_GetVersion(M4_VersionInfo* pVersionInfo); 796 797 798 #ifdef WIN32 799 /** 800 ****************************************************************************** 801 * M4OSA_ERR M4VSS3GPP_GetErrorMessage() 802 * @brief Return a string describing the given error code 803 * @note The input string must be already allocated (and long enough!) 804 * @param err (IN) Error code to get the description from 805 * @param sMessage (IN/OUT) Allocated string in which the description will be copied 806 * @return M4NO_ERROR: Input error is from the VSS3GPP module 807 * @return M4ERR_PARAMETER:Input error is not from the VSS3GPP module 808 ****************************************************************************** 809 */ 810 M4OSA_ERR M4VSS3GPP_GetErrorMessage(M4OSA_ERR err, M4OSA_Char* sMessage); 811 #endif /**< WIN32 */ 812 813 814 #ifdef __cplusplus 815 } 816 #endif /* __cplusplus */ 817 818 #endif /* __M4VSS3GPP_API_H__ */ 819 820