The Audio Metadata API provides functions to get information about audio items.

Required Header

#include <media_content.h>

Overview

The Audio Metadata API provides functions to get information about stored audio files. Its purpose is twofold:

to provide information about audio content
to organize audio content logically (grouping)

API provides functions that allow to check attributes of audio files. Following information about audio content is provided:

Attribute	Filter Keyword	Comments
title	MEDIA_TITLE	Get from metadata if exist. if not, base name except file extension.
album	MEDIA_ALBUM	Get from metadata if exist.
artist	MEDIA_ARTIST	Get from metadata if exist.
album_artist	MEDIA_ALBUM_ARTIST	Get from metadata if exist.
genre	MEDIA_GENRE	Get from metadata if exist.
composer	MEDIA_COMPOSER	Get from metadata if exist.
year	MEDIA_YEAR	Get from metadata if exist.
recorded_date	MEDIA_RECORDED_DATE	Get from metadata if exist. if not, same as modified time.
copyright	MEDIA_COPYRIGHT	Get from metadata if exist.
track_num	MEDIA_TRACK_NUM	Get from metadata if exist.
bit_rate	MEDIA_BITRATE	Bitrate
bitpersample	MEDIA_BITPERSAMPLE	Bit per sample
sample_rate	MEDIA_SAMPLERATE	Samplerate
channel	MEDIA_CHANNEL	Channel
duration	MEDIA_DURATION	Duration
rating	MEDIA_RATING	Get from metadata if exist.
author	MEDIA_AUTHOR	Get from metadata if exist.

For getting the audio handle (audio_meta_h) from the media information (media_info_h), call media_info_get_audio() function.
For getting the information related to audio files stored in the device, call the respective get functions e.g. to get the artist of a audio, call audio_meta_get_artist() function and to get bitrate of a audio, call audio_meta_get_bit_rate() function and so on.
When the audio handle is no longer needed, it should be destroyed by calling audio_meta_destroy() function.

Functions
int	audio_meta_clone (audio_meta_h *dst, audio_meta_h src)
	Clones the audio metadata.
int	audio_meta_destroy (audio_meta_h audio)
	Destroys the audio metadata.
int	audio_meta_get_media_id (audio_meta_h audio, char **media_id)
	Gets the ID of the media of the given audio metadata.
int	audio_meta_get_album (audio_meta_h audio, char **album)
	Gets the album of the given audio metadata.
int	audio_meta_get_artist (audio_meta_h audio, char **artist)
	Gets the artist of the given audio metadata.
int	audio_meta_get_album_artist (audio_meta_h audio, char **album_artist)
	Gets the album artist of the given audio metadata.
int	audio_meta_get_genre (audio_meta_h audio, char **genre)
	Gets the genre of the given audio metadata.
int	audio_meta_get_composer (audio_meta_h audio, char **composer)
	Gets the composer of the given audio metadata.
int	audio_meta_get_year (audio_meta_h audio, char **year)
	Gets the year of the given audio metadata.
int	audio_meta_get_recorded_date (audio_meta_h audio, char **recorded_date)
	Gets the recorded date of the given audio metadata.
int	audio_meta_get_copyright (audio_meta_h audio, char **copyright)
	Gets the copyright notice of the given audio metadata.
int	audio_meta_get_track_num (audio_meta_h audio, char **track_num)
	Gets the track number of the given audio metadata.
int	audio_meta_get_bit_rate (audio_meta_h audio, int *bit_rate)
	Gets the bitrate of the given audio metadata in bitrate per second.
int	audio_meta_get_bitpersample (audio_meta_h audio, int *bitpersample)
	Gets bit per sample of the given audio metadata.
int	audio_meta_get_sample_rate (audio_meta_h audio, int *sample_rate)
	Gets the sample rate of the given audio metadata.
int	audio_meta_get_channel (audio_meta_h audio, int *channel)
	Gets the channel of the given audio metadata.
int	audio_meta_get_duration (audio_meta_h audio, int *duration)
	Gets the track duration of the given audio metadata.
int	audio_meta_get_played_count (audio_meta_h audio, int *played_count) TIZEN_DEPRECATED_API
	Gets the number of times the given audio has been played.
int	audio_meta_get_played_time (audio_meta_h audio, time_t *played_time) TIZEN_DEPRECATED_API
	Gets the last played time parameter of the audio.
int	audio_meta_get_played_position (audio_meta_h audio, int *played_position) TIZEN_DEPRECATED_API
	Gets the played position parameter of the audio.
int	audio_meta_set_played_count (audio_meta_h audio, int played_count) TIZEN_DEPRECATED_API
	Sets the played count of the audio.
int	audio_meta_set_played_time (audio_meta_h audio, time_t played_time) TIZEN_DEPRECATED_API
	Sets the last played time of the audio.
int	audio_meta_set_played_position (audio_meta_h audio, int played_position) TIZEN_DEPRECATED_API
	Sets the played position of the audio.
int	audio_meta_update_to_db (audio_meta_h audio) TIZEN_DEPRECATED_API
	Updates an audio metadata with modified attributes in the media database.
Typedefs
typedef struct audio_meta_s *	audio_meta_h
	The structure type for the Audio metadata handle.

Typedef Documentation

typedef struct audio_meta_s* audio_meta_h

The structure type for the Audio metadata handle.

Since :: 2.3

Function Documentation

int audio_meta_clone	(	audio_meta_h *	dst,
		audio_meta_h	src
	)

Clones the audio metadata.

This function copies the audio metadata handle from a source to destination.

Since :: 2.3

Remarks:: The dst should be released using audio_meta_destroy().

Parameters:

[out]	dst	The destination handle to the audio metadata
[in]	src	The source handle to the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

See also:: audio_meta_destroy()

int audio_meta_destroy ( audio_meta_h audio )

Destroys the audio metadata.

This function frees all resources related to the audio metadata handle. This handle no longer can be used to perform any operation. A new handle has to be created before the next use.

Since :: 2.3

Parameters:

[in] audio The handle to the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Get a copy of audio metadata handle handle by calling audio_meta_clone().

See also:: audio_meta_clone()

int audio_meta_get_album	(	audio_meta_h	audio,
		char **	album
	)

Gets the album of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no album info, the method returns empty string.

Since :: 2.3

Remarks:: The album should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	album	The album of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_album_artist	(	audio_meta_h	audio,
		char **	album_artist
	)

Gets the album artist of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no album artist info, the method returns empty string.

Since :: 2.3

Remarks:: The album_artist should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	album_artist	The album artist of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_artist	(	audio_meta_h	audio,
		char **	artist
	)

Gets the artist of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no artist info, the method returns empty string.

Since :: 2.3

Remarks:: The artist should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	artist	The artist of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_bit_rate	(	audio_meta_h	audio,
		int *	bit_rate
	)

Gets the bitrate of the given audio metadata in bitrate per second.

Since :: 2.3

Parameters:

[in]	audio	The handle to the audio metadata
[out]	bit_rate	The audio bitrate in bit per second [bps]

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_bitpersample	(	audio_meta_h	audio,
		int *	bitpersample
	)

Gets bit per sample of the given audio metadata.

Since :: 2.3

Parameters:

[in]	audio	The handle to the audio metadata
[out]	bitpersample	The audio bit per sample

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_channel	(	audio_meta_h	audio,
		int *	channel
	)

Gets the channel of the given audio metadata.

Since :: 2.3

Parameters:

[in]	audio	The handle to the audio metadata
[out]	channel	The channel of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_composer	(	audio_meta_h	audio,
		char **	composer
	)

Gets the composer of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no composer info, the method returns empty string.

Since :: 2.3

Remarks:: The composer should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	composer	The composer of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_copyright	(	audio_meta_h	audio,
		char **	copyright
	)

Gets the copyright notice of the given audio metadata.

If the media content has no copyright info, the method returns empty string.

Since :: 2.3

Remarks:: The copyright should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	copyright	The copyright of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_duration	(	audio_meta_h	audio,
		int *	duration
	)

Gets the track duration of the given audio metadata.

Since :: 2.3

Parameters:

[in]	audio	The handle to the audio metadata
[out]	duration	The audio file duration

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_genre	(	audio_meta_h	audio,
		char **	genre
	)

Gets the genre of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no genre info, the method returns empty string.

Since :: 2.3

Remarks:: The genre should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	genre	The genre of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_media_id	(	audio_meta_h	audio,
		char **	media_id
	)

Gets the ID of the media of the given audio metadata.

Since :: 2.3

Remarks:: The media_id should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	media_id	The media ID

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_played_count	(	audio_meta_h	audio,
		int *	played_count
	)

Gets the number of times the given audio has been played.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.

Since :: 2.3

Parameters:

[in]	audio	The audio metadata handle
[out]	played_count	The counter of the audio played

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_played_position	(	audio_meta_h	audio,
		int *	played_position
	)

Gets the played position parameter of the audio.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.

This function returns the elapsed playback position parameter of the audio as a period starting from the beginning of the track.

Since :: 2.3

Parameters:

[in]	audio	The audio metadata handle
[out]	played_position	The elapsed time of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_played_time	(	audio_meta_h	audio,
		time_t *	played_time
	)

Gets the last played time parameter of the audio.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.

Since :: 2.3

Parameters:

[in]	audio	The audio metadata handle
[out]	played_time	The last played time of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_recorded_date	(	audio_meta_h	audio,
		char **	recorded_date
	)

Gets the recorded date of the given audio metadata.

The recorded date is got from audio file's metadata. Some formats like mp4 use UTC and the rest can be different.
So, please refer to the format specification if needed.

Since :: 2.3

Remarks:: The recorded_date should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	recorded_date	The recorded date of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_sample_rate	(	audio_meta_h	audio,
		int *	sample_rate
	)

Gets the sample rate of the given audio metadata.

Since :: 2.3

Parameters:

[in]	audio	The handle to the audio metadata
[out]	sample_rate	The audio sample rate[hz]

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_get_track_num	(	audio_meta_h	audio,
		char **	track_num
	)

Gets the track number of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no track info, the method returns empty string.

Since :: 2.3

Remarks:: The track_num should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	track_num	The audio track number of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_get_year	(	audio_meta_h	audio,
		char **	year
	)

Gets the year of the given audio metadata.

If the value is an empty string, the method returns "Unknown".
Since 3.0, if the media content has no year info, the method returns empty string.

Since :: 2.3

Remarks:: The year should be released using free().

Parameters:

[in]	audio	The handle to the audio metadata
[out]	year	The year of the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int audio_meta_set_played_count	(	audio_meta_h	audio,
		int	played_count
	)

Sets the played count of the audio.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.

Since :: 2.3

Parameters:

[in]	audio	The audio metadata handle
[in]	played_count	The played count of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_set_played_position	(	audio_meta_h	audio,
		int	played_position
	)

Sets the played position of the audio.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.

Since :: 2.3

Remarks:: It is NOT recommended to use this attribute for your application-specific purpose because this attribute can be overwritten by other applications (even 0).

Parameters:

[in]	audio	The audio metadata handle
[in]	played_position	The played position of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_set_played_time	(	audio_meta_h	audio,
		time_t	played_time
	)

Sets the last played time of the audio.

Deprecated:: Deprecated since 2.4.
This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.

Since :: 2.3

Parameters:

[in]	audio	The audio metadata handle
[in]	played_time	The last played time of the audio

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int audio_meta_update_to_db ( audio_meta_h audio )

Updates an audio metadata with modified attributes in the media database.

Deprecated:: Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.

The function updates the given audio meta in the media database. The function should be called after any change in audio attributes, to be updated to the media database.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/content.write

Remarks:: Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().

Parameters:

[in] audio The handle to the audio metadata

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

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy
MEDIA_CONTENT_ERROR_NETWORK	Network fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

Precondition:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect()

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation