Tizen Native API  5.0
Media Muxer

The Media Muxer APIs provides functions for muxing media data.

Required Header

#include <mediamuxer.h>

Overview

MEDIAMUXER API set allows : The API set allows one to directly access media muxer on device. Application can create, add relevant media track(s) and write corresponding samples to get muxed media files. mediamuxer takes encoded media as input and gives muxed media in a compatible container format.

Typical Call Flow of mediamuxer APIs is: mediamuxer_create() mediamuxer_set_data_sink() mediamuxer_add_track(1) mediamuxer_add_track(2) [add more tracks, if needed] mediamuxer_prepare() mediamuxer_start() while() if (is_track(1)_data_available) mediamuxer_write_sample(track(1)), else mediamuxer_close_track(1) if (is_track(2)_data_available) mediamuxer_write_sample(track(2)) else mediamuxer_close_track(2) mediamuxer_stop() mediamuxer_unprepare() mediamuxer_destroy()

Functions

int mediamuxer_create (mediamuxer_h *muxer)
 Creates a media muxer handle for muxing.
int mediamuxer_set_data_sink (mediamuxer_h muxer, char *path, mediamuxer_output_format_e format)
 Sets the sink path of output stream.
int mediamuxer_add_track (mediamuxer_h muxer, media_format_h media_format, int *track_index)
 Adds the media track of interest to the muxer handle.
int mediamuxer_prepare (mediamuxer_h muxer)
 Prepares the media muxer.
int mediamuxer_start (mediamuxer_h muxer)
 Starts the media muxer.
int mediamuxer_write_sample (mediamuxer_h muxer, int track_index, media_packet_h inbuf)
 Writes the media packet of interest to the muxer handle.
int mediamuxer_close_track (mediamuxer_h muxer, int track_index)
 Closes the track from further writing of data.
int mediamuxer_pause (mediamuxer_h muxer)
 Pauses the media muxer.
int mediamuxer_resume (mediamuxer_h muxer)
 Resumes the media muxer.
int mediamuxer_stop (mediamuxer_h muxer)
 Stops the media muxer.
int mediamuxer_unprepare (mediamuxer_h muxer)
 Unprepares the media muxer.
int mediamuxer_destroy (mediamuxer_h muxer)
 Removes the instance of media muxer and clear all its context memory.
int mediamuxer_get_state (mediamuxer_h muxer, mediamuxer_state_e *state)
 Gets media muxer state.
int mediamuxer_set_error_cb (mediamuxer_h muxer, mediamuxer_error_cb callback, void *user_data)
 Sets a error callback function to be invoked when an error occurs.
int mediamuxer_unset_error_cb (mediamuxer_h muxer)
 Unsets the error callback function.
int mediamuxer_set_eos_cb (mediamuxer_h muxer, mediamuxer_eos_cb callback, void *user_data)
 Sets an EOS (end of stream) callback function to be invoked when an EOS occurs.
int mediamuxer_unset_eos_cb (mediamuxer_h muxer)
 Unsets the EOS (end of stream) callback function.

Typedefs

typedef struct mediamuxer_s * mediamuxer_h
 Media Muxer handle type.
typedef void(* mediamuxer_error_cb )(mediamuxer_error_e error, void *user_data)
 Called when error occurs in media muxer.
typedef void(* mediamuxer_eos_cb )(void *user_data)
 Called when end of stream occurs in media muxer.

Typedef Documentation

typedef void(* mediamuxer_eos_cb)(void *user_data)

Called when end of stream occurs in media muxer.

Since :
4.0
Parameters:
[in]user_dataThe user data passed from the code where mediamuxer_set_eos_cb() was invoked;
this data will be accessible from mediamuxer_eos_cb()
Precondition:
Create media muxer handle by calling mediamuxer_create() function.
See also:
mediamuxer_set_eos_cb()
mediamuxer_unset_eos_cb()
typedef void(* mediamuxer_error_cb)(mediamuxer_error_e error, void *user_data)

Called when error occurs in media muxer.

Following error codes can be delivered. MEDIAMUXER_ERROR_INVALID_OPERATION, MEDIAMUXER_ERROR_NOT_SUPPORTED, MEDIAMUXER_ERROR_INVALID_PATH, MEDIAMUXER_ERROR_RESOURCE_LIMIT

Since :
3.0
Parameters:
[in]errorThe error that occurred in media muxer
[in]user_dataThe user data passed from the code where mediamuxer_set_error_cb() was invoked This data will be accessible from user_data mediamuxer_error_cb
Precondition:
Create media muxer handle by calling mediamuxer_create() function.
See also:
mediamuxer_set_error_cb()
mediamuxer_unset_error_cb()
typedef struct mediamuxer_s* mediamuxer_h

Media Muxer handle type.

Since :
3.0

Enumeration Type Documentation

Enumeration for media muxer error.

Since :
3.0
Enumerator:
MEDIAMUXER_ERROR_NONE 

Successful

MEDIAMUXER_ERROR_OUT_OF_MEMORY 

Out of memory

MEDIAMUXER_ERROR_INVALID_PARAMETER 

Invalid parameter

MEDIAMUXER_ERROR_INVALID_OPERATION 

Invalid operation

MEDIAMUXER_ERROR_NOT_SUPPORTED 

Not supported

MEDIAMUXER_ERROR_PERMISSION_DENIED 

Permission denied

MEDIAMUXER_ERROR_INVALID_STATE 

Invalid state

MEDIAMUXER_ERROR_INVALID_PATH 

Invalid path

MEDIAMUXER_ERROR_RESOURCE_LIMIT 

Resource limit

Enumeration for media muxer output format.

Since :
3.0
Enumerator:
MEDIAMUXER_CONTAINER_FORMAT_MP4 

The mediamuxer output format is MP4 container

MEDIAMUXER_CONTAINER_FORMAT_3GP 

The mediamuxer output format is 3GP container

MEDIAMUXER_CONTAINER_FORMAT_WAV 

The mediamuxer output format is WAV container

MEDIAMUXER_CONTAINER_FORMAT_AMR_NB 

The mediamuxer output format is ARM_NB container

MEDIAMUXER_CONTAINER_FORMAT_AMR_WB 

The mediamuxer output format is AMR_WB container

MEDIAMUXER_CONTAINER_FORMAT_AAC_ADTS 

The mediamuxer output format is AAC_ADTS container

Enumeration for media muxer state.

Since :
3.0
Enumerator:
MEDIAMUXER_STATE_NONE 

The mediamuxer is not created

MEDIAMUXER_STATE_IDLE 

The mediamuxer is created, but not prepared

MEDIAMUXER_STATE_READY 

The mediamuxer is ready to mux media

MEDIAMUXER_STATE_MUXING 

The mediamuxer is muxing media

MEDIAMUXER_STATE_PAUSED 

The mediamuxer is paused while muxing media


Function Documentation

int mediamuxer_add_track ( mediamuxer_h  muxer,
media_format_h  media_format,
int *  track_index 
)

Adds the media track of interest to the muxer handle.

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
[in]media_formatThe format of media muxer
[out]track_indexThe index of the media track
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_IDLE.
See also:
media_format_h
mediamuxer_create()
mediamuxer_prepare()
int mediamuxer_close_track ( mediamuxer_h  muxer,
int  track_index 
)

Closes the track from further writing of data.

Since :
3.0
Remarks:
For each added track, user needs to call this function to indicate the end of stream.
Parameters:
[in]muxerThe media muxer handle
[in]track_indexThe selected track index
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_MUXING.
See also:
mediamuxer_write_sample()
mediamuxer_pause()
mediamuxer_unprepare()
mediamuxer_error_e
int mediamuxer_create ( mediamuxer_h muxer)

Creates a media muxer handle for muxing.

Since :
3.0
Remarks:
You must release muxer using mediamuxer_destroy() function.
Parameters:
[out]muxerA new handle to media muxer
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid Operation
MEDIAMUXER_ERROR_OUT_OF_MEMORYAllocation Failed, Out of Memory.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_IDLE.
See also:
mediamuxer_destroy()

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

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
Create a media muxer handle by calling mediamuxer_create() function.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_NONE.
See also:
mediamuxer_create()

Gets media muxer state.

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
[out]stateThe media muxer sate
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
Create a media muxer handle by calling mediamuxer_create() function.
See also:
mediamuxer_state_e

Pauses the media muxer.

Since :
3.0
Remarks:
To temporarily disable writing data for muxing. This function pauses a playing muxer If the prior state of the muxer is not in PLAYING, no action will be taken.
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_MUXING.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_PAUSED.
See also:
mediamuxer_write_sample()
mediamuxer_resume()

Prepares the media muxer.

Since :
3.0
Remarks:
Initiates the necessary parameters.
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_IDLE.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_READY.
See also:
mediamuxer_create()
mediamuxer_unprepare()

Resumes the media muxer.

Since :
3.0
Remarks:
Make it ready for any further writing. This function will resume a paused muxer. If the prior state of the muxer is not playing, no action will be taken.
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_PAUSED.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_MUXING.
See also:
mediamuxer_pause()
int mediamuxer_set_data_sink ( mediamuxer_h  muxer,
char *  path,
mediamuxer_output_format_e  format 
)

Sets the sink path of output stream.

Since :
3.0
Remarks:
The mediastorage privilege(http://tizen.org/privilege/mediastorage) should be added if any video/audio files are to be saved in the internal storage.
The externalstorage privilege(http://tizen.org/privilege/externalstorage) should be added if any video/audio files are to be saved in the external storage.
Parameters:
[in]muxerA new handle to media muxer
[in]pathThe location of the output media file, such as the file path This is the path at which the muxed file should be saved.
[in]formatThe format of the output media file
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
MEDIAMUXER_ERROR_INVALID_PATHInvalid path
Precondition:
The media muxer state will be MEDIAMUXER_STATE_IDLE by calling mediamuxer_create
See also:
mediamuxer_output_format_e
int mediamuxer_set_eos_cb ( mediamuxer_h  muxer,
mediamuxer_eos_cb  callback,
void *  user_data 
)

Sets an EOS (end of stream) callback function to be invoked when an EOS occurs.

Since :
4.0
Parameters:
[in]muxerThe media muxer handle
[in]callbackCallback function pointer
[in]user_dataThe user data passed from the code where mediamuxer_set_eos_cb() was invoked;
this data will be accessible from mediamuxer_eos_cb()
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
Create a media muxer handle by calling mediamuxer_create() function.
Postcondition:
mediamuxer_eos_cb() will be invoked.
See also:
mediamuxer_unset_eos_cb()
mediamuxer_eos_cb()
int mediamuxer_set_error_cb ( mediamuxer_h  muxer,
mediamuxer_error_cb  callback,
void *  user_data 
)

Sets a error callback function to be invoked when an error occurs.

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
[in]callbackCallback function pointer
[in]user_dataThe user data passed from the code where mediamuxer_set_error_cb() was invoked This data will be accessible from user_data mediamuxer_error_cb
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create a media muxer handle by calling mediamuxer_create() function.
Postcondition:
mediamuxer_error_cb() will be invoked.
See also:
mediamuxer_unset_error_cb()
mediamuxer_error_cb()

Starts the media muxer.

Since :
3.0
Remarks:
Keeps the muxer ready for writing data.
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_READY.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_MUXING.
See also:
mediamuxer_prepare()
mediamuxer_stop()
int mediamuxer_stop ( mediamuxer_h  muxer)

Stops the media muxer.

Since :
3.0
Remarks:
Keeps the muxer ready for writing data.
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_MUXING or MEDIAMUXER_STATE_PAUSED.
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_READY.
See also:
mediamuxer_start()
mediamuxer_unprepare()

Unprepares the media muxer.

Since :
3.0
Remarks:
Unrefs the variables created after calling mediamuxer_prepare().
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_READY or set to MEDIAMUXER_STATE_PAUSED by calling mediamuxer_pause().
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_IDLE.
See also:
mediamuxer_write_sample()
mediamuxer_pause()
mediamuxer_destroy()

Unsets the EOS (end of stream) callback function.

Since :
4.0
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
See also:
mediamuxer_eos_cb()

Unsets the error callback function.

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediamuxer_error_cb()
int mediamuxer_write_sample ( mediamuxer_h  muxer,
int  track_index,
media_packet_h  inbuf 
)

Writes the media packet of interest to the muxer handle.

Since :
3.0
Parameters:
[in]muxerThe media muxer handle
[in]track_indexThe index of the media track
[in]inbufThe packet of media muxer
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAMUXER_ERROR_NONESuccessful
MEDIAMUXER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAMUXER_ERROR_INVALID_OPERATIONInvalid operation
MEDIAMUXER_ERROR_INVALID_STATEInvalid state
Precondition:
The media muxer state must be set to MEDIAMUXER_STATE_READY by calling mediamuxer_prepare() or set to MEDIAMUXER_STATE_PAUSED by calling mediamuxer_pause().
Postcondition:
The media muxer state will be MEDIAMUXER_STATE_MUXING.
See also:
mediamuxer_prepare()
mediamuxer_close_track()
mediamuxer_pause()
media_packet_h