include/media_audio.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18 #ifndef __TIZEN_CONTENT_MEDIA_AUDIO_H__
  19 #define __TIZEN_CONTENT_MEDIA_AUDIO_H__
  20
  21 #include <media_content_type.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @file media_audio.h
  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.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Clones the audio metadata.
  41  * @details This function copies the audio metadata handle from a source to destination.
  42  *
  43  * @since_tizen 2.3
  44  *
  45  * @remarks The @a dst should be released using audio_meta_destroy().
  46  *
  47  * @param[out] dst The destination handle to the audio metadata
  48  * @param[in] src The source handle to the audio metadata
  49  *
  50  * @return @c 0 on success,
  51  *         otherwise a negative error value
  52  *
  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
  56  *
  57  * @see audio_meta_destroy()
  58  */
  59 int audio_meta_clone(audio_meta_h *dst, audio_meta_h src);
  60
  61 /**
  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.
  66  *
  67  * @since_tizen 2.3
  68  *
  69  * @param[in] audio The handle to the audio metadata
  70  *
  71  * @return @c 0 on success,
  72  *         otherwise a negative error value
  73  *
  74  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  75  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  76  *
  77  * @pre Get a copy of audio metadata handle handle by calling audio_meta_clone().
  78  *
  79  * @see audio_meta_clone()
  80  */
  81 int audio_meta_destroy(audio_meta_h audio);
  82
  83 /**
  84  * @brief Gets the ID of the media of the given audio metadata.
  85  * @since_tizen 2.3
  86  *
  87  * @remarks The @a media_id should be released using free().
  88  *
  89  * @param[in] audio The handle to the audio metadata
  90  * @param[out] media_id The media ID
  91  *
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  *
  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
  98  */
  99 int audio_meta_get_media_id(audio_meta_h audio, char **media_id);
 100
 101 /**
 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.
 105  *
 106  * @since_tizen 2.3
 107  *
 108  * @remarks The @a album should be released using free().
 109  *
 110  * @param[in] audio The handle to the audio metadata
 111  * @param[out] album The album of the audio metadata
 112  *
 113  * @return @c 0 on success,
 114  *         otherwise a negative error value
 115  *
 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
 119  */
 120 int audio_meta_get_album(audio_meta_h audio, char **album);
 121
 122 /**
 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.
 126  *
 127  * @since_tizen 2.3
 128  *
 129  * @remarks The @a artist should be released using free().
 130  *
 131  * @param[in] audio The handle to the audio metadata
 132  * @param[out] artist The artist of the audio metadata
 133  *
 134  * @return @c 0 on success,
 135  *         otherwise a negative error value
 136  *
 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
 140  */
 141 int audio_meta_get_artist(audio_meta_h audio, char **artist);
 142
 143 /**
 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.
 147  *
 148  * @since_tizen 2.3
 149  *
 150  * @remarks The @a album_artist should be released using free().
 151  *
 152  * @param[in] audio The handle to the audio metadata
 153  * @param[out] album_artist The album artist of the audio metadata
 154  *
 155  * @return @c 0 on success,
 156  *         otherwise a negative error value
 157  *
 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
 161  */
 162 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist);
 163
 164 /**
 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.
 168  *
 169  * @since_tizen 2.3
 170  *
 171  * @remarks The @a genre should be released using free().
 172  *
 173  * @param[in] audio The handle to the audio metadata
 174  * @param[out] genre The genre of the audio metadata
 175  *
 176  * @return @c 0 on success,
 177  *         otherwise a negative error value
 178  *
 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
 182  */
 183 int audio_meta_get_genre(audio_meta_h audio, char **genre);
 184
 185 /**
 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.
 190  *
 191  * @since_tizen 2.3
 192  *
 193  * @remarks The @a composer should be released using free().
 194  *
 195  * @param[in] audio The handle to the audio metadata
 196  * @param[out] composer The composer of the audio metadata
 197  *
 198  * @return @c 0 on success,
 199  *         otherwise a negative error value
 200  *
 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
 204  */
 205 int audio_meta_get_composer(audio_meta_h audio, char **composer) TIZEN_DEPRECATED_API;
 206
 207 /**
 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.
 211  *
 212  * @since_tizen 2.3
 213  *
 214  * @remarks The @a year should be released using free().
 215  *
 216  * @param[in] audio The handle to the audio metadata
 217  * @param[out] year The year of the audio metadata
 218  *
 219  * @return @c 0 on success,
 220  *         otherwise a negative error value
 221  *
 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
 225  */
 226 int audio_meta_get_year(audio_meta_h audio, char **year);
 227
 228 /**
 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.
 233  *
 234  * @since_tizen 2.3
 235  *
 236  * @remarks The @a recorded_date should be released using free().
 237  *
 238  * @param[in] audio The handle to the audio metadata
 239  * @param[out] recorded_date The recorded date of the audio metadata
 240  *
 241  * @return @c 0 on success,
 242  *         otherwise a negative error value
 243  *
 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
 247  */
 248 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date) TIZEN_DEPRECATED_API;
 249
 250 /**
 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.
 254  *
 255  * @since_tizen 2.3
 256  *
 257  * @remarks The @a copyright should be released using free().
 258  *
 259  * @param[in] audio The handle to the audio metadata
 260  * @param[out] copyright The copyright of the audio metadata
 261  *
 262  * @return @c 0 on success,
 263  *         otherwise a negative error value
 264  *
 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
 268  */
 269 int audio_meta_get_copyright(audio_meta_h audio, char **copyright) TIZEN_DEPRECATED_API;
 270
 271 /**
 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.
 275  *
 276  * @since_tizen 2.3
 277  *
 278  * @remarks The @a track_num should be released using free().
 279  *
 280  * @param[in] audio The handle to the audio metadata
 281  * @param[out] track_num The audio track number of the audio metadata
 282  *
 283  * @return @c 0 on success,
 284  *         otherwise a negative error value
 285  *
 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
 289  */
 290 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
 291
 292 /**
 293  * @deprecated Deprecated since 9.0.
 294  * @brief Gets the bitrate of the given audio metadata in bitrate per second.
 295  * @since_tizen 2.3
 296  *
 297  * @param[in] audio The handle to the audio metadata
 298  * @param[out] bit_rate The audio bitrate in bit per second [bps]
 299  *
 300  * @return @c 0 on success,
 301  *         otherwise a negative error value
 302  *
 303  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 304  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 305  */
 306 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate) TIZEN_DEPRECATED_API;
 307
 308 /**
 309  * @deprecated Deprecated since 9.0.
 310  * @brief Gets bit per sample of the given audio metadata.
 311  * @since_tizen 2.3
 312  *
 313  * @param[in] audio The handle to the audio metadata
 314  * @param[out] bitpersample The audio bit per sample
 315  *
 316  * @return @c 0 on success,
 317  *         otherwise a negative error value
 318  *
 319  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 320  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 321  */
 322 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample) TIZEN_DEPRECATED_API;
 323
 324 /**
 325  * @deprecated Deprecated since 9.0.
 326  * @brief Gets the sample rate of the given audio metadata.
 327  * @since_tizen 2.3
 328  *
 329  * @param[in] audio The handle to the audio metadata
 330  * @param[out] sample_rate The audio sample rate[hz]
 331  *
 332  * @return @c 0 on success,
 333  *         otherwise a negative error value
 334  *
 335  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 336  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 337  */
 338 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate) TIZEN_DEPRECATED_API;
 339
 340 /**
 341  * @deprecated Deprecated since 9.0.
 342  * @brief Gets the channel of the given audio metadata.
 343  * @since_tizen 2.3
 344  *
 345  * @param[in] audio The handle to the audio metadata
 346  * @param[out] channel The channel of the audio
 347  *
 348  * @return @c 0 on success,
 349  *         otherwise a negative error value
 350  *
 351  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 352  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 353  */
 354 int audio_meta_get_channel(audio_meta_h audio, int *channel) TIZEN_DEPRECATED_API;
 355
 356 /**
 357  * @deprecated Deprecated since 9.0.
 358  * @brief Gets the track duration of the given audio metadata.
 359  * @since_tizen 2.3
 360  *
 361  * @param[in] audio The handle to the audio metadata
 362  * @param[out] duration The audio file duration
 363  *
 364  * @return @c 0 on success,
 365  *         otherwise a negative error value
 366  *
 367  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 368  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 369  */
 370 int audio_meta_get_duration(audio_meta_h audio, int *duration) TIZEN_DEPRECATED_API;
 371
 372 /**
 373  *@}
 374  */
 375
 376 #ifdef __cplusplus
 377 }
 378 #endif /* __cplusplus */
 379
 380 #endif /*__TIZEN_CONTENT_MEDIA_AUDIO_H__*/