The Metadata Editor API provides functions for editing the metadata of mp3, mp4 contents. Since 6.0, this module supports WAV, FLAC and OGG files as well.

Required Header

#include <metadata_editor.h>

Overview

The Metadata Editor API allows you to read the metadata from a media file(metadata_editor_get_metadata()). To edit a metadata(metadata_editor_set_metadata()), create/destroy the handle(metadata_editor_create()/metadata_editor_destroy), and append/ remove a picture in the metadata(metadata_editor_append_picture()/ metadata_editor_remove_picture()).

Functions
int	metadata_editor_create (metadata_editor_h *metadata)
	Creates metadata.
int	metadata_editor_set_path (metadata_editor_h metadata, const char *path)
	Sets file path to read or write metadata.
int	metadata_editor_get_metadata (metadata_editor_h metadata, metadata_editor_attr_e attribute, char **value)
	Gets the metadata corresponding to the attribute.
int	metadata_editor_set_metadata (metadata_editor_h metadata, metadata_editor_attr_e attribute, const char *value)
	Sets the attribute of the metadata.
int	metadata_editor_update_metadata (metadata_editor_h metadata)
	Updates the modified metadata.
int	metadata_editor_get_picture (metadata_editor_h metadata, int index, void *picture, int size, char **mime_type)
	Gets the picture in the media file.
int	metadata_editor_append_picture (metadata_editor_h metadata, const char *picture_path)
	Appends the picture to the media file.
int	metadata_editor_remove_picture (metadata_editor_h metadata, int index)
	Removes artwork image from media file.
int	metadata_editor_destroy (metadata_editor_h metadata)
	Destroys metadata.
Typedefs
typedef void *	metadata_editor_h
	The handle of media metadata.
Defines
#define	METADATA_EDITOR_ERROR_CLASS TIZEN_ERROR_METADATA_EDITOR
	Definition for Metadata editor Error Class.

Define Documentation

#define METADATA_EDITOR_ERROR_CLASS TIZEN_ERROR_METADATA_EDITOR

Definition for Metadata editor Error Class.

Since :: 3.0

Typedef Documentation

typedef void* metadata_editor_h

The handle of media metadata.

Since :: 3.0

Enumeration Type Documentation

enum metadata_editor_attr_e

The enumerations of attribute.

Since :: 3.0

Enumerator:

METADATA_EDITOR_ATTR_ARTIST	Artist
METADATA_EDITOR_ATTR_TITLE	Title
METADATA_EDITOR_ATTR_ALBUM	Album
METADATA_EDITOR_ATTR_GENRE	Genre
METADATA_EDITOR_ATTR_AUTHOR	Author
METADATA_EDITOR_ATTR_COPYRIGHT	Copyright
METADATA_EDITOR_ATTR_DATE	Date
METADATA_EDITOR_ATTR_DESCRIPTION	Description
METADATA_EDITOR_ATTR_COMMENT	Comment
METADATA_EDITOR_ATTR_TRACK_NUM	Track number info
METADATA_EDITOR_ATTR_PICTURE_NUM	Picture number
METADATA_EDITOR_ATTR_CONDUCTOR	Conductor
METADATA_EDITOR_ATTR_UNSYNCLYRICS	Unsynchronized lyric

enum metadata_editor_error_e

The enumerations of media metadata error.

Since :: 3.0

Enumerator:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_FILE_EXISTS	File not exist
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied
METADATA_EDITOR_ERROR_NOT_SUPPORTED	Unsupported type
METADATA_EDITOR_ERROR_OPERATION_FAILED	Invalid internal operation
METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE	Update not possible (Since 6.0)

Function Documentation

int metadata_editor_append_picture	(	metadata_editor_h	metadata,
		const char *	picture_path
	)

Appends the picture to the media file.

Since :: 3.0

Remarks:: You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata().
Image type of the metadata supports jpeg and png.
In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage. This function doesn't support updating metadata of an invalid media file. Before 6.0, this function returned METADATA_EDITOR_ERROR_OPERATION_FAILED. Since 6.0, METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE is returned in such cases.

Parameters:

[in]	metadata	The handle to metadata
[in]	picture_path	The path of picture for adding to the metadata

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_NOT_SUPPORTED	unsupported file type
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied
METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE	Update not possible

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_update_metadata(); metadata_editor_destroy()

int metadata_editor_create ( metadata_editor_h * metadata )

Creates metadata.

Since :: 3.0

Remarks:: The metadata should be released using metadata_editor_destroy().

Parameters:

[in] metadata The handle to metadata

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory

See also:: metadata_editor_destroy()

int metadata_editor_destroy ( metadata_editor_h metadata )

Destroys metadata.

Since :: 3.0

Parameters:

[in] metadata The handle to metadata

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail

Precondition:: Create metadata handle by calling metadata_editor_create()

See also:: metadata_editor_create()

int metadata_editor_get_metadata	(	metadata_editor_h	metadata,
		metadata_editor_attr_e	attribute,
		char **	value
	)

Gets the metadata corresponding to the attribute.

Since :: 3.0

Remarks:: The value should be released using free().
If the attribute value of the metadata is empty, return value is NULL.
In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.

Parameters:

[in]	metadata	The handle to metadata
[in]	attribute	key attribute name to get
[out]	value	The value of the attribute

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_destroy()

int metadata_editor_get_picture	(	metadata_editor_h	metadata,
		int	index,
		void **	picture,
		int *	size,
		char **	mime_type
	)

Gets the picture in the media file.

If there is no picture or if the index is invalid, this function returns METADATA_EDITOR_ERROR_INVALID_PARAMETER.
You can get picture number by using metadata_editor_get_metadata() and index starts with 0.

Since :: 3.0

Remarks:: The picture and mime_type should be released using free().
In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.

Parameters:

[in]	metadata	The handle to metadata
[in]	index	picture order (starts with 0)
[out]	picture	encoded picture
[out]	size	encoded picture size
[out]	mime_type	the MIME of the picture

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_destroy()

int metadata_editor_remove_picture	(	metadata_editor_h	metadata,
		int	index
	)

Removes artwork image from media file.

Since :: 3.0

Remarks:: You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata().
In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.

Parameters:

[in]	metadata	The handle to metadata
[in]	index	artwork image order

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_update_metadata(); metadata_editor_destroy()

int metadata_editor_set_metadata	(	metadata_editor_h	metadata,
		metadata_editor_attr_e	attribute,
		const char *	value
	)

Sets the attribute of the metadata.

This function set the attribute of the metadata for updating the metadata.
If attribute is METADATA_EDITOR_ATTR_PICTURE_NUM, this function returns METADATA_EDITOR_ERROR_INVALID_PARAMETER.

Since :: 3.0

Remarks:: The value should be released using free().
You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata(). This function doesn't support updating metadata of an invalid media file. Before 6.0, this function returned METADATA_EDITOR_ERROR_OPERATION_FAILED. Since 6.0, METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE is returned in such cases.

Parameters:

[in]	metadata	The handle to metadata
[in]	attribute	key attribute name to get
[in]	value	The value of the attribute

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail
METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE	Update not possible

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_update_metadata(); metadata_editor_destroy()

int metadata_editor_set_path	(	metadata_editor_h	metadata,
		const char *	path
	)

Sets file path to read or write metadata.

Since :: 3.0

Remarks:: In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.

Parameters:

[in]	metadata	The handle to metadata
[in]	path	path to read or write metadata

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_FILE_EXISTS	File not exist
METADATA_EDITOR_ERROR_NOT_SUPPORTED	unsupported file type
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail

Precondition:: Create metadata handle by calling metadata_editor_create()

See also:: metadata_editor_create(); metadata_editor_destroy()

int metadata_editor_update_metadata ( metadata_editor_h metadata )

Updates the modified metadata.

This function update the metadata in the media file that is modified by metadata_editor_set_metadata().

Since :: 3.0

Remarks:: In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path.
For example, if you get the specific path by using storage_get_directory(). you should add privilege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.

Parameters:

[in] metadata The handle to metadata

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

Return values:

METADATA_EDITOR_ERROR_NONE	Successful
METADATA_EDITOR_ERROR_INVALID_PARAMETER	Invalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORY	Out of memory
METADATA_EDITOR_ERROR_PERMISSION_DENIED	Permission denied
METADATA_EDITOR_ERROR_OPERATION_FAILED	Internal Operation Fail

Precondition:: Set path to read or write metadata by calling metadata_editor_set_path()

See also:: metadata_editor_create(); metadata_editor_set_path(); metadata_editor_destroy()

Required Header

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation