1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
|
/*
* 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; /**<Transition behaviour*/
#ifdef M4VSS_SUPPORT_EXTENDED_FEATURES
M4xVSS_TransitionSettings xVSS;
#endif
} M4VSS3GPP_TransitionSettings;
/**
******************************************************************************
* struct M4VSS3GPP_ClipSettings
* @brief This structure defines an input clip for the edition.
* @note It also contains the settings for the cut and begin/end effects applied to the clip.
******************************************************************************
*/
typedef struct
{
M4OSA_Void *pFile; /**< Clip file descriptor */
M4VIDEOEDITING_FileType FileType; /**< .3gp, .amr, .mp3 */
M4OSA_UInt32 filePathSize; /**< Clip path size
(add because of UTF16 conversion)*/
M4VIDEOEDITING_ClipProperties ClipProperties; /**< Clip analysis previously computed
with M4VSS3GPP_editAnalyseClip */
M4OSA_UInt32 uiBeginCutTime; /**< Begin cut time, in milliseconds */
M4OSA_UInt32 uiEndCutTime; /**< End cut time, in milliseconds */
M4OSA_Bool bTranscodingRequired;
#ifdef M4VSS_SUPPORT_EXTENDED_FEATURES
M4xVSS_ClipSettings xVSS;
#endif
} M4VSS3GPP_ClipSettings;
/**
******************************************************************************
* struct M4VSS3GPP_EditSettings
* @brief This structure gathers all the information needed to define a complete
* edition operation
******************************************************************************
*/
typedef struct
{
/**< Number of element of the clip list pClipList */
M4OSA_UInt8 uiClipNumber;
/**< The properties of this clip will be used as a reference for compatibility checking */
M4OSA_UInt8 uiMasterClip;
/**< List of the input clips settings. Pointer to an array of uiClipNumber
clip settings pointers */
M4VSS3GPP_ClipSettings **pClipList;
/**< List of the transition settings. Pointer to an array of uiClipNumber-1
transition settings pointers */
M4VSS3GPP_TransitionSettings **pTransitionList;
M4VSS3GPP_EffectSettings *Effects; /**< List of effects */
M4OSA_UInt8 nbEffects; /**< Number of effects in the above list */
/**< Frame rate at which the modified video sections will be encoded */
M4VIDEOEDITING_VideoFramerate videoFrameRate;
M4OSA_Void *pOutputFile; /**< Output 3GPP clip file descriptor */
M4OSA_UInt32 uiOutputPathSize; /**< Output file path size*/
/**< Temporary file to store metadata ("moov.bin") */
M4OSA_Void *pTemporaryFile;
#ifdef M4VSS_SUPPORT_EXTENDED_FEATURES
M4xVSS_EditSettings xVSS;
#endif
M4OSA_Float PTVolLevel;
} M4VSS3GPP_EditSettings;
/**
******************************************************************************
* M4OSA_ERR M4VSS3GPP_editAnalyseClip()
* @brief This function allows checking if a clip is compatible with VSS 3GPP editing
* @note It also fills a ClipAnalysis structure, which can be used to check if two
* clips are compatible
* @param pClip (IN) File descriptor of the input 3GPP/MP3 clip file.
* @param pClipProperties (IN) Pointer to a valid ClipProperties structure.
* @param FileType (IN) Type of the input file (.3gp, .amr, .mp3)
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only)
* @return M4VSS3GPP_ERR_H263_PROFILE_NOT_SUPPORTED
* @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION
* @return M4VSS3GPP_ERR_AMR_EDITING_UNSUPPORTED
* @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_H263_PROFILE
* @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_PROFILE
* @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_MPEG4_RVLC
* @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT
* @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_VIDEO_STREAM_IN_FILE
* @return M4VSS3GPP_ERR_EDITING_UNSUPPORTED_AUDIO_FORMAT
* @return M4VSS3GPP_ERR_EDITING_NO_SUPPORTED_STREAM_IN_FILE
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_editAnalyseClip(M4OSA_Void *pClip, M4VIDEOEDITING_FileType FileType,
M4VIDEOEDITING_ClipProperties *pClipProperties,
M4OSA_FileReadPointer *pFileReadPtrFct);
/**
******************************************************************************
* M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility()
* @brief This function allows checking if two clips are compatible with each other
* for VSS 3GPP editing assembly feature.
* @note
* @param pClip1Properties (IN) Clip analysis of the first clip
* @param pClip2Properties (IN) Clip analysis of the second clip
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL (debug only)
* @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_VERSION
* @return M4VSS3GPP_ERR_INVALID_CLIP_ANALYSIS_PLATFORM
* @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FORMAT
* @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_FRAME_SIZE
* @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_TIME_SCALE
* @return M4VSS3GPP_ERR_INCOMPATIBLE_VIDEO_DATA_PARTITIONING
* @return M4VSS3GPP_ERR_UNSUPPORTED_MP3_ASSEMBLY
* @return M4VSS3GPP_ERR_UNSUPPORTED_INPUT_VIDEO_FORMAT
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_editCheckClipCompatibility(M4VIDEOEDITING_ClipProperties *pClip1Properties,
M4VIDEOEDITING_ClipProperties *pClip2Properties);
/**
******************************************************************************
* M4OSA_ERR M4VSS3GPP_editInit()
* @brief Initializes the VSS 3GPP edit operation (allocates an execution context).
* @note
* @param pContext (OUT) Pointer on the VSS 3GPP edit context to allocate
* @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
* @return M4ERR_ALLOC: There is no more available memory
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_editInit(
M4VSS3GPP_EditContext* pContext,
M4OSA_FileReadPointer* pFileReadPtrFct,
M4OSA_FileWriterPointer* pFileWritePtrFct );
/**
******************************************************************************
* M4OSA_ERR M4VSS3GPP_editCreateClipSettings()
* @brief Allows filling a clip settings structure with default values
*
* @note WARNING: pClipSettings->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__ */
|