Tizen Native API
Functions | Typedefs
Audio Metadata
Media Information

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.

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.

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

Since :
2.3
Remarks:
The destination handle must be released using audio_meta_destroy().
Parameters:
[out]dstThe destination handle to 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.

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

Gets the album name of the given audio metadata.

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

Since :
2.3
Remarks:
You must release album_name using free().
Parameters:
[in]audioThe audio metadata handle
[out]album_nameThe name of the album
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_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
Remarks:
You must release album_artist_name using free().
Parameters:
[in]audioThe audio metadata handle
[out]album_artist_nameThe name of the album artist
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_name 
)

Gets the artist name of the given audio metadata.

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

Since :
2.3
Remarks:
You must release artist_name using free().
Parameters:
[in]audioThe audio metadata handle
[out]artist_nameThe name of the artist
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_name 
)

Gets the composer name of the given audio metadata.

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

Since :
2.3
Remarks:
You must release author_name using free().
Parameters:
[in]audioThe audio metadata handle
[out]composer_nameThe name of the author 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_copyright ( audio_meta_h  audio,
char **  copyright 
)

Gets the copyright notice of the given audio metadata.

Since :
2.3
Remarks:
You must release copyright using free().
Parameters:
[in]audioThe audio metadata handle
[out]copyrightThe audio copyright notice
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_name 
)

Gets the genre name of the given audio metadata.

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

Since :
2.3
Remarks:
You must release genre_name using free().
Parameters:
[in]audioThe audio metadata handle
[out]genre_nameThe name of the genre
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 audio ID 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 an audio.

Deprecated:
Deprecated since 2.4.

This function returns audio's elapsed playback position parameter 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 played time parameter of an audio.

Deprecated:
Deprecated since 2.4. [Use media_info_get_played_time() instead]

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

Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]played_timeThe 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_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 file
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 :
2.3
Parameters:
[in]audioThe audio metadata handle
[out]track_numThe audio track number
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_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
Remarks:
You must release year using free().
Parameters:
[in]audioThe audio metadata handle
[out]yearThe year of the audio file
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 to an audio meta handle.

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 to an audio meta handle.

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 played time to an audio meta handle.

Deprecated:
Deprecated since 2.4. [Use media_info_set_played_time() instead]
Since :
2.3
Parameters:
[in]audioThe audio metadata handle
[in]played_timeThe 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.

Since :
2.3
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]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_count()
audio_meta_set_played_time()
audio_meta_set_played_position()