Tizen Native API  6.0
Metadata Editor

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 :
2.4

Typedef Documentation

typedef void* metadata_editor_h

The handle of media metadata.

Since :
2.4

Enumeration Type Documentation

The enumerations of attribute.

Since :
2.4
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

The enumerations of media metadata error.

Since :
2.4
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 :
2.4
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]metadataThe handle to metadata
[in]picture_pathThe path of picture for adding to the metadata
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_NOT_SUPPORTEDunsupported file type
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission denied
METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLEUpdate 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()

Creates metadata.

Since :
2.4
Remarks:
The metadata should be released using metadata_editor_destroy().
Parameters:
[in]metadataThe handle to metadata
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
See also:
metadata_editor_destroy()

Destroys metadata.

Since :
2.4
Parameters:
[in]metadataThe handle to metadata
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal 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 :
2.4
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]metadataThe handle to metadata
[in]attributekey attribute name to get
[out]valueThe value of the attribute
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission denied
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal 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 :
2.4
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]metadataThe handle to metadata
[in]indexpicture order (starts with 0)
[out]pictureencoded picture
[out]sizeencoded picture size
[out]mime_typethe MIME of the picture
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission 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 :
2.4
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]metadataThe handle to metadata
[in]indexartwork image order
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal Operation Fail
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission 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 :
2.4
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]metadataThe handle to metadata
[in]attributekey attribute name to get
[in]valueThe value of the attribute
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal Operation Fail
METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLEUpdate 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 :
2.4
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]metadataThe handle to metadata
[in]pathpath to read or write metadata
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_FILE_EXISTSFile not exist
METADATA_EDITOR_ERROR_NOT_SUPPORTEDunsupported file type
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission denied
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal Operation Fail
Precondition:
Create metadata handle by calling metadata_editor_create()
See also:
metadata_editor_create()
metadata_editor_destroy()

Updates the modified metadata.

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

Since :
2.4
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]metadataThe handle to metadata
Returns:
0 on success, otherwise a negative error value
Return values:
METADATA_EDITOR_ERROR_NONESuccessful
METADATA_EDITOR_ERROR_INVALID_PARAMETERInvalid parameter
METADATA_EDITOR_ERROR_OUT_OF_MEMORYOut of memory
METADATA_EDITOR_ERROR_PERMISSION_DENIEDPermission denied
METADATA_EDITOR_ERROR_OPERATION_FAILEDInternal 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()