xref: /frameworks/av/libvideoeditor/vss/mcs/inc/M4MCS_API.h

/*
 * Copyright (C) 2011 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 ******************************************************************************
 * @file    M4MCS_API.h
 * @brief   Media Conversion Service public API.
 * @note    MCS allows transcoding a 3gp/mp4 file into a new 3gp/mp4 file changing the
 *          video and audio encoding settings.
 *          It is a straightforward and fully synchronous API.
 ******************************************************************************
 */

#ifndef __M4MCS_API_H__
#define __M4MCS_API_H__

/**
 *    OSAL basic types and errors */
#include "M4OSA_Types.h"
#include "M4OSA_Error.h"

/**
 *    OSAL types for file access */
#include "M4OSA_FileReader.h"
#include "M4OSA_FileWriter.h"

/**
 *    Definition of M4_VersionInfo */
#include "M4TOOL_VersionInfo.h"

/**
 * Common definitions of video editing components */
#include "M4_VideoEditingCommon.h"

/**
 * To enable external audio codecs registering*/
#include "M4AD_Common.h"
#include "M4ENCODER_AudioCommon.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 *    Public type of the MCS context */
typedef M4OSA_Void* M4MCS_Context;


/**
 ******************************************************************************
 * enum        M4MCS_MediaRendering
 * @brief    This enum defines different media rendering
 ******************************************************************************
 */
typedef enum
{
    M4MCS_kResizing = 0,    /**< The media is resized, the aspect ratio can be
                              different from the original one.
                              All of the media is rendered */
    M4MCS_kCropping,        /**< The media is cropped, the aspect ratio is the
                              same as the original one.
                              The media is not rendered entirely */
    M4MCS_kBlackBorders     /**< Black borders are rendered in order to keep the
                              original aspect ratio. All the media is rendered */
} M4MCS_MediaRendering;


/**
 ******************************************************************************
 * struct   M4MCS_ExternalProgress
 * @brief   This structure contains information provided to the external Effect functions
 * @note    The uiProgress value should be enough for most cases
 ******************************************************************************
 */
typedef struct
{
    M4OSA_UInt32    uiProgress;     /**< Progress of the Effect from 0 to 1000 (one thousand) */
    M4OSA_UInt32    uiClipTime;     /**< Current time, in milliseconds,
                                          in the current clip time-line */
    M4OSA_UInt32    uiOutputTime;   /**< Current time, in milliseconds,
                                          in the output clip time-line */

} M4MCS_ExternalProgress;


/**
 ******************************************************************************
 * enum     M4MCS_AudioEffectType
 * @brief   This enumeration defines the audio effect types of the MCS
 ******************************************************************************
 */
typedef enum
{
    M4MCS_kAudioEffectType_None    = 0,
    M4MCS_kAudioEffectType_FadeIn  = 8, /**< Intended for begin effect */
    M4MCS_kAudioEffectType_FadeOut = 16, /**< Intended for end effect */
    M4MCS_kAudioEffectType_External = 256

} M4MCS_AudioEffectType;


/**
 ******************************************************************************
 * prototype    M4MCS_editAudioEffectFct
 * @brief       Audio effect functions implemented by the integrator
 *              must match this prototype.
 * @note        The function is provided with the original PCM data buffer and its size.
 *              Audio effect have to be applied on it.
 *              The progress of the effect is given, on a scale from 0 to 1000.
 *              When the effect function is called, all the buffers are valid and
 *              owned by the MCS.
 *
 * @param   pFunctionContext    (IN) The function context, previously set by the integrator
 * @param   pPCMdata            (IN/OUT) valid PCM data buffer
 * @param   uiPCMsize           (IN/OUT) PCM data buffer corresponding size
 * @param   pProgress           (IN) Set of information about the audio effect progress.
 *
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 ******************************************************************************
 */
typedef M4OSA_ERR (*M4MCS_editAudioEffectFct)
(
    M4OSA_Void *pFunctionContext,
    M4OSA_Int16 *pPCMdata,
    M4OSA_UInt32 uiPCMsize,
    M4MCS_ExternalProgress *pProgress
);


/**
 ******************************************************************************
 * struct   M4MCS_EffectSettings
 * @brief   This structure defines an audio effect for the edition.
 ******************************************************************************
 */
typedef struct
{
    M4OSA_UInt32                 uiStartTime;              /**< In ms */
    M4OSA_UInt32                 uiDuration;               /**< In ms */
    M4MCS_editAudioEffectFct     ExtAudioEffectFct;        /**< External effect function */
    M4OSA_Void                   *pExtAudioEffectFctCtxt;  /**< Context given to the external
                                                                effect function */
    M4MCS_AudioEffectType        AudioEffectType;         /**< None, FadeIn, FadeOut */

} M4MCS_EffectSettings;


/**
 ******************************************************************************
 * struct    M4MCS_OutputParams
 * @brief    MCS Output parameters
 * @note     Following parameters are used for still picture inputs :
 *             - OutputFileType (must be set to M4VIDEOEDITING_kFileType_JPG)
 *             - bDiscardExif must be set to M4OSA_TRUE or M4OSA_FALSE
 *             - bAdjustOrientation must be set to M4OSA_TRUE or M4OSA_FALSE
 *             - (MediaRendering is not handled : output image resolution is always
                 set according to BestFit criteria)
 *            bDiscardExif and bAdjustOrientation are still picture only parameters
 ******************************************************************************
 */
typedef struct
{
    /**< Format of the output file */
    M4VIDEOEDITING_FileType                 OutputFileType;
    /**< Output video compression format, see enum */
    M4VIDEOEDITING_VideoFormat              OutputVideoFormat;
    /**< Output frame size : QQVGA, QCIF or SQCIF */
    M4VIDEOEDITING_VideoFrameSize           OutputVideoFrameSize;
    /**< Targeted Output framerate, see enum */
    M4VIDEOEDITING_VideoFramerate           OutputVideoFrameRate;
    /**< Format of the audio in the stream */
    M4VIDEOEDITING_AudioFormat              OutputAudioFormat;
    /**< Sampling frequency of the audio in the stream */
    M4VIDEOEDITING_AudioSamplingFrequency   OutputAudioSamplingFrequency;
    /**< Set to M4OSA_TRUE if the output audio is mono */
    M4OSA_Bool                              bAudioMono;
    /**< Output PCM file if not NULL */
    M4OSA_Char                              *pOutputPCMfile;
    /**< To crop, resize, or render black borders*/
    M4MCS_MediaRendering                    MediaRendering;
    /**< List of effects */
    M4MCS_EffectSettings                    *pEffects;
    /**< Number of effects in the above list */
    M4OSA_UInt8                             nbEffects;

    /*--- STILL PICTURE ---*/
    /**< TRUE: Even if the input file contains an EXIF section,
    the output file won't contain any EXIF section.*/
    M4OSA_Bool                              bDiscardExif ;

    /**< =TRUE : picture must be rotated if Exif tags hold a rotation info
    (and rotation info is set to 0)*/
    M4OSA_Bool                              bAdjustOrientation ;
    /*--- STILL PICTURE ---*/
    M4OSA_Int32 outputVideoProfile;
    M4OSA_Int32 outputVideoLevel;
} M4MCS_OutputParams;

/*--- STILL PICTURE ---*/
/**
 ******************************************************************************
 * enum      M4MCS_SPOutputResolution
 * @brief    Still picture specific : MCS output targeted file resolution
 ******************************************************************************
 */
typedef enum
{
    M4MCS_kResSameAsInput       = 0x00, /*width x height*/
    M4MCS_kResQVGA              = 0x01, /*320x240*/
    M4MCS_kResVGA               = 0x02, /*640x480*/
    M4MCS_kResWQVGA             = 0x03, /*400x240*/
    M4MCS_kResWVGA              = 0x04, /*800x480*/
    M4MCS_kResXGA               = 0x05, /*1024x768*/
    M4MCS_kResCustom            = 0xFF  /*Size is set via StillPictureCustomWidth/Height*/
} M4MCS_SPOutputResolution ;


/**
 ******************************************************************************
 * enum      M4MCS_SPStrategy
 * @brief    Still picture specific : MCS strategy to configure the encoding parameters
 ******************************************************************************
 */
typedef enum
{
    M4MCS_kFileSizeOnlyFixed            = 0x00, /*StillPictureResolution and
                                                 QualityFactor are ignored*/
    M4MCS_kFileSizeAndResFixed          = 0x01, /*QualityFactor is ignored*/
    M4MCS_kQualityAndResFixed           = 0x02  /*OutputFileSize is ignored*/
} M4MCS_SPStrategy ;


/**
 ******************************************************************************
 * enum      M4MCS_SPCrop
 * @brief    Still picture specific : indicate whether cropping should be done
                                     before changing the resolution
 ******************************************************************************
 */
typedef enum
{
    M4MCS_kNoCrop                = 0x00, /*No Cropping is performed*/
    M4MCS_kCropBeforeResize      = 0x01  /*Input image is cropped (before changing resolution)*/
} M4MCS_SPCrop ;


/**
 ******************************************************************************
 * struct    M4MCS_EncodingParams
 * @brief    MCS file size, bitrate and cut parameters
 * @note     Following parameters are used for still picture inputs :
 *             - OutputFileSize
 *             - StillPictureResolution
 *             - QualityFactor
 *             - StillPictureStrategy
 *             - StillPictureCustomWidth/Height (if StillPictureResolution==M4MCS_kResCustom)
 *            Still picture only parameters : StillPictureResolution, QualityFactor,
 *            StillPictureStrategy and StillPictureCustomWidth/Height
 ******************************************************************************
 */
typedef struct
{
    M4VIDEOEDITING_Bitrate    OutputVideoBitrate;     /**< Targeted video bitrate */
    M4VIDEOEDITING_Bitrate    OutputAudioBitrate;     /**< Targeted audio bitrate */
    M4OSA_UInt32              BeginCutTime;           /**< Beginning cut time in input file */
    M4OSA_UInt32              EndCutTime;             /**< End cut time in input file */
    M4OSA_UInt32              OutputFileSize;         /**< Expected resulting file size */
    M4OSA_UInt32              OutputVideoTimescale;   /**< Optional parameter used to fix a
                                                           timescale during transcoding */

    /*--- STILL PICTURE ---*/
    M4OSA_Int32               QualityFactor ;         /**< =-1 (undefined) or 0(lowest)..
                                                            50(best) : This parameter is the
                                                            quality indication for the JPEG output
                                                            file (if =-1 the MCS will set quality
                                                            automatically)*/
    M4MCS_SPStrategy            StillPictureStrategy ; /**< Defines which input parameters
                                                            will be taken into account by MCS*/
    M4MCS_SPOutputResolution    StillPictureResolution;/**< Desired output resolution for
                                                            a still picture file */
    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image width */
    M4OSA_UInt32                StillPictureCustomWidth;
    /**< (only if Resolution==M4MCS_kResCustom) : Custom output image height */
    M4OSA_UInt32                StillPictureCustomHeight;
    /**< Indicate whether Crop should be performed */
    M4MCS_SPCrop                StillPictureCrop;
    /**< (only if cropping) X coordinate of topleft corner of the crop window */
    M4OSA_UInt32                StillPictureCrop_X;
    /**< (only if cropping) Y coordinate of topleft corner of the crop window */
    M4OSA_UInt32                StillPictureCrop_Y;
    /**< (only if cropping) Width of the crop window (in pixels) */
    M4OSA_UInt32                StillPictureCrop_W;
    /**< (only if cropping) Height of the crop window (in pixels) */
    M4OSA_UInt32                StillPictureCrop_H;
    /*--- STILL PICTURE ---*/
} M4MCS_EncodingParams;

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);
 * @brief    Get the MCS version.
 * @note Can be called anytime. Do not need any context.
 * @param    pVersionInfo        (OUT) Pointer to a version info structure
 * @return   M4NO_ERROR:         No error
 * @return   M4ERR_PARAMETER:    pVersionInfo is M4OSA_NULL (If Debug Level >= 2)
 ******************************************************************************
 */
M4OSA_ERR M4MCS_getVersion(M4_VersionInfo* pVersionInfo);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
                        M4OSA_FileWriterPointer* pFileWritePtrFct);
 * @brief    Initializes the MCS (allocates an execution context).
 * @note
 * @param    pContext            (OUT) Pointer on the MCS context to allocate
 * @param    pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
 * @param    pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
 * @return   M4NO_ERROR:         No error
 * @return   M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (If Debug Level >= 2)
 * @return   M4ERR_ALLOC:        There is no more available memory
 ******************************************************************************
 */
M4OSA_ERR M4MCS_init(M4MCS_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
                      M4OSA_FileWriterPointer* pFileWritePtrFct);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn, M4OSA_Void* pFileOut,
                          M4OSA_UInt32 uiMaxMetadataSize);
 * @brief   Set the MCS input and output files.
 * @note    It opens the input file, but the output file is not created yet.
 *          In case of still picture, four InputFileType are possible
 *          (M4VIDEOEDITING_kFileType_JPG/BMP/GIF/PNG
 *          If one of them is set, the OutputFileType SHALL be set to M4VIDEOEDITING_kFileType_JPG
 * @param   pContext            (IN) MCS context
 * @param   pFileIn             (IN) Input file to transcode (The type of this parameter
 *                                    (URL, pipe...) depends on the OSAL implementation).
 * @param   mediaType           (IN) Container type (.3gp,.amr, ...) of input file.
 * @param   pFileOut            (IN) Output file to create  (The type of this parameter
 *                                    (URL, pipe...) depends on the OSAL implementation).
 * @param   pTempFile           (IN) Temporary file for the constant memory writer to store
 *                                    metadata ("moov.bin").
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4ERR_ALLOC:        There is no more available memory
 * @return  M4ERR_FILE_NOT_FOUND:   The input file has not been found
 * @return  M4MCS_ERR_INVALID_INPUT_FILE:   The input file is not a valid file, or is corrupted
 * @return  M4MCS_ERR_INPUT_FILE_CONTAINS_NO_SUPPORTED_STREAM:  The input file contains no
 *                                                               supported audio or video stream
 ******************************************************************************
 */
M4OSA_ERR M4MCS_open(M4MCS_Context pContext, M4OSA_Void* pFileIn,
                     M4VIDEOEDITING_FileType InputFileType,
                     M4OSA_Void* pFileOut, M4OSA_Void* pTempFile);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);
 * @brief   Perform one step of trancoding.
 * @note
 * @param   pContext            (IN) MCS context
 * @param   pProgress           (OUT) Progress percentage (0 to 100) of the transcoding
 * @note    pProgress must be a valid address.
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    One of the parameters is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4MCS_WAR_TRANSCODING_DONE: Transcoding is over, user should now call M4MCS_close()
 * @return  M4MCS_ERR_AUDIO_CONVERSION_FAILED: The audio conversion (AAC to AMR-NB, MP3) failed
 * @return  M4MCS_ERR_INVALID_AAC_SAMPLING_FREQUENCY: The input file contains an AAC audio track
 *                                                     with an invalid sampling frequency
 *                                                     (should never happen)
 * @return  M4MCS_WAR_PICTURE_AUTO_RESIZE: Picture will be automatically resized to fit
 *                                          into requirements
 ******************************************************************************
 */
M4OSA_ERR M4MCS_step(M4MCS_Context pContext, M4OSA_UInt8 *pProgress);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);
 * @brief   Pause the transcoding i.e. release the (external hardware) video decoder.
 * @note    This function is not needed if no hardware accelerators are used.
 *          In that case, pausing the MCS is simply achieved by temporarily suspending
 *          the M4MCS_step function calls.
 * @param   pContext            (IN) MCS context
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 ******************************************************************************
 */
M4OSA_ERR M4MCS_pause(M4MCS_Context pContext);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);
 * @brief   Resume the transcoding after a pause (see M4MCS_pause).
 * @note    This function is not needed if no hardware accelerators are used.
 *          In that case, resuming the MCS is simply achieved by calling
 *          the M4MCS_step function.
 * @param   pContext            (IN) MCS context
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 ******************************************************************************
 */
M4OSA_ERR M4MCS_resume(M4MCS_Context pContext);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_close(M4MCS_Context pContext);
 * @brief    Finish the MCS transcoding.
 * @note The output 3GPP file is ready to be played after this call
 * @param    pContext            (IN) MCS context
 * @return   M4NO_ERROR:         No error
 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 ******************************************************************************
 */
M4OSA_ERR M4MCS_close(M4MCS_Context pContext);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);
 * @brief    Free all resources used by the MCS.
 * @note The context is no more valid after this call
 * @param    pContext            (IN) MCS context
 * @return   M4NO_ERROR:         No error
 * @return   M4ERR_PARAMETER:    pContext is M4OSA_NULL (If Debug Level >= 2)
 * @return   M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 ******************************************************************************
 */
M4OSA_ERR M4MCS_cleanUp(M4MCS_Context pContext);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);
 * @brief    Finish the MCS transcoding and free all resources used by the MCS
 *          whatever the state is.
 * @note    The context is no more valid after this call
 * @param    pContext            (IN) MCS context
 * @return    M4NO_ERROR:            No error
 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL (debug only)
 ******************************************************************************
 */
M4OSA_ERR M4MCS_abort(M4MCS_Context pContext);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
 *                                          M4VIDEOEDITING_ClipProperties* pFileProperties);
 * @brief   Retrieves the properties of the audio and video streams from the input file.
 * @param   pContext            (IN) MCS context
 * @param   pProperties         (OUT) Pointer on an allocated M4VIDEOEDITING_ClipProperties
                                structure which is filled with the input stream properties.
 * @note    The structure pProperties must be allocated and further de-allocated
            by the application. The function must be called in the opened state.
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 ******************************************************************************
 */
M4OSA_ERR M4MCS_getInputFileProperties(M4MCS_Context pContext,
                                        M4VIDEOEDITING_ClipProperties *pFileProperties);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);
 * @brief   Set the MCS video output parameters.
 * @note    Must be called after M4MCS_open. Must be called before M4MCS_step.
 * @param   pContext            (IN) MCS context
 * @param   pParams             (IN/OUT) Transcoding parameters
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_SIZE_FOR_H263 : Output video frame size parameter is
 *                                                          incompatible with H263 encoding
 * @return  M4MCS_ERR_INVALID_VIDEO_FRAME_RATE_FOR_H263 : Output video frame size parameter is
 *                                                          incompatible with H263 encoding
 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FORMAT     : Undefined output video format parameter
 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE : Undefined output video frame size
 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_VIDEO_FRAME_RATE : Undefined output video frame rate
 * @return  M4MCS_ERR_UNDEFINED_OUTPUT_AUDIO_FORMAT : Undefined output audio format parameter
 * @return  M4MCS_ERR_DURATION_IS_NULL : Specified output parameters define a null duration stream
 *                                        (no audio and video)
 ******************************************************************************
 */
M4OSA_ERR M4MCS_setOutputParams(M4MCS_Context pContext, M4MCS_OutputParams* pParams);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
 * @brief   Set the values of the encoding parameters
 * @note    Must be called before M4MCS_checkParamsAndStart().
 * @param   pContext           (IN) MCS context
 * @param   pRates             (IN) Transcoding parameters
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
 *                                           12.2 for amr, 8 for mp3)
 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
 *                                                     the input clip duration
 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
 *                                            file at given bitrates
 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW: Video bitrate too low
 ******************************************************************************
 */
M4OSA_ERR M4MCS_setEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates)
 * @brief   Get the extended values of the encoding parameters
 * @note    Could be called after M4MCS_setEncodingParams.
 * @param   pContext           (IN) MCS context
 * @param   pRates             (OUT) Transcoding parameters
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Encoding settings would produce a
 *                                              null duration clip = encoding is impossible
 ******************************************************************************
 */
M4OSA_ERR M4MCS_getExtendedEncodingParams(M4MCS_Context pContext, M4MCS_EncodingParams* pRates);

/**
 ******************************************************************************
 * M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext)
 * @brief
 * @note
 * @param   pContext           (IN) MCS context
 * @return  M4NO_ERROR:         No error
 * @return  M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL (debug only)
 * @return  M4ERR_STATE:        MCS is not in an appropriate state for this function to be called
 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_HIGH: Audio bitrate too high (we limit to 96 kbps)
 * @return  M4MCS_ERR_AUDIOBITRATE_TOO_LOW: Audio bitrate is too low (16 kbps min for aac,
 *                                           12.2 for amr, 8 for mp3)
 * @return  M4MCS_ERR_BEGIN_CUT_EQUALS_END_CUT: Begin cut and End cut are equals
 * @return  M4MCS_ERR_BEGIN_CUT_LARGER_THAN_DURATION: Begin cut time is larger than
 *                                                    the input clip duration
 * @return  M4MCS_ERR_END_CUT_SMALLER_THAN_BEGIN_CUT: End cut time is smaller than begin cut time
 * @return  M4MCS_ERR_MAXFILESIZE_TOO_SMALL: Not enough space to store whole output
 *                                            file at given bitrates
 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_HIGH: Video bitrate too high (we limit to 800 kbps)
 * @return  M4MCS_ERR_VIDEOBITRATE_TOO_LOW:  Video bitrate too low
 ******************************************************************************
 */
M4OSA_ERR M4MCS_checkParamsAndStart(M4MCS_Context pContext);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __M4MCS_API_H__ */