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