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.
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.
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.
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.
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.
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.
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.
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 * @deprecated Deprecated since 9.0.
187 * @brief Gets the composer of the given audio metadata.
188 * @details If the value is an empty string, the method returns "Unknown". \n
189 * Since 3.0, if the media content has no composer info, the method returns empty string.
193 * @remarks The @a composer should be released using free().
195 * @param[in] audio The handle to the audio metadata
196 * @param[out] composer The composer of the audio metadata
198 * @return @c 0 on success,
199 * otherwise a negative error value
201 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
202 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
203 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
205 int audio_meta_get_composer(audio_meta_h audio, char **composer) TIZEN_DEPRECATED_API;
208 * @brief Gets the year of the given audio metadata.
209 * @details If the value is an empty string, the method returns "Unknown". \n
210 * Since 3.0, if the media content has no year info, the method returns empty string.
214 * @remarks The @a year should be released using free().
216 * @param[in] audio The handle to the audio metadata
217 * @param[out] year The year of the audio metadata
219 * @return @c 0 on success,
220 * otherwise a negative error value
222 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
223 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
224 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
226 int audio_meta_get_year(audio_meta_h audio, char **year);
229 * @deprecated Deprecated since 9.0.
230 * @brief Gets the recorded date of the given audio metadata.
231 * @details The format of the recorded date may vary depending on the file format. \n
232 * For more details on the recorded date format, refer to the file format specification.
236 * @remarks The @a recorded_date should be released using free().
238 * @param[in] audio The handle to the audio metadata
239 * @param[out] recorded_date The recorded date of the audio metadata
241 * @return @c 0 on success,
242 * otherwise a negative error value
244 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
245 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
246 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
248 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date) TIZEN_DEPRECATED_API;
251 * @deprecated Deprecated since 9.0.
252 * @brief Gets the copyright notice of the given audio metadata.
253 * @details If the media content has no copyright info, the method returns empty string.
257 * @remarks The @a copyright should be released using free().
259 * @param[in] audio The handle to the audio metadata
260 * @param[out] copyright The copyright of the audio metadata
262 * @return @c 0 on success,
263 * otherwise a negative error value
265 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
266 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
267 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
269 int audio_meta_get_copyright(audio_meta_h audio, char **copyright) TIZEN_DEPRECATED_API;
272 * @brief Gets the track number of the given audio metadata.
273 * @details If the value is an empty string, the method returns "Unknown". \n
274 * Since 3.0, if the media content has no track info, the method returns empty string.
278 * @remarks The @a track_num should be released using free().
280 * @param[in] audio The handle to the audio metadata
281 * @param[out] track_num The audio track number of the audio metadata
283 * @return @c 0 on success,
284 * otherwise a negative error value
286 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
287 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
288 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
290 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
293 * @deprecated Deprecated since 9.0.
294 * @brief Gets the bitrate of the given audio metadata in bitrate per second.
297 * @param[in] audio The handle to the audio metadata
298 * @param[out] bit_rate The audio bitrate in bit per second [bps]
300 * @return @c 0 on success,
301 * otherwise a negative error value
303 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
304 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
306 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate) TIZEN_DEPRECATED_API;
309 * @deprecated Deprecated since 9.0.
310 * @brief Gets bit per sample of the given audio metadata.
313 * @param[in] audio The handle to the audio metadata
314 * @param[out] bitpersample The audio bit per sample
316 * @return @c 0 on success,
317 * otherwise a negative error value
319 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
320 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
322 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample) TIZEN_DEPRECATED_API;
325 * @deprecated Deprecated since 9.0.
326 * @brief Gets the sample rate of the given audio metadata.
329 * @param[in] audio The handle to the audio metadata
330 * @param[out] sample_rate The audio sample rate[hz]
332 * @return @c 0 on success,
333 * otherwise a negative error value
335 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
336 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
338 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate) TIZEN_DEPRECATED_API;
341 * @deprecated Deprecated since 9.0.
342 * @brief Gets the channel of the given audio metadata.
345 * @param[in] audio The handle to the audio metadata
346 * @param[out] channel The channel of the audio
348 * @return @c 0 on success,
349 * otherwise a negative error value
351 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
352 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
354 int audio_meta_get_channel(audio_meta_h audio, int *channel) TIZEN_DEPRECATED_API;
357 * @deprecated Deprecated since 9.0.
358 * @brief Gets the track duration of the given audio metadata.
361 * @param[in] audio The handle to the audio metadata
362 * @param[out] duration The audio file duration
364 * @return @c 0 on success,
365 * otherwise a negative error value
367 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
368 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
370 int audio_meta_get_duration(audio_meta_h audio, int *duration) TIZEN_DEPRECATED_API;
378 #endif /* __cplusplus */
380 #endif /*__TIZEN_CONTENT_MEDIA_AUDIO_H__*/