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