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    M4OSA_Int32 outputVideoProfile;
210    M4OSA_Int32 outputVideoLevel;
211} M4MCS_OutputParams;
212
213/*--- STILL PICTURE ---*/
214/**
215 ******************************************************************************
216 * enum      M4MCS_SPOutputResolution
217 * @brief    Still picture specific : MCS output targeted file resolution
218 ******************************************************************************
219 */
220typedef enum
221{
222    M4MCS_kResSameAsInput       = 0x00, /*width x height*/
223    M4MCS_kResQVGA              = 0x01, /*320x240*/
224    M4MCS_kResVGA               = 0x02, /*640x480*/
225    M4MCS_kResWQVGA             = 0x03, /*400x240*/
226    M4MCS_kResWVGA              = 0x04, /*800x480*/
227    M4MCS_kResXGA               = 0x05, /*1024x768*/
228    M4MCS_kResCustom            = 0xFF  /*Size is set via StillPictureCustomWidth/Height*/
229} M4MCS_SPOutputResolution ;
230
231
232/**
233 ******************************************************************************
234 * enum      M4MCS_SPStrategy
235 * @brief    Still picture specific : MCS strategy to configure the encoding parameters
236 ******************************************************************************
237 */
238typedef enum
239{
240    M4MCS_kFileSizeOnlyFixed            = 0x00, /*StillPictureResolution and
241                                                 QualityFactor are ignored*/
242    M4MCS_kFileSizeAndResFixed          = 0x01, /*QualityFactor is ignored*/
243    M4MCS_kQualityAndResFixed           = 0x02  /*OutputFileSize is ignored*/
244} M4MCS_SPStrategy ;
245
246
247/**
248 ******************************************************************************
249 * enum      M4MCS_SPCrop
250 * @brief    Still picture specific : indicate whether cropping should be done
251                                     before changing the resolution
252 ******************************************************************************
253 */
254typedef enum
255{
256    M4MCS_kNoCrop                = 0x00, /*No Cropping is performed*/
257    M4MCS_kCropBeforeResize      = 0x01  /*Input image is cropped (before changing resolution)*/
258} M4MCS_SPCrop ;
259
260
261/**
262 ******************************************************************************
263 * struct    M4MCS_EncodingParams
264 * @brief    MCS file size, bitrate and cut parameters
265 * @note     Following parameters are used for still picture inputs :
266 *             - OutputFileSize
267 *             - StillPictureResolution
268 *             - QualityFactor
269 *             - StillPictureStrategy
270 *             - StillPictureCustomWidth/Height (if StillPictureResolution==M4MCS_kResCustom)
271 *            Still picture only parameters : StillPictureResolution, QualityFactor,
272 *            StillPictureStrategy and StillPictureCustomWidth/Height
273 ******************************************************************************
274 */
275typedef struct
276{
277    M4VIDEOEDITING_Bitrate    OutputVideoBitrate;     /**< Targeted video bitrate */
278    M4VIDEOEDITING_Bitrate    OutputAudioBitrate;     /**< Targeted audio bitrate */
279    M4OSA_UInt32              BeginCutTime;           /**< Beginning cut time in input file */
280    M4OSA_UInt32              EndCutTime;             /**< End cut time in input file */
281    M4OSA_UInt32              OutputFileSize;         /**< Expected resulting file size */
282    M4OSA_UInt32              OutputVideoTimescale;   /**< Optional parameter used to fix a
283                                                           timescale during transcoding */
284
285    /*--- STILL PICTURE ---*/
286    M4OSA_Int32               QualityFactor ;         /**< =-1 (undefined) or 0(lowest)..
287                                                            50(best) : This parameter is the
288                                                            quality indication for the JPEG output
289                                                            file (if =-1 the MCS will set quality
290                                                            automatically)*/
291    M4MCS_SPStrategy            StillPictureStrategy ; /**< Defines which input parameters
292                                                            will be taken into account by MCS*/
293    M4MCS_SPOutputResolution    StillPictureResolution;/**< Desired output resolution for
294                                                            a still picture file */
295    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image width */
296    M4OSA_UInt32                StillPictureCustomWidth;
297    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image height */
298    M4OSA_UInt32                StillPictureCustomHeight;
299    /**< Indicate whether Crop should be performed */
300    M4MCS_SPCrop                StillPictureCrop;
301    /**< (only if cropping) X coordinate of topleft corner of the crop window */
302    M4OSA_UInt32                StillPictureCrop_X;
303    /**< (only if cropping) Y coordinate of topleft corner of the crop window */
304    M4OSA_UInt32                StillPictureCrop_Y;
305    /**< (only if cropping) Width of the crop window (in pixels) */
306    M4OSA_UInt32                StillPictureCrop_W;
307    /**< (only if cropping) Height of the crop window (in pixels) */
308    M4OSA_UInt32                StillPictureCrop_H;
309    /*--- STILL PICTURE ---*/
310} M4MCS_EncodingParams;
311
312/**
313 ******************************************************************************
314 * M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
315 * @brief    Get the MCS version.
316 * @note Can be called anytime. Do not need any context.
317 * @param    pVersionInfo        (OUT) Pointer to a version info structure
318 * @return   M4NO_ERROR:         No error
319 * @return   M4ERR_PARAMETER:    pVersionInfo is M4OSA_NULL (If Debug Level >= 2)
320 ******************************************************************************
321 */
322M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
323
324/**
325 ******************************************************************************
326 * M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
327                        M4OSA_FileWriterPointer* pFileWritePtrFct);
328 * @brief    Initializes the MCS (allocates an execution context).
329 * @note
330 * @param    pContext            (OUT) Pointer on the MCS context to allocate
331 * @param    pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
332 * @param    pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
333 * @return   M4NO_ERROR:         No error
334 * @return   M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (If Debug Level >= 2)
335 * @return   M4ERR_ALLOC:        There is no more available memory
336 ******************************************************************************
337 */
338M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
339                      M4OSA_FileWriterPointer* pFileWritePtrFct);
340
341/**
342 ******************************************************************************
343 * M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, M4OSA_Void* pFileOut,
344                          M4OSA_UInt32 uiMaxMetadataSize);
345 * @brief   Set the MCS input and output files.
346 * @note    It opens the input file, but the output file is not created yet.
347 *          In case of still picture, four InputFileType are possible
348 *          (M4VIDEOEDITING_kFileType_JPG/BMP/GIF/PNG
349 *          If one of them is set, the OutputFileType SHALL be set to M4VIDEOEDITING_kFileType_JPG
350 * @param   pContext            (IN) MCS context
351 * @param   pFileIn             (IN) Input file to transcode (The type of this parameter
352 *                                    (URL, pipe...) depends on the OSAL implementation).
353 * @param   mediaType           (IN) Container type (.3gp,.amr, ...) of input file.
354 * @param   pFileOut            (IN) Output file to create  (The type of this parameter
355 *                                    (URL, pipe...) depends on the OSAL implementation).
356 * @param   pTempFile           (IN) Temporary file for the constant memory writer to store
357 *                                    metadata ("moov.bin").
358 * @return  M4NO_ERROR:         No error
359 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
360 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
361 * @return  M4ERR_ALLOC:        There is no more available memory
362 * @return  M4ERR_FILE_NOT_FOUND:   The input file has not been found
363 * @return  M4MCS_ERR_INVALID_INPUT_FILE:   The input file is not a valid file, or is corrupted
364 * @return  M4MCS_ERR_INPUT_FILE_CONTAINS_NO_SUPPORTED_STREAM:  The input file contains no
365 *                                                               supported audio or video stream
366 ******************************************************************************
367 */
368M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn,
369                     M4VIDEOEDITING_FileType InputFileType,
370                     M4OSA_Void* pFileOut, M4OSA_Void* pTempFile);
371
372/**
373 ******************************************************************************
374 * M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
375 * @brief   Perform one step of trancoding.
376 * @note
377 * @param   pContext            (IN) MCS context
378 * @param   pProgress           (OUT) Progress percentage (0 to 100) of the transcoding
379 * @note    pProgress must be a valid address.
380 * @return  M4NO_ERROR:         No error
381 * @return  M4ERR_PARAMETER:    One of the parameters is M4OSA_NULL (debug only)
382 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
383 * @return  M4MCS_WAR_TRANSCODING_DONE: Transcoding is over, user should now call M4MCS_close()
384 * @return  M4MCS_ERR_AUDIO_CONVERSION_FAILED: The audio conversion (AAC to AMR-NB, MP3) failed
385 * @return  M4MCS_ERR_INVALID_AAC_SAMPLING_FREQUENCY: The input file contains an AAC audio track
386 *                                                     with an invalid sampling frequency
387 *                                                     (should never happen)
388 * @return  M4MCS_WAR_PICTURE_AUTO_RESIZE: Picture will be automatically resized to fit
389 *                                          into requirements
390 ******************************************************************************
391 */
392M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
393
394/**
395 ******************************************************************************
396 * M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
397 * @brief   Pause the transcoding i.e. release the (external hardware) video decoder.
398 * @note    This function is not needed if no hardware accelerators are used.
399 *          In that case, pausing the MCS is simply achieved by temporarily suspending
400 *          the M4MCS_step function calls.
401 * @param   pContext            (IN) MCS context
402 * @return  M4NO_ERROR:         No error
403 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
404 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
405 ******************************************************************************
406 */
407M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
408
409/**
410 ******************************************************************************
411 * M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
412 * @brief   Resume the transcoding after a pause (see M4MCS_pause).
413 * @note    This function is not needed if no hardware accelerators are used.
414 *          In that case, resuming the MCS is simply achieved by calling
415 *          the M4MCS_step function.
416 * @param   pContext            (IN) MCS context
417 * @return  M4NO_ERROR:         No error
418 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
419 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
420 ******************************************************************************
421 */
422M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
423
424/**
425 ******************************************************************************
426 * M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
427 * @brief    Finish the MCS transcoding.
428 * @note The output 3GPP file is ready to be played after this call
429 * @param    pContext            (IN) MCS context
430 * @return   M4NO_ERROR:         No error
431 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
432 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
433 ******************************************************************************
434 */
435M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
436
437/**
438 ******************************************************************************
439 * M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
440 * @brief    Free all resources used by the MCS.
441 * @note The context is no more valid after this call
442 * @param    pContext            (IN) MCS context
443 * @return   M4NO_ERROR:         No error
444 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
445 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
446 ******************************************************************************
447 */
448M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
449
450/**
451 ******************************************************************************
452 * M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
453 * @brief    Finish the MCS transcoding and free all resources used by the MCS
454 *          whatever the state is.
455 * @note    The context is no more valid after this call
456 * @param    pContext            (IN) MCS context
457 * @return    M4NO_ERROR:            No error
458 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
459 ******************************************************************************
460 */
461M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
462
463/**
464 ******************************************************************************
465 * M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
466 *                                          M4VIDEOEDITING_ClipProperties* pFileProperties);
467 * @brief   Retrieves the properties of the audio and video streams from the input file.
468 * @param   pContext            (IN) MCS context
469 * @param   pProperties         (OUT) Pointer on an allocated M4VIDEOEDITING_ClipProperties
470                                structure which is filled with the input stream properties.
471 * @note    The structure pProperties must be allocated and further de-allocated
472            by the application. The function must be called in the opened state.
473 * @return  M4NO_ERROR:         No error
474 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
475 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
476 ******************************************************************************
477 */
478M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
479                                        M4VIDEOEDITING_ClipProperties *pFileProperties);
480
481/**
482 ******************************************************************************
483 * M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
484 * @brief   Set the MCS video output parameters.
485 * @note    Must be called after M4MCS_open. Must be called before M4MCS_step.
486 * @param   pContext            (IN) MCS context
487 * @param   pParams             (IN/OUT) Transcoding parameters
488 * @return  M4NO_ERROR:         No error
489 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
490 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
491 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_SIZE_FOR_H263 : Output video frame size parameter is
492 *                                                          incompatible with H263 encoding
493 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_RATE_FOR_H263 : Output video frame size parameter is
494 *                                                          incompatible with H263 encoding
495 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FORMAT     : Undefined output video format parameter
496 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE : Undefined output video frame size
497 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_RATE : Undefined output video frame rate
498 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_AUDIO_FORMAT : Undefined output audio format parameter
499 * @return  M4MCS_ERR_DURATION_IS_NULL : Specified output parameters define a null duration stream
500 *                                        (no audio and video)
501 ******************************************************************************
502 */
503M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
504
505/**
506 ******************************************************************************
507 * M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
508 * @brief   Set the values of the encoding parameters
509 * @note    Must be called before M4MCS_checkParamsAndStart().
510 * @param   pContext           (IN) MCS context
511 * @param   pRates             (IN) Transcoding parameters
512 * @return  M4NO_ERROR:         No error
513 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
514 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
515 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
516 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
517 *                                           12.2 for amr, 8 for mp3)
518 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
519 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
520 *                                                     the input clip duration
521 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
522 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
523 *                                            file at given bitrates
524 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
525 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low
526 ******************************************************************************
527 */
528M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
529
530/**
531 ******************************************************************************
532 * M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
533 * @brief   Get the extended values of the encoding parameters
534 * @note    Could be called after M4MCS_setEncodingParams.
535 * @param   pContext           (IN) MCS context
536 * @param   pRates             (OUT) Transcoding parameters
537 * @return  M4NO_ERROR:         No error
538 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
539 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
540 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Encoding settings would produce a
541 *                                              null duration clip = encoding is impossible
542 ******************************************************************************
543 */
544M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);
545
546/**
547 ******************************************************************************
548 * M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext)
549 * @brief
550 * @note
551 * @param   pContext           (IN) MCS context
552 * @return  M4NO_ERROR:         No error
553 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
554 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
555 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
556 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
557 *                                           12.2 for amr, 8 for mp3)
558 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
559 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
560 *                                                    the input clip duration
561 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
562 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
563 *                                            file at given bitrates
564 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
565 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW:  Video bitrate too low
566 ******************************************************************************
567 */
568M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext);
569
570#ifdef __cplusplus
571}
572#endif /* __cplusplus */
573
574#endif /* __M4MCS_API_H__ */
575
576