Tizen Native API  4.0
Media Demuxer

The Media Demuxer APIs provides functions for demuxing media data.

Required Header

#include <mediademuxer.h>

Overview

MEDIADEMUXER API allows :
1) To extract elementary audio, video or text data from a multiplexed stream
2) To choose one or multiple desired stream to extract.
3) To choose the local or remote input source.
4) To create single or multiple instances of media demuxer. One instance can demux only one
input stream
5) To demux all the popular media formats such as MP4, AAC-NB, AAC-WB, MP3 etc.
6) To extract elementary media sample information, such as timestamp, sample size, key-frame(I-frame) etc.
7) To identify encrypted format
8) To seek to a different position-forward or backward- while extracting

Typical Call Flow of mediamuxer APIs is:
mediademuxer_create()
mediademuxer_set_data_source()
mediademuxer_prepare()
mediademuxer_get_track_count()
mediademuxer_select_track()
mediademuxer_start()
mediademuxer_get_track_info()

 while(EOS) {
	if(track1 is set) {
		mediademuxer_read_sample();
		if(seek_request)
			mediademuxer_seek();
	}
	else if(track2 is set) {
		 mediademuxer_read_sample();
	}
	if(track2_not_needed)
		mediademuxer_unselect_track(track2);
  }
 

mediademuxer_stop()
mediademuxer_unprepare()
mediademuxer_destroy()

Functions

int mediademuxer_create (mediademuxer_h *demuxer)
 Creates a media demuxer handle for demuxing.
int mediademuxer_set_data_source (mediademuxer_h demuxer, const char *path)
 Sets the source path of input stream.
int mediademuxer_prepare (mediademuxer_h demuxer)
 Prepares the media demuxer for demuxing.
int mediademuxer_get_track_count (mediademuxer_h demuxer, int *count)
 Gets the total track count present in the container stream.
int mediademuxer_select_track (mediademuxer_h demuxer, int track_index)
 Selects the track to be performed.
int mediademuxer_start (mediademuxer_h demuxer)
 Starts the media demuxer.
int mediademuxer_get_track_info (mediademuxer_h demuxer, int track_index, media_format_h *format)
 Retrieves the track format of the read sample.
int mediademuxer_read_sample (mediademuxer_h demuxer, int track_index, media_packet_h *outbuf)
 Reads a frame(sample) of one single track.
int mediademuxer_seek (mediademuxer_h demuxer, int64_t pos)
 Seeks to a particular instance of time (in milli seconds).
int mediademuxer_unselect_track (mediademuxer_h demuxer, int track_index)
 Unselects the selected track.
int mediademuxer_stop (mediademuxer_h demuxer)
 Stops the media demuxer.
int mediademuxer_unprepare (mediademuxer_h demuxer)
 Resets the media demuxer.
int mediademuxer_destroy (mediademuxer_h demuxer)
 Removes the instance of media demuxer and clear all its context memory.
int mediademuxer_get_state (mediademuxer_h demuxer, mediademuxer_state *state)
 Gets media demuxer state.
int mediademuxer_set_error_cb (mediademuxer_h demuxer, mediademuxer_error_cb callback, void *user_data)
 Registers an error callback function to be invoked when an error occurs.
int mediademuxer_unset_error_cb (mediademuxer_h demuxer)
 Unregisters the error callback function.
int mediademuxer_set_eos_cb (mediademuxer_h demuxer, mediademuxer_eos_cb callback, void *user_data)
 Registers an eos callback function to be invoked when an eos occurs.
int mediademuxer_unset_eos_cb (mediademuxer_h demuxer)
 Unregisters the eos callback function.

Typedefs

typedef struct mediademuxer_s * mediademuxer_h
 Media Demuxer handle type.
typedef void(* mediademuxer_error_cb )(mediademuxer_error_e error, void *user_data)
 Called when error occurs in media demuxer.
typedef void(* mediademuxer_eos_cb )(int track_num, void *user_data)
 Called when end of stream occurs in media demuxer.

Typedef Documentation

typedef void(* mediademuxer_eos_cb)(int track_num, void *user_data)

Called when end of stream occurs in media demuxer.

Since :
3.0
Parameters:
[in]track_numThe track_num which indicate eos for which track number occured
[in]user_dataThe user data passed from the code where mediademuxer_set_eos_cb() was invoked This data will be accessible from mediademuxer_eos_cb()
Precondition:
Create media demuxer handle by calling mediademuxer_create() function.
See also:
mediademuxer_set_eos_cb()
mediademuxer_unset_eos_cb()
typedef void(* mediademuxer_error_cb)(mediademuxer_error_e error, void *user_data)

Called when error occurs in media demuxer.

Following error codes can be delivered. MEDIADEMUXER_ERROR_INVALID_OPERATION, MEDIADEMUXER_ERROR_NOT_SUPPORTED, MEDIADEMUXER_ERROR_INVALID_PATH, MEDIADEMUXER_ERROR_RESOURCE_LIMIT, MEDIADEMUXER_ERROR_SEEK_FAILED, MEDIADEMUXER_ERROR_DRM_NOT_PERMITTED

Since :
3.0
Parameters:
[in]errorThe error that occurred in media demuxer
[in]user_dataThe user data passed from the code where mediademuxer_set_error_cb() was invoked This data will be accessible from mediademuxer_error_cb()
Precondition:
Create media demuxer handle by calling mediademuxer_create() function.
See also:
mediademuxer_set_error_cb()
mediademuxer_unset_error_cb()
typedef struct mediademuxer_s* mediademuxer_h

Media Demuxer handle type.

Since :
3.0

Enumeration Type Documentation

Enumeration for media demuxer error.

Since :
3.0
Enumerator:
MEDIADEMUXER_ERROR_NONE 

Successful

MEDIADEMUXER_ERROR_OUT_OF_MEMORY 

Out of memory

MEDIADEMUXER_ERROR_INVALID_PARAMETER 

Invalid parameter

MEDIADEMUXER_ERROR_INVALID_OPERATION 

Invalid operation

MEDIADEMUXER_ERROR_NOT_SUPPORTED 

Not supported

MEDIADEMUXER_ERROR_PERMISSION_DENIED 

Permission denied

MEDIADEMUXER_ERROR_INVALID_STATE 

Invalid state

MEDIADEMUXER_ERROR_INVALID_PATH 

Invalid path

MEDIADEMUXER_ERROR_RESOURCE_LIMIT 

Resource limit

MEDIADEMUXER_ERROR_SEEK_FAILED 

Seek operation failure

MEDIADEMUXER_ERROR_DRM_NOT_PERMITTED 

Not permitted format

Enumeration for media demuxer state.

Since :
3.0
Enumerator:
MEDIADEMUXER_STATE_NONE 

The mediademuxer is not created

MEDIADEMUXER_STATE_IDLE 

The mediademuxer is created, but not prepared

MEDIADEMUXER_STATE_READY 

The mediademuxer is ready to demux media

MEDIADEMUXER_STATE_DEMUXING 

The mediademuxer is demuxing media


Function Documentation

int mediademuxer_create ( mediademuxer_h demuxer)

Creates a media demuxer handle for demuxing.

Since :
3.0
Remarks:
You must release demuxer using mediademuxer_destroy() function.
Parameters:
[out]demuxerA new handle to media demuxer
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
MEDIADEMUXER_ERROR_OUT_OF_MEMORYOut of memory
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
Postcondition:
The media demuxer state will be MEDIADEMUXER_STATE_IDLE.
See also:
mediademuxer_destroy()

Removes the instance of media demuxer and clear all its context memory.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
Create a media demuxer handle by calling mediademuxer_create() function.
Postcondition:
The media demuxer state will be MEDIADEMUXER_STATE_NONE.
See also:
mediademuxer_create()

Gets media demuxer state.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[out]stateThe media demuxer sate
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
Create a media demuxer handle by calling mediademuxer_create() function.
See also:
mediademuxer_state
int mediademuxer_get_track_count ( mediademuxer_h  demuxer,
int *  count 
)

Gets the total track count present in the container stream.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[out]countThe number of tracks present
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_READY.
See also:
mediademuxer_prepare()
mediademuxer_select_track()
int mediademuxer_get_track_info ( mediademuxer_h  demuxer,
int  track_index,
media_format_h format 
)

Retrieves the track format of the read sample.

Since :
3.0
Remarks:
The format should be released using media_format_unref() function.
Parameters:
[in]demuxerThe media demuxer handle
[in]track_indexThe index of the track
[out]formatThe media format handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state must be set to MEDIADEMUXER_STATE_DEMUXING by calling mediademuxer_start() or set to MEDIADEMUXER_STATE_READY by calling mediademuxer_prepare().
See also:
mediademuxer_get_track_count()
mediademuxer_select_track()
media_format_unref()
media_format_h

Prepares the media demuxer for demuxing.

Since :
3.0
Remarks:
User should call this before mediademuxer_start() function.
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_IDLE.
mediademuxer_set_error_cb should be called before mediademuxer_prepare().
Postcondition:
The media demuxer state will be MEDIADEMUXER_STATE_READY.
See also:
mediademuxer_set_data_source()
mediademuxer_unprepare()
int mediademuxer_read_sample ( mediademuxer_h  demuxer,
int  track_index,
media_packet_h outbuf 
)

Reads a frame(sample) of one single track.

Since :
3.0
Remarks:
The outbuf should be released using media_packet_destroy() function.
Once this API is called, user app can call the mediatool APIs to extract side information such as pts, size, duration, flags etc.
Parameters:
[in]demuxerThe media demuxer handle
[in]track_indexThe index of track of which data is needed
[out]outbufThe media packet handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_DEMUXING.
See also:
mediademuxer_start()
mediademuxer_get_track_info()
mediademuxer_seek() if need to seek to a particular location
mediademuxer_unselect_track()
mediademuxer_stop()
media_packet_destroy()
media_packet_h
int mediademuxer_seek ( mediademuxer_h  demuxer,
int64_t  pos 
)

Seeks to a particular instance of time (in milli seconds).

Since :
3.0
Remarks:
If mediademuxer_seek() is followed by mediademuxer_read_sample(), outbuf will be the key frame right before the seek position.
Parameters:
[in]demuxerThe media demuxer handle
[in]posThe value of the new start position
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_DEMUXING.
See also:
mediademuxer_read_sample()
mediademuxer_stop()
int mediademuxer_select_track ( mediademuxer_h  demuxer,
int  track_index 
)

Selects the track to be performed.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[in]track_indexThe track index on which is selected for read
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_READY.
See also:
mediademuxer_get_track_count()
mediademuxer_start()
int mediademuxer_set_data_source ( mediademuxer_h  demuxer,
const char *  path 
)

Sets the source path of input stream.

Since :
3.0
Remarks:
The mediastorage privilege(http://tizen.org/privilege/mediastorage) should be added if any video/audio files are used to play located in the internal storage.
The externalstorage privilege(http://tizen.org/privilege/externalstorage) should be added if any video/audio files are used to play located in the external storage.
You must release demuxer using mediademuxer_destroy() function.
Parameters:
[in]demuxerThe media demuxer handle
[in]pathThe content location, such as the file path
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
MEDIADEMUXER_ERROR_INVALID_PATHInvalid path
Precondition:
The media muxer state will be MEDIADEMUXER_STATE_IDLE by calling mediademuxer_create() function.
int mediademuxer_set_eos_cb ( mediademuxer_h  demuxer,
mediademuxer_eos_cb  callback,
void *  user_data 
)

Registers an eos callback function to be invoked when an eos occurs.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[in]callbackCallback function pointer
[in]user_dataThe user data passed from the code where mediademuxer_set_eos_cb() was invoked This data will be accessible from mediademuxer_eos_cb()
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
Create a media demuxer handle by calling mediademuxer_create() function.
Postcondition:
mediademuxer_eos_cb() will be invoked.
See also:
mediademuxer_unset_eos_cb()
mediademuxer_eos_cb()
int mediademuxer_set_error_cb ( mediademuxer_h  demuxer,
mediademuxer_error_cb  callback,
void *  user_data 
)

Registers an error callback function to be invoked when an error occurs.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[in]callbackCallback function pointer
[in]user_dataThe user data passed from the code where mediademuxer_set_error_cb() was invoked This data will be accessible from mediademuxer_error_cb()
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
Create a media demuxer handle by calling mediademuxer_create() function.
Postcondition:
mediademuxer_error_cb() will be invoked.
See also:
mediademuxer_unset_error_cb()
mediademuxer_error_cb()

Starts the media demuxer.

Since :
3.0
Remarks:
User should call this before mediademuxer_read_sample() function.
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_READY.
Postcondition:
The media demuxer state will be MEDIADEMUXER_STATE_DEMUXING.
See also:
mediademuxer_prepare()
mediademuxer_get_track_count()
mediademuxer_select_track()
mediademuxer_get_track_info()

Stops the media demuxer.

Since :
3.0
Remarks:
User can call this if need to stop demuxing if needed.
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state must be set to MEDIADEMUXER_STATE_DEMUXING.
Postcondition:
The media demuxer state will be in MEDIADEMUXER_STATE_READY.
See also:
mediademuxer_start()
mediademuxer_unprepare()

Resets the media demuxer.

Since :
3.0
Remarks:
User should call this before mediademuxer_destroy() function.
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state should be MEDIADEMUXER_STATE_READY.
Postcondition:
The media demuxer state will be MEDIADEMUXER_STATE_IDLE.
See also:
mediademuxer_prepare()
int mediademuxer_unselect_track ( mediademuxer_h  demuxer,
int  track_index 
)

Unselects the selected track.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
[in]track_indexThe track index to be unselected
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
MEDIADEMUXER_ERROR_INVALID_OPERATIONInvalid Operation
Precondition:
The media demuxer state must be set to MEDIADEMUXER_STATE_DEMUXING by calling mediademuxer_read_sample() or set to MEDIADEMUXER_STATE_READY by calling mediademuxer_select_track().
See also:
mediademuxer_select_track()
mediademuxer_read_sample()

Unregisters the eos callback function.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
See also:
mediademuxer_eos_cb()

Unregisters the error callback function.

Since :
3.0
Parameters:
[in]demuxerThe media demuxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIADEMUXER_ERROR_NONESuccessful
MEDIADEMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIADEMUXER_ERROR_INVALID_STATEInvalid state
See also:
mediademuxer_error_cb()