Tizen Native API
4.0
|
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()