Tizen Native API  3.0
Functions | Typedefs
Audio Metadata
Media Information

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:

  • 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_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)
 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 last played time parameter of the audio.
int audio_meta_get_played_position (audio_meta_h audio, int *played_position)
 Gets the played position parameter of the audio.
int audio_meta_set_played_count (audio_meta_h audio, int played_count)
 Sets the played count of the audio.
int audio_meta_set_played_time (audio_meta_h audio, time_t played_time)
 Sets the last played time of the audio.
int audio_meta_set_played_position (audio_meta_h audio, int played_position)
 Sets the played position of the audio.
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.

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:
You must release the destination handle using audio_meta_destroy().
Parameters:
[out]dstThe destination handle to the audio metadata
[in]srcThe source handle to the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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]audioThe audio metadata handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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 
)

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:
You must release album using free().
Parameters:
[in]audioThe audio metadata handle
[out]albumThe album of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release album_artist using free().
Parameters:
[in]audioThe audio metadata handle
[out]album_artistThe album artist of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release artist using free().
Parameters:
[in]audioThe audio metadata handle
[out]artistThe artist of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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
Parameters:
[in]audioThe audio metadata handle
[out]bit_rateThe audio bitrate in bit per second [bps]
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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]audioThe handle to the audio metadata
[out]bitpersampleThe audio bit per sample
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
int audio_meta_get_channel ( audio_meta_h  audio,
int *  channel 
)

Gets the channel of the given audio metadata.

Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]channelThe channel of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release composer using free().
Parameters:
[in]audioThe audio metadata handle
[out]composerThe composer of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release copyright using free().
Parameters:
[in]audioThe audio metadata handle
[out]copyrightThe copyright of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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]audioThe audio metadata handle
[out]durationThe audio file duration
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release genre using free().
Parameters:
[in]audioThe audio metadata handle
[out]genreThe genre of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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:
You must release media_id using free().
Parameters:
[in]audioThe audio metadata handle
[out]media_idThe ID of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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.

Deprecated:
Deprecated since 2.4. [Use media_info_get_played_count() instead]
Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]played_countThe counter of the audio played
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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 returns the elapsed playback position parameter of the audio as a period starting from the beginning of the track.

Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]played_positionThe elapsed time of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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. [Use media_info_get_played_time() instead]
Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]played_timeThe last played time of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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
Remarks:
You must release recorded_date using free().
Parameters:
[in]audioThe audio metadata handle
[out]recorded_dateThe recorded date of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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
Parameters:
[in]audioThe audio metadata handle
[out]sample_rateThe audio sample rate[hz]
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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 3.0, if the media content has no track info, the method returns empty string.

Since :
2.3
Remarks:
You must release track_num using free().
Parameters:
[in]audioThe audio metadata handle
[out]track_numThe audio track number of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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 3.0, if the media content has no year info, the method returns empty string.

Since :
2.3
Remarks:
You must release year using free().
Parameters:
[in]audioThe audio metadata handle
[out]yearThe year of the audio metadata
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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. [Use media_info_increase_played_count() instead]
Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[in]played_countThe played count of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
audio_meta_update_to_db().
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.
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]audioThe audio metadata handle
[in]played_positionThe played position of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
audio_meta_update_to_db().
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. [Use media_info_set_played_time() instead]
Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[in]played_timeThe last played time of the audio
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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. The function should be called after any change in audio attributes, to be updated to the media database. For example, for setting the played time using audio_meta_get_played_time(), after that the audio_meta_update_to_db() function should be called to update 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]audioThe audio metadata handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
audio_meta_set_played_time()
audio_meta_set_played_count()
audio_meta_set_played_position()