M4VSS3GPP_API.h revision 7dbd2c46824000ce473966637c11b8564682cb55
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 65extern "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 */ 84typedef 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 */ 93typedef 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 */ 110typedef 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 */ 125typedef 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 */ 141typedef 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 */ 157typedef 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 */ 184typedef 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 */ 235typedef 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 */ 272typedef 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 */ 290typedef 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 */ 313typedef 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 */ 329typedef 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 */ 359typedef 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 370#ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 371 M4xVSS_ClipSettings xVSS; 372#endif 373 374} M4VSS3GPP_ClipSettings; 375 376 377/** 378 ****************************************************************************** 379 * struct M4VSS3GPP_EditSettings 380 * @brief This structure gathers all the information needed to define a complete 381 * edition operation 382 ****************************************************************************** 383 */ 384typedef struct 385{ 386 /**< Number of element of the clip list pClipList */ 387 M4OSA_UInt8 uiClipNumber; 388 /**< The properties of this clip will be used as a reference for compatibility checking */ 389 M4OSA_UInt8 uiMasterClip; 390 /**< List of the input clips settings. Pointer to an array of uiClipNumber 391 clip settings pointers */ 392 M4VSS3GPP_ClipSettings **pClipList; 393 /**< List of the transition settings. Pointer to an array of uiClipNumber-1 394 transition settings pointers */ 395 M4VSS3GPP_TransitionSettings **pTransitionList; 396 M4VSS3GPP_EffectSettings *Effects; /**< List of effects */ 397 M4OSA_UInt8 nbEffects; /**< Number of effects in the above list */ 398 /**< Frame rate at which the modified video sections will be encoded */ 399 M4VIDEOEDITING_VideoFramerate videoFrameRate; 400 M4OSA_Void *pOutputFile; /**< Output 3GPP clip file descriptor */ 401 M4OSA_UInt32 uiOutputPathSize; /**< Output file path size*/ 402 /**< Temporary file to store metadata ("moov.bin") */ 403 M4OSA_Void *pTemporaryFile; 404 405#ifdef M4VSS_SUPPORT_EXTENDED_FEATURES 406 M4xVSS_EditSettings xVSS; 407#endif 408 M4OSA_Float PTVolLevel; 409} M4VSS3GPP_EditSettings; 410 411 412/** 413 ****************************************************************************** 414 * M4OSA_ERR M4VSS3GPP_editAnalyseClip() 415 * @brief This function allows checking if a clip is compatible with VSS 3GPP editing 416 * @note It also fills a ClipAnalysis structure, which can be used to check if two 417 * clips are compatible 418 * @param pClip (IN) File descriptor of the input 3GPP/MP3 clip file. 419 * @param pClipProperties (IN) Pointer to a valid ClipProperties structure. 420 * @param FileType (IN) Type of the input file (.3gp, .amr, .mp3) 421 * @return M4NO_ERROR: No error 422 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 423 * @return M4VSS3GPP_ERR_H263_PROFILE_NOT_SUPPORTED 424 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION 425 * @return M4VSS3GPP_ERR_AMR_EDITING_UNSUPPORTED 426 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_H263_PROFILE 427 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_PROFILE 428 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_RVLC 429 * @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT 430 * @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_VIDEO_STREAM_IN_FILE 431 * @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_AUDIO_FORMAT 432 * @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_STREAM_IN_FILE 433 ****************************************************************************** 434 */ 435M4OSA_ERR M4VSS3GPP_editAnalyseClip(M4OSA_Void *pClip, M4VIDEOEDITING_FileType FileType, 436 M4VIDEOEDITING_ClipProperties *pClipProperties, 437 M4OSA_FileReadPointer *pFileReadPtrFct); 438 439/** 440 ****************************************************************************** 441 * M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility() 442 * @brief This function allows checking if two clips are compatible with each other 443 * for VSS 3GPP editing assembly feature. 444 * @note 445 * @param pClip1Properties (IN) Clip analysis of the first clip 446 * @param pClip2Properties (IN) Clip analysis of the second clip 447 * @return M4NO_ERROR: No error 448 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 449 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION 450 * @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_PLATFORM 451 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FORMAT 452 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FRAME_SIZE 453 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_TIME_SCALE 454 * @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_DATA_PARTITIONING 455 * @return M4VSS3GPP_ERR_UNSUPPORTED_MP3_ASSEMBLY 456 * @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT 457 ****************************************************************************** 458 */ 459M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility(M4VIDEOEDITING_ClipProperties *pClip1Properties, 460 M4VIDEOEDITING_ClipProperties *pClip2Properties); 461 462/** 463 ****************************************************************************** 464 * M4OSA_ERR M4VSS3GPP_editInit() 465 * @brief Initializes the VSS 3GPP edit operation (allocates an execution context). 466 * @note 467 * @param pContext (OUT) Pointer on the VSS 3GPP edit context to allocate 468 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 469 * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions 470 * @return M4NO_ERROR: No error 471 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL 472 * @return M4ERR_ALLOC: There is no more available memory 473 ****************************************************************************** 474 */ 475M4OSA_ERR M4VSS3GPP_editInit( 476 M4VSS3GPP_EditContext* pContext, 477 M4OSA_FileReadPointer* pFileReadPtrFct, 478 M4OSA_FileWriterPointer* pFileWritePtrFct ); 479 480/** 481 ****************************************************************************** 482 * M4OSA_ERR M4VSS3GPP_editCreateClipSettings() 483 * @brief Allows filling a clip settings structure with default values 484 * 485 * @note WARNING: pClipSettings->pFile will be allocated in this function. 486 * 487 * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 488 * @param pFile (IN) Clip file name 489 * @param filePathSize (IN) Size of the clip path (needed for UTF16 conversion) 490 * @param nbEffects (IN) Nb of effect settings to allocate 491 * @return M4NO_ERROR: No error 492 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 493 ****************************************************************************** 494 */ 495M4OSA_ERR M4VSS3GPP_editCreateClipSettings(M4VSS3GPP_ClipSettings *pClipSettings, 496 M4OSA_Void* pFile, M4OSA_UInt32 filePathSize, 497 M4OSA_UInt8 nbEffects); 498 499/** 500 ****************************************************************************** 501 * M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings() 502 * @brief Duplicates a clip settings structure, performing allocations if required 503 * 504 * @param pClipSettingsDest (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 505 * @param pClipSettingsOrig (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 506 * @param bCopyEffects (IN) Flag to know if we have to duplicate effects (deprecated) 507 * @return M4NO_ERROR: No error 508 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 509 ****************************************************************************** 510 */ 511M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings(M4VSS3GPP_ClipSettings *pClipSettingsDest, 512 M4VSS3GPP_ClipSettings *pClipSettingsOrig, 513 M4OSA_Bool bCopyEffects); 514 515/** 516 ****************************************************************************** 517 * M4OSA_ERR M4VSS3GPP_editFreeClipSettings() 518 * @brief Free the pointers allocated in the ClipSetting structure (pFile, Effects). 519 * 520 * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure 521 * @return M4NO_ERROR: No error 522 * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) 523 ****************************************************************************** 524 */ 525M4OSA_ERR M4VSS3GPP_editFreeClipSettings(M4VSS3GPP_ClipSettings *pClipSettings); 526 527/** 528 ****************************************************************************** 529 * M4OSA_ERR M4VSS3GPP_editOpen() 530 * @brief Set the VSS 3GPP input and output files, and set the settings. 531 * @note 532 * @param pContext (IN) VSS 3GPP edit context 533 * @param pSettings (IN) Edit settings 534 * @return M4NO_ERROR: No error 535 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 536 * @return M4ERR_STATE: VSS is not in an appropriate state for this function to be called 537 * @return M4ERR_ALLOC: There is no more available memory 538 ****************************************************************************** 539 */ 540M4OSA_ERR M4VSS3GPP_editOpen(M4VSS3GPP_EditContext pContext, M4VSS3GPP_EditSettings *pSettings); 541 542/** 543 ****************************************************************************** 544 * M4OSA_ERR M4VSS3GPP_editStep() 545 * @brief Perform one step of editing. 546 * @note 547 * @param pContext (IN) VSS 3GPP edit context 548 * @param pProgress (OUT) Progress percentage (0 to 100) of the editing operation 549 * @return M4NO_ERROR: No error 550 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 551 * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function to 552 * be called 553 * @return M4VSS3GPP_WAR_EDITING_DONE:Edition is done, user should now call M4VSS3GPP_editClose() 554 ****************************************************************************** 555 */ 556M4OSA_ERR M4VSS3GPP_editStep(M4VSS3GPP_EditContext pContext, M4OSA_UInt8 *pProgress); 557 558/** 559 ****************************************************************************** 560 * M4OSA_ERR M4VSS3GPP_editClose() 561 * @brief Finish the VSS 3GPP edit operation. 562 * @note The output 3GPP file is ready to be played after this call 563 * @param pContext (IN) VSS 3GPP edit context 564 * @return M4NO_ERROR: No error 565 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 566 * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function 567 * to be called 568 ****************************************************************************** 569 */ 570M4OSA_ERR M4VSS3GPP_editClose(M4VSS3GPP_EditContext pContext); 571 572/** 573 ****************************************************************************** 574 * M4OSA_ERR M4VSS3GPP_editCleanUp() 575 * @brief Free all resources used by the VSS 3GPP edit operation. 576 * @note The context is no more valid after this call 577 * @param pContext (IN) VSS 3GPP edit context 578 * @return M4NO_ERROR: No error 579 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 580 ****************************************************************************** 581 */ 582M4OSA_ERR M4VSS3GPP_editCleanUp(M4VSS3GPP_EditContext pContext); 583 584/** 585 ****************************************************************************** 586 ****************************************************************************** 587 ****************************************************************************** 588 * 589 * Audio Mixing Feature 590 * 591 ****************************************************************************** 592 ****************************************************************************** 593 ****************************************************************************** 594 */ 595/** 596 * Public type of the VSS audio mixing context */ 597typedef M4OSA_Void* M4VSS3GPP_AudioMixingContext; 598 599 600/** 601 ****************************************************************************** 602 * struct M4VSS3GPP_AudioMixingSettings 603 * @brief This structure defines the settings of the audio mixing operation. 604 ****************************************************************************** 605 */ 606typedef struct { 607 M4OSA_Void* pOriginalClipFile; /**< Input 3GPP clip file */ 608 M4OSA_Void* pAddedAudioTrackFile; /**< New audio track */ 609 M4VIDEOEDITING_FileType AddedAudioFileType; /**< File Format of the new audio file */ 610 M4OSA_UInt32 uiAddCts; /**< Time, in milliseconds, 611 at which the added audio track is inserted */ 612 M4OSA_UInt32 uiAddVolume; /**< Volume, in percentage, 613 of the added audio track */ 614 M4OSA_UInt32 uiBeginLoop; /**< Describes in milli-second the 615 start time of the loop */ 616 M4OSA_UInt32 uiEndLoop; /**< Describes in milli-second the end 617 time of the loop (0 means no loop) */ 618 M4OSA_Bool bRemoveOriginal; /**< If true, the original audio track 619 is not taken into account */ 620 M4OSA_Void* pOutputClipFile; /**< Output 3GPP clip file */ 621 M4OSA_Void* pTemporaryFile; /**< Temporary file to store metadata 622 ("moov.bin") */ 623 /**< The following parameters are optionnal. They are just used in case of MP3 replacement. */ 624 M4VIDEOEDITING_AudioSamplingFrequency outputASF; /**< Output sampling frequency */ 625 M4VIDEOEDITING_AudioFormat outputAudioFormat; /**< Output audio codec(AAC/AMR)*/ 626 M4VIDEOEDITING_Bitrate outputAudioBitrate; /**< Output audio bitrate */ 627 M4OSA_UInt8 outputNBChannels; /**< Output audio nb of channels */ 628 M4OSA_Bool b_DuckingNeedeed; 629 M4OSA_Int32 InDucking_threshold; 630 M4OSA_Float fBTVolLevel; 631 M4OSA_Float fPTVolLevel; 632 M4OSA_Float InDucking_lowVolume; 633 M4OSA_Bool bLoop; 634 M4OSA_UInt32 uiSamplingFrequency; 635 M4OSA_UInt32 uiNumChannels; 636} M4VSS3GPP_AudioMixingSettings; 637 638/** 639 ****************************************************************************** 640 * M4OSA_ERR M4VSS3GPP_audioMixingInit(M4VSS3GPP_AudioMixingContext* pContext, 641 * M4VSS3GPP_AudioMixingSettings* pSettings) 642 * @brief Initializes the VSS audio mixing operation (allocates an execution context). 643 * @note 644 * @param pContext (OUT) Pointer on the VSS audio mixing context to allocate 645 * @param pSettings (IN) Pointer to valid audio mixing settings 646 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 647 * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions 648 * @return M4NO_ERROR: No error 649 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 650 * @return M4ERR_ALLOC: There is no more available memory 651 ****************************************************************************** 652 */ 653M4OSA_ERR M4VSS3GPP_audioMixingInit( 654 M4VSS3GPP_AudioMixingContext* pContext, 655 M4VSS3GPP_AudioMixingSettings* pSettings, 656 M4OSA_FileReadPointer* pFileReadPtrFct, 657 M4OSA_FileWriterPointer* pFileWritePtrFct ); 658 659/** 660 ****************************************************************************** 661 * M4OSA_ERR M4VSS3GPP_audioMixingStep() 662 * @brief Perform one step of audio mixing. 663 * @note 664 * @param pContext (IN) VSS 3GPP audio mixing context 665 * @return M4NO_ERROR: No error 666 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 667 * @param pProgress (OUT) Progress percentage (0 to 100) 668 of the finalization operation 669 * @return M4ERR_STATE: VSS is not in an appropriate state for 670 this function to be called 671 * @return M4VSS3GPP_WAR_END_OF_AUDIO_MIXING: Audio mixing is over, user should 672 now call M4VSS3GPP_audioMixingCleanUp() 673 ****************************************************************************** 674 */ 675M4OSA_ERR M4VSS3GPP_audioMixingStep(M4VSS3GPP_AudioMixingContext pContext, 676 M4OSA_UInt8 *pProgress); 677 678/** 679 ****************************************************************************** 680 * M4OSA_ERR M4VSS3GPP_audioMixingCleanUp() 681 * @brief Free all resources used by the VSS audio mixing operation. 682 * @note The context is no more valid after this call 683 * @param pContext (IN) VSS 3GPP audio mixing context 684 * @return M4NO_ERROR: No error 685 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 686 ****************************************************************************** 687 */ 688M4OSA_ERR M4VSS3GPP_audioMixingCleanUp(M4VSS3GPP_AudioMixingContext pContext); 689 690 691/** 692 ****************************************************************************** 693 ****************************************************************************** 694 ****************************************************************************** 695 * 696 * Extract Picture Feature 697 * 698 ****************************************************************************** 699 ****************************************************************************** 700 ****************************************************************************** 701 */ 702/** 703 * Public type of the VSS extract picture context */ 704typedef M4OSA_Void* M4VSS3GPP_ExtractPictureContext; 705 706/** 707 ****************************************************************************** 708 * struct M4VSS3GPP_ExtractPictureSettings 709 * @brief This structure defines the settings of the extract picture audio operation. 710 ****************************************************************************** 711 */ 712typedef struct { 713 M4OSA_Void* pInputClipFile; /**< Input 3GPP clip file */ 714 M4OSA_Int32 iExtractionTime; /**< frame time (in ms) to be extracted */ 715 M4OSA_Void* pOutputYuvPic; /**< Output YUV picture name */ 716} M4VSS3GPP_ExtractPictureSettings; 717 718 719/****************************************************************************** 720 * M4OSA_ERR M4VSS3GPP_extractPictureInit() 721 * @brief Initializes the VSS extract picture operation (allocates an execution context). 722 * @note 723 * @param pContext (OUT) Pointer on the VSS extract picture context to allocate 724 * @param pSettings (IN) Pointer to valid extract picture settings 725 * @param pWidth (OUT) video stream width 726 * @param pHeight (OUT) video stream height 727 * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions 728 * @return M4NO_ERROR: No error 729 * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) 730 * @return M4ERR_ALLOC: There is no more available memory 731 * @return M4VSS3GPP_ERR_INVALID_CLIP1: The input clip is empty 732 ****************************************************************************** 733 */ 734M4OSA_ERR M4VSS3GPP_extractPictureInit( 735 M4VSS3GPP_ExtractPictureContext* pContext, 736 M4VSS3GPP_ExtractPictureSettings* pSettings, 737 M4OSA_UInt32 *pWidth, 738 M4OSA_UInt32 *pHeight, 739 M4OSA_FileReadPointer* pFileReadPtrFct ); 740 741/** 742 ****************************************************************************** 743 * M4OSA_ERR M4VSS3GPP_extractPictureStep() 744 * @brief Perform one step of picture extraction. 745 * @note 746 * @param pContext (IN) VSS extract picture context 747 * @return M4NO_ERROR: No error 748 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 749 * @param pDecPlanes (OUT) Plane in wich the extracted picture is copied 750 * @param pProgress (OUT) Progress percentage (0 to 100) 751 of the picture extraction 752 * @return M4ERR_STATE: VSS is not in an appropriate state for this 753 function to be called 754 * @return VSS_WAR_END_OF_EXTRACT_PICTURE: Picture extraction is over, user should now 755 call M4VSS3GPP_extractPictureCleanUp() 756 ****************************************************************************** 757 */ 758M4OSA_ERR M4VSS3GPP_extractPictureStep(M4VSS3GPP_ExtractPictureContext pContext, 759 M4VIFI_ImagePlane *pDecPlanes, M4OSA_UInt8 *pProgress); 760 761/** 762 ****************************************************************************** 763 * M4OSA_ERR M4VSS3GPP_extractPictureCleanUp() 764 * @brief Free all resources used by the VSS picture extraction. 765 * @note The context is no more valid after this call 766 * @param pContext (IN) VSS extract picture context 767 * @return M4NO_ERROR: No error 768 * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) 769 ****************************************************************************** 770 */ 771M4OSA_ERR M4VSS3GPP_extractPictureCleanUp(M4VSS3GPP_ExtractPictureContext pContext); 772 773/** 774 ****************************************************************************** 775 ****************************************************************************** 776 ****************************************************************************** 777 * 778 * Common features 779 * 780 ****************************************************************************** 781 ****************************************************************************** 782 ****************************************************************************** 783 */ 784 785/** 786 ****************************************************************************** 787 * M4OSA_ERR M4VSS3GPP_GetVersion() 788 * @brief Get the VSS version. 789 * @note Can be called anytime. Do not need any context. 790 * @param pVersionInfo (OUT) Pointer to a version info structure 791 * @return M4NO_ERROR: No error 792 ****************************************************************************** 793 */ 794M4OSA_ERR M4VSS3GPP_GetVersion(M4_VersionInfo* pVersionInfo); 795 796 797#ifdef WIN32 798/** 799 ****************************************************************************** 800 * M4OSA_ERR M4VSS3GPP_GetErrorMessage() 801 * @brief Return a string describing the given error code 802 * @note The input string must be already allocated (and long enough!) 803 * @param err (IN) Error code to get the description from 804 * @param sMessage (IN/OUT) Allocated string in which the description will be copied 805 * @return M4NO_ERROR: Input error is from the VSS3GPP module 806 * @return M4ERR_PARAMETER:Input error is not from the VSS3GPP module 807 ****************************************************************************** 808 */ 809M4OSA_ERR M4VSS3GPP_GetErrorMessage(M4OSA_ERR err, M4OSA_Char* sMessage); 810#endif /**< WIN32 */ 811 812 813#ifdef __cplusplus 814} 815#endif /* __cplusplus */ 816 817#endif /* __M4VSS3GPP_API_H__ */ 818 819