Tizen Native API  7.0

The Mediaeditor API provides functions for editing media clip and creating output media file.

Required Header

#include <media_editor.h>

Overview

The Mediaeditor API allows application developers to edit media clip.

The Mediaeditor API set allows you to:

  • add/remove/split/group/ungroup the media clip
  • add/remove/move layer
  • add/remove audio, video effect to media clip

State Transitions

FUNCTION PRE-STATE POST-STATE SYNC TYPE
mediaeditor_create() NONE IDLE SYNC
mediaeditor_destroy() IDLE/RENDERING/PREVIEW NONE SYNC
mediaeditor_start_preview() IDLE PREVIEW ASYNC
mediaeditor_start_render() IDLE RENDERING ASYNC

(*) The transition from the RENDERING state to the IDLE state will be processed after finishing the rendering.

Callback(Event) Operations

The callback mechanism is used to notify the application about significant mediaeditor events.

REGISTER UNREGISTER CALLBACK DESCRIPTION
mediaeditor_set_state_changed_cb() mediaeditor_unset_state_changed_cb() mediaeditor_state_changed_cb() This callback is used to notify that the mediaeditor state has changed
mediaeditor_set_error_cb() mediaeditor_unset_error_cb() mediaeditor_error_cb() This callback is used to notify that an error has occurred

Related Feature

This API is related with the following feature:

  • http://tizen.org/feature/display

It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions

int mediaeditor_create (mediaeditor_h *editor)
 Creates a new media editor handle.
int mediaeditor_destroy (mediaeditor_h editor)
 Destroys a media editor handle and releases all its resources.
int mediaeditor_set_display (mediaeditor_h editor, mediaeditor_display_type_e type, mediaeditor_display_h display)
 Sets a display for preview.
int mediaeditor_get_state (mediaeditor_h editor, mediaeditor_state_e *state)
 Gets the current state.
int mediaeditor_start_render (mediaeditor_h editor, const char *path, mediaeditor_render_completed_cb callback, void *user_data)
 Starts to render with given path, asynchronously.
int mediaeditor_cancel_render (mediaeditor_h editor)
 Cancels rendering.
int mediaeditor_start_preview (mediaeditor_h editor)
 Starts to preview.
int mediaeditor_stop_preview (mediaeditor_h editor)
 Stops to preview.
int mediaeditor_set_error_cb (mediaeditor_h editor, mediaeditor_error_cb callback, void *user_data)
 Sets a callback function to be invoked when an asynchronous operation error occurs.
int mediaeditor_unset_error_cb (mediaeditor_h editor)
 Unsets an error callback function.
int mediaeditor_set_state_changed_cb (mediaeditor_h editor, mediaeditor_state_changed_cb callback, void *user_data)
 Sets a callback function to be invoked when the media editor state is changed.
int mediaeditor_unset_state_changed_cb (mediaeditor_h editor)
 Unsets a state changed callback function.

Typedefs

typedef void * mediaeditor_h
 The media editor handle.
typedef void * mediaeditor_display_h
 The media editor display handle type.
typedef void(* mediaeditor_error_cb )(mediaeditor_error_e error, mediaeditor_state_e state, void *user_data)
 Called when an error occurs.
typedef void(* mediaeditor_state_changed_cb )(mediaeditor_state_e previous, mediaeditor_state_e current, void *user_data)
 Called when the state of media editor is changed.
typedef void(* mediaeditor_render_completed_cb )(void *user_data)
 Called when rendering output is completed.

Typedef Documentation

typedef void* mediaeditor_display_h

The media editor display handle type.

Since :
7.0
typedef void(* mediaeditor_error_cb)(mediaeditor_error_e error, mediaeditor_state_e state, void *user_data)

Called when an error occurs.

The following error codes can be received:
MEDIAEDITOR_ERROR_INVALID_OPERATION
MEDIAEDITOR_ERROR_INVALID_STATE
MEDIAEDITOR_ERROR_RESOURCE_CONFLICT
MEDIAEDITOR_ERROR_RESOURCE_FAILED

Since :
7.0
Parameters:
[in]errorThe error code
[in]stateThe state when error was occurred
[in]user_dataThe user data passed from the callback registration function
See also:
mediaeditor_set_error_cb()
mediaeditor_unset_error_cb()
typedef void* mediaeditor_h

The media editor handle.

Since :
7.0
typedef void(* mediaeditor_render_completed_cb)(void *user_data)

Called when rendering output is completed.

Since :
7.0
Parameters:
[in]user_dataThe user data passed from the callback registration function
See also:
mediaeditor_start_render()
typedef void(* mediaeditor_state_changed_cb)(mediaeditor_state_e previous, mediaeditor_state_e current, void *user_data)

Called when the state of media editor is changed.

Since :
7.0
Parameters:
[in]previousThe previous state
[in]currentThe current state
[in]user_dataThe user data passed from the callback registration function
See also:
mediaeditor_set_state_changed_cb()
mediaeditor_unset_state_changed_cb()

Enumeration Type Documentation

Enumeration for the media editor display type.

Since :
7.0
Enumerator:
MEDIAEDITOR_DISPLAY_TYPE_OVERLAY 

Overlay surface display

MEDIAEDITOR_DISPLAY_TYPE_EVAS 

Evas object surface display

MEDIAEDITOR_DISPLAY_TYPE_ECORE 

Ecore object surface display

MEDIAEDITOR_DISPLAY_TYPE_NONE 

This disposes of buffers

Enumeration for the error codes of media editor.

Since :
7.0
Enumerator:
MEDIAEDITOR_ERROR_NONE 

Successful

MEDIAEDITOR_ERROR_NOT_SUPPORTED 

Not supported

MEDIAEDITOR_ERROR_INVALID_OPERATION 

Internal error

MEDIAEDITOR_ERROR_INVALID_PARAMETER 

Invalid parameter

MEDIAEDITOR_ERROR_PERMISSION_DENIED 

The access to the resources can not be granted

MEDIAEDITOR_ERROR_INVALID_STATE 

Invalid state

MEDIAEDITOR_ERROR_RESOURCE_CONFLICT 

Blocked by resource conflicted

MEDIAEDITOR_ERROR_RESOURCE_FAILED 

Blocked by resource failed

Enumeration for the media editor state.

Since :
7.0
Enumerator:
MEDIAEDITOR_STATE_IDLE 

Created, but not started to render

MEDIAEDITOR_STATE_RENDERING 

Start to rendering and saving

MEDIAEDITOR_STATE_PREVIEW 

Start to preview without saving


Function Documentation

Cancels rendering.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_RENDERING.
Postcondition:
editor state will be MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_start_render()
int mediaeditor_create ( mediaeditor_h editor)

Creates a new media editor handle.

Since :
7.0
Remarks:
The editor must be released using mediaeditor_destroy().
The timeline which is composed of a set of layers and clips will be created.
Parameters:
[out]editorA newly returned handle to the media editor
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_RESOURCE_FAILEDResource manager initialization error
Postcondition:
editor state will be MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_destroy()

Destroys a media editor handle and releases all its resources.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_RESOURCE_FAILEDResource manager deinitialization error
See also:
mediaeditor_create()

Gets the current state.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[out]stateThe media editor state
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mediaeditor_state_e

Sets a display for preview.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]typeThe display type
[in]displayThe display handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_NOT_SUPPORTEDThe feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_start_preview()
int mediaeditor_set_error_cb ( mediaeditor_h  editor,
mediaeditor_error_cb  callback,
void *  user_data 
)

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

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
mediaeditor_error_cb() will be invoked.
See also:
mediaeditor_unset_error_cb()
mediaeditor_error_cb()
int mediaeditor_set_state_changed_cb ( mediaeditor_h  editor,
mediaeditor_state_changed_cb  callback,
void *  user_data 
)

Sets a callback function to be invoked when the media editor state is changed.

Since :
7.0
Parameters:
[in]editorThe media editor handle
[in]callbackCallback function pointer
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
mediaeditor_state_changed_cb() will be invoked.
See also:
mediaeditor_unset_state_changed_cb()
mediaeditor_state_changed_cb()

Starts to preview.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_NOT_SUPPORTEDThe feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
The display handle must be set by calling mediaeditor_set_display()
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
editor state will be MEDIAEDITOR_STATE_PREVIEW.
See also:
mediaeditor_set_display()
int mediaeditor_start_render ( mediaeditor_h  editor,
const char *  path,
mediaeditor_render_completed_cb  callback,
void *  user_data 
)

Starts to render with given path, asynchronously.

Since :
7.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/mediastorage
Privilege:
http://tizen.org/privilege/externalstorage
Remarks:
If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage.
Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage.
If you want to access both storage, you must add both privileges.
Parameters:
[in]editorThe media editor handle
[in]pathThe path to save rendered output
[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:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_PERMISSION_DENIEDPermission denied
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
User must add clip by calling mediaeditor_add_clip().
editor state must be set to MEDIAEDITOR_STATE_IDLE.
Postcondition:
editor state will be MEDIAEDITOR_STATE_RENDERING.
mediaeditor_render_completed_cb() will be invoked.
See also:
mediaeditor_add_clip()
mediaeditor_cancel_render()

Stops to preview.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_NOT_SUPPORTEDThe feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_PREVIEW.
Postcondition:
editor state will be MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_start_preview()

Unsets an error callback function.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_set_error_cb()

Unsets a state changed callback function.

Since :
7.0
Parameters:
[in]editorThe media editor handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIAEDITOR_ERROR_NONESuccessful
MEDIAEDITOR_ERROR_INVALID_PARAMETERInvalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATIONInvalid operation
MEDIAEDITOR_ERROR_INVALID_STATEInvalid state
Precondition:
editor state must be set to MEDIAEDITOR_STATE_IDLE.
See also:
mediaeditor_set_state_changed_cb()