M4MCS_API.h revision 0a389ab70db304fb840e33f33781ecc0503eae3c 
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/**
50 * To enable external audio codecs registering*/
51#include "M4AD_Common.h"
52#include "M4ENCODER_AudioCommon.h"
53
54#ifdef __cplusplus
55extern "C" {
56#endif
57
58/**
59 *    Public type of the MCS context */
60typedef M4OSA_Void* M4MCS_Context;
61
62
63/**
64 ******************************************************************************
65 * enum        M4MCS_MediaRendering
66 * @brief    This enum defines different media rendering
67 ******************************************************************************
68 */
69typedef enum
70{
71    M4MCS_kResizing = 0,    /**< The media is resized, the aspect ratio can be
72                              different from the original one.
73                              All of the media is rendered */
74    M4MCS_kCropping,        /**< The media is cropped, the aspect ratio is the
75                              same as the original one.
76                              The media is not rendered entirely */
77    M4MCS_kBlackBorders     /**< Black borders are rendered in order to keep the
78                              original aspect ratio. All the media is rendered */
79} M4MCS_MediaRendering;
80
81
82/**
83 ******************************************************************************
84 * struct   M4MCS_ExternalProgress
85 * @brief   This structure contains information provided to the external Effect functions
86 * @note    The uiProgress value should be enough for most cases
87 ******************************************************************************
88 */
89typedef struct
90{
91    M4OSA_UInt32    uiProgress;     /**< Progress of the Effect from 0 to 1000 (one thousand) */
92    M4OSA_UInt32    uiClipTime;     /**< Current time, in milliseconds,
93                                          in the current clip time-line */
94    M4OSA_UInt32    uiOutputTime;   /**< Current time, in milliseconds,
95                                          in the output clip time-line */
96
97} M4MCS_ExternalProgress;
98
99
100/**
101 ******************************************************************************
102 * enum     M4MCS_AudioEffectType
103 * @brief   This enumeration defines the audio effect types of the MCS
104 ******************************************************************************
105 */
106typedef enum
107{
108    M4MCS_kAudioEffectType_None    = 0,
109    M4MCS_kAudioEffectType_FadeIn  = 8, /**< Intended for begin effect */
110    M4MCS_kAudioEffectType_FadeOut = 16, /**< Intended for end effect */
111    M4MCS_kAudioEffectType_External = 256
112
113} M4MCS_AudioEffectType;
114
115
116/**
117 ******************************************************************************
118 * prototype    M4MCS_editAudioEffectFct
119 * @brief       Audio effect functions implemented by the integrator
120 *              must match this prototype.
121 * @note        The function is provided with the original PCM data buffer and its size.
122 *              Audio effect have to be applied on it.
123 *              The progress of the effect is given, on a scale from 0 to 1000.
124 *              When the effect function is called, all the buffers are valid and
125 *              owned by the MCS.
126 *
127 * @param   pFunctionContext    (IN) The function context, previously set by the integrator
128 * @param   pPCMdata            (IN/OUT) valid PCM data buffer
129 * @param   uiPCMsize           (IN/OUT) PCM data buffer corresponding size
130 * @param   pProgress           (IN) Set of information about the audio effect progress.
131 *
132 * @return  M4NO_ERROR:         No error
133 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
134 ******************************************************************************
135 */
136typedef M4OSA_ERR (*M4MCS_editAudioEffectFct)
137(
138    M4OSA_Void *pFunctionContext,
139    M4OSA_Int16 *pPCMdata,
140    M4OSA_UInt32 uiPCMsize,
141    M4MCS_ExternalProgress *pProgress
142);
143
144
145/**
146 ******************************************************************************
147 * struct   M4MCS_EffectSettings
148 * @brief   This structure defines an audio effect for the edition.
149 ******************************************************************************
150 */
151typedef struct
152{
153    M4OSA_UInt32                 uiStartTime;              /**< In ms */
154    M4OSA_UInt32                 uiDuration;               /**< In ms */
155    M4MCS_editAudioEffectFct     ExtAudioEffectFct;        /**< External effect function */
156    M4OSA_Void                   *pExtAudioEffectFctCtxt;  /**< Context given to the external
157                                                                effect function */
158    M4MCS_AudioEffectType        AudioEffectType;         /**< None, FadeIn, FadeOut */
159
160} M4MCS_EffectSettings;
161
162
163/**
164 ******************************************************************************
165 * struct    M4MCS_OutputParams
166 * @brief    MCS Output parameters
167 * @note     Following parameters are used for still picture inputs :
168 *             - OutputFileType (must be set to M4VIDEOEDITING_kFileType_JPG)
169 *             - bDiscardExif must be set to M4OSA_TRUE or M4OSA_FALSE
170 *             - bAdjustOrientation must be set to M4OSA_TRUE or M4OSA_FALSE
171 *             - (MediaRendering is not handled : output image resolution is always
172                 set according to BestFit criteria)
173 *            bDiscardExif and bAdjustOrientation are still picture only parameters
174 ******************************************************************************
175 */
176typedef struct
177{
178    /**< Format of the output file */
179    M4VIDEOEDITING_FileType                 OutputFileType;
180    /**< Output video compression format, see enum */
181    M4VIDEOEDITING_VideoFormat              OutputVideoFormat;
182    /**< Output frame size : QQVGA, QCIF or SQCIF */
183    M4VIDEOEDITING_VideoFrameSize           OutputVideoFrameSize;
184    /**< Targeted Output framerate, see enum */
185    M4VIDEOEDITING_VideoFramerate           OutputVideoFrameRate;
186    /**< Format of the audio in the stream */
187    M4VIDEOEDITING_AudioFormat              OutputAudioFormat;
188    /**< Sampling frequency of the audio in the stream */
189    M4VIDEOEDITING_AudioSamplingFrequency   OutputAudioSamplingFrequency;
190    /**< Set to M4OSA_TRUE if the output audio is mono */
191    M4OSA_Bool                              bAudioMono;
192    /**< Output PCM file if not NULL */
193    M4OSA_Char                              *pOutputPCMfile;
194    /**< To crop, resize, or render black borders*/
195    M4MCS_MediaRendering                    MediaRendering;
196    /**< List of effects */
197    M4MCS_EffectSettings                    *pEffects;
198    /**< Number of effects in the above list */
199    M4OSA_UInt8                             nbEffects;
200
201    /*--- STILL PICTURE ---*/
202    /**< TRUE: Even if the input file contains an EXIF section,
203    the output file won't contain any EXIF section.*/
204    M4OSA_Bool                              bDiscardExif ;
205
206    /**< =TRUE : picture must be rotated if Exif tags hold a rotation info
207    (and rotation info is set to 0)*/
208    M4OSA_Bool                              bAdjustOrientation ;
209    /*--- STILL PICTURE ---*/
210} M4MCS_OutputParams;
211
212/*--- STILL PICTURE ---*/
213/**
214 ******************************************************************************
215 * enum      M4MCS_SPOutputResolution
216 * @brief    Still picture specific : MCS output targeted file resolution
217 ******************************************************************************
218 */
219typedef enum
220{
221    M4MCS_kResSameAsInput       = 0x00, /*width x height*/
222    M4MCS_kResQVGA              = 0x01, /*320x240*/
223    M4MCS_kResVGA               = 0x02, /*640x480*/
224    M4MCS_kResWQVGA             = 0x03, /*400x240*/
225    M4MCS_kResWVGA              = 0x04, /*800x480*/
226    M4MCS_kResXGA               = 0x05, /*1024x768*/
227    M4MCS_kResCustom            = 0xFF  /*Size is set via StillPictureCustomWidth/Height*/
228} M4MCS_SPOutputResolution ;
229
230
231/**
232 ******************************************************************************
233 * enum      M4MCS_SPStrategy
234 * @brief    Still picture specific : MCS strategy to configure the encoding parameters
235 ******************************************************************************
236 */
237typedef enum
238{
239    M4MCS_kFileSizeOnlyFixed            = 0x00, /*StillPictureResolution and
240                                                 QualityFactor are ignored*/
241    M4MCS_kFileSizeAndResFixed          = 0x01, /*QualityFactor is ignored*/
242    M4MCS_kQualityAndResFixed           = 0x02  /*OutputFileSize is ignored*/
243} M4MCS_SPStrategy ;
244
245
246/**
247 ******************************************************************************
248 * enum      M4MCS_SPCrop
249 * @brief    Still picture specific : indicate whether cropping should be done
250                                     before changing the resolution
251 ******************************************************************************
252 */
253typedef enum
254{
255    M4MCS_kNoCrop                = 0x00, /*No Cropping is performed*/
256    M4MCS_kCropBeforeResize      = 0x01  /*Input image is cropped (before changing resolution)*/
257} M4MCS_SPCrop ;
258
259
260/**
261 ******************************************************************************
262 * struct    M4MCS_EncodingParams
263 * @brief    MCS file size, bitrate and cut parameters
264 * @note     Following parameters are used for still picture inputs :
265 *             - OutputFileSize
266 *             - StillPictureResolution
267 *             - QualityFactor
268 *             - StillPictureStrategy
269 *             - StillPictureCustomWidth/Height (if StillPictureResolution==M4MCS_kResCustom)
270 *            Still picture only parameters : StillPictureResolution, QualityFactor,
271 *            StillPictureStrategy and StillPictureCustomWidth/Height
272 ******************************************************************************
273 */
274typedef struct
275{
276    M4VIDEOEDITING_Bitrate    OutputVideoBitrate;     /**< Targeted video bitrate */
277    M4VIDEOEDITING_Bitrate    OutputAudioBitrate;     /**< Targeted audio bitrate */
278    M4OSA_UInt32              BeginCutTime;           /**< Beginning cut time in input file */
279    M4OSA_UInt32              EndCutTime;             /**< End cut time in input file */
280    M4OSA_UInt32              OutputFileSize;         /**< Expected resulting file size */
281    M4OSA_UInt32              OutputVideoTimescale;   /**< Optional parameter used to fix a
282                                                           timescale during transcoding */
283
284    /*--- STILL PICTURE ---*/
285    M4OSA_Int32               QualityFactor ;         /**< =-1 (undefined) or 0(lowest)..
286                                                            50(best) : This parameter is the
287                                                            quality indication for the JPEG output
288                                                            file (if =-1 the MCS will set quality
289                                                            automatically)*/
290    M4MCS_SPStrategy            StillPictureStrategy ; /**< Defines which input parameters
291                                                            will be taken into account by MCS*/
292    M4MCS_SPOutputResolution    StillPictureResolution;/**< Desired output resolution for
293                                                            a still picture file */
294    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image width */
295    M4OSA_UInt32                StillPictureCustomWidth;
296    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image height */
297    M4OSA_UInt32                StillPictureCustomHeight;
298    /**< Indicate whether Crop should be performed */
299    M4MCS_SPCrop                StillPictureCrop;
300    /**< (only if cropping) X coordinate of topleft corner of the crop window */
301    M4OSA_UInt32                StillPictureCrop_X;
302    /**< (only if cropping) Y coordinate of topleft corner of the crop window */
303    M4OSA_UInt32                StillPictureCrop_Y;
304    /**< (only if cropping) Width of the crop window (in pixels) */
305    M4OSA_UInt32                StillPictureCrop_W;
306    /**< (only if cropping) Height of the crop window (in pixels) */
307    M4OSA_UInt32                StillPictureCrop_H;
308    /*--- STILL PICTURE ---*/
309} M4MCS_EncodingParams;
310
311/**
312 ******************************************************************************
313 * M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
314 * @brief    Get the MCS version.
315 * @note Can be called anytime. Do not need any context.
316 * @param    pVersionInfo        (OUT) Pointer to a version info structure
317 * @return   M4NO_ERROR:         No error
318 * @return   M4ERR_PARAMETER:    pVersionInfo is M4OSA_NULL (If Debug Level >= 2)
319 ******************************************************************************
320 */
321M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
322
323/**
324 ******************************************************************************
325 * M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
326                        M4OSA_FileWriterPointer* pFileWritePtrFct);
327 * @brief    Initializes the MCS (allocates an execution context).
328 * @note
329 * @param    pContext            (OUT) Pointer on the MCS context to allocate
330 * @param    pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
331 * @param    pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
332 * @return   M4NO_ERROR:         No error
333 * @return   M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (If Debug Level >= 2)
334 * @return   M4ERR_ALLOC:        There is no more available memory
335 ******************************************************************************
336 */
337M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
338                      M4OSA_FileWriterPointer* pFileWritePtrFct);
339
340/**
341 ******************************************************************************
342 * M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, M4OSA_Void* pFileOut,
343                          M4OSA_UInt32 uiMaxMetadataSize);
344 * @brief   Set the MCS input and output files.
345 * @note    It opens the input file, but the output file is not created yet.
346 *          In case of still picture, four InputFileType are possible
347 *          (M4VIDEOEDITING_kFileType_JPG/BMP/GIF/PNG
348 *          If one of them is set, the OutputFileType SHALL be set to M4VIDEOEDITING_kFileType_JPG
349 * @param   pContext            (IN) MCS context
350 * @param   pFileIn             (IN) Input file to transcode (The type of this parameter
351 *                                    (URL, pipe...) depends on the OSAL implementation).
352 * @param   mediaType           (IN) Container type (.3gp,.amr, ...) of input file.
353 * @param   pFileOut            (IN) Output file to create  (The type of this parameter
354 *                                    (URL, pipe...) depends on the OSAL implementation).
355 * @param   pTempFile           (IN) Temporary file for the constant memory writer to store
356 *                                    metadata ("moov.bin").
357 * @return  M4NO_ERROR:         No error
358 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
359 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
360 * @return  M4ERR_ALLOC:        There is no more available memory
361 * @return  M4ERR_FILE_NOT_FOUND:   The input file has not been found
362 * @return  M4MCS_ERR_INVALID_INPUT_FILE:   The input file is not a valid file, or is corrupted
363 * @return  M4MCS_ERR_INPUT_FILE_CONTAINS_NO_SUPPORTED_STREAM:  The input file contains no
364 *                                                               supported audio or video stream
365 ******************************************************************************
366 */
367M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn,
368                     M4VIDEOEDITING_FileType InputFileType,
369                     M4OSA_Void* pFileOut, M4OSA_Void* pTempFile);
370
371/**
372 ******************************************************************************
373 * M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
374 * @brief   Perform one step of trancoding.
375 * @note
376 * @param   pContext            (IN) MCS context
377 * @param   pProgress           (OUT) Progress percentage (0 to 100) of the transcoding
378 * @note    pProgress must be a valid address.
379 * @return  M4NO_ERROR:         No error
380 * @return  M4ERR_PARAMETER:    One of the parameters is M4OSA_NULL (debug only)
381 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
382 * @return  M4MCS_WAR_TRANSCODING_DONE: Transcoding is over, user should now call M4MCS_close()
383 * @return  M4MCS_ERR_AUDIO_CONVERSION_FAILED: The audio conversion (AAC to AMR-NB, MP3) failed
384 * @return  M4MCS_ERR_INVALID_AAC_SAMPLING_FREQUENCY: The input file contains an AAC audio track
385 *                                                     with an invalid sampling frequency
386 *                                                     (should never happen)
387 * @return  M4MCS_WAR_PICTURE_AUTO_RESIZE: Picture will be automatically resized to fit
388 *                                          into requirements
389 ******************************************************************************
390 */
391M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
392
393/**
394 ******************************************************************************
395 * M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
396 * @brief   Pause the transcoding i.e. release the (external hardware) video decoder.
397 * @note    This function is not needed if no hardware accelerators are used.
398 *          In that case, pausing the MCS is simply achieved by temporarily suspending
399 *          the M4MCS_step function calls.
400 * @param   pContext            (IN) MCS context
401 * @return  M4NO_ERROR:         No error
402 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
403 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
404 ******************************************************************************
405 */
406M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
407
408/**
409 ******************************************************************************
410 * M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
411 * @brief   Resume the transcoding after a pause (see M4MCS_pause).
412 * @note    This function is not needed if no hardware accelerators are used.
413 *          In that case, resuming the MCS is simply achieved by calling
414 *          the M4MCS_step function.
415 * @param   pContext            (IN) MCS context
416 * @return  M4NO_ERROR:         No error
417 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
418 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
419 ******************************************************************************
420 */
421M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
422
423/**
424 ******************************************************************************
425 * M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
426 * @brief    Finish the MCS transcoding.
427 * @note The output 3GPP file is ready to be played after this call
428 * @param    pContext            (IN) MCS context
429 * @return   M4NO_ERROR:         No error
430 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
431 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
432 ******************************************************************************
433 */
434M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
435
436/**
437 ******************************************************************************
438 * M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
439 * @brief    Free all resources used by the MCS.
440 * @note The context is no more valid after this call
441 * @param    pContext            (IN) MCS context
442 * @return   M4NO_ERROR:         No error
443 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
444 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
445 ******************************************************************************
446 */
447M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
448
449/**
450 ******************************************************************************
451 * M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
452 * @brief    Finish the MCS transcoding and free all resources used by the MCS
453 *          whatever the state is.
454 * @note    The context is no more valid after this call
455 * @param    pContext            (IN) MCS context
456 * @return    M4NO_ERROR:            No error
457 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
458 ******************************************************************************
459 */
460M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
461
462/**
463 ******************************************************************************
464 * M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
465 *                                          M4VIDEOEDITING_ClipProperties* pFileProperties);
466 * @brief   Retrieves the properties of the audio and video streams from the input file.
467 * @param   pContext            (IN) MCS context
468 * @param   pProperties         (OUT) Pointer on an allocated M4VIDEOEDITING_ClipProperties
469                                structure which is filled with the input stream properties.
470 * @note    The structure pProperties must be allocated and further de-allocated
471            by the application. The function must be called in the opened state.
472 * @return  M4NO_ERROR:         No error
473 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
474 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
475 ******************************************************************************
476 */
477M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
478                                        M4VIDEOEDITING_ClipProperties *pFileProperties);
479
480/**
481 ******************************************************************************
482 * M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
483 * @brief   Set the MCS video output parameters.
484 * @note    Must be called after M4MCS_open. Must be called before M4MCS_step.
485 * @param   pContext            (IN) MCS context
486 * @param   pParams             (IN/OUT) Transcoding parameters
487 * @return  M4NO_ERROR:         No error
488 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
489 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
490 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_SIZE_FOR_H263 : Output video frame size parameter is
491 *                                                          incompatible with H263 encoding
492 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_RATE_FOR_H263 : Output video frame size parameter is
493 *                                                          incompatible with H263 encoding
494 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FORMAT     : Undefined output video format parameter
495 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE : Undefined output video frame size
496 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_RATE : Undefined output video frame rate
497 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_AUDIO_FORMAT : Undefined output audio format parameter
498 * @return  M4MCS_ERR_DURATION_IS_NULL : Specified output parameters define a null duration stream
499 *                                        (no audio and video)
500 ******************************************************************************
501 */
502M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
503
504/**
505 ******************************************************************************
506 * M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
507 * @brief   Set the values of the encoding parameters
508 * @note    Must be called before M4MCS_checkParamsAndStart().
509 * @param   pContext           (IN) MCS context
510 * @param   pRates             (IN) 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_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
515 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
516 *                                           12.2 for amr, 8 for mp3)
517 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
518 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
519 *                                                     the input clip duration
520 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
521 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
522 *                                            file at given bitrates
523 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
524 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low
525 ******************************************************************************
526 */
527M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
528
529/**
530 ******************************************************************************
531 * M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
532 * @brief   Get the extended values of the encoding parameters
533 * @note    Could be called after M4MCS_setEncodingParams.
534 * @param   pContext           (IN) MCS context
535 * @param   pRates             (OUT) Transcoding parameters
536 * @return  M4NO_ERROR:         No error
537 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
538 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
539 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Encoding settings would produce a
540 *                                              null duration clip = encoding is impossible
541 ******************************************************************************
542 */
543M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
544
545/**
546 ******************************************************************************
547 * M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext)
548 * @brief
549 * @note
550 * @param   pContext           (IN) MCS context
551 * @return  M4NO_ERROR:         No error
552 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
553 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
554 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
555 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
556 *                                           12.2 for amr, 8 for mp3)
557 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
558 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
559 *                                                    the input clip duration
560 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
561 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
562 *                                            file at given bitrates
563 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
564 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW:  Video bitrate too low
565 ******************************************************************************
566 */
567M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext);
568
569#ifdef __cplusplus
570}
571#endif /* __cplusplus */
572
573#endif /* __M4MCS_API_H__ */
574
575