M4MCS_API.h revision 3b25fdc4a33b53cfcf67315c2d42ad699b8cefe2 
1/*
2 * Copyright (C) 2004-2011 NXP Software
3 * Copyright (C) 2011 The Android Open Source Project
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 ******************************************************************************
20 * @file    M4MCS_API.h
21 * @brief   Media Conversion Service public API.
22 * @note    MCS allows transcoding a 3gp/mp4 file into a new 3gp/mp4 file changing the
23 *          video and audio encoding settings.
24 *          It is a straightforward and fully synchronous API.
25 ******************************************************************************
26 */
27
28#ifndef __M4MCS_API_H__
29#define __M4MCS_API_H__
30
31/**
32 *    OSAL basic types and errors */
33#include "M4OSA_Types.h"
34#include "M4OSA_Error.h"
35
36/**
37 *    OSAL types for file access */
38#include "M4OSA_FileReader.h"
39#include "M4OSA_FileWriter.h"
40
41/**
42 *    Definition of M4_VersionInfo */
43#include "M4TOOL_VersionInfo.h"
44
45/**
46 * Common definitions of video editing components */
47#include "M4_VideoEditingCommon.h"
48
49#include "M4VD_HW_API.h"
50#include "M4VE_API.h"
51
52/**
53 * To enable external audio codecs registering*/
54#include "M4AD_Common.h"
55#include "M4ENCODER_AudioCommon.h"
56
57#ifdef __cplusplus
58extern "C" {
59#endif
60
61/**
62 *    Public type of the MCS context */
63typedef M4OSA_Void* M4MCS_Context;
64
65
66/**
67 ******************************************************************************
68 * enum        M4MCS_MediaRendering
69 * @brief    This enum defines different media rendering
70 ******************************************************************************
71 */
72typedef enum
73{
74    M4MCS_kResizing = 0,    /**< The media is resized, the aspect ratio can be
75                              different from the original one.
76                              All of the media is rendered */
77    M4MCS_kCropping,        /**< The media is cropped, the aspect ratio is the
78                              same as the original one.
79                              The media is not rendered entirely */
80    M4MCS_kBlackBorders     /**< Black borders are rendered in order to keep the
81                              original aspect ratio. All the media is rendered */
82} M4MCS_MediaRendering;
83
84
85/**
86 ******************************************************************************
87 * struct   M4MCS_ExternalProgress
88 * @brief   This structure contains information provided to the external Effect functions
89 * @note    The uiProgress value should be enough for most cases
90 ******************************************************************************
91 */
92typedef struct
93{
94    M4OSA_UInt32    uiProgress;     /**< Progress of the Effect from 0 to 1000 (one thousand) */
95    M4OSA_UInt32    uiClipTime;     /**< Current time, in milliseconds,
96                                          in the current clip time-line */
97    M4OSA_UInt32    uiOutputTime;   /**< Current time, in milliseconds,
98                                          in the output clip time-line */
99
100} M4MCS_ExternalProgress;
101
102
103/**
104 ******************************************************************************
105 * enum     M4MCS_AudioEffectType
106 * @brief   This enumeration defines the audio effect types of the MCS
107 ******************************************************************************
108 */
109typedef enum
110{
111    M4MCS_kAudioEffectType_None    = 0,
112    M4MCS_kAudioEffectType_FadeIn  = 8, /**< Intended for begin effect */
113    M4MCS_kAudioEffectType_FadeOut = 16, /**< Intended for end effect */
114    M4MCS_kAudioEffectType_External = 256
115
116} M4MCS_AudioEffectType;
117
118
119/**
120 ******************************************************************************
121 * prototype    M4MCS_editAudioEffectFct
122 * @brief       Audio effect functions implemented by the integrator
123 *              must match this prototype.
124 * @note        The function is provided with the original PCM data buffer and its size.
125 *              Audio effect have to be applied on it.
126 *              The progress of the effect is given, on a scale from 0 to 1000.
127 *              When the effect function is called, all the buffers are valid and
128 *              owned by the MCS.
129 *
130 * @param   pFunctionContext    (IN) The function context, previously set by the integrator
131 * @param   pPCMdata            (IN/OUT) valid PCM data buffer
132 * @param   uiPCMsize           (IN/OUT) PCM data buffer corresponding size
133 * @param   pProgress           (IN) Set of information about the audio effect progress.
134 *
135 * @return  M4NO_ERROR:         No error
136 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
137 ******************************************************************************
138 */
139typedef M4OSA_ERR (*M4MCS_editAudioEffectFct)
140(
141    M4OSA_Void *pFunctionContext,
142    M4OSA_Int16 *pPCMdata,
143    M4OSA_UInt32 uiPCMsize,
144    M4MCS_ExternalProgress *pProgress
145);
146
147
148/**
149 ******************************************************************************
150 * struct   M4MCS_EffectSettings
151 * @brief   This structure defines an audio effect for the edition.
152 ******************************************************************************
153 */
154typedef struct
155{
156    M4OSA_UInt32                 uiStartTime;              /**< In ms */
157    M4OSA_UInt32                 uiDuration;               /**< In ms */
158    M4MCS_editAudioEffectFct     ExtAudioEffectFct;        /**< External effect function */
159    M4OSA_Void                   *pExtAudioEffectFctCtxt;  /**< Context given to the external
160                                                                effect function */
161    M4MCS_AudioEffectType        AudioEffectType;         /**< None, FadeIn, FadeOut */
162
163} M4MCS_EffectSettings;
164
165
166/**
167 ******************************************************************************
168 * struct    M4MCS_OutputParams
169 * @brief    MCS Output parameters
170 * @note     Following parameters are used for still picture inputs :
171 *             - OutputFileType (must be set to M4VIDEOEDITING_kFileType_JPG)
172 *             - bDiscardExif must be set to M4OSA_TRUE or M4OSA_FALSE
173 *             - bAdjustOrientation must be set to M4OSA_TRUE or M4OSA_FALSE
174 *             - (MediaRendering is not handled : output image resolution is always
175                 set according to BestFit criteria)
176 *            bDiscardExif and bAdjustOrientation are still picture only parameters
177 ******************************************************************************
178 */
179typedef struct
180{
181    /**< Format of the output file */
182    M4VIDEOEDITING_FileType                 OutputFileType;
183    /**< Output video compression format, see enum */
184    M4VIDEOEDITING_VideoFormat              OutputVideoFormat;
185    /**< Output frame size : QQVGA, QCIF or SQCIF */
186    M4VIDEOEDITING_VideoFrameSize           OutputVideoFrameSize;
187    /**< Targeted Output framerate, see enum */
188    M4VIDEOEDITING_VideoFramerate           OutputVideoFrameRate;
189    /**< Format of the audio in the stream */
190    M4VIDEOEDITING_AudioFormat              OutputAudioFormat;
191    /**< Sampling frequency of the audio in the stream */
192    M4VIDEOEDITING_AudioSamplingFrequency   OutputAudioSamplingFrequency;
193    /**< Set to M4OSA_TRUE if the output audio is mono */
194    M4OSA_Bool                              bAudioMono;
195    /**< Output PCM file if not NULL */
196    M4OSA_Char                              *pOutputPCMfile;
197    /**< To crop, resize, or render black borders*/
198    M4MCS_MediaRendering                    MediaRendering;
199    /**< List of effects */
200    M4MCS_EffectSettings                    *pEffects;
201    /**< Number of effects in the above list */
202    M4OSA_UInt8                             nbEffects;
203
204    /*--- STILL PICTURE ---*/
205    /**< TRUE: Even if the input file contains an EXIF section,
206    the output file won't contain any EXIF section.*/
207    M4OSA_Bool                              bDiscardExif ;
208
209    /**< =TRUE : picture must be rotated if Exif tags hold a rotation info
210    (and rotation info is set to 0)*/
211    M4OSA_Bool                              bAdjustOrientation ;
212    /*--- STILL PICTURE ---*/
213} M4MCS_OutputParams;
214
215/*--- STILL PICTURE ---*/
216/**
217 ******************************************************************************
218 * enum      M4MCS_SPOutputResolution
219 * @brief    Still picture specific : MCS output targeted file resolution
220 ******************************************************************************
221 */
222typedef enum
223{
224    M4MCS_kResSameAsInput       = 0x00, /*width x height*/
225    M4MCS_kResQVGA              = 0x01, /*320x240*/
226    M4MCS_kResVGA               = 0x02, /*640x480*/
227    M4MCS_kResWQVGA             = 0x03, /*400x240*/
228    M4MCS_kResWVGA              = 0x04, /*800x480*/
229    M4MCS_kResXGA               = 0x05, /*1024x768*/
230    M4MCS_kResCustom            = 0xFF  /*Size is set via StillPictureCustomWidth/Height*/
231} M4MCS_SPOutputResolution ;
232
233
234/**
235 ******************************************************************************
236 * enum      M4MCS_SPStrategy
237 * @brief    Still picture specific : MCS strategy to configure the encoding parameters
238 ******************************************************************************
239 */
240typedef enum
241{
242    M4MCS_kFileSizeOnlyFixed            = 0x00, /*StillPictureResolution and
243                                                 QualityFactor are ignored*/
244    M4MCS_kFileSizeAndResFixed          = 0x01, /*QualityFactor is ignored*/
245    M4MCS_kQualityAndResFixed           = 0x02  /*OutputFileSize is ignored*/
246} M4MCS_SPStrategy ;
247
248
249/**
250 ******************************************************************************
251 * enum      M4MCS_SPCrop
252 * @brief    Still picture specific : indicate whether cropping should be done
253                                     before changing the resolution
254 ******************************************************************************
255 */
256typedef enum
257{
258    M4MCS_kNoCrop                = 0x00, /*No Cropping is performed*/
259    M4MCS_kCropBeforeResize      = 0x01  /*Input image is cropped (before changing resolution)*/
260} M4MCS_SPCrop ;
261
262/**
263 ******************************************************************************
264 * enum      M4MCS_ExifInfos
265 * @brief    Still picture specific : The following structure contains all available exif field
266 ******************************************************************************
267 */
268typedef struct {
269    M4OSA_Char* ImageTitle;              /* Image title */
270    M4OSA_Char* EquipmentManufacturer;   /* Image input equipment manufacturer */
271    M4OSA_Char* EquipmentModel;          /* Image input equipment model */
272    M4OSA_Char* Software;                /* Software used */
273    M4OSA_Char* Artist;                  /* Artist */
274    M4OSA_Char* Copyright;               /* Copyright */
275    M4OSA_Char* CreationDateTime;        /* Creation date and time */
276    M4OSA_UInt32 Orientation;            /* Orientation of the picture */
277    M4OSA_Char* LastChangeDateTime;      /* Last Change date and time*/
278    M4OSA_UInt32 PixelXDimension;        /* Image width*/
279    M4OSA_UInt32 PixelYDimension;        /* Image Height*/
280} M4MCS_ExifInfos;
281
282/*--- STILL PICTURE ---*/
283
284/**
285 ******************************************************************************
286 * struct    M4MCS_EncodingParams
287 * @brief    MCS file size, bitrate and cut parameters
288 * @note     Following parameters are used for still picture inputs :
289 *             - OutputFileSize
290 *             - StillPictureResolution
291 *             - QualityFactor
292 *             - StillPictureStrategy
293 *             - StillPictureCustomWidth/Height (if StillPictureResolution==M4MCS_kResCustom)
294 *            Still picture only parameters : StillPictureResolution, QualityFactor,
295 *            StillPictureStrategy and StillPictureCustomWidth/Height
296 ******************************************************************************
297 */
298typedef struct
299{
300    M4VIDEOEDITING_Bitrate    OutputVideoBitrate;     /**< Targeted video bitrate */
301    M4VIDEOEDITING_Bitrate    OutputAudioBitrate;     /**< Targeted audio bitrate */
302    M4OSA_UInt32              BeginCutTime;           /**< Beginning cut time in input file */
303    M4OSA_UInt32              EndCutTime;             /**< End cut time in input file */
304    M4OSA_UInt32              OutputFileSize;         /**< Expected resulting file size */
305    M4OSA_UInt32              OutputVideoTimescale;   /**< Optional parameter used to fix a
306                                                           timescale during transcoding */
307
308    /*--- STILL PICTURE ---*/
309    M4OSA_Int32               QualityFactor ;         /**< =-1 (undefined) or 0(lowest)..
310                                                            50(best) : This parameter is the
311                                                            quality indication for the JPEG output
312                                                            file (if =-1 the MCS will set quality
313                                                            automatically)*/
314    M4MCS_SPStrategy            StillPictureStrategy ; /**< Defines which input parameters
315                                                            will be taken into account by MCS*/
316    M4MCS_SPOutputResolution    StillPictureResolution;/**< Desired output resolution for
317                                                            a still picture file */
318    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image width */
319    M4OSA_UInt32                StillPictureCustomWidth;
320    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image height */
321    M4OSA_UInt32                StillPictureCustomHeight;
322    /**< Indicate whether Crop should be performed */
323    M4MCS_SPCrop                StillPictureCrop;
324    /**< (only if cropping) X coordinate of topleft corner of the crop window */
325    M4OSA_UInt32                StillPictureCrop_X;
326    /**< (only if cropping) Y coordinate of topleft corner of the crop window */
327    M4OSA_UInt32                StillPictureCrop_Y;
328    /**< (only if cropping) Width of the crop window (in pixels) */
329    M4OSA_UInt32                StillPictureCrop_W;
330    /**< (only if cropping) Height of the crop window (in pixels) */
331    M4OSA_UInt32                StillPictureCrop_H;
332    /*--- STILL PICTURE ---*/
333} M4MCS_EncodingParams;
334
335/**
336 ******************************************************************************
337 * M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
338 * @brief    Get the MCS version.
339 * @note Can be called anytime. Do not need any context.
340 * @param    pVersionInfo        (OUT) Pointer to a version info structure
341 * @return   M4NO_ERROR:         No error
342 * @return   M4ERR_PARAMETER:    pVersionInfo is M4OSA_NULL (If Debug Level >= 2)
343 ******************************************************************************
344 */
345M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
346
347/**
348 ******************************************************************************
349 * M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
350                        M4OSA_FileWriterPointer* pFileWritePtrFct);
351 * @brief    Initializes the MCS (allocates an execution context).
352 * @note
353 * @param    pContext            (OUT) Pointer on the MCS context to allocate
354 * @param    pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
355 * @param    pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
356 * @return   M4NO_ERROR:         No error
357 * @return   M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (If Debug Level >= 2)
358 * @return   M4ERR_ALLOC:        There is no more available memory
359 ******************************************************************************
360 */
361M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
362                      M4OSA_FileWriterPointer* pFileWritePtrFct);
363
364/**
365 ******************************************************************************
366 * M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, M4OSA_Void* pFileOut,
367                          M4OSA_UInt32 uiMaxMetadataSize);
368 * @brief   Set the MCS input and output files.
369 * @note    It opens the input file, but the output file is not created yet.
370 *          In case of still picture, four InputFileType are possible
371 *          (M4VIDEOEDITING_kFileType_JPG/BMP/GIF/PNG
372 *          If one of them is set, the OutputFileType SHALL be set to M4VIDEOEDITING_kFileType_JPG
373 * @param   pContext            (IN) MCS context
374 * @param   pFileIn             (IN) Input file to transcode (The type of this parameter
375 *                                    (URL, pipe...) depends on the OSAL implementation).
376 * @param   mediaType           (IN) Container type (.3gp,.amr, ...) of input file.
377 * @param   pFileOut            (IN) Output file to create  (The type of this parameter
378 *                                    (URL, pipe...) depends on the OSAL implementation).
379 * @param   pTempFile           (IN) Temporary file for the constant memory writer to store
380 *                                    metadata ("moov.bin").
381 * @return  M4NO_ERROR:         No error
382 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
383 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
384 * @return  M4ERR_ALLOC:        There is no more available memory
385 * @return  M4ERR_FILE_NOT_FOUND:   The input file has not been found
386 * @return  M4MCS_ERR_INVALID_INPUT_FILE:   The input file is not a valid file, or is corrupted
387 * @return  M4MCS_ERR_INPUT_FILE_CONTAINS_NO_SUPPORTED_STREAM:  The input file contains no
388 *                                                               supported audio or video stream
389 ******************************************************************************
390 */
391M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn,
392                     M4VIDEOEDITING_FileType InputFileType,
393                     M4OSA_Void* pFileOut, M4OSA_Void* pTempFile);
394
395/**
396 ******************************************************************************
397 * M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
398 * @brief   Perform one step of trancoding.
399 * @note
400 * @param   pContext            (IN) MCS context
401 * @param   pProgress           (OUT) Progress percentage (0 to 100) of the transcoding
402 * @note    pProgress must be a valid address.
403 * @return  M4NO_ERROR:         No error
404 * @return  M4ERR_PARAMETER:    One of the parameters is M4OSA_NULL (debug only)
405 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
406 * @return  M4MCS_WAR_TRANSCODING_DONE: Transcoding is over, user should now call M4MCS_close()
407 * @return  M4MCS_ERR_AUDIO_CONVERSION_FAILED: The audio conversion (AAC to AMR-NB, MP3) failed
408 * @return  M4MCS_ERR_INVALID_AAC_SAMPLING_FREQUENCY: The input file contains an AAC audio track
409 *                                                     with an invalid sampling frequency
410 *                                                     (should never happen)
411 * @return  M4MCS_WAR_PICTURE_AUTO_RESIZE: Picture will be automatically resized to fit
412 *                                          into requirements
413 ******************************************************************************
414 */
415M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
416
417/**
418 ******************************************************************************
419 * M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
420 * @brief   Pause the transcoding i.e. release the (external hardware) video decoder.
421 * @note    This function is not needed if no hardware accelerators are used.
422 *          In that case, pausing the MCS is simply achieved by temporarily suspending
423 *          the M4MCS_step function calls.
424 * @param   pContext            (IN) MCS context
425 * @return  M4NO_ERROR:         No error
426 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
427 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
428 ******************************************************************************
429 */
430M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
431
432/**
433 ******************************************************************************
434 * M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
435 * @brief   Resume the transcoding after a pause (see M4MCS_pause).
436 * @note    This function is not needed if no hardware accelerators are used.
437 *          In that case, resuming the MCS is simply achieved by calling
438 *          the M4MCS_step function.
439 * @param   pContext            (IN) MCS context
440 * @return  M4NO_ERROR:         No error
441 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
442 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
443 ******************************************************************************
444 */
445M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
446
447/**
448 ******************************************************************************
449 * M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
450 * @brief    Finish the MCS transcoding.
451 * @note The output 3GPP file is ready to be played after this call
452 * @param    pContext            (IN) MCS context
453 * @return   M4NO_ERROR:         No error
454 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
455 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
456 ******************************************************************************
457 */
458M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
459
460/**
461 ******************************************************************************
462 * M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
463 * @brief    Free all resources used by the MCS.
464 * @note The context is no more valid after this call
465 * @param    pContext            (IN) MCS context
466 * @return   M4NO_ERROR:         No error
467 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
468 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
469 ******************************************************************************
470 */
471M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
472
473/**
474 ******************************************************************************
475 * M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
476 * @brief    Finish the MCS transcoding and free all resources used by the MCS
477 *          whatever the state is.
478 * @note    The context is no more valid after this call
479 * @param    pContext            (IN) MCS context
480 * @return    M4NO_ERROR:            No error
481 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
482 ******************************************************************************
483 */
484M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
485
486/**
487 ******************************************************************************
488 * M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
489 *                                          M4VIDEOEDITING_ClipProperties* pFileProperties);
490 * @brief   Retrieves the properties of the audio and video streams from the input file.
491 * @param   pContext            (IN) MCS context
492 * @param   pProperties         (OUT) Pointer on an allocated M4VIDEOEDITING_ClipProperties
493                                structure which is filled with the input stream properties.
494 * @note    The structure pProperties must be allocated and further de-allocated
495            by the application. The function must be called in the opened state.
496 * @return  M4NO_ERROR:         No error
497 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
498 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
499 ******************************************************************************
500 */
501M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
502                                        M4VIDEOEDITING_ClipProperties *pFileProperties);
503
504/**
505 ******************************************************************************
506 * M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
507 * @brief   Set the MCS video output parameters.
508 * @note    Must be called after M4MCS_open. Must be called before M4MCS_step.
509 * @param   pContext            (IN) MCS context
510 * @param   pParams             (IN/OUT) Transcoding parameters
511 * @return  M4NO_ERROR:         No error
512 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
513 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
514 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_SIZE_FOR_H263 : Output video frame size parameter is
515 *                                                          incompatible with H263 encoding
516 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_RATE_FOR_H263 : Output video frame size parameter is
517 *                                                          incompatible with H263 encoding
518 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FORMAT     : Undefined output video format parameter
519 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE : Undefined output video frame size
520 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_RATE : Undefined output video frame rate
521 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_AUDIO_FORMAT : Undefined output audio format parameter
522 * @return  M4MCS_ERR_DURATION_IS_NULL : Specified output parameters define a null duration stream
523 *                                        (no audio and video)
524 ******************************************************************************
525 */
526M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
527
528/**
529 ******************************************************************************
530 * M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
531 * @brief   Set the values of the encoding parameters
532 * @note    Must be called before M4MCS_checkParamsAndStart().
533 * @param   pContext           (IN) MCS context
534 * @param   pRates             (IN) Transcoding parameters
535 * @return  M4NO_ERROR:         No error
536 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
537 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
538 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
539 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
540 *                                           12.2 for amr, 8 for mp3)
541 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
542 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
543 *                                                     the input clip duration
544 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
545 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
546 *                                            file at given bitrates
547 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
548 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low
549 ******************************************************************************
550 */
551M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
552
553/**
554 ******************************************************************************
555 * M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
556 * @brief   Get the extended values of the encoding parameters
557 * @note    Could be called after M4MCS_setEncodingParams.
558 * @param   pContext           (IN) MCS context
559 * @param   pRates             (OUT) Transcoding parameters
560 * @return  M4NO_ERROR:         No error
561 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
562 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
563 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Encoding settings would produce a
564 *                                              null duration clip = encoding is impossible
565 ******************************************************************************
566 */
567M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
568
569/**
570 ******************************************************************************
571 * M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext)
572 * @brief
573 * @note
574 * @param   pContext           (IN) MCS context
575 * @return  M4NO_ERROR:         No error
576 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
577 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
578 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
579 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
580 *                                           12.2 for amr, 8 for mp3)
581 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
582 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
583 *                                                    the input clip duration
584 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
585 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
586 *                                            file at given bitrates
587 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
588 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW:  Video bitrate too low
589 ******************************************************************************
590 */
591M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext);
592
593/**
594 ******************************************************************************
595 * M4OSA_ERR M4MCS_registerExternalVideoDecoder(M4MCS_Context pContext,
596 *                                     M4VD_VideoType decoderType,
597 *                                     M4VD_Interface*    pDecoderInterface,
598 *                                     M4OSA_Void* pUserData)
599 * @brief    Registers an external Video decoder
600 * @note
601 * @param   pContext           (IN) MCS context
602 * @param   decoderType        (IN) Type of decoder (MPEG4 ...)
603 * @param   pDecoderInterface  (IN) Decoder interface
604 * @param   pUserData          (IN) Pointer on a user data to give to external decoder
605 * @return  M4NO_ERROR:         No error
606 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
607 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
608 ******************************************************************************
609 */
610M4OSA_ERR M4MCS_registerExternalVideoDecoder(M4MCS_Context pContext,
611                                     M4VD_VideoType decoderType,
612                                     M4VD_Interface*    pDecoderInterface,
613                                     M4OSA_Void* pUserData);
614
615M4OSA_ERR M4MCS_registerExternalVideoEncoder(M4MCS_Context pContext,
616                                     M4VE_EncoderType encoderType,
617                                     M4VE_Interface*    pEncoderInterface,
618                                     M4OSA_Void* pUserData);
619
620
621/**
622 ************************************************************************
623 * M4OSA_ERR M4MCS_registerExternalAudioDecoder(M4MCS_Context pContext,
624 *                                    M4AD_Type decoderType,
625 *                                    M4AD_Interface *pDecoderInterface);
626 * @brief    This function will register a specific external audio decoder.
627 * @note    According to the decoderType, this function will store in the internal context
628 *          the decoder interface.
629 * @param    context            (IN/OUT) MCS context.
630 * @param    decoderType        (IN) Audio decoder type
631 * @param    pDecoderInterface  (IN) Audio decoder interface.
632 * @return   M4NO_ERROR:        No error
633 * @return   M4ERR_PARAMETER:   A parameter is null, or the decoder type is invalid(in DEBUG only)
634 ************************************************************************
635 */
636M4OSA_ERR M4MCS_registerExternalAudioDecoder(M4MCS_Context pContext,
637                                    M4AD_Type decoderType,
638                                    M4AD_Interface *pDecoderInterface);
639
640
641/**
642 ******************************************************************************
643 * M4OSA_ERR   M4MCS_registerExternalAudioEncoder(M4MCS_Context pContext,
644 *                                    M4ENCODER_AudioFormat mediaType,
645 *                                    M4ENCODER_AudioGlobalInterface *pEncGlobalInterface)
646 * @brief    This function will register a specific external audio encoder.
647 * @note    According to the Mediatype, this function will store in the internal context
648 *          the encoder interface.
649 * @param    pContext:                (IN) Execution context.
650 * @param    mediaType:                (IN) The media type.
651 * @param    pEncGlobalInterface:    (OUT) the encoder interface functions.
652 * @return    M4NO_ERROR: there is no error
653 * @return    M4ERR_PARAMETER: pContext or pEncGlobalInterface is M4OSA_NULL (debug only)
654 ******************************************************************************
655 */
656M4OSA_ERR M4MCS_registerExternalAudioEncoder(M4MCS_Context pContext,
657                                    M4ENCODER_AudioFormat MediaType,
658                                    M4ENCODER_AudioGlobalInterface *pEncGlobalInterface);
659
660
661#ifdef __cplusplus
662}
663#endif /* __cplusplus */
664
665#endif /* __M4MCS_API_H__ */
666
667