/* * Copyright (C) 2011 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef __M4VSS3GPP_API_H__ #define __M4VSS3GPP_API_H__ /** ****************************************************************************** * @file M4VSS3GPP_API.h * @brief Video Studio Service 3GPP public API. * @note VSS allows editing 3GPP files. * It is a straightforward and fully synchronous API. ****************************************************************************** */ /** * OSAL basic types and errors */ #include "M4OSA_Types.h" #include "M4OSA_Error.h" /** * OSAL types for file access */ #include "M4OSA_FileReader.h" #include "M4OSA_FileWriter.h" /** * Definition of M4_VersionInfo */ #include "M4TOOL_VersionInfo.h" /** * Image planes definition */ #include "M4VIFI_FiltersAPI.h" /** * Common definitions of video editing components */ #include "M4_VideoEditingCommon.h" #include "M4ENCODER_AudioCommon.h" #include "M4AD_Common.h" #include "M4DA_Types.h" /** * Extended API (xVSS) */ #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES #include "M4VSS3GPP_Extended_API.h" #endif //#include "M4VD_HW_API.h" //#include "M4VE_API.h" #ifdef __cplusplus extern "C" { #endif /** ****************************************************************************** ****************************************************************************** ****************************************************************************** * * Edition Feature * ****************************************************************************** ****************************************************************************** ****************************************************************************** */ /** * Public type of the VSS edit context */ typedef M4OSA_Void* M4VSS3GPP_EditContext; /** ****************************************************************************** * enum M4VSS3GPP_VideoEffectType * @brief This enumeration defines the video effect types of the VSS3GPP ****************************************************************************** */ typedef enum { M4VSS3GPP_kVideoEffectType_None = 0, /**< No video effect */ M4VSS3GPP_kVideoEffectType_FadeFromBlack = 8, /**< Intended for begin effect */ M4VSS3GPP_kVideoEffectType_FadeToBlack = 16, /**< Intended for end effect */ M4VSS3GPP_kVideoEffectType_External = 256 /**< External effect function is used */ /* reserved 256 + n */ /**< External effect number n */ } M4VSS3GPP_VideoEffectType; /** ****************************************************************************** * enum M4VSS3GPP_AudioEffectType * @brief This enumeration defines the audio effect types of the VSS3GPP ****************************************************************************** */ typedef enum { M4VSS3GPP_kAudioEffectType_None = 0, M4VSS3GPP_kAudioEffectType_FadeIn = 8, /**< Intended for begin effect */ M4VSS3GPP_kAudioEffectType_FadeOut = 16 /**< Intended for end effect */ } M4VSS3GPP_AudioEffectType; /** ****************************************************************************** * enum M4VSS3GPP_VideoTransitionType * @brief This enumeration defines the video effect that can be applied during a transition. ****************************************************************************** */ typedef enum { M4VSS3GPP_kVideoTransitionType_None = 0, M4VSS3GPP_kVideoTransitionType_CrossFade = 1, M4VSS3GPP_kVideoTransitionType_External = 256 /* reserved 256 + n */ /**< External transition number n */ } M4VSS3GPP_VideoTransitionType; /** ****************************************************************************** * enum M4VSS3GPP_AudioTransitionType * @brief This enumeration defines the audio effect that can be applied during a transition. ****************************************************************************** */ typedef enum { M4VSS3GPP_kAudioTransitionType_None = 0, M4VSS3GPP_kAudioTransitionType_CrossFade } M4VSS3GPP_AudioTransitionType; /** ****************************************************************************** * struct M4VSS3GPP_ExternalProgress * @brief This structure contains information provided to the external Effect * and Transition functions * @note The uiProgress value should be enough for most cases ****************************************************************************** */ typedef struct { /**< Progress of the Effect or the Transition, from 0 to 1000 (one thousand) */ M4OSA_UInt32 uiProgress; /**< Index of the current clip (first clip in case of a Transition), from 0 to N */ //M4OSA_UInt8 uiCurrentClip; /**< Current time, in milliseconds, in the current clip time-line */ M4OSA_UInt32 uiClipTime; /**< Current time, in milliseconds, in the output clip time-line */ M4OSA_UInt32 uiOutputTime; M4OSA_Bool bIsLast; } M4VSS3GPP_ExternalProgress; /** ************************************************************************ * enum M4VSS3GPP_codecType * @brief This enum defines the codec types used to create interfaces * @note This enum is used internally by the VSS3GPP services to identify * a currently supported codec interface. Each codec is * registered with one of this type associated. * When a codec instance is needed, this type is used to * identify and retrieve its interface. * This can be extended for other codecs. ************************************************************************ */ typedef enum { /* Video Decoder Types */ M4VSS3GPP_kVideoDecMPEG4 = 0, M4VSS3GPP_kVideoDecH264, /* Video Encoder Types */ M4VSS3GPP_kVideoEncMPEG4, M4VSS3GPP_kVideoEncH263, M4VSS3GPP_kVideoEncH264, /* Audio Decoder Types */ M4VSS3GPP_kAudioDecAMRNB, M4VSS3GPP_kAudioDecAAC, M4VSS3GPP_kAudioDecMP3, /* Audio Encoder Types */ M4VSS3GPP_kAudioEncAMRNB, M4VSS3GPP_kAudioEncAAC, /* number of codecs, keep it as last enum entry, before invlaid type */ M4VSS3GPP_kCodecType_NB, /* invalid codec type */ M4VSS3GPP_kCodecTypeInvalid = 255 } M4VSS3GPP_codecType; /** ****************************************************************************** * prototype M4VSS3GPP_editVideoEffectFct * @brief Begin and End video effect functions implemented by the integrator * must match this prototype. * @note The function is provided with the original image of the clip. * It must apply the video effect to build the output image. * The progress of the effect is given, on a scale from 0 to 1000. * When the effect function is called, all the image plane structures * and buffers are valid and owned by the VSS 3GPP. * * @param pFunctionContext (IN) The function context, previously set by the integrator * @param pInputPlanes (IN) Input YUV420 image: pointer to an array of three valid image planes (Y, U and V) * @param pOutputPlanes (IN/OUT) Output (filtered) YUV420 image: pointer to an array of three valid image planes (Y, U and V) * @param pProgress (IN) Set of information about the video transition progress. * @param uiExternalEffectId (IN) Which effect function should be used (for external effects) * * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) ****************************************************************************** */ typedef M4OSA_ERR (*M4VSS3GPP_editVideoEffectFct) ( M4OSA_Void *pFunctionContext, M4VIFI_ImagePlane *pInputPlanes, M4VIFI_ImagePlane *pOutputPlanes, M4VSS3GPP_ExternalProgress *pProgress, M4OSA_UInt32 uiExternalEffectId ); /** ****************************************************************************** * prototype M4VSS3GPP_editVideoTransitionFct * @brief External transition functions implemented by the integrator * must match this prototype. * @note The function is provided with the image of the first clip and * the image of the second clip. It must build the output image * from the two input images. * The progress of the transition is given, on a scale from 0 to 1000. * When the external function is called, all the image plane * structures and buffers are valid and owned by the VSS 3GPP. * * @param pFunctionContext (IN) The function context, previously set by the integrator * @param pClip1InputPlanes (IN) First input YUV420 image: pointer to an array of three valid image planes (Y, U and V) * @param pClip2InputPlanes (IN) Second input YUV420 image: pointer to an array of three valid image planes (Y, U and V) * @param pOutputPlanes (IN/OUT) Output (filtered) YUV420 image: pointer to an array of three valid image planes (Y, U and V) * @param pProgress (IN) Set of information about the video effect progress. * @param uiExternalTransitionId (IN) Which transition function should be used (for external transitions) * * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) ****************************************************************************** */ typedef M4OSA_ERR (*M4VSS3GPP_editVideoTransitionFct) ( M4OSA_Void *pFunctionContext, M4VIFI_ImagePlane *pClip1InputPlanes, M4VIFI_ImagePlane *pClip2InputPlanes, M4VIFI_ImagePlane *pOutputPlanes, M4VSS3GPP_ExternalProgress *pProgress, M4OSA_UInt32 uiExternalTransitionId ); /** ****************************************************************************** * struct M4VSS3GPP_EffectSettings * @brief This structure defines an audio/video effect for the edition. * @note Effect start time is relative to output clip. ****************************************************************************** */ typedef struct { M4OSA_UInt32 uiStartTime; /**< In ms */ M4OSA_UInt32 uiDuration; /**< In ms */ M4VSS3GPP_VideoEffectType VideoEffectType; /**< None, FadeIn, FadeOut, etc. */ M4VSS3GPP_editVideoEffectFct ExtVideoEffectFct; /**< External effect function */ M4OSA_Void *pExtVideoEffectFctCtxt;/**< Context given to the external effect function */ M4VSS3GPP_AudioEffectType AudioEffectType; /**< None, FadeIn, FadeOut */ #ifdef M4VSS_SUPPORT_EXTENDED_FEATURES M4xVSS_EffectSettings xVSS; #endif } M4VSS3GPP_EffectSettings; /** ****************************************************************************** * enum M4VSS3GPP_TransitionBehaviour * @brief Transition behavior ****************************************************************************** */ typedef enum { M4VSS3GPP_TransitionBehaviour_SpeedUp = 0, M4VSS3GPP_TransitionBehaviour_Linear, M4VSS3GPP_TransitionBehaviour_SpeedDown, M4VSS3GPP_TransitionBehaviour_SlowMiddle, M4VSS3GPP_TransitionBehaviour_FastMiddle } M4VSS3GPP_TransitionBehaviour; /** ****************************************************************************** * struct M4VSS3GPP_TransitionSettings * @brief This structure defines the transition to be applied when assembling two clips. ****************************************************************************** */ typedef struct { /**< Duration of the transition, in milliseconds (set to 0 to get no transition) */ M4OSA_UInt32 uiTransitionDuration; /**< Type of the video transition */ M4VSS3GPP_VideoTransitionType VideoTransitionType; /**< External transition video effect function */ M4VSS3GPP_editVideoTransitionFct ExtVideoTransitionFct; /**< Context of the external transition video effect function */ M4OSA_Void *pExtVideoTransitionFctCtxt; M4VSS3GPP_AudioTransitionType AudioTransitionType; /**< Type of the audio transition */ M4VSS3GPP_TransitionBehaviour TransitionBehaviour; /**pFile will be allocated in this function. * * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure * @param pFile (IN) Clip file name * @param filePathSize (IN) Size of the clip path (needed for UTF16 conversion) * @param nbEffects (IN) Nb of effect settings to allocate * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editCreateClipSettings(M4VSS3GPP_ClipSettings *pClipSettings, M4OSA_Void* pFile, M4OSA_UInt32 filePathSize, M4OSA_UInt8 nbEffects); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings() * @brief Duplicates a clip settings structure, performing allocations if required * * @param pClipSettingsDest (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure * @param pClipSettingsOrig (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure * @param bCopyEffects (IN) Flag to know if we have to duplicate effects (deprecated) * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editDuplicateClipSettings(M4VSS3GPP_ClipSettings *pClipSettingsDest, M4VSS3GPP_ClipSettings *pClipSettingsOrig, M4OSA_Bool bCopyEffects); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editFreeClipSettings() * @brief Free the pointers allocated in the ClipSetting structure (pFile, Effects). * * @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editFreeClipSettings(M4VSS3GPP_ClipSettings *pClipSettings); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editOpen() * @brief Set the VSS 3GPP input and output files, and set the settings. * @note * @param pContext (IN) VSS 3GPP edit context * @param pSettings (IN) Edit settings * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) * @return M4ERR_STATE: VSS is not in an appropriate state for this function to be called * @return M4ERR_ALLOC: There is no more available memory ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editOpen(M4VSS3GPP_EditContext pContext, M4VSS3GPP_EditSettings *pSettings); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editStep() * @brief Perform one step of editing. * @note * @param pContext (IN) VSS 3GPP edit context * @param pProgress (OUT) Progress percentage (0 to 100) of the editing operation * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function to * be called * @return M4VSS3GPP_WAR_EDITING_DONE:Edition is done, user should now call M4VSS3GPP_editClose() ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editStep(M4VSS3GPP_EditContext pContext, M4OSA_UInt8 *pProgress); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editClose() * @brief Finish the VSS 3GPP edit operation. * @note The output 3GPP file is ready to be played after this call * @param pContext (IN) VSS 3GPP edit context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) * @return M4ERR_STATE: VSS 3GPP is not in an appropriate state for this function * to be called ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editClose(M4VSS3GPP_EditContext pContext); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_editCleanUp() * @brief Free all resources used by the VSS 3GPP edit operation. * @note The context is no more valid after this call * @param pContext (IN) VSS 3GPP edit context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_editCleanUp(M4VSS3GPP_EditContext pContext); /** ****************************************************************************** ****************************************************************************** ****************************************************************************** * * Audio Mixing Feature * ****************************************************************************** ****************************************************************************** ****************************************************************************** */ /** * Public type of the VSS audio mixing context */ typedef M4OSA_Void* M4VSS3GPP_AudioMixingContext; /** ****************************************************************************** * struct M4VSS3GPP_AudioMixingSettings * @brief This structure defines the settings of the audio mixing operation. ****************************************************************************** */ typedef struct { M4OSA_Void* pOriginalClipFile; /**< Input 3GPP clip file */ M4OSA_Void* pAddedAudioTrackFile; /**< New audio track */ M4VIDEOEDITING_FileType AddedAudioFileType; /**< File Format of the new audio file */ M4OSA_UInt32 uiAddCts; /**< Time, in milliseconds, at which the added audio track is inserted */ M4OSA_UInt32 uiAddVolume; /**< Volume, in percentage, of the added audio track */ M4OSA_UInt32 uiBeginLoop; /**< Describes in milli-second the start time of the loop */ M4OSA_UInt32 uiEndLoop; /**< Describes in milli-second the end time of the loop (0 means no loop) */ M4OSA_Bool bRemoveOriginal; /**< If true, the original audio track is not taken into account */ M4OSA_Void* pOutputClipFile; /**< Output 3GPP clip file */ M4OSA_Void* pTemporaryFile; /**< Temporary file to store metadata ("moov.bin") */ /**< The following parameters are optionnal. They are just used in case of MP3 replacement. */ M4VIDEOEDITING_AudioSamplingFrequency outputASF; /**< Output sampling frequency */ M4VIDEOEDITING_AudioFormat outputAudioFormat; /**< Output audio codec(AAC/AMR)*/ M4VIDEOEDITING_Bitrate outputAudioBitrate; /**< Output audio bitrate */ M4OSA_UInt8 outputNBChannels; /**< Output audio nb of channels */ M4OSA_Bool b_DuckingNeedeed; M4OSA_Int32 InDucking_threshold; M4OSA_Float fBTVolLevel; M4OSA_Float fPTVolLevel; M4OSA_Float InDucking_lowVolume; M4OSA_Bool bLoop; M4OSA_UInt32 uiSamplingFrequency; M4OSA_UInt32 uiNumChannels; } M4VSS3GPP_AudioMixingSettings; /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_audioMixingInit(M4VSS3GPP_AudioMixingContext* pContext, * M4VSS3GPP_AudioMixingSettings* pSettings) * @brief Initializes the VSS audio mixing operation (allocates an execution context). * @note * @param pContext (OUT) Pointer on the VSS audio mixing context to allocate * @param pSettings (IN) Pointer to valid audio mixing settings * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions * @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) * @return M4ERR_ALLOC: There is no more available memory ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_audioMixingInit( M4VSS3GPP_AudioMixingContext* pContext, M4VSS3GPP_AudioMixingSettings* pSettings, M4OSA_FileReadPointer* pFileReadPtrFct, M4OSA_FileWriterPointer* pFileWritePtrFct ); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_audioMixingStep() * @brief Perform one step of audio mixing. * @note * @param pContext (IN) VSS 3GPP audio mixing context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) * @param pProgress (OUT) Progress percentage (0 to 100) of the finalization operation * @return M4ERR_STATE: VSS is not in an appropriate state for this function to be called * @return M4VSS3GPP_WAR_END_OF_AUDIO_MIXING: Audio mixing is over, user should now call M4VSS3GPP_audioMixingCleanUp() ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_audioMixingStep(M4VSS3GPP_AudioMixingContext pContext, M4OSA_UInt8 *pProgress); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_audioMixingCleanUp() * @brief Free all resources used by the VSS audio mixing operation. * @note The context is no more valid after this call * @param pContext (IN) VSS 3GPP audio mixing context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_audioMixingCleanUp(M4VSS3GPP_AudioMixingContext pContext); /** ****************************************************************************** ****************************************************************************** ****************************************************************************** * * Extract Picture Feature * ****************************************************************************** ****************************************************************************** ****************************************************************************** */ /** * Public type of the VSS extract picture context */ typedef M4OSA_Void* M4VSS3GPP_ExtractPictureContext; /** ****************************************************************************** * struct M4VSS3GPP_ExtractPictureSettings * @brief This structure defines the settings of the extract picture audio operation. ****************************************************************************** */ typedef struct { M4OSA_Void* pInputClipFile; /**< Input 3GPP clip file */ M4OSA_Int32 iExtractionTime; /**< frame time (in ms) to be extracted */ M4OSA_Void* pOutputYuvPic; /**< Output YUV picture name */ } M4VSS3GPP_ExtractPictureSettings; /****************************************************************************** * M4OSA_ERR M4VSS3GPP_extractPictureInit() * @brief Initializes the VSS extract picture operation (allocates an execution context). * @note * @param pContext (OUT) Pointer on the VSS extract picture context to allocate * @param pSettings (IN) Pointer to valid extract picture settings * @param pWidth (OUT) video stream width * @param pHeight (OUT) video stream height * @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only) * @return M4ERR_ALLOC: There is no more available memory * @return M4VSS3GPP_ERR_INVALID_CLIP1: The input clip is empty ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_extractPictureInit( M4VSS3GPP_ExtractPictureContext* pContext, M4VSS3GPP_ExtractPictureSettings* pSettings, M4OSA_UInt32 *pWidth, M4OSA_UInt32 *pHeight, M4OSA_FileReadPointer* pFileReadPtrFct ); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_extractPictureStep() * @brief Perform one step of picture extraction. * @note * @param pContext (IN) VSS extract picture context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) * @param pDecPlanes (OUT) Plane in wich the extracted picture is copied * @param pProgress (OUT) Progress percentage (0 to 100) of the picture extraction * @return M4ERR_STATE: VSS is not in an appropriate state for this function to be called * @return VSS_WAR_END_OF_EXTRACT_PICTURE: Picture extraction is over, user should now call M4VSS3GPP_extractPictureCleanUp() ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_extractPictureStep(M4VSS3GPP_ExtractPictureContext pContext, M4VIFI_ImagePlane *pDecPlanes, M4OSA_UInt8 *pProgress); /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_extractPictureCleanUp() * @brief Free all resources used by the VSS picture extraction. * @note The context is no more valid after this call * @param pContext (IN) VSS extract picture context * @return M4NO_ERROR: No error * @return M4ERR_PARAMETER: pContext is M4OSA_NULL (debug only) ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_extractPictureCleanUp(M4VSS3GPP_ExtractPictureContext pContext); /** ****************************************************************************** ****************************************************************************** ****************************************************************************** * * Common features * ****************************************************************************** ****************************************************************************** ****************************************************************************** */ /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_GetVersion() * @brief Get the VSS version. * @note Can be called anytime. Do not need any context. * @param pVersionInfo (OUT) Pointer to a version info structure * @return M4NO_ERROR: No error ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_GetVersion(M4_VersionInfo* pVersionInfo); #ifdef WIN32 /** ****************************************************************************** * M4OSA_ERR M4VSS3GPP_GetErrorMessage() * @brief Return a string describing the given error code * @note The input string must be already allocated (and long enough!) * @param err (IN) Error code to get the description from * @param sMessage (IN/OUT) Allocated string in which the description will be copied * @return M4NO_ERROR: Input error is from the VSS3GPP module * @return M4ERR_PARAMETER:Input error is not from the VSS3GPP module ****************************************************************************** */ M4OSA_ERR M4VSS3GPP_GetErrorMessage(M4OSA_ERR err, M4OSA_Char* sMessage); #endif /**< WIN32 */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* __M4VSS3GPP_API_H__ */