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