2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_CONTENT_MEDIA_AUDIO_H__
19 #define __TIZEN_CONTENT_MEDIA_AUDIO_H__
21 #include <media_content_type.h>
25 #endif /* __cplusplus */
29 * @brief This file contains the audio metadata API and related functions to proceed with audio metadata. \n
30 * Description of the audio content involves: album, artist, album_artist, genre and description tags. \n
31 * Parameters of the recording are also supported such as format, bitrate, duration, size etc.
35 * @addtogroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE
40 * @brief Clones the audio metadata.
41 * @details This function copies the audio metadata handle from a source to destination.
43 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
45 * @remarks The @a dst should be released using audio_meta_destroy().
47 * @param[out] dst The destination handle to the audio metadata
48 * @param[in] src The source handle to the audio metadata
50 * @return @c 0 on success,
51 * otherwise a negative error value
53 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
54 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
55 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
57 * @see audio_meta_destroy()
59 int audio_meta_clone(audio_meta_h *dst, audio_meta_h src);
62 * @brief Destroys the audio metadata.
63 * @details This function frees all resources related to the audio metadata handle. This handle
64 * no longer can be used to perform any operations. A new handle has to
65 * be created before the next use.
67 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
69 * @param[in] audio The handle to the audio metadata
71 * @return @c 0 on success,
72 * otherwise a negative error value
74 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
75 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
77 * @pre Get a copy of audio metadata handle handle by calling audio_meta_clone().
79 * @see audio_meta_clone()
81 int audio_meta_destroy(audio_meta_h audio);
84 * @brief Gets the ID of the media of the given audio metadata.
85 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
87 * @remarks The @a media_id should be released using free().
89 * @param[in] audio The handle to the audio metadata
90 * @param[out] media_id The media ID
92 * @return @c 0 on success,
93 * otherwise a negative error value
95 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
96 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
97 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
99 int audio_meta_get_media_id(audio_meta_h audio, char **media_id);
102 * @brief Gets the album of the given audio metadata.
103 * @details If the value is an empty string, the method returns "Unknown". \n
104 * Since 3.0, if the media content has no album info, the method returns empty string.
106 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
108 * @remarks The @a album should be released using free().
110 * @param[in] audio The handle to the audio metadata
111 * @param[out] album The album of the audio metadata
113 * @return @c 0 on success,
114 * otherwise a negative error value
116 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
117 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
118 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
120 int audio_meta_get_album(audio_meta_h audio, char **album);
123 * @brief Gets the artist of the given audio metadata.
124 * @details If the value is an empty string, the method returns "Unknown". \n
125 * Since 3.0, if the media content has no artist info, the method returns empty string.
127 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
129 * @remarks The @a artist should be released using free().
131 * @param[in] audio The handle to the audio metadata
132 * @param[out] artist The artist of the audio metadata
134 * @return @c 0 on success,
135 * otherwise a negative error value
137 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
138 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
139 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
141 int audio_meta_get_artist(audio_meta_h audio, char **artist);
144 * @brief Gets the album artist of the given audio metadata.
145 * @details If the value is an empty string, the method returns "Unknown". \n
146 * Since 3.0, if the media content has no album artist info, the method returns empty string.
148 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
150 * @remarks The @a album_artist should be released using free().
152 * @param[in] audio The handle to the audio metadata
153 * @param[out] album_artist The album artist of the audio metadata
155 * @return @c 0 on success,
156 * otherwise a negative error value
158 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
159 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
160 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
162 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist);
165 * @brief Gets the genre of the given audio metadata.
166 * @details If the value is an empty string, the method returns "Unknown". \n
167 * Since 3.0, if the media content has no genre info, the method returns empty string.
169 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
171 * @remarks The @a genre should be released using free().
173 * @param[in] audio The handle to the audio metadata
174 * @param[out] genre The genre of the audio metadata
176 * @return @c 0 on success,
177 * otherwise a negative error value
179 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
180 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
181 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
183 int audio_meta_get_genre(audio_meta_h audio, char **genre);
186 * @brief Gets the composer of the given audio metadata.
187 * @details If the value is an empty string, the method returns "Unknown". \n
188 * Since 3.0, if the media content has no composer info, the method returns empty string.
190 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
192 * @remarks The @a composer should be released using free().
194 * @param[in] audio The handle to the audio metadata
195 * @param[out] composer The composer of the audio metadata
197 * @return @c 0 on success,
198 * otherwise a negative error value
200 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
201 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
202 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
204 int audio_meta_get_composer(audio_meta_h audio, char **composer);
207 * @brief Gets the year of the given audio metadata.
208 * @details If the value is an empty string, the method returns "Unknown". \n
209 * Since 3.0, if the media content has no year info, the method returns empty string.
211 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
213 * @remarks The @a year should be released using free().
215 * @param[in] audio The handle to the audio metadata
216 * @param[out] year The year of the audio metadata
218 * @return @c 0 on success,
219 * otherwise a negative error value
221 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
222 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
223 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
225 int audio_meta_get_year(audio_meta_h audio, char **year);
228 * @brief Gets the recorded date of the given audio metadata.
229 * @details The recorded date is got from audio file's metadata. Some formats like mp4 use UTC and the rest can be different. \n
230 * So, please refer to the format specification if needed.
232 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
234 * @remarks The @a recorded_date should be released using free().
236 * @param[in] audio The handle to the audio metadata
237 * @param[out] recorded_date The recorded date of the audio metadata
239 * @return @c 0 on success,
240 * otherwise a negative error value
242 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
243 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
244 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
246 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date);
249 * @brief Gets the copyright notice of the given audio metadata.
250 * @details If the media content has no copyright info, the method returns empty string.
252 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
254 * @remarks The @a copyright should be released using free().
256 * @param[in] audio The handle to the audio metadata
257 * @param[out] copyright The copyright of the audio metadata
259 * @return @c 0 on success,
260 * otherwise a negative error value
262 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
263 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
264 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
266 int audio_meta_get_copyright(audio_meta_h audio, char **copyright);
269 * @brief Gets the track number of the given audio metadata.
270 * @details If the value is an empty string, the method returns "Unknown". \n
271 * Since 3.0, if the media content has no track info, the method returns empty string.
273 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
275 * @remarks The @a track_num should be released using free().
277 * @param[in] audio The handle to the audio metadata
278 * @param[out] track_num The audio track number of the audio metadata
280 * @return @c 0 on success,
281 * otherwise a negative error value
283 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
284 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
285 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
287 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
290 * @brief Gets the bitrate of the given audio metadata in bitrate per second.
291 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
293 * @param[in] audio The handle to the audio metadata
294 * @param[out] bit_rate The audio bitrate in bit per second [bps]
296 * @return @c 0 on success,
297 * otherwise a negative error value
299 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
300 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
302 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate);
305 * @brief Gets bit per sample of the given audio metadata.
306 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
308 * @param[in] audio The handle to the audio metadata
309 * @param[out] bitpersample The audio bit per sample
311 * @return @c 0 on success,
312 * otherwise a negative error value
314 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
315 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
317 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample);
320 * @brief Gets the sample rate of the given audio metadata.
321 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
323 * @param[in] audio The handle to the audio metadata
324 * @param[out] sample_rate The audio sample rate[hz]
326 * @return @c 0 on success,
327 * otherwise a negative error value
329 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
330 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
332 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate);
335 * @brief Gets the channel of the given audio metadata.
336 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
338 * @param[in] audio The handle to the audio metadata
339 * @param[out] channel The channel of the audio
341 * @return @c 0 on success,
342 * otherwise a negative error value
344 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
345 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
347 int audio_meta_get_channel(audio_meta_h audio, int *channel);
350 * @brief Gets the track duration of the given audio metadata.
351 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
353 * @param[in] audio The handle to the audio metadata
354 * @param[out] duration The audio file duration
356 * @return @c 0 on success,
357 * otherwise a negative error value
359 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
360 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
362 int audio_meta_get_duration(audio_meta_h audio, int *duration);
370 #endif /* __cplusplus */
372 #endif /*__TIZEN_CONTENT_MEDIA_AUDIO_H__*/