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]	error	The error code
[in]	state	The state when error was occurred
[in]	user_data	The 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_data The 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]	previous	The previous state
[in]	current	The current state
[in]	user_data	The user data passed from the callback registration function

See also:: mediaeditor_set_state_changed_cb(); mediaeditor_unset_state_changed_cb()

Enumeration Type Documentation

enum mediaeditor_display_type_e

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

enum mediaeditor_error_e

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

enum mediaeditor_state_e

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

int mediaeditor_cancel_render ( mediaeditor_h editor )

Cancels rendering.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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] editor A newly returned handle to the media editor

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_RESOURCE_FAILED	Resource manager initialization error

Postcondition:: editor state will be MEDIAEDITOR_STATE_IDLE.

See also:: mediaeditor_destroy()

int mediaeditor_destroy ( mediaeditor_h editor )

Destroys a media editor handle and releases all its resources.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_RESOURCE_FAILED	Resource manager deinitialization error

See also:: mediaeditor_create()

int mediaeditor_get_state	(	mediaeditor_h	editor,
		mediaeditor_state_e *	state
	)

Gets the current state.

Since :: 7.0

Parameters:

[in]	editor	The media editor handle
[out]	state	The media editor state

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: mediaeditor_state_e

int mediaeditor_set_display	(	mediaeditor_h	editor,
		mediaeditor_display_type_e	type,
		mediaeditor_display_h	display
	)

Sets a display for preview.

Since :: 7.0

Parameters:

[in]	editor	The media editor handle
[in]	type	The display type
[in]	display	The display handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_NOT_SUPPORTED	The feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	callback	Callback function pointer
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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()

int mediaeditor_start_preview ( mediaeditor_h editor )

Starts to preview.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_NOT_SUPPORTED	The feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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]	editor	The media editor handle
[in]	path	The path to save rendered output
[in]	callback	The callback function to register
[in]	user_data	The user data to be passed to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_PERMISSION_DENIED	Permission denied
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid 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()

int mediaeditor_stop_preview ( mediaeditor_h editor )

Stops to preview.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_NOT_SUPPORTED	The feature is not supported
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid state

Precondition:: editor state must be set to MEDIAEDITOR_STATE_PREVIEW.

Postcondition:: editor state will be MEDIAEDITOR_STATE_IDLE.

See also:: mediaeditor_start_preview()

int mediaeditor_unset_error_cb ( mediaeditor_h editor )

Unsets an error callback function.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid state

Precondition:: editor state must be set to MEDIAEDITOR_STATE_IDLE.

See also:: mediaeditor_set_error_cb()

int mediaeditor_unset_state_changed_cb ( mediaeditor_h editor )

Unsets a state changed callback function.

Since :: 7.0

Parameters:

[in] editor The media editor handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIAEDITOR_ERROR_NONE	Successful
MEDIAEDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIAEDITOR_ERROR_INVALID_OPERATION	Invalid operation
MEDIAEDITOR_ERROR_INVALID_STATE	Invalid state

Precondition:: editor state must be set to MEDIAEDITOR_STATE_IDLE.

See also:: mediaeditor_set_state_changed_cb()

Required Header

Overview

State Transitions

Callback(Event) Operations

Related Feature

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation