Tizen Native API

The Media Codec APIs provides functions for encodinging and decoding using media data.

Required Header

#include <media_codec.h>

Overview

MEDIA CODEC API allows : The API allows you to direct access to the media codec on device. It operates on "raw" data, so any file headers must be stripped off. media_packet is used for zero-copy.

Functions

int mediacodec_create (mediacodec_h *mediacodec)
 Creates a mediacodec handle for decoding/encoding.
int mediacodec_destroy (mediacodec_h mediacodec)
 Destroys the mediacodec handle and releases all its resources.
int mediacodec_set_codec (mediacodec_h mediacodec, mediacodec_codec_type_e codec_id, mediacodec_support_type_e flags)
 Sets the codec type and decoder/encoder.
int mediacodec_set_vdec_info (mediacodec_h mediacodec, int width, int height)
 Sets the default info for the video decoder.
int mediacodec_set_venc_info (mediacodec_h mediacodec, int width, int height, int fps, int target_bits)
 Sets the default info for the video encoder.
int mediacodec_set_adec_info (mediacodec_h mediacodec, int samplerate, int channel, int bit)
 Sets the default info for the audio decoder.
int mediacodec_set_aenc_info (mediacodec_h mediacodec, int samplerate, int channel, int bit, int bitrate)
 Sets the default info for the audio encdoer.
int mediacodec_prepare (mediacodec_h mediacodec)
 Prepares mediacodec for encoding/decoding.
int mediacodec_unprepare (mediacodec_h mediacodec)
 Unprepares mediacodec for encoding/decoding.
int mediacodec_process_input (mediacodec_h mediacodec, media_packet_h inbuf, uint64_t timeOutUs)
 Decodes/Encodes a packet. The function passed undecoded/unencoded packet to the input queue and decode/encode a frame sequentially.
int mediacodec_get_output (mediacodec_h mediacodec, media_packet_h *outbuf, uint64_t timeOutUs)
 Gets the decoded or encoded packet from the output queue.
int mediacodec_set_input_buffer_used_cb (mediacodec_h mediacodec, mediacodec_input_buffer_used_cb callback, void *user_data)
 set empty buffer callback the media codec for process, asynchronously.
int mediacodec_unset_input_buffer_used_cb (mediacodec_h mediacodec)
 unset input buffer used callback the media codec for process, asynchronously.
int mediacodec_set_output_buffer_available_cb (mediacodec_h mediacodec, mediacodec_output_buffer_available_cb callback, void *user_data)
 set output buffer available callback the media codec for process, asynchronously.
int mediacodec_unset_output_buffer_available_cb (mediacodec_h mediacodec)
 unset output buffer available callback the media codec for process, asynchronously.
int mediacodec_set_error_cb (mediacodec_h mediacodec, mediacodec_error_cb callback, void *user_data)
 set error callback the media codec for process, asynchronously.
int mediacodec_unset_error_cb (mediacodec_h mediacodec)
 unset error callback the media codec for process, asynchronously.
int mediacodec_set_eos_cb (mediacodec_h mediacodec, mediacodec_eos_cb callback, void *user_data)
 set eos callback the media codec for process, asynchronously.
int mediacodec_unset_eos_cb (mediacodec_h mediacodec)
 unset eos callback the media codec for process, asynchronously.

Typedefs

typedef struct mediacodec_s * mediacodec_h
 Media Codec type handle.
typedef void(* mediacodec_input_buffer_used_cb )(media_packet_h pkt, void *user_data)
 Called when the input buffer(pkt) used up.
typedef void(* mediacodec_output_buffer_available_cb )(media_packet_h pkt, void *user_data)
 Called when the output buffer is available.
typedef void(* mediacodec_error_cb )(mediacodec_error_e error, void *user_data)
 Called when the error has occured.
typedef void(* mediacodec_eos_cb )(void *user_data)
 Called when there is no data to decode/encode.

Typedef Documentation

typedef void(* mediacodec_eos_cb)(void *user_data)

Called when there is no data to decode/encode.

Since :
2.3.1

It will be invoked when the end-of-stream is reached.

Parameters:
[in]user_dataThe user data passed from the callback registration function
Precondition:
It will be invoked when the eos event generate if you register this callback using mediacodec_set_eos_cb().
See also:
mediacodec_set_eos_cb()
mediacodec_unset_eos_cb()
typedef void(* mediacodec_error_cb)(mediacodec_error_e error, void *user_data)

Called when the error has occured.

Since :
2.3.1

It will be invoked when the error has occured.

Parameters:
[in]error_codeThe error code
[in]user_dataThe user data passed from the callback registration function
Precondition:
It will be invoked when the error has occured if you register this callback using mediacodec_set_error_cb().
See also:
mediacodec_set_error_cb()
mediacodec_unset_error_cb()
typedef struct mediacodec_s* mediacodec_h

Media Codec type handle.

Since :
2.3.1
typedef void(* mediacodec_input_buffer_used_cb)(media_packet_h pkt, void *user_data)

Called when the input buffer(pkt) used up.

Since :
2.3.1

It will be invoked when mediacodec has used input buffer.

Parameters:
[in]pktThe media packet handle
[in]user_dataThe user data passed from the callback registration function
Precondition:
It will be invoked when input buffer process completed if you register this callback using mediacodec_set_input_buffer_used_cb().
See also:
mediacodec_set_input_buffer_used_cb()
mediacodec_unset_input_buffer_used_cb()
typedef void(* mediacodec_output_buffer_available_cb)(media_packet_h pkt, void *user_data)

Called when the output buffer is available.

Since :
2.3.1

It will be invoked when mediacodec has output buffer.

Parameters:
[in]pktThe media packet handle
[in]user_dataThe user data passed from the callback registration function
Precondition:
It will be invoked when mediacodec process completed(had output buffer) if you register this callback using mediacodec_set_fill_buffer_cb().
See also:
mediacodec_set_output_buffer_available_cb()
mediacodec_unset_output_buffer_available_cb()

Enumeration Type Documentation

Enumerations of media codec type.

Since :
2.3.1
Enumerator:
MEDIACODEC_NONE 

NONE

MEDIACODEC_L16 

L16

MEDIACODEC_ALAW 

ALAW

MEDIACODEC_ULAW 

ULAW

MEDIACODEC_AMR 

AMR

MEDIACODEC_G729 

G729

MEDIACODEC_AAC 

AAC

MEDIACODEC_MP3 

MP3

MEDIACODEC_H261 

H.261

MEDIACODEC_H263 

H.263

MEDIACODEC_H264 

H.264

MEDIACODEC_MJPEG 

MJPEG

MEDIACODEC_MPEG1 

MPEG1

MEDIACODEC_MPEG2 

MPEG2

MEDIACODEC_MPEG4 

MPEG4

Enumeration of media codec error.

Since :
2.3.1
Enumerator:
MEDIACODEC_ERROR_NONE 

Successful

MEDIACODEC_ERROR_OUT_OF_MEMORY 

Out of memory

MEDIACODEC_ERROR_INVALID_PARAMETER 

Invalid parameter

MEDIACODEC_ERROR_INVALID_OPERATION 

Invalid operation

MEDIACODEC_ERROR_NOT_SUPPORTED_ON_DEVICE 

Not supported

MEDIACODEC_ERROR_PERMISSION_DENIED 

Permission denied

MEDIACODEC_ERROR_INVALID_STATE 

Invalid state

MEDIACODEC_ERROR_INVALID_INBUFFER 

Invalid input buffer

MEDIACODEC_ERROR_INVALID_OUTBUFFER 

Invalid output buffer

MEDIACODEC_ERROR_INTERNAL 

Internal error

MEDIACODEC_ERROR_NOT_INITIALIZED 

Not initialized mediacodec

MEDIACODEC_ERROR_INVALID_STREAM 

Invalid stream

MEDIACODEC_ERROR_CODEC_NOT_FOUND 

Not supported format

MEDIACODEC_ERROR_DECODE 

Error while decoding data

MEDIACODEC_ERROR_NO_FREE_SPACE 

Out of storage

MEDIACODEC_ERROR_STREAM_NOT_FOUND 

Cannot find stream

MEDIACODEC_ERROR_NOT_SUPPORTED_FORMAT 

Not supported format

MEDIACODEC_ERROR_BUFFER_NOT_AVAILABLE 

Not available buffer

Enumeration of media codec support type.

Since :
2.3.1
Remarks:
If this codec is to be used as an encoder or decoder, the codec flag must be set to MEDIACODEC_ENCODER or MEDIACODEC_DECODER. If user doesn't set optional flag, default flags will be set to MEDIACODEC_SUPPORT_TYPE_HW.
Enumerator:
MEDIACODEC_ENCODER 

This flag is for using the encoder

MEDIACODEC_DECODER 

This flag is for using the decoder

MEDIACODEC_SUPPORT_TYPE_HW 

This is an optional flag for using the h/w codec

MEDIACODEC_SUPPORT_TYPE_SW 

This is an optional flag for using the s/w codec


Function Documentation

int mediacodec_create ( mediacodec_h mediacodec)

Creates a mediacodec handle for decoding/encoding.

Since :
2.3.1
Remarks:
you must release mediacodec using mediacodec_destroy().
Although you can create multiple mediacodec handles at the same time, the mediacodec cannot guarantee proper operation because of limited resources, like audio or display device.
Parameters:
[out]mediacodecA new handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_destroy ( mediacodec_h  mediacodec)

Destroys the mediacodec handle and releases all its resources.

Since :
2.3.1
Remarks:
To completely shutdown the mediacodec operation, call this function with a valid player handle from any mediacodec
Parameters:
[in]mediacodecThe handle to mediacodec to be destroyed.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_get_output ( mediacodec_h  mediacodec,
media_packet_h outbuf,
uint64_t  timeOutUs 
)

Gets the decoded or encoded packet from the output queue.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]outbufThe current output of the decoder/encoder. this function passed decoded/encoded frame to output queue.
[in]timeOutUsThe timeout in microseconds.
The input buffer wait up to "timeOutUs" microseconds.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_prepare ( mediacodec_h  mediacodec)

Prepares mediacodec for encoding/decoding.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
The mediacodec should call mediacodec_set_codec()and mediacodec_set_vdec_info()/mediacodec_set_venc_info() before calling mediacodec_prepare() If the decoder is set by mediacodec_set_codec(), mediacodec_set_vdec_info() should be called. If the encoder is set by mediacodec_set_codec(), mediacodec_set_venc_info() should be called.
int mediacodec_process_input ( mediacodec_h  mediacodec,
media_packet_h  inbuf,
uint64_t  timeOutUs 
)

Decodes/Encodes a packet. The function passed undecoded/unencoded packet to the input queue and decode/encode a frame sequentially.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]inbufThe current input format for the decoder/encoder
[in]timeOutUsThe timeout in microseconds.
The input buffer wait up to "timeOutUs" microseconds.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_set_adec_info ( mediacodec_h  mediacodec,
int  samplerate,
int  channel,
int  bit 
)

Sets the default info for the audio decoder.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]samplerateThe samplerate for audio decoding.
[in]channelThe channels for audio decoding.
[in]bitThe bits resolution for audio decoding.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_set_aenc_info ( mediacodec_h  mediacodec,
int  samplerate,
int  channel,
int  bit,
int  bitrate 
)

Sets the default info for the audio encdoer.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]samplerateThe samplerate for audio encoding.
[in]channelThe channels for audio encoding.
[in]bitThe bits resolution for audio encoding.
[in]bitrateThe bitrate for audio encoding.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation

Sets the codec type and decoder/encoder.

Since :
2.3.1
Remarks:
If this codec is to be used as a decoder, pass the MEDIACODEC_DECODER flag. If this codec is to be used as an encoder, pass the MEDIACODEC_ENCODER flag. By default, It is used hardware default setting. If user want software setting, pass the MEDIACODEC_SUPPORT_TYPE_SW flags.
Parameters:
[in]mediacodecThe handle of mediacodec
[in]codec_idThe identifier of the codec type of the decoder/encoder
[in]flagsThe encoding/decoding scheme.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
MEDIACODEC_ERROR_CODEC_NOT_FOUNDCodec not found
int mediacodec_set_eos_cb ( mediacodec_h  mediacodec,
mediacodec_eos_cb  callback,
void *  user_data 
)

set eos callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
mediacodec_set_eos_cb should be called before mediacodec_preare().
Postcondition:
mediacodec_eos_cb will be invoked.
See also:
mediacodec_set_eos_cb()
mediacodec_unset_eos_cb()
int mediacodec_set_error_cb ( mediacodec_h  mediacodec,
mediacodec_error_cb  callback,
void *  user_data 
)

set error callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
mediacodec_set_error_cb should be called before mediacodec_preare().
Postcondition:
mediacodec_error_cb will be invoked.
See also:
mediacodec_set_error_cb()
mediacodec_unset_error_cb()
int mediacodec_set_input_buffer_used_cb ( mediacodec_h  mediacodec,
mediacodec_input_buffer_used_cb  callback,
void *  user_data 
)

set empty buffer callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
mediacodec_set_input_buffer_used_cb should be called before mediacodec_preare().
Postcondition:
mediacodec_input_buffer_used_cb will be invoked.
See also:
mediacodec_set_input_buffer_used_cb()
mediacodec_unset_input_buffer_used_cb()

set output buffer available callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
mediacodec_set_output_buffer_available_cb should be called before mediacodec_preare().
Postcondition:
mediacodec_output_buffer_available_cb will be invoked.
See also:
mediacodec_set_output_buffer_available_cb()
mediacodec_unset_output_buffer_available_cb()
int mediacodec_set_vdec_info ( mediacodec_h  mediacodec,
int  width,
int  height 
)

Sets the default info for the video decoder.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
[in]widthThe width for video decoding.
[in]heightThe height for video decoding.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_set_venc_info ( mediacodec_h  mediacodec,
int  width,
int  height,
int  fps,
int  target_bits 
)

Sets the default info for the video encoder.

Since :
2.3.1
Remarks:
The frame rate is the speed of recording and the speed of playback. If user wants the default setting for ratecontrol, set target_bits to 0.
Parameters:
[in]mediacodecThe handle to mediacodec
[in]widthThe width for video encoding.
[in]heightThe height for video encoding.
[in]fpsThe frame rate in frames per second.
[in]target_bitsThe target bitrates in bits per second.(a unit of kbit)
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation
int mediacodec_unprepare ( mediacodec_h  mediacodec)

Unprepares mediacodec for encoding/decoding.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
MEDIACODEC_ERROR_OUT_OF_MEMORYOut of memory
MEDIACODEC_ERROR_INVALID_OPERATIONInvalid operation

unset eos callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediacodec_set_event_handler_cb()

unset error callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediacodec_set_error_cb()

unset input buffer used callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediacodec_set_input_buffer_used_cb()

unset output buffer available callback the media codec for process, asynchronously.

Since :
2.3.1
Parameters:
[in]mediacodecThe handle to mediacodec
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIACODEC_ERROR_NONESuccessful
MEDIACODEC_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediacodec_set_output_buffer_available_cb()