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