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