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

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:

album
artist
genre
composer
year
recorded_date
copyright
track number
sample rate
played count
played time
played position
bitrate

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_destroy (audio_meta_h audio)
	Destroys the audio metadata.
int	audio_meta_clone (audio_meta_h *dst, audio_meta_h src)
	Clones the audio metadata.
int	audio_meta_get_media_id (audio_meta_h audio, char **media_id)
	Gets the audio ID of the given audio metadata.
int	audio_meta_get_album (audio_meta_h audio, char **album_name)
	Gets the album name of the given audio metadata.
int	audio_meta_get_artist (audio_meta_h audio, char **artist_name)
	Gets the artist name of the given audio metadata.
int	audio_meta_get_album_artist (audio_meta_h audio, char **album_artist_name)
	Gets the album artist name of the given audio metadata.
int	audio_meta_get_genre (audio_meta_h audio, char **genre_name)
	Gets the genre name of the given audio metadata.
int	audio_meta_get_composer (audio_meta_h audio, char **composer_name)
	Gets the composer name 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)
	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)
	Gets the played time parameter of an audio.
int	audio_meta_get_played_position (audio_meta_h audio, int *played_position)
	Gets the played position parameter of an audio.
int	audio_meta_set_played_count (audio_meta_h audio, int played_count)
	Sets the played count to an audio meta handle.
int	audio_meta_set_played_time (audio_meta_h audio, time_t played_time)
	Sets the played time to an audio meta handle.
int	audio_meta_set_played_position (audio_meta_h audio, int played_position)
	Sets the played position to an audio meta handle.
int	audio_meta_update_to_db (audio_meta_h audio)
	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.

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 source to destination.

Since :: 2.3.1

Remarks:: The destination handle must be released using audio_meta_destroy().

Parameters:

[out]	dst	The destination handle to 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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

See also:: audio_meta_destroy()

int audio_meta_destroy ( audio_meta_h audio )

Destroys the audio metadata.

Since :: 2.3.1

Parameters:

[in] audio The audio metadata handle

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_PERMISSION_DENIED	Permission denied

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_name
	)

Gets the album name of the given audio metadata.

If the value is an empty string, the method returns "Unknown".

Since :: 2.3.1

Remarks:: You must release album_name using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	album_name	The name of the album

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_PERMISSION_DENIED	Permission denied

int audio_meta_get_album_artist	(	audio_meta_h	audio,
		char **	album_artist_name
	)

Gets the album artist name of the given audio metadata.

If the value is an empty string, the method returns "Unknown".

Since :: 2.3.1

Remarks:: You must release album_artist_name using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	album_artist_name	The name of the album artist

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_PERMISSION_DENIED	Permission denied

int audio_meta_get_artist	(	audio_meta_h	audio,
		char **	artist_name
	)

Gets the artist name of the given audio metadata.

If the value is an empty string, the method returns "Unknown".

Since :: 2.3.1

Remarks:: You must release artist_name using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	artist_name	The name of the artist

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_PERMISSION_DENIED	Permission denied

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.1

Parameters:

[in]	audio	The audio metadata handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_bitpersample	(	audio_meta_h	audio,
		int *	bitpersample
	)

Gets bit per sample of the given audio metadata.

Since :: 2.3.1

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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_channel	(	audio_meta_h	audio,
		int *	channel
	)

Gets the channel of the given audio metadata.

Since :: 2.3.1

Parameters:

[in]	audio	The audio metadata handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_composer	(	audio_meta_h	audio,
		char **	composer_name
	)

Gets the composer name of the given audio metadata.

If the value is an empty string, the method returns "Unknown".

Since :: 2.3.1

Remarks:: You must release author_name using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	composer_name	The name of the author 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
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_copyright	(	audio_meta_h	audio,
		char **	copyright
	)

Gets the copyright notice of the given audio metadata.

Since :: 2.3.1

Remarks:: You must release copyright using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	copyright	The audio copyright notice

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_PERMISSION_DENIED	Permission denied

int audio_meta_get_duration	(	audio_meta_h	audio,
		int *	duration
	)

Gets the track duration of the given audio metadata.

Since :: 2.3.1

Parameters:

[in]	audio	The audio metadata handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_genre	(	audio_meta_h	audio,
		char **	genre_name
	)

Gets the genre name of the given audio metadata.

If the value is an empty string, the method returns "Unknown".

Since :: 2.3.1

Remarks:: You must release genre_name using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	genre_name	The name of the genre

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_PERMISSION_DENIED	Permission denied

int audio_meta_get_media_id	(	audio_meta_h	audio,
		char **	media_id
	)

Gets the audio ID of the given audio metadata.

Since :: 2.3.1

Remarks:: You must release media_id using free().

Parameters:

[in]	audio	The audio metadata handle
[out]	media_id	The ID 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
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_played_count	(	audio_meta_h	audio,
		int *	played_count
	)

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

Since :: 2.3.1

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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_played_position	(	audio_meta_h	audio,
		int *	played_position
	)

Gets the played position parameter of an audio.

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

Since :: 2.3.1

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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_played_time	(	audio_meta_h	audio,
		time_t *	played_time
	)

Gets the played time parameter of an audio.

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

Since :: 2.3.1

Parameters:

[in]	audio	The audio metadata handle
[out]	played_time	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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

int audio_meta_get_recorded_date	(	audio_meta_h	audio,
		char **	recorded_date
	)

Gets the recorded date of the given audio metadata.

Since :: 2.3.1

Remarks:: You must release recorded_date using free().

Parameters:

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

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_PERMISSION_DENIED	Permission denied

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.1

Parameters:

[in]	audio	The audio metadata handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

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

Parameters:

[in]	audio	The audio metadata handle
[out]	track_num	The audio track number

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_PERMISSION_DENIED	Permission denied

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

Remarks:: You must release year using free().

Parameters:

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

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_PERMISSION_DENIED	Permission denied

int audio_meta_set_played_count	(	audio_meta_h	audio,
		int	played_count
	)

Sets the played count to an audio meta handle.

Since :: 2.3.1

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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

Postcondition:: audio_meta_update_to_db().

int audio_meta_set_played_position	(	audio_meta_h	audio,
		int	played_position
	)

Sets the played position to an audio meta handle.

Since :: 2.3.1

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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

Postcondition:: audio_meta_update_to_db().

int audio_meta_set_played_time	(	audio_meta_h	audio,
		time_t	played_time
	)

Sets the played time to an audio meta handle.

Since :: 2.3.1

Parameters:

[in]	audio	The audio metadata handle
[in]	played_time	The 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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

Postcondition:: audio_meta_update_to_db().

int audio_meta_update_to_db ( audio_meta_h audio )

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

The function updates the given audio meta in the media database.

Since :: 2.3.1

Privilege Level:: public

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

Remarks:: The function should be called after any change in the attributes, to update the media database. For example, after using audio_meta_set_played_count() for changing the count of the played, the audio_meta_update_to_db() function should be called to update the given attributes in the media database.
Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().

Parameters:

[in] audio The audio metadata handle

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_PERMISSION_DENIED	Permission denied

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

See also:: media_content_connect(); audio_meta_set_played_count(); audio_meta_set_played_time(); audio_meta_set_played_position()

Required Header

Overview

Functions

Typedefs

Function Documentation