Version: 20 Mar 2024

ml_media_codec.h

Classes

	Name
struct	MLMediaCodecBufferInfo
struct	MLMediaCodecInputBufferInfo MediaCodec Input buffer information.
struct	MLMediaCodecOutputBufferInfo MediaCodec Output buffer information.
struct	MLMediaCodecOutputFormatInfo MediaCodec Output Format information.
struct	MLMediaCodecErrorInfo MediaCodec Output Format information.
struct	MLMediaCodecCallbacksEx Callbacks for notifying asynchronously of various codec events to the user/client. If user intends to use codec in asynchronous mode, then the user/client is expected to implement these callbacks and take proper actions where appropriate.
struct	MLMediaCodecFrameRenderedInfo MediaCodec Output Frame Rendered information.
struct	MLMediaCodecOutputFrameListener Callbacks for notifying when an output frame is available for consumption or has been rendered on the output surface.
struct	MLMediaCodecCryptoPattern Metadata describing an encryption pattern for the protected bytes in a subsample.
struct	MLMediaCodecCryptoInfo Metadata describing the structure of a (at least partially) encrypted input sample. A buffer's data is considered to be partitioned into "subSamples", each subSample starts with a (potentially empty) run of plain, unencrypted bytes followed by a (also potentially empty) run of encrypted bytes. If pattern encryption applies, each of the encrypted runs is encrypted only partly, according to a repeating pattern of "encrypt" and "skip" blocks. This information encapsulates per-sample metadata as outlined in ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files".

Types

	Name
typedef struct MLMediaCodecBufferInfo	MLMediaCodecBufferInfo
typedef struct MLMediaCodecInputBufferInfo	MLMediaCodecInputBufferInfo MediaCodec Input buffer information.
typedef struct MLMediaCodecOutputBufferInfo	MLMediaCodecOutputBufferInfo MediaCodec Output buffer information.
typedef struct MLMediaCodecOutputFormatInfo	MLMediaCodecOutputFormatInfo MediaCodec Output Format information.
typedef struct MLMediaCodecErrorInfo	MLMediaCodecErrorInfo MediaCodec Output Format information.
typedef struct MLMediaCodecCallbacksEx	MLMediaCodecCallbacksEx Callbacks for notifying asynchronously of various codec events to the user/client. If user intends to use codec in asynchronous mode, then the user/client is expected to implement these callbacks and take proper actions where appropriate.
typedef struct MLMediaCodecFrameRenderedInfo	MLMediaCodecFrameRenderedInfo MediaCodec Output Frame Rendered information.
typedef struct MLMediaCodecOutputFrameListener	MLMediaCodecOutputFrameListener Callbacks for notifying when an output frame is available for consumption or has been rendered on the output surface.
typedef struct MLMediaCodecCryptoPattern	MLMediaCodecCryptoPattern Metadata describing an encryption pattern for the protected bytes in a subsample.
typedef struct MLMediaCodecCryptoInfo	MLMediaCodecCryptoInfo Metadata describing the structure of a (at least partially) encrypted input sample. A buffer's data is considered to be partitioned into "subSamples", each subSample starts with a (potentially empty) run of plain, unencrypted bytes followed by a (also potentially empty) run of encrypted bytes. If pattern encryption applies, each of the encrypted runs is encrypted only partly, according to a repeating pattern of "encrypt" and "skip" blocks. This information encapsulates per-sample metadata as outlined in ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files".

Enums

	Name
enum	MLMediaCodecCreation { MLMediaCodecCreation_ByName, MLMediaCodecCreation_ByType, MLMediaCodecCreation_Ensure32Bits = 0x7FFFFFFF }
enum	MLMediaCodecType { MLMediaCodecType_Encoder, MLMediaCodecType_Decoder, MLMediaCodecType_Ensure32Bits = 0x7FFFFFFF }
enum	MLMediaCodecBufferFlag { MLMediaCodecBufferFlag_KeyFrame = 1, MLMediaCodecBufferFlag_CodecConfig = 2, MLMediaCodecBufferFlag_EOS = 4, MLMediaCodecBufferFlag_PartialFrame = 8, MLMediaCodecBufferFlag_MuxerData = 16, MLMediaCodecBufferFlag_Ensure32Bits = 0x7FFFFFFF } Indicate the type of data when queuing the input buffer via MLMediaCodecQueueInputBuffer() or MLMediaCodecQueueSecureInputBuffer().
enum	MLMediaCodecOutputBufferStatus { MLMediaCodec_OutputBuffersChanged = -1014, MLMediaCodec_FormatChanged = -1012, MLMediaCodec_TryAgainLater = -11, MLMediaCodecOutputBufferStatus_Ensure32Bits = 0x7FFFFFFF } Other than the normal buffer index, the output of MLMediaCodecDequeueOutputBuffer() can take on one of these statuses.
enum	MLMediaCodecCryptoMode { MLMediaCodecCryptoMode_Clear, MLMediaCodecCryptoMode_CTR, MLMediaCodecCryptoMode_CBC, MLMediaCodecCryptoMode_Ensure32Bits = 0x7FFFFFFF }

Functions

	Name
void	MLMediaCodecCallbacksExInit(MLMediaCodecCallbacksEx * inout_callbacks) Initializes MLMediaCodecCallbacksEx with default values.
void	MLMediaCodecOutputFrameListenerInit(MLMediaCodecOutputFrameListener * inout_callbacks) Initializes MLMediaCodecOutputFrameListener with default values.
void	MLMediaCodecCryptoInfoInit(MLMediaCodecCryptoInfo * inout_crypto_info) Initializes MLMediaCodecCryptoInfo with default values.
MLResult	MLMediaCodecCreateCryptoInfo(const MLMediaCodecCryptoInfo crypto_info, MLHandle out_crypto_info_handle) Create a Crypto Info object.
MLResult	MLMediaCodecReleaseCryptoInfo(MLHandle crypto_info_handle) Release the Crypto Info created by MLMediaCodecCreateCryptoInfo.
MLResult	MLMediaCodecCreateCodec(MLMediaCodecCreation method, MLMediaCodecType type, const char name_str, MLHandle out_handle) Create a new MLMediaCodec.
MLResult	MLMediaCodecDestroy(MLHandle handle) Destroy a MLMediaCodec.
MLResult	MLMediaCodecSetCallbacksEx(MLHandle handle, MLMediaCodecCallbacksEx callbacks, void user_data) Set callbacks to notify client codec events. Client needs to implement the callback functions.
MLResult	MLMediaCodecSetOutputFrameListener(MLHandle handle, MLMediaCodecOutputFrameListener callbacks, void user_data) Registers a callback to be invoked when an output frame is available or rendered on the output surface.
MLResult	MLMediaCodecGetName(MLHandle handle, char * out_name) Obtain the name of the created codec.
MLResult	MLMediaCodecConfigure(MLHandle handle, MLHandle format_handle, MLHandle surface_handle, MLHandle crypto_handle) Configure the MLMediaCodec.
MLResult	MLMediaCodecStart(MLHandle handle) Start the codec.
MLResult	MLMediaCodecStop(MLHandle handle) Stop the codec.
MLResult	MLMediaCodecReset(MLHandle handle) Reset the codec.
MLResult	MLMediaCodecFlush(MLHandle handle) Flush the both the input and output ports of the codec.
MLResult	MLMediaCodecSetParameters(MLHandle handle, MLHandle format_handle) Communicate additional parameter changes to a codec.
MLResult	MLMediaCodecGetInputBufferPointer(MLHandle handle, int64_t buffer_index, uint8_t * out_buffer_ptr, size_t out_buffer_size) Obtain a writable buffer pointer for a dequeued input buffer index to contain the input data.
MLResult	MLMediaCodecGetOutputBufferPointer(MLHandle handle, int64_t buffer_index, const uint8_t * out_buffer_ptr, size_t out_buffer_size) Obtain a read-only buffer pointer for a dequeued output buffer index.
MLResult	MLMediaCodecQueueInputBuffer(MLHandle handle, int64_t buffer_index, int64_t offset, size_t size, uint64_t time_us, int flags) After filling a range of the input buffer at the specified index submit it to the component.
MLResult	MLMediaCodecQueueSecureInputBuffer(MLHandle handle, int64_t buffer_index, int64_t offset, MLHandle crypto_info_handle, uint64_t time_us, int flags) Similar to queueInputBuffer but submits a buffer that is potentially encrypted.
MLResult	MLMediaCodecDequeueInputBuffer(MLHandle handle, int64_t timeout_us, int64_t * out_buffer_index) Dequeue an input buffer from buffer queue.
MLResult	MLMediaCodecDequeueOutputBuffer(MLHandle handle, MLMediaCodecBufferInfo out_buffer_info, int64_t timeout_us, int64_t out_buffer_index) Dequeue an output buffer from buffer queue.
MLResult	MLMediaCodecGetInputFormat(MLHandle handle, MLHandle * out_format_handle) Obtain input format supported by the codec.
MLResult	MLMediaCodecGetOutputFormat(MLHandle handle, MLHandle * out_format_handle) Return output format supported by the codec, or the format to which the configuration has changed.
MLResult	MLMediaCodecCreateInputSurface(MLHandle handle, MLHandle * out_input_surface_handle) Create an input surface for a hardware encoder.
MLResult	MLMediaCodecDestroyInputSurface(MLHandle handle, MLHandle input_surface_handle) Release the Surface that was created by MLMediaCodecCreateInputSurface.
MLResult	MLMediaCodecSignalEndOfInputStream(MLHandle handle) Signal end-of-stream on input to a surface.
MLResult	MLMediaCodecReleaseOutputBuffer(MLHandle handle, int64_t buffer_index, bool render) Release buffer to codec or to render it on output surface.
MLResult	MLMediaCodecReleaseOutputBufferAtTime(MLHandle handle, int64_t buffer_index, int64_t timestamp_ns) Update surface timestamp and returns it to the codec to render it on the output surface. If codec is not configured with output surface, this call simply returns the buffer to codec.

Defines

	Name
	MAX_CODEC_NAME_SIZE

Enums Documentation

MLMediaCodecCreation

Enumerator	Value	Description
MLMediaCodecCreation_ByName		Create by name.
MLMediaCodecCreation_ByType		Create by type.
MLMediaCodecCreation_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Media codec creation method.

MLMediaCodecType

Enumerator	Value	Description
MLMediaCodecType_Encoder		Encoder.
MLMediaCodecType_Decoder		Decoder.
MLMediaCodecType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Media codec type.

MLMediaCodecBufferFlag

Enumerator	Value	Description
MLMediaCodecBufferFlag_KeyFrame	1	The (encoded) buffer contains the data for a key frame.
MLMediaCodecBufferFlag_CodecConfig	2	Buffer contains codec initialization OR codec specific data instead of media data.
MLMediaCodecBufferFlag_EOS	4	Signals the end of stream, i.e. no buffers will be available after this.
MLMediaCodecBufferFlag_PartialFrame	8	Buffer only contains part of a frame, and the decoder should batch the data until a buffer without this flag appears before decoding the frame.
MLMediaCodecBufferFlag_MuxerData	16	Buffer contains muxer data - Supported only for Exif data block.
MLMediaCodecBufferFlag_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Indicate the type of data when queuing the input buffer via MLMediaCodecQueueInputBuffer() or MLMediaCodecQueueSecureInputBuffer().

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecOutputBufferStatus

Enumerator	Value	Description
MLMediaCodec_OutputBuffersChanged	-1014	Output buffer changed.
MLMediaCodec_FormatChanged	-1012	Format changed.
MLMediaCodec_TryAgainLater	-11	Try again later.
MLMediaCodecOutputBufferStatus_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Other than the normal buffer index, the output of MLMediaCodecDequeueOutputBuffer() can take on one of these statuses.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecCryptoMode

Enumerator	Value	Description
MLMediaCodecCryptoMode_Clear		Clear samples.
MLMediaCodecCryptoMode_CTR		Sample encrypted with AES CTR mode.
MLMediaCodecCryptoMode_CBC		Sample encrypted with AES CBC mode.
MLMediaCodecCryptoMode_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Crypto mode using which media samples are encrypted.

Types Documentation

MLMediaCodecBufferInfo

typedef struct MLMediaCodecBufferInfo MLMediaCodecBufferInfo;

Media codec buffer info.

More Info

MLMediaCodecInputBufferInfo

typedef struct MLMediaCodecInputBufferInfo MLMediaCodecInputBufferInfo;

MediaCodec Input buffer information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecOutputBufferInfo

typedef struct MLMediaCodecOutputBufferInfo MLMediaCodecOutputBufferInfo;

MediaCodec Output buffer information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecOutputFormatInfo

typedef struct MLMediaCodecOutputFormatInfo MLMediaCodecOutputFormatInfo;

MediaCodec Output Format information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecErrorInfo

typedef struct MLMediaCodecErrorInfo MLMediaCodecErrorInfo;

MediaCodec Output Format information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecCallbacksEx

typedef struct MLMediaCodecCallbacksEx MLMediaCodecCallbacksEx;

Callbacks for notifying asynchronously of various codec events to the user/client. If user intends to use codec in asynchronous mode, then the user/client is expected to implement these callbacks and take proper actions where appropriate.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecFrameRenderedInfo

typedef struct MLMediaCodecFrameRenderedInfo MLMediaCodecFrameRenderedInfo;

MediaCodec Output Frame Rendered information.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecOutputFrameListener

typedef struct MLMediaCodecOutputFrameListener MLMediaCodecOutputFrameListener;

Callbacks for notifying when an output frame is available for consumption or has been rendered on the output surface.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecCryptoPattern

typedef struct MLMediaCodecCryptoPattern MLMediaCodecCryptoPattern;

Metadata describing an encryption pattern for the protected bytes in a subsample.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecCryptoInfo

typedef struct MLMediaCodecCryptoInfo MLMediaCodecCryptoInfo;

Metadata describing the structure of a (at least partially) encrypted input sample. A buffer's data is considered to be partitioned into "subSamples", each subSample starts with a (potentially empty) run of plain, unencrypted bytes followed by a (also potentially empty) run of encrypted bytes. If pattern encryption applies, each of the encrypted runs is encrypted only partly, according to a repeating pattern of "encrypt" and "skip" blocks. This information encapsulates per-sample metadata as outlined in ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files".

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

Functions Documentation

MLMediaCodecCallbacksExInit

static inline void MLMediaCodecCallbacksExInit(
    MLMediaCodecCallbacksEx * inout_callbacks
)

Initializes MLMediaCodecCallbacksEx with default values.

Parameters


MLMediaCodecCallbacksEx *	inout_callbacks	MediaCodec Callback structure defined by MLMediaCodecCallbacksEx that needs to be initialized.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecOutputFrameListenerInit

static inline void MLMediaCodecOutputFrameListenerInit(
    MLMediaCodecOutputFrameListener * inout_callbacks
)

Initializes MLMediaCodecOutputFrameListener with default values.

Parameters


MLMediaCodecOutputFrameListener *	inout_callbacks	MediaCodec Callback structure defined by MLMediaCodecOutputFrameListener that needs to be initialized.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecCryptoInfoInit

static inline void MLMediaCodecCryptoInfoInit(
    MLMediaCodecCryptoInfo * inout_crypto_info
)

Initializes MLMediaCodecCryptoInfo with default values.

Parameters


MLMediaCodecCryptoInfo *	inout_crypto_info	CryptoInfo structure defined by MLMediaCodecCryptoInfo that needs to be initialized.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecCreateCryptoInfo

MLResult MLMediaCodecCreateCryptoInfo(
    const MLMediaCodecCryptoInfo * crypto_info,
    MLHandle * out_crypto_info_handle
)

Create a Crypto Info object.

Parameters


const MLMediaCodecCryptoInfo *	crypto_info	Input Structure that encapsulates sample crypto info.
MLHandle *	out_crypto_info_handle	Upon successful return will point to handle to the created Crypto info. Or else, it will point to ML_INVALID_HANDLE.

Returns


MLResult	MLResult_InvalidParam	If one of parameters is invalid.
MLResult	MLResult_Ok	If operation succeeded.

Required Permissions:

None

The CryptoInfo object should be released by calling MLMediaCodecReleaseCryptoInfo.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecReleaseCryptoInfo

MLResult MLMediaCodecReleaseCryptoInfo(
    MLHandle crypto_info_handle
)

Release the Crypto Info created by MLMediaCodecCreateCryptoInfo.

Parameters


MLHandle	crypto_info_handle	Handle to Crypto info that needs to be released.

Returns


MLResult	MLResult_InvalidParam	If one of parameters is invalid.
MLResult	MLResult_Ok	If operation succeeded.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecCreateCodec

MLResult MLMediaCodecCreateCodec(
    MLMediaCodecCreation method,
    MLMediaCodecType type,
    const char * name_str,
    MLHandle * out_handle
)

Create a new MLMediaCodec.

Parameters


MLMediaCodecCreation	method	One of the creation methods defined by MLMediaCodecCreation.
MLMediaCodecType	type	One of the codec types defined by MLMediaCodecType.
const char *	name_str	If creating a codec by name, this is the name of the codec. If creating a codec by type, this is the mime type of the codec. Refer to APIs in MLMediaCodecList for retrieving the list of names and mime types of supported codecs.
MLHandle *	out_handle	Upon successful return will point to handle to the created MLMediaCodec. Or else, it will point to ML_INVALID_HANDLE.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	MLMediaCodec object was created successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecDestroy

MLResult MLMediaCodecDestroy(
    MLHandle handle
)

Destroy a MLMediaCodec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	MLMediaCodec object was successfully destroyed.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecSetCallbacksEx

MLResult MLMediaCodecSetCallbacksEx(
    MLHandle handle,
    MLMediaCodecCallbacksEx * callbacks,
    void * user_data
)

Set callbacks to notify client codec events. Client needs to implement the callback functions.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLMediaCodecCallbacksEx *	callbacks	Set of codec callbacks. Can be set to NULL to unset all the callback altogether.
void *	user_data	Pointer to user payload data.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	callback was set successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

If the client intends to use the codec component in asynchronous mode, a valid callback should be provided before MLMediaCodecConfigure is called. When asynchronous callback is enabled, the client should not call:

MLMediaCodecDequeueInputBuffer
MLMediaCodecDequeueOutputBuffer Calling those functions will return MLMediaGenericResult_InvalidOperation. Also, MLMediaCodecFlush() behaves differently in asynchronous mode. After calling MLMediaCodecFlush, you must call MLMediaCodecStart() to "resume" receiving input buffers, even if an input surface was created.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecSetOutputFrameListener

MLResult MLMediaCodecSetOutputFrameListener(
    MLHandle handle,
    MLMediaCodecOutputFrameListener * callbacks,
    void * user_data
)

Registers a callback to be invoked when an output frame is available or rendered on the output surface.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLMediaCodecOutputFrameListener *	callbacks	Set of codec callbacks. Can be set to NULL to unset all the callback altogether.
void *	user_data	Pointer to user payload data.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	callback was set successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

This method can be called in any codec state, but will only have an effect in the "Executing" state for codecs that render buffers to the output surface.

Note:

This callback is for informational purposes only: to get precise render timing samples, and can be significantly delayed and batched. Some frames may have been rendered even if there was no callback generated.
This callback doesn't set the codec to operate in asynchrous mode.
Since audio codec doesn't use Surface, this callback as no effect when audio codec is instantiated.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecGetName

MLResult MLMediaCodecGetName(
    MLHandle handle,
    char * out_name
)

Obtain the name of the created codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
char *	out_name	Pointer to the user-maintained buffer for storing the output C-style name string.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	MLMediaCodec name was retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

User shall allocate at least MAX_CODEC_NAME_SIZE bytes of memory for storing the output name string.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecConfigure

MLResult MLMediaCodecConfigure(
    MLHandle handle,
    MLHandle format_handle,
    MLHandle surface_handle,
    MLHandle crypto_handle
)

Configure the MLMediaCodec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle	format_handle	MLHandle to the #MediaFormat object.
MLHandle	surface_handle	MLHandle to the Surface object.
MLHandle	crypto_handle	MLHandle to the #MediaCrypto object. Pass 0 for clear content.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	MLMediaCodec was configured successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Encoder configuration: surface_handle and crypto_handle should be 0. Decoder Configuration: The surface_handle should be provided if using output surface. The crypto_handle should be provided for encrypted content.

The output surface can be:

Native surface created by MLNativeSurfaceCreate().
Native surface texture created by MLNativeSurfaceTextureCreate().
The surface object created on an encoder using MLMediaCodecCreateInputSurface().
Pass 0 or ML_INVALID_HANDLE if the codec does not generate raw video output (e.g. not a video decoder) and/or if you want to configure the codec with CPU bound output buffers. NOTE that:

For the first 3 cases (above), the decoded output of the decoder will be consumed direclty by the surface. This allows implementation of fast, zero-copy raw video consumption operation. Also, calling MLMediaCodecGetOutputBufferPointer will return MLMediaGenericResult_InvalidOperation
For the last case, user will have to explictly consume the output of the decoder by calling MLMediaCodecGetOutputBufferPointer.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecStart

MLResult MLMediaCodecStart(
    MLHandle handle
)

Start the codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	MLMediaCodec was started successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Shall be called upon successful configuration.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecStop

MLResult MLMediaCodecStop(
    MLHandle handle
)

Stop the codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	MLMediaCodec was stopped successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Codec is stopped and not destroyed, therefore can be started again.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecReset

MLResult MLMediaCodecReset(
    MLHandle handle
)

Reset the codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	MLMediaCodec was stopped successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

This will reset the codec to initial (Uninitialized) state. Call this when:

Input or output queuing operation fails.
An error is notified through the asynchronous event MLMediaCodecCallbacks.on_error. Resetting a codec can fail when an unrecoverable error occurs (which is Hardare codec implementation specific), in which case codec will be in unusable state and should be destroyed using MLMediaCodecDestroy.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecFlush

MLResult MLMediaCodecFlush(
    MLHandle handle
)

Flush the both the input and output ports of the codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidParam	MLMediaCodec object is invalid.
MLResult	MLResult_Ok	MLMediaCodec was flushed successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Upon return, all indices previously returned in calls to MLMediaCodecDequeueInputBuffer() and MLMediaCodecDequeueOutputBuffer() become invalid, and all buffers are owned by the codec.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecSetParameters

MLResult MLMediaCodecSetParameters(
    MLHandle handle,
    MLHandle format_handle
)

Communicate additional parameter changes to a codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle	format_handle	MLHandle to the MLMediaFormat containing the parameters to set.

Returns


MLResult	MLResult_InvalidParam	At least one of the input parameters or one of the format parameter values is invalid.
MLResult	MLResult_Ok	The operation was successful.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	At least one format parameter is not applicable.
MLResult	MLMediaGenericResult_NoInit	MLMediaCodec was not initialized.

Dynamically modify or add configuration parameters to a configured or started codec.

Create an empty MLMediaFormat object using MLMediaFormatCreate() and set the appropriate parameters. For more details, refer to ml_media_format.h.

Parameters and associated values that may be applied are:

MLMediaFormat_Key_Parameter_Video_Bitrate: Dynamically change the video encoder's target bitrate. Associated value is an int32_t representing the new encode bitrate in bits-per-second. Applicable to any video encoder.
MLMediaFormat_Key_Parameter_Request_Sync_Frame: Communicate to the encoder to produce a sync frame soon. Associated value is an int32_t with the value 0. Applicable to any video encoder.
MLMediaFormat_Key_Parameter_Drop_After: Set the time after which samples should be dropped and not submitted to the encoder. Associated value is an int64_t value representing the system time in micro-seconds. Applicable to an encoder receiving input from a surface.
MLMediaFormat_Key_Parameter_Drop_Before: Set the time before which samples should be dropped and not submitted to the encoder. Associated value is an int64_t value representing the system time in micro-seconds. Applicable to an encoder receiving input from a surface.
MLMediaFormat_Key_Parameter_Set_Suspend: Temporarily suspend or resume video encoding of input data. When suspended, all incoming buffers are discarded until suspension is lifted. Used in conjunction with MLMediaFormat_Key_Parameter_Set_Suspend_Time to speficy the time of suspension or resumption. Associated value is an int32_t value with the value 1 or 0 to suspend or resume, respectively. Applicable to an encoder receiving input from a surface.
MLMediaFormat_Key_Parameter_Set_Suspend_Time: Specifies the time when the action associated with the value of MLMediaFormat_Key_Parameter_Set_Suspend should take effect. Associated value is an int64_t value representing the system time, in micro-seconds, indicating when suspendion or resumption takes effect. Applicable to an encoder receiving input from a surface.
MLMediaFormat_Key_Parameter_Time_Offset: Describes an offset to adjust timestamps going forward on a video endcoder. Associated value is an int64_t value representing the offset timestamp, in micro-seconds. Applicable to an encoder receiving input from a surface.
MLMediaFormat_Key_Operating_Rate: Describes the rate at which a codec is expected to operate. For video, this is the operating frame rate; for audio, this is the sample rate. Associated value is a float value representing either the frames-per-second or the samples-per-second for video or audio, respectively. Applicable to any codec. Note: This key is ignored if it fails to apply. Note: This key can also be set as part of the MLMediaFormat provided at configure-time.
MLMediaFormat_Key_Intra_Refresh_Period: Describes the period of intra refresh in frames. Associated value is a int32_t value representing the period in frames after which the whole frame is completely refreshed. Applicable to any video encoder. Note: This key is ignored if not supported by the codec or it fails to apply. Note: This key can also be set as part of the MLMediaFormat provided at configure-time.
MLMediaFormat_Key_Latency: Describes the latency, in frames, a video encoder should have queued up before outputting at least one output frame. Associated value is an int32_t value representing the latency, in number of frames. Applicable to any video encoder. Note: This key is ignored if not supported by the codec or it fails to apply. Note: This key can also be set as part of the MLMediaFormat provided at configure-time.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

note

Some of these parameter changes may silently fail to apply. Unless specified below, an error will be returned on unsuccesful application.

API Level:

MLMediaCodecGetInputBufferPointer

MLResult MLMediaCodecGetInputBufferPointer(
    MLHandle handle,
    int64_t buffer_index,
    uint8_t ** out_buffer_ptr,
    size_t * out_buffer_size
)

Obtain a writable buffer pointer for a dequeued input buffer index to contain the input data.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
int64_t	buffer_index	The index of a client-owned input buffer previously returned from a call to MLMediaCodecDequeueInputBuffer().
uint8_t **	out_buffer_ptr	Pointer to returned input buffer.
size_t *	out_buffer_size	Size of returned input buffer.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Input buffer pointer is retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	Buffer pointer could not be retrieved. Note that this API returns MLMediaGenericResult_InvalidOperation especially if video encoder has hardware input surface (see MLMediaCodecCreateInputSurface), and thus, out_buffer_ptr will be set to NULL and out_buffer_size set to 0.

Required Permissions:

None

After calling this method any buffer pointer previously returned for the same input index MUST no longer be used.

Note: For VIDEO encoder, this API will fail if an input surface was created by MLMediaCodecCreateInputSurface (see return value documentation below).

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecGetOutputBufferPointer

MLResult MLMediaCodecGetOutputBufferPointer(
    MLHandle handle,
    int64_t buffer_index,
    const uint8_t ** out_buffer_ptr,
    size_t * out_buffer_size
)

Obtain a read-only buffer pointer for a dequeued output buffer index.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
int64_t	buffer_index	The index of a client-owned output buffer previously returned from a call to MLMediaCodecDequeueOutputBuffer().
const uint8_t **	out_buffer_ptr	Pointer to returned output buffer.
size_t *	out_buffer_size	Size of returned output buffer.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Output buffer pointer is retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	Buffer pointer could not be retrieved. Note that this API returns MLMediaGenericResult_InvalidOperation especially if codec was VIDEO and configured with a hardware surface using MLMediaCodecConfigure(), and thus, out_buffer_ptr will be set to NULL and out_buffer_size set to 0 since decoded buffer lives in GPU memory and is not accessible via a pointer.

Required Permissions:

None

The position and limit of the returned buffer are set to the valid output data. After calling this method any buffer pointer previously returned for the same output index MUST no longer be used.

Note: For VIDEO decoder, this API will fail if codec was configured with a hardware surface (see return value documentation below).

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecQueueInputBuffer

MLResult MLMediaCodecQueueInputBuffer(
    MLHandle handle,
    int64_t buffer_index,
    int64_t offset,
    size_t size,
    uint64_t time_us,
    int flags
)

After filling a range of the input buffer at the specified index submit it to the component.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
int64_t	buffer_index	Index of a client-owned input buffer previously returned in a call to MLMediaCodecDequeueInputBuffer().
int64_t	offset	Byte offset into the input buffer at which the data starts.
size_t	size	Number of bytes of valid input data.
uint64_t	time_us	Presentation timestamp in microseconds for this buffer. This is normally the media time at which this buffer should be presented (rendered).
int	flags	A bitmask of flags defined by MLMediaCodecBufferFlag. While not prohibited, most codecs do not use the MLMediaCodecBufferFlag_KeyFrame flag for input buffers.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Intput buffer is queued successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Once an input buffer is queued to the codec, it MUST NOT be used until it is later retrieved by MLMediaCodecGetInputBufferPointer() in response to a MLMediaCodecDequeueInputBuffer() return value.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecQueueSecureInputBuffer

MLResult MLMediaCodecQueueSecureInputBuffer(
    MLHandle handle,
    int64_t buffer_index,
    int64_t offset,
    MLHandle crypto_info_handle,
    uint64_t time_us,
    int flags
)

Similar to queueInputBuffer but submits a buffer that is potentially encrypted.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
int64_t	buffer_index	Index of a client-owned input buffer previously returned in a call to MLMediaCodecDequeueInputBuffer().
int64_t	offset	Byte offset into the input buffer at which the data starts.
MLHandle	crypto_info_handle	Metadata required to facilitate decryption, the object can be reused immediately after this call returns.
uint64_t	time_us	Presentation timestamp in microseconds for this buffer. This is normally the media time at which this buffer should be presented (rendered).
int	flags	A bitmask of flags defined by MLMediaCodecBufferFlag. While not prohibited, most codecs do not use the MLMediaCodecBufferFlag_KeyFrame flag for input buffers.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Secure Intput buffer is queued successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecDequeueInputBuffer

MLResult MLMediaCodecDequeueInputBuffer(
    MLHandle handle,
    int64_t timeout_us,
    int64_t * out_buffer_index
)

Dequeue an input buffer from buffer queue.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
int64_t	timeout_us	Timeout in microseconds. Negative timeout indicates "infinite".
int64_t *	out_buffer_index	Index of an Input buffer from buffer queue, or MLMediaCodec_TryAgainLater status.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Intput buffer is dequeued successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	if the codec is configured to operate in async mode.

Required Permissions:

None

This method will return immediately if timeoutUs == 0, wait indefinitely for the availability of an input buffer if timeoutUs < 0 or wait up to "timeoutUs" microseconds if timeoutUs > 0.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecDequeueOutputBuffer

MLResult MLMediaCodecDequeueOutputBuffer(
    MLHandle handle,
    MLMediaCodecBufferInfo * out_buffer_info,
    int64_t timeout_us,
    int64_t * out_buffer_index
)

Dequeue an output buffer from buffer queue.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLMediaCodecBufferInfo *	out_buffer_info	Will be filled with buffer meta data.
int64_t	timeout_us	Timeout in microseconds. Negative timeout indicates "infinite".
int64_t *	out_buffer_index	Index of an output buffer from buffer queue, or one of the statuses defined by MLMediaCodecOutputBufferStatus.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Output buffer is dequeued successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	if the codec is configured to operate in async mode.

Required Permissions:

None

This method will return immediately if timeoutUs == 0, wait indefinitely for the availability of an input buffer if timeoutUs < 0 or wait up to "timeoutUs" microseconds if timeoutUs > 0.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecGetInputFormat

MLResult MLMediaCodecGetInputFormat(
    MLHandle handle,
    MLHandle * out_format_handle
)

Obtain input format supported by the codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle *	out_format_handle	Input format supported by the codec.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Input Media format is retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Call this function, after successful codec configuration, to determine what optional configuration parameters were supported by the codec.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecGetOutputFormat

MLResult MLMediaCodecGetOutputFormat(
    MLHandle handle,
    MLHandle * out_format_handle
)

Return output format supported by the codec, or the format to which the configuration has changed.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle *	out_format_handle	Output format supported by the codec, or the format to which the configuration has changed.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Output Media format is retrieved successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

MLMediaCodecCreateInputSurface

MLResult MLMediaCodecCreateInputSurface(
    MLHandle handle,
    MLHandle * out_input_surface_handle
)

Create an input surface for a hardware encoder.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle *	out_input_surface_handle	MLHandle to created input native surface. Valid only if result is MLResult_Ok.

Returns


MLResult	MLResult_AllocFailed	The operation failed to allocate the surface.
MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Input input surface was created successfully.
MLResult	MLMediaGenericResult_AlreadyExists	An input surface has already been created for the given handle.
MLResult	MLMediaGenericResult_InvalidOperation	MLMediaCodec is not an encoder.
MLResult	MLMediaGenericResult_NoInit	MLMediaCodec was not initialized.
MLResult	MLMediaGenericResult_UnspecifiedFailure	Input surface could not be created.

Required Permissions:

None

Requests an input surface to use as the input to an encoder, in place of input buffers.

This API must only be called after MLMediaCodecConfigure() and before MLMediaCodecStart() otherwise the operation will fail and an input surface cannot be created.

An input surface allows video consumers, such as a video encoder, to process raw input video buffers natively. The input surface is intended to act as a destination surface for your input data.

When using an input surface, there are no accessible input buffers, as buffers are automatically passed from the input surface to the codec. In synchronous mode, calling MLMediaCodecDequeueInputBuffer() will return MLMediaGenericResult_InvalidOperation. In asynchronous mode, the client will not be notified when an input buffer is available (i.e. the on_input_buffer_available callback will not fire).

The returned input surface can be passed as a destination surface to a decoder when calling MLMediaCodecConfigure(). Decoded output of the decoder can be consumed direclty as input to an encoder without copying. This allows implementation of fast, zero-copy transcoding.

The returned input surface can also be passed as a destination surface to:

A video capture session when using MLCameraConnectFlag_CamOnly.
A virtual capture session when using MLCameraConnectFlag_VirtualOnly .
A mixed reality capture session when using MLCameraConnectFlag_MR. Captured raw video frames will be consumed directly as input to an encoder without copying. The user of this API is responsible for calling #MLMediaCodecReleaseSurface() on the Surface when done.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecDestroyInputSurface

MLResult MLMediaCodecDestroyInputSurface(
    MLHandle handle,
    MLHandle input_surface_handle
)

Release the Surface that was created by MLMediaCodecCreateInputSurface.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.
MLHandle	input_surface_handle	MLHandle to the internal Surface object.

Returns


MLResult	MLResult_InvalidParam	MLHandle is invalid.
MLResult	MLResult_Ok	Surface object was successfully released.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_InvalidOperation	MLMediaCodec is not an encoder.
MLResult	MLMediaGenericResult_NoInit	MLMediaCodec was not initialized.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecSignalEndOfInputStream

MLResult MLMediaCodecSignalEndOfInputStream(
    MLHandle handle
)

Signal end-of-stream on input to a surface.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec.

Returns


MLResult	MLResult_InvalidOperation	MLMediaCodec is not an encoder or MLMediaCodec is not receving input from a surface.
MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	The operation was successful.
MLResult	MLMediaGenericResult_NoInit	MLMediaCodec was not initialized.

This may only be used with encoders receiving input from a surface created by MLMediaCodecCreateInputSurface().

Equivalent to submitting an empty buffer with MLMediaCodecBufferFlag_EOS set when queueing an input buffer.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecReleaseOutputBuffer

MLResult MLMediaCodecReleaseOutputBuffer(
    MLHandle handle,
    int64_t buffer_index,
    bool render
)

Release buffer to codec or to render it on output surface.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec object.
int64_t	buffer_index	Index of a client-owned output buffer previously returned from a call to MLMediaCodecDequeueOutputBuffer().
bool	render	If a valid surface was specified when configuring the codec, passing `true` renders this output buffer to the surface.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Output buffer was released successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

If codec is configured with an output surface, setting render to true will send the buffer to that output surface. The surface will release the buffer back to the codec once it is no longer used/displayed.

Once an output buffer is released to codec, it MUST NOT be used until it is later retrieved by MLMediaCodecGetOutputBufferPointer() in response to a MLMediaCodecDequeueOutputBuffer() return value.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCodecReleaseOutputBufferAtTime

MLResult MLMediaCodecReleaseOutputBufferAtTime(
    MLHandle handle,
    int64_t buffer_index,
    int64_t timestamp_ns
)

Update surface timestamp and returns it to the codec to render it on the output surface. If codec is not configured with output surface, this call simply returns the buffer to codec.

Parameters


MLHandle	handle	MLHandle to the MLMediaCodec object.
int64_t	buffer_index	Index of a client-owned output buffer previously returned from a call to MLMediaCodecDequeueOutputBuffer().
int64_t	timestamp_ns	The timestamp in nanoseconds to associate with this buffer when it is sent to the Surface.

Returns


MLResult	MLResult_InvalidParam	One of the parameters is invalid.
MLResult	MLResult_Ok	Output buffer was released successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

The timestamp may have special meaning depending on the destination surface.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

Macros Documentation

MAX_CODEC_NAME_SIZE

#define MAX_CODEC_NAME_SIZE 64

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"

ML_EXTERN_C_BEGIN

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecBufferInfo {
  size_t offset;
  size_t size;
  size_t flags;
  int64_t presentation_time_us;
} MLMediaCodecBufferInfo;

typedef enum MLMediaCodecCreation {
  MLMediaCodecCreation_ByName,
  MLMediaCodecCreation_ByType,
  MLMediaCodecCreation_Ensure32Bits = 0x7FFFFFFF
} MLMediaCodecCreation;

typedef enum MLMediaCodecType {
  MLMediaCodecType_Encoder,
  MLMediaCodecType_Decoder,
  MLMediaCodecType_Ensure32Bits = 0x7FFFFFFF
} MLMediaCodecType;

typedef enum MLMediaCodecBufferFlag {
  MLMediaCodecBufferFlag_KeyFrame     = 1,
  MLMediaCodecBufferFlag_CodecConfig  = 2,
  MLMediaCodecBufferFlag_EOS          = 4,
  MLMediaCodecBufferFlag_PartialFrame = 8,
  MLMediaCodecBufferFlag_MuxerData = 16,
  MLMediaCodecBufferFlag_Ensure32Bits = 0x7FFFFFFF
} MLMediaCodecBufferFlag;

typedef enum MLMediaCodecOutputBufferStatus {
  MLMediaCodec_OutputBuffersChanged           = -1014,
  MLMediaCodec_FormatChanged                  = -1012,
  MLMediaCodec_TryAgainLater                  = -11,
  MLMediaCodecOutputBufferStatus_Ensure32Bits = 0x7FFFFFFF
} MLMediaCodecOutputBufferStatus;

#define MAX_CODEC_NAME_SIZE 64

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecInputBufferInfo {
  int64_t input_buffer_index;
  void *data;
} MLMediaCodecInputBufferInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecOutputBufferInfo {
  int64_t output_buffer_index;
  MLMediaCodecBufferInfo *buffer_info;
  void *data;
} MLMediaCodecOutputBufferInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecOutputFormatInfo {
  MLHandle new_output_format;
  void *data;
} MLMediaCodecOutputFormatInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecErrorInfo {
  int error_code;
  void *data;
} MLMediaCodecErrorInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecCallbacksEx {
  uint32_t version;

  void (*on_input_buffer_available)(MLHandle media_codec, const MLMediaCodecInputBufferInfo *info);

  void (*on_output_buffer_available)(MLHandle media_codec, const MLMediaCodecOutputBufferInfo *info);

  void (*on_output_format_changed)(MLHandle media_codec, const MLMediaCodecOutputFormatInfo *info);

  void (*on_error)(MLHandle media_codec, const MLMediaCodecErrorInfo *info);
} MLMediaCodecCallbacksEx;

ML_STATIC_INLINE void MLMediaCodecCallbacksExInit(MLMediaCodecCallbacksEx *inout_callbacks) {
  if (inout_callbacks) {
    inout_callbacks->version = 1;
    inout_callbacks->on_input_buffer_available = NULL;
    inout_callbacks->on_output_buffer_available = NULL;
    inout_callbacks->on_output_format_changed = NULL;
    inout_callbacks->on_error = NULL;
  }
}

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecFrameRenderedInfo {
  int64_t presentation_time_us;
  int64_t system_time_nano;
  void *data;
} MLMediaCodecFrameRenderedInfo;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecOutputFrameListener {
  uint32_t version;

  void (*on_frame_rendered)(MLHandle media_codec, const MLMediaCodecFrameRenderedInfo *info);
} MLMediaCodecOutputFrameListener;

ML_STATIC_INLINE void MLMediaCodecOutputFrameListenerInit(MLMediaCodecOutputFrameListener *inout_callbacks) {
  if (inout_callbacks) {
    inout_callbacks->version = 1;
    inout_callbacks->on_frame_rendered = NULL;
  }
}

typedef enum MLMediaCodecCryptoMode {
  MLMediaCodecCryptoMode_Clear,
  MLMediaCodecCryptoMode_CTR,
  MLMediaCodecCryptoMode_CBC,
  MLMediaCodecCryptoMode_Ensure32Bits = 0x7FFFFFFF
} MLMediaCodecCryptoMode;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecCryptoPattern {
  size_t encrypt_blocks;
  size_t skip_blocks;
} MLMediaCodecCryptoPattern;

typedef ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.") struct MLMediaCodecCryptoInfo {
  uint32_t version;

  size_t                    number_of_subsamples;
  MLMediaCodecCryptoMode    crypto_mode;
  MLMediaCodecCryptoPattern crypto_pattern;
  const uint8_t*            key;
  const uint8_t*            iv;
  const size_t*             bytes_of_clear_data;
  const size_t*             bytes_of_encrypted_data;
} MLMediaCodecCryptoInfo;

ML_STATIC_INLINE void MLMediaCodecCryptoInfoInit(MLMediaCodecCryptoInfo *inout_crypto_info) {
  if (inout_crypto_info) {
    inout_crypto_info->version = 1;
    inout_crypto_info->number_of_subsamples = 0;
    inout_crypto_info->crypto_mode = MLMediaCodecCryptoMode_Clear;
    inout_crypto_info->crypto_pattern.encrypt_blocks = 0;
    inout_crypto_info->crypto_pattern.skip_blocks = 0;
    inout_crypto_info->key = NULL;
    inout_crypto_info->iv = NULL;
    inout_crypto_info->bytes_of_clear_data = NULL;
    inout_crypto_info->bytes_of_encrypted_data = NULL;
  }
}

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecCreateCryptoInfo(const MLMediaCodecCryptoInfo *crypto_info, MLHandle *out_crypto_info_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecReleaseCryptoInfo(MLHandle crypto_info_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecCreateCodec(MLMediaCodecCreation method, MLMediaCodecType type, const char *name_str, MLHandle *out_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecDestroy(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecSetCallbacksEx(MLHandle handle, MLMediaCodecCallbacksEx *callbacks, void *user_data);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecSetOutputFrameListener(MLHandle handle, MLMediaCodecOutputFrameListener *callbacks, void *user_data);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecGetName(MLHandle handle, char *out_name);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecConfigure(MLHandle handle, MLHandle format_handle, MLHandle surface_handle, MLHandle crypto_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecStart(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecStop(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecReset(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecFlush(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecSetParameters(MLHandle handle, MLHandle format_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecGetInputBufferPointer(MLHandle handle, int64_t buffer_index, uint8_t **out_buffer_ptr, size_t *out_buffer_size);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecGetOutputBufferPointer(MLHandle handle, int64_t buffer_index, const uint8_t **out_buffer_ptr, size_t *out_buffer_size);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecQueueInputBuffer(MLHandle handle, int64_t buffer_index, int64_t offset, size_t size, uint64_t time_us, int flags);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecQueueSecureInputBuffer(MLHandle handle, int64_t buffer_index, int64_t offset, MLHandle crypto_info_handle, uint64_t time_us, int flags);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecDequeueInputBuffer(MLHandle handle, int64_t timeout_us, int64_t *out_buffer_index);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecDequeueOutputBuffer(MLHandle handle, MLMediaCodecBufferInfo *out_buffer_info, int64_t timeout_us, int64_t *out_buffer_index);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecGetInputFormat(MLHandle handle, MLHandle *out_format_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecGetOutputFormat(MLHandle handle, MLHandle *out_format_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecCreateInputSurface(MLHandle handle, MLHandle *out_input_surface_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecDestroyInputSurface(MLHandle handle, MLHandle input_surface_handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecSignalEndOfInputStream(MLHandle handle);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecReleaseOutputBuffer(MLHandle handle, int64_t buffer_index, bool render);

ML_DEPRECATED_MSG("Use standard Android SDK and NDK APIs.")
ML_API MLResult ML_CALL MLMediaCodecReleaseOutputBufferAtTime(MLHandle handle, int64_t buffer_index, int64_t timestamp_ns);

ML_EXTERN_C_END

ml_media_codec.h

Classes​

Types​

Enums​

Functions​

Defines​

Enums Documentation​

MLMediaCodecCreation​

MLMediaCodecType​

MLMediaCodecBufferFlag​

MLMediaCodecOutputBufferStatus​

MLMediaCodecCryptoMode​

Types Documentation​

MLMediaCodecBufferInfo​

MLMediaCodecInputBufferInfo​

MLMediaCodecOutputBufferInfo​

MLMediaCodecOutputFormatInfo​

MLMediaCodecErrorInfo​

MLMediaCodecCallbacksEx​

MLMediaCodecFrameRenderedInfo​

MLMediaCodecOutputFrameListener​

MLMediaCodecCryptoPattern​

MLMediaCodecCryptoInfo​

Functions Documentation​

MLMediaCodecCallbacksExInit​

MLMediaCodecOutputFrameListenerInit​

MLMediaCodecCryptoInfoInit​

MLMediaCodecCreateCryptoInfo​

MLMediaCodecReleaseCryptoInfo​

MLMediaCodecCreateCodec​

MLMediaCodecDestroy​

MLMediaCodecSetCallbacksEx​

MLMediaCodecSetOutputFrameListener​

MLMediaCodecGetName​

MLMediaCodecConfigure​

MLMediaCodecStart​

MLMediaCodecStop​

MLMediaCodecReset​

MLMediaCodecFlush​

MLMediaCodecSetParameters​

MLMediaCodecGetInputBufferPointer​

MLMediaCodecGetOutputBufferPointer​

MLMediaCodecQueueInputBuffer​

MLMediaCodecQueueSecureInputBuffer​

MLMediaCodecDequeueInputBuffer​

MLMediaCodecDequeueOutputBuffer​

MLMediaCodecGetInputFormat​

MLMediaCodecGetOutputFormat​

MLMediaCodecCreateInputSurface​

MLMediaCodecDestroyInputSurface​

MLMediaCodecSignalEndOfInputStream​

MLMediaCodecReleaseOutputBuffer​

MLMediaCodecReleaseOutputBufferAtTime​

Macros Documentation​

MAX_CODEC_NAME_SIZE​

Source code​

Classes

Types

Enums

Functions

Defines

Enums Documentation

MLMediaCodecCreation

MLMediaCodecType

MLMediaCodecBufferFlag

MLMediaCodecOutputBufferStatus

MLMediaCodecCryptoMode

Types Documentation

MLMediaCodecBufferInfo

MLMediaCodecInputBufferInfo

MLMediaCodecOutputBufferInfo

MLMediaCodecOutputFormatInfo

MLMediaCodecErrorInfo

MLMediaCodecCallbacksEx

MLMediaCodecFrameRenderedInfo

MLMediaCodecOutputFrameListener

MLMediaCodecCryptoPattern

MLMediaCodecCryptoInfo

Functions Documentation

MLMediaCodecCallbacksExInit

MLMediaCodecOutputFrameListenerInit

MLMediaCodecCryptoInfoInit

MLMediaCodecCreateCryptoInfo

MLMediaCodecReleaseCryptoInfo

MLMediaCodecCreateCodec

MLMediaCodecDestroy

MLMediaCodecSetCallbacksEx

MLMediaCodecSetOutputFrameListener

MLMediaCodecGetName

MLMediaCodecConfigure

MLMediaCodecStart

MLMediaCodecStop

MLMediaCodecReset

MLMediaCodecFlush

MLMediaCodecSetParameters

MLMediaCodecGetInputBufferPointer

MLMediaCodecGetOutputBufferPointer

MLMediaCodecQueueInputBuffer

MLMediaCodecQueueSecureInputBuffer

MLMediaCodecDequeueInputBuffer

MLMediaCodecDequeueOutputBuffer

MLMediaCodecGetInputFormat

MLMediaCodecGetOutputFormat

MLMediaCodecCreateInputSurface

MLMediaCodecDestroyInputSurface

MLMediaCodecSignalEndOfInputStream

MLMediaCodecReleaseOutputBuffer

MLMediaCodecReleaseOutputBufferAtTime

Macros Documentation

MAX_CODEC_NAME_SIZE

Source code