include/mm_file.h

   1 /*
   2  * libmm-fileinfo
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Haejeong Kim <backto.kim@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 /**
  23  * This file declares data structures and functions of flie library.
  24  *
  25  * @file                mm_file.h
  26  * @author
  27  * @version             1.0
  28  * @brief               This file declares data structures and functions of flie
  29  *                              library.
  30  */
  31
  32 #ifndef __MM_FILE_H__
  33 #define __MM_FILE_H__
  34
  35 #include <glib.h>
  36
  37 #include <mm_types.h>
  38 #include "mm_file_error.h"
  39
  40 /**
  41         @addtogroup FILEINFO
  42         @{
  43
  44         @par
  45         This part describes the APIs with respect to extract meta data or media
  46         information directly from file.
  47
  48 */
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 typedef enum {
  55         MMFILE_360_NONE = 0,
  56         MMFILE_360_NON_STITCHED = 0x00010000,
  57         MMFILE_360_STITCHED = 0x00020000,
  58         MMFILE_360_MASK = 0x00001111,
  59 } MMFILE_360_TYPE;
  60
  61 #define RFC_AMBISONIC_SA3DBOX_VERSION_SUPPORTED 0
  62 #define RFC_AMBISONIC_TYPE_PERIPHONIC 0
  63 #define RFC_AMBISONIC_CHANNEL_ORDERING_ACN 0
  64 #define RFC_AMBISONIC_CHANNEL_ORDERING_FUMA 1   /* FIXME: Currently value is not defined in Spatial Audio RFC */
  65 #define RFC_AMBISONIC_NORMALIZATION_SN3D 0
  66 #define RFC_AMBISONIC_NORMALIZATION_FUMA 1              /* FIXME: Currently value is not defined in Spatial Audio RFC */
  67
  68 typedef enum {
  69         MMFILE_AMBISONIC_TYPE_UNKNOWN = 0,
  70         MMFILE_AMBISONIC_TYPE_PERIPHONIC = 1,           /**< To comply with Google's Spatial Audio RFC*/
  71         MMFILE_AMBISONIC_TYPE_NON_PERIPHONIC = 2,
  72 } MMFILE_AMBISONIC_TYPE;
  73
  74 typedef enum {
  75         MMFILE_AMBISONIC_FORMAT_UNKNOWN = 0,
  76         MMFILE_AMBISONIC_FORMAT_AMBIX = 1,              /**< AMBIX (Channel sequence: ACN, Normalization: SN3D) */
  77         MMFILE_AMBISONIC_FORMAT_AMB = 2,                /**< .AMB, Tetraproc (Channel sequence: FuMa, Normalization: FuMa) */
  78         MMFILE_AMBISONIC_FORMAT_UA = 3,                 /**< Universal Ambisonics (Channel sequence: SID, Normalization: N3D) */
  79 } MMFILE_AMBISONIC_FORMAT;
  80
  81 typedef enum {
  82         MMFILE_AMBISONIC_ORDER_UNKNOWN = 0,
  83         MMFILE_AMBISONIC_ORDER_FOA = 1,                 /**< First order Ambisonics */
  84         MMFILE_AMBISONIC_ORDER_SOA = 2,                 /**< Second order Ambisonics */
  85         MMFILE_AMBISONIC_ORDER_TOA = 3,                 /**< Third order Ambisonics */
  86 } MMFILE_AMBISONIC_ORDER;
  87
  88 typedef enum {
  89         MMFILE_AMBISONIC_CHANNEL_ORDERING_UNKNOWN = 0,
  90         MMFILE_AMBISONIC_CHANNEL_ORDERING_ACN = 1,              /**< Ambisonic Channel Number (ACN) system */
  91         MMFILE_AMBISONIC_CHANNEL_ORDERING_FUMA = 2,             /**< Furse-Malham ordering*/
  92         MMFILE_AMBISONIC_CHANNEL_ORDERING_SID = 3,              /**< Single Index Designation ordering */
  93 } MMFILE_AMBISONIC_CHANNEL_ORDERING;
  94
  95 typedef enum {
  96         MMFILE_AMBISONIC_NORMALIZATION_UNKNOWN = 0,
  97         MMFILE_AMBISONIC_NORMALIZATION_SN3D = 1,        /**< Schmidt semi-normalization */
  98         MMFILE_AMBISONIC_NORMALIZATION_FUMA = 2,        /**< Furse-Malham MaxN normalization*/
  99         MMFILE_AMBISONIC_NORMALIZATION_N3D = 3,         /**< Full 3D normalization  */
 100 } MMFILE_AMBISONIC_NORMALIZATION;
 101
 102 /**
 103  * content attributes.
 104  */
 105 #define MM_FILE_CONTENT_DURATION                        "content-duration"              /**< Duration of media */
 106 #define MM_FILE_CONTENT_VIDEO_CODEC                     "content-video-codec"           /**< Used video codec */
 107 #define MM_FILE_CONTENT_VIDEO_FORMAT            "content-video-format"          /**< Used video format */
 108 #define MM_FILE_CONTENT_VIDEO_BITRATE           "content-video-bitrate"         /**< Bitrate of video stream */
 109 #define MM_FILE_CONTENT_VIDEO_FPS                       "content-video-fps"             /**< Frames per second of video stream */
 110 #define MM_FILE_CONTENT_VIDEO_WIDTH                     "content-video-width"           /**< Width of video stream */
 111 #define MM_FILE_CONTENT_VIDEO_HEIGHT            "content-video-height"          /**< Height of video stream */
 112 #define MM_FILE_CONTENT_VIDEO_THUMBNAIL         "content-video-thumbnail"       /**< Thumbnail of video stream */
 113 #define MM_FILE_CONTENT_VIDEO_TRACK_INDEX       "content-video-track-index" /**< Current stream of video */
 114 #define MM_FILE_CONTENT_VIDEO_TRACK_COUNT       "content-video-track-count"/**< Number of video streams */
 115 #define MM_FILE_CONTENT_AUDIO_CODEC                     "content-audio-codec"           /**< Used audio codec */
 116 #define MM_FILE_CONTENT_AUDIO_BITRATE           "content-audio-bitrate" /**< Bitrate of audio stream */
 117 #define MM_FILE_CONTENT_AUDIO_CHANNELS          "content-audio-channels"        /**< Channels of audio stream */
 118 #define MM_FILE_CONTENT_AUDIO_SAMPLERATE        "content-audio-samplerate" /**< Sampling rate of audio stream */
 119 #define MM_FILE_CONTENT_AUDIO_TRACK_INDEX       "content-audio-track-index"     /**< Current stream of audio */
 120 #define MM_FILE_CONTENT_AUDIO_TRACK_COUNT       "content-audio-track-count"/**< Number of audio streams */
 121 #define MM_FILE_CONTENT_AUDIO_BITPERSAMPLE      "content-audio-bitpersample" /**< Bit per sample of audio stream */
 122
 123 /**
 124  * tag attributes.
 125  */
 126 #define MM_FILE_TAG_ARTIST                      "tag-artist"                    /**< Artist */
 127 #define MM_FILE_TAG_TITLE                       "tag-title"                     /**< Title */
 128 #define MM_FILE_TAG_ALBUM                       "tag-album"                     /**< Album */
 129 #define MM_FILE_TAG_ALBUM_ARTIST        "tag-album-artist"                      /**< Album_Artist */
 130 #define MM_FILE_TAG_GENRE                       "tag-genre"                     /**< Genre */
 131 #define MM_FILE_TAG_AUTHOR                      "tag-author"                    /**< Author / Composer */
 132 #define MM_FILE_TAG_COPYRIGHT           "tag-copyright"         /**< Copyright */
 133 #define MM_FILE_TAG_DATE                        "tag-date"                      /**< Year */
 134 #define MM_FILE_TAG_DESCRIPTION         "tag-description"               /**< Description */
 135 #define MM_FILE_TAG_COMMENT                     "tag-comment"           /**< Comment */
 136 #define MM_FILE_TAG_ARTWORK                     "tag-artwork"                   /**< Artwork */
 137 #define MM_FILE_TAG_ARTWORK_SIZE        "tag-artwork-size"              /**< Artwork size */
 138 #define MM_FILE_TAG_ARTWORK_MIME        "tag-artwork-mime"      /**< Artwork mime type */
 139 #define MM_FILE_TAG_TRACK_NUM           "tag-track-num"         /**< Number of tracks */
 140 #define MM_FILE_TAG_CLASSIFICATION      "tag-classification"            /**< Classification Information */
 141 #define MM_FILE_TAG_RATING          "tag-rating"                        /**< Rating Information */
 142 #define MM_FILE_TAG_LONGITUDE       "tag-longitude"             /**< location Information*/
 143 #define MM_FILE_TAG_LATIDUE         "tag-latitude"                      /**< location Information*/
 144 #define MM_FILE_TAG_ALTIDUE         "tag-altitude"                      /**< location Information*/
 145 #define MM_FILE_TAG_CONDUCTOR       "tag-conductor"             /**< Conductor Information*/
 146 #define MM_FILE_TAG_UNSYNCLYRICS    "tag-unsynclyrics"  /**< Unsynchronized Lyrics Information*/
 147 #define MM_FILE_TAG_SYNCLYRICS_NUM  "tag-synclyrics-num"        /**< Synchronized Lyrics Information*/
 148 #define MM_FILE_TAG_RECDATE                     "tag-recdate"                   /**< Recoding date */
 149 #define MM_FILE_TAG_POS                 "tag-part-of-set"                       /**< Part of a set */
 150 #define MM_FILE_TAG_ROTATE                      "tag-rotate"                    /**< Rotate(Orientation) Information*/
 151 #define MM_FILE_TAG_CDIS                        "tag-cdis"                              /**< CDIS in User Data Information*/
 152 #define MM_FILE_TAG_SMTA                        "tag-smta"                              /**< SMTA in User Data Information*/
 153 #define MM_FILE_TAG_SPHERICAL                                                   "tag-spherical"                                 /**< Flag indicating if the video is a spherical video*/
 154 #define MM_FILE_TAG_SPHERICAL_STITCHED                                  "tag-stitched"                                  /**< Flag indicating if the video is stitched*/
 155 #define MM_FILE_TAG_SPHERICAL_STITCHING_SOFTWARE                "tag-stitching-software"                /**< Software used to stitch the spherical video*/
 156 #define MM_FILE_TAG_SPHERICAL_PROJECTION_TYPE                   "tag-projection-type"                   /**< Projection type used in the video frames*/
 157 #define MM_FILE_TAG_SPHERICAL_STEREO_MODE                               "tag-stereo-mode"                               /**< Description of stereoscopic 3D layout*/
 158 #define MM_FILE_TAG_SPHERICAL_SOURCE_COUNT                              "tag-source-count"                              /**< Number of cameras used to create the spherical video*/
 159 #define MM_FILE_TAG_SPHERICAL_INIT_VIEW_HEADING                 "tag-init-view-heading"                 /**< The heading angle of the initial view in degrees.*/
 160 #define MM_FILE_TAG_SPHERICAL_INIT_VIEW_PITCH                   "tag-init-view-pitch"                   /**< The pitch angle of the initial view in degrees*/
 161 #define MM_FILE_TAG_SPHERICAL_INIT_VIEW_ROLL                    "tag-init-view-roll"                    /**< The roll angle of the initial view in degrees*/
 162 #define MM_FILE_TAG_SPHERICAL_TIMESTAMP                                 "tag-timestamp"                                 /**< Epoch timestamp of when the first frame in the video was recorded*/
 163 #define MM_FILE_TAG_SPHERICAL_FULL_PANO_WIDTH                   "tag-full-pano-width"                   /**< Width of the encoded video frame in pixels*/
 164 #define MM_FILE_TAG_SPHERICAL_FULL_PANO_HEIGHT                  "tag-full-pano-height"                  /**< Height of the encoded video frame in pixels*/
 165 #define MM_FILE_TAG_SPHERICAL_CROPPED_AREA_IMAGE_WIDTH  "tag-cropped-area-image-width"  /**< Width of the video frame to display (e.g. cropping)*/
 166 #define MM_FILE_TAG_SPHERICAL_CROPPED_AREA_IMAGE_HEIGHT "tag-cropped-area-image-height" /**< Height of the video frame to display (e.g. cropping)*/
 167 #define MM_FILE_TAG_SPHERICAL_CROPPED_AREA_LEFT                 "tag-cropped-area-left"                 /**< Column where the left edge of the image was cropped from the full sized panorama*/
 168 #define MM_FILE_TAG_SPHERICAL_CROPPED_AREA_TOP                  "tag-cropped-area-top"                  /**< Row where the top edge of the image was cropped from the full sized panorama*/
 169 #define MM_FILE_TAG_AMBISONIC_TYPE                      "tag-ambisonic-type"            /**< Ambisonics type in User Data Information*/
 170 #define MM_FILE_TAG_AMBISONIC_FORMAT            "tag-ambisonic-format"          /**< Ambisonics format in User Data Information*/
 171 #define MM_FILE_TAG_AMBISONIC_ORDER                     "tag-ambisonic-order"           /**< Ambisonics order in User Data Information*/
 172 #define MM_FILE_TAG_SPHERICAL_V2_STEREO_MODE            "stereo-mode-v2"                                        /**< Stereo frame layout*/
 173 #define MM_FILE_TAG_SPHERICAL_V2_METADATA_SOURCE        "metadata-source-v2"                            /**< Tool used to create the Spherical Video Metadata V2*/
 174 #define MM_FILE_TAG_SPHERICAL_V2_PROJ_TYPE                      "proj-type-v2"                                          /**< Projection type*/
 175 #define MM_FILE_TAG_SPHERICAL_V2_POSE_YAW                       "pose-yaw-degrees-v2"                           /**< Counter-clockwise rotation in degrees around the up vector*/
 176 #define MM_FILE_TAG_SPHERICAL_V2_POSE_PITCH                     "pose-pitch-degrees-v2"                         /**< Counter-clockwise rotation in degrees around the right vector post yaw transform*/
 177 #define MM_FILE_TAG_SPHERICAL_V2_POSE_ROLL                      "pose-roll-degrees-v2"                          /**< Clockwise-rotation in degrees around the forward vector post yaw and pitch transform*/
 178 #define MM_FILE_TAG_SPHERICAL_V2_CBMP_LAYOUT            "cbmp-layout-v2"                                        /**< Layout of cube faces for the Cubemap Projection*/
 179 #define MM_FILE_TAG_SPHERICAL_V2_CBMP_PADDING           "cbmp-padding-v2"                                       /**< Number of pixels to pad from the edge of each cube face for the Cubemap Projection*/
 180 #define MM_FILE_TAG_SPHERICAL_V2_EQUI_BOUNDS_TOP        "equi-projection-bounds-top-v2"         /**< Amount from the top of the frame to crop*/
 181 #define MM_FILE_TAG_SPHERICAL_V2_EQUI_BOUNDS_BOTTOM     "equi-projection-bounds-bottom-v2"      /**< Amount from the bottom of the frame to crop*/
 182 #define MM_FILE_TAG_SPHERICAL_V2_EQUI_BOUNDS_LEFT       "equi-projection-bounds-left-v2"        /**< Amount from the left of the frame to crop*/
 183 #define MM_FILE_TAG_SPHERICAL_V2_EQUI_BOUNDS_RIGHT      "equi-projection-bounds-right-v2"       /**< Amount from the right of the frame to crop*/
 184
 185 /**
 186   * This function is to create tag attribute from given media file path.<BR>
 187   * Handle can be used to get actual tag information by mm_file_get_attrs() after this function.<BR>
 188   * Handle should be destroyed using mm_file_destroy_tag_attrs() after use.<BR>
 189   *
 190   * @param       tag_attrs      [out]   tag attribute handle
 191   * @param       filename       [in]    media file path
 192   *
 193   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 194   *
 195   * @remark     Filename must be UTF-8 format.
 196   *
 197   * @pre                File should be exists.
 198   * @post       Handle is ready to use.
 199   * @see                mm_file_destroy_tag_attrs, mm_file_get_attrs
 200   * @par Example:
 201   * @code
 202 #include <mm_file.h>
 203
 204 MMHandleType tag_attrs = NULL;
 205 // get tag handle
 206 mm_file_create_tag_attrs(&tag_attrs, filename);
 207
 208 // get attributes of tag
 209 ret = mm_file_get_attrs(tag_attrs,
 210                                                         &err_attr_name,
 211                                                         MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 212                                                         MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 213                                                         MM_FILE_TAG_TITLE, &ctag.title.value.s_val, &ctag.title.len,
 214                                                         MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 215                                                         MM_FILE_TAG_GENRE, &ctag.genre.value.s_val, &ctag.genre.len,
 216                                                         NULL);
 217 if (ret != MM_ERROR_NONE)
 218 {
 219         printf("failed to get %s attrs\n", *err_attr_name);
 220         return -1;
 221 }
 222
 223 // Use tag information
 224
 225 // Release tag
 226 mm_file_destroy_tag_attrs(tag_attrs);
 227
 228  *      @endcode
 229  */
 230 int mm_file_create_tag_attrs(MMHandleType *tag_attrs, const char *filename);
 231
 232 /**
 233  * This function is to destory the tag attribute handle which is created by mm_file_create_tag_attrs().<BR>
 234  * Handle should be destroyed using mm_file_destroy_tag_attrs() after use.
 235  *
 236  * @param        tag_attrs      [in]    tag attribute handle
 237  *
 238  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 239  *
 240  * @remark      None.
 241  *      @pre            Handle should be valid.
 242  *      @post   Handle is not valid any more.
 243  * @see         mm_file_create_tag_attrs, mm_file_get_attrs
 244  * @par Example:
 245  * @code
 246 #include <mm_file.h>
 247
 248 MMHandleType tag_attrs = NULL;
 249 // get tag handle
 250 mm_file_create_tag_attrs(&tag_attrs, filename);
 251
 252 // get attributes of tag
 253 ret = mm_file_get_attrs(tag_attrs,
 254                                                         &err_attr_name,
 255                                                         MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 256                                                         MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 257                                                         MM_FILE_TAG_TITLE, &ctag.title.value.s_val, &ctag.title.len,
 258                                                         MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 259                                                         MM_FILE_TAG_GENRE, &ctag.genre.value.s_val, &ctag.genre.len,
 260                                                         NULL);
 261 if (ret != MM_ERROR_NONE)
 262 {
 263         printf("failed to get %s attrs\n", *err_attr_name);
 264         return -1;
 265 }
 266
 267 // Use tag information
 268
 269 // Release tag
 270 mm_file_destroy_tag_attrs(tag_attrs);
 271
 272  *      @endcode
 273  */
 274 int mm_file_destroy_tag_attrs(MMHandleType tag_attrs);
 275
 276 /**
 277  * This function is to create content attribute from media file.<BR>
 278  * Handle can be used to get actual content information by mm_file_get_attrs() after this function.<BR>
 279  * Handle should be destroyed using mm_file_destroy_content_attrs() after use.<BR>
 280  *
 281  * @param        content_attrs          [out]   content attribute handle.
 282  * @param        filename       [in]    file path.
 283  *
 284  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 285  *
 286  * @remark      Filename must be UTF-8 format.
 287  *
 288  * @pre File should be exists.
 289  * @post        Handle is ready to use.
 290  * @see mm_file_destroy_content_attrs, mm_file_get_attrs
 291  * @par Example:
 292  * @code
 293 #include <mm_file.h>
 294
 295 // get track info
 296 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 297 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 298
 299 // create content handle
 300 mm_file_create_content_attrs(&content_attrs, filename);
 301
 302 // get duration information
 303 ret = mm_file_get_attrs(content_attrs, &err_attr_name, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 304 printf("duration: %d\n", ccontent.duration);
 305
 306 if (ret != MM_ERROR_NONE)
 307 {
 308         printf("failed to get %s\n", *err_attr_name);
 309         free(err_attr_name);
 310 }
 311
 312 // if audio track exists, get audio related information
 313 if (audio_track_num)
 314 {
 315         mm_file_get_attrs(content_attrs,
 316                                         NULL,
 317                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 318                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 319                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 320                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 321                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 322                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 323                                         NULL);
 324
 325         // Use audio information
 326 }
 327
 328 // if video track exists, get video related information
 329 if (video_track_num)
 330 {
 331          void *thumbnail = NULL;
 332
 333         mm_file_get_attrs(content_attrs,
 334                                         NULL,
 335                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 336                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 337                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 338                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 339                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 340                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 341                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 342                                         NULL);
 343
 344         // Use video information
 345 }
 346
 347 // Destory content handle
 348 mm_file_destroy_content_attrs(content_attrs);
 349  * @endcode
 350  */
 351 int mm_file_create_content_attrs(MMHandleType *content_attrs, const char *filename);
 352
 353 /**
 354   * This function is to destroy content attribute handle.<BR>
 355   * Handle should be destroyed using mm_file_destroy_content_attrs() after use.<BR>
 356   *
 357   * @param      content_attrs   [in]    content attribute handle.
 358   *
 359   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 360   *
 361   * @remark     None.
 362   *
 363   * @pre                Handle should be valid.
 364   * @post       Handle is not valid anymore.
 365   * @see                mm_file_create_content_attrs, mm_file_get_attrs
 366   * @par Example:
 367   * @code
 368 #include <mm_file.h>
 369
 370 // get track info
 371 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 372 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 373
 374 // create content handle
 375 mm_file_create_content_attrs(&content_attrs, filename);
 376
 377 // get duration information
 378 ret = mm_file_get_attrs(content_attrs, &err_attr_name, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 379 printf("duration: %d\n", ccontent.duration);
 380
 381 if (ret != MM_ERROR_NONE)
 382 {
 383         printf("failed to get %s\n", *err_attr_name);
 384         free(err_attr_name);
 385 }
 386
 387 // if audio track exists, get audio related information
 388 if (audio_track_num)
 389 {
 390         mm_file_get_attrs(content_attrs,
 391                                         NULL,
 392                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 393                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 394                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 395                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 396                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 397                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 398                                         NULL);
 399
 400         // Use audio information
 401 }
 402
 403 // if video track exists, get video related information
 404 if (video_track_num)
 405 {
 406         void *thumbnail = NULL;
 407
 408         mm_file_get_attrs(content_attrs,
 409                                         NULL,
 410                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 411                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 412                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 413                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 414                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 415                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 416                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 417                                         NULL);
 418
 419         // Use video information
 420 }
 421
 422 // Destory content handle
 423 mm_file_destroy_content_attrs(content_attrs);
 424 * @endcode
 425 */
 426 int mm_file_destroy_content_attrs(MMHandleType content_attrs);
 427
 428 /**
 429   * This function is to get the attributes from media tag or content.<BR>
 430   * Handle should be valid and created by using create functions such as mm_file_create_content_attrs(), mm_file_create_tag_attrs().<BR>
 431   * Handle should be destroyed after use.
 432   *
 433   * @param      attrs           [in]    tag or content attribute handle.
 434   * @param   err_attr_name           [out]  Name of attribute which is failed to get
 435   * @param   first_attribute_name [in]  Name of the first attribute to get
 436   * @param   ...                                         [in]           Value for the first attribute, followed optionally by more name/value pairs, terminated by NULL.
 437   *                                                                             But, in the case of data or string type, it should be name/value/size.
 438   *
 439   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 440   *
 441   * @remark     This function must be terminated by NULL argument.<BR>
 442   *                     And, if this function is failed, err_attr_name param must be free.
 443   * @pre                Handle should be valid.
 444   * @post       Every input parameters are set by each information attributes.
 445   * @see                mm_file_create_content_attrs, mm_file_create_tag_attrs
 446   * @par Example:
 447   * @code
 448 #include <mm_file.h>
 449
 450 // get track info
 451 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 452 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 453
 454 // create content handle
 455 mm_file_create_content_attrs(&content_attrs, filename);
 456
 457 // get duration information
 458 ret = mm_file_get_attrs(content_attrs, &err_attr_name, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 459 printf("duration: %d\n", ccontent.duration);
 460
 461 if (ret != MM_ERROR_NONE)
 462 {
 463         printf("failed to get %s\n", *err_attr_name);
 464         free(err_attr_name);
 465 }
 466
 467 // if audio track exists, get audio related information
 468 if (audio_track_num)
 469 {
 470         mm_file_get_attrs(content_attrs,
 471                                         NULL,
 472                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 473                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 474                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 475                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 476                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 477                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 478                                         NULL);
 479
 480         // Use audio information
 481 }
 482
 483 // if video track exists, get video related information
 484 if (video_track_num)
 485 {
 486          void *thumbnail = NULL;
 487
 488         mm_file_get_attrs(content_attrs,
 489                                         NULL,
 490                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 491                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 492                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 493                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 494                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 495                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 496                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 497                                         NULL);
 498
 499         // Use video information
 500 }
 501
 502 // Destory content handle
 503 mm_file_destroy_content_attrs(content_attrs);
 504   * @endcode
 505   */
 506
 507 int mm_file_get_attrs(MMHandleType attrs, char **err_attr_name, const char *first_attribute_name, ...)G_GNUC_NULL_TERMINATED;
 508
 509 /**
 510   * This function is to get the tag attributes from media data on memory while mm_file_create_tag_attrs() extracts from file.<BR>
 511   * This function acts same functionality as mm_file_create_tag_attrs() except media source format (file/memory).
 512   *
 513   * @param      tag_attrs       [out]   tag attributes handle.
 514   * @param      data    [in]    memory pointer of media data.
 515   * @param      size    [in]    size of media data.
 516   * @param      format  [in]    file format of media data.
 517   *
 518   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 519   *
 520   * @remark     Must be free return value.
 521   *
 522   * @pre        Input data pointer and input size should be valid. format should be matched with actual data.
 523   * @post       Tag attribute handle is ready to use.
 524   * @see                mm_file_destroy_tag_attrs
 525   * @code
 526 #include <mm_file.h>
 527
 528 // create tag handle from memory
 529 mm_file_create_tag_attrs_from_memory(&tag_attrs, data, size, MM_FILE_FORMAT_MP3);
 530
 531 // get audio artist & album tag
 532 mm_file_get_attrs(tag_attrs,
 533                                 NULL,
 534                                 MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 535                                 MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 536                                 MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 537                                 NULL);
 538
 539 // Destory tag handle
 540 mm_file_destroy_tag_attrs(tag_attrs);
 541   * @endcode
 542  */
 543 int mm_file_create_tag_attrs_from_memory(MMHandleType *tag_attrs, const void *data, unsigned int size, int format);
 544
 545 /**
 546   * This function is to get the content attributes from media data on memory while mm_file_create_content_attrs() extracts from file.<BR>
 547   * This function acts same functionality as mm_file_create_content_attrs() except media source format (file/memory).
 548   *
 549   * @param      content_attrs   [out]   content attributes handle.
 550   * @param      data    [in]    memory pointer of media data.
 551   * @param      size    [in]    size of media data.
 552   * @param      format  [in]    file format of media data.
 553   *
 554   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 555   *
 556   * @remark     Must be free return value.
 557   *
 558   * @pre        Input data pointer and input size should be valid. format should be matched with actual data.
 559   * @post       Content attribute handle is ready to use.
 560   * @see                mm_file_destroy_content_attrs
 561   * @par Example::
 562   * @code
 563 #include <mm_file.h>
 564
 565 // create content handle from memory
 566 mm_file_create_content_attrs_from_memory(&content_attrs, data, size, MM_FILE_FORMAT_MP3);
 567
 568 // get audio bit rate and sample rate
 569 mm_file_get_attrs(content_attrs,
 570                                 NULL,
 571                                 MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 572                                 MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 573                                 NULL);
 574
 575 // Destory content handle
 576 mm_file_destroy_content_attrs(content_attrs);
 577    * @endcode
 578    */
 579 int mm_file_create_content_attrs_from_memory(MMHandleType *content_attrs, const void *data, unsigned int size, int format);
 580
 581 /**
 582  * This function is to get the count of audio/video stream from media file.<BR>
 583  * This function is useful for determining whether content is audio or video file.<BR>
 584  * For example, If content contains video streams, then content can be treat as video contents.
 585  *
 586  * @param filename              [in]    file path
 587  * @param audio_stream_num      [out]   number of audio stream of media file
 588  * @param        video_stream_num       [out]   number of video stream of media file
 589  *
 590  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 591  * @remark      None.
 592  * @pre         File path should be exists and input param should be valid.
 593  * @post        Audio/Video stream count will be set
 594  * @see None.
 595  * @par Example::
 596  * @code
 597 #include <mm_file.h>
 598
 599 // get track info
 600 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 601 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 602  * @endcode
 603  */
 604
 605 int mm_file_get_stream_info(const char *filename, int *audio_stream_num, int *video_stream_num);
 606
 607 /**
 608   * This function is to get the content attributes without thumbnail from media file.<BR>
 609   * This function is almost same as mm_file_create_content_attrs() except extracting thumbnail feature.<BR>
 610   * As this function is not extracting thumbnail, this is faster than mm_file_create_content_attrs().
 611   *
 612   * @param       content_attrs          [out]   content attribute handle.
 613   * @param       filename       [in]    file path.
 614   *
 615   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 616   *
 617   * @remark     Filename must be UTF-8 format.
 618   *
 619   * @pre        File should be exists.
 620   * @post       Handle is ready to use.
 621   * @see                mm_file_destroy_content_attrs, mm_file_get_attrs
 622   * @par Example::
 623   * @code
 624 #include <mm_file.h>
 625
 626 // create content handle
 627 mm_file_create_content_attrs_simple(&content_attrs, filename);
 628
 629 // get width, height information
 630 mm_file_get_attrs(content_attrs,
 631                                 NULL,
 632                                 MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 633                                 MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 634                                 NULL);
 635
 636 // Destory content handle
 637 mm_file_destroy_content_attrs(content_attrs);
 638   * @endcode
 639   */
 640 int mm_file_create_content_attrs_simple(MMHandleType *content_attrs, const char *filename);
 641
 642 int mm_file_create_content_attrs_safe(MMHandleType *content_attrs, const char *filename);
 643
 644 int mm_file_get_synclyrics_info(MMHandleType tag_attrs, int index, unsigned long *time_info, char **lyrics);
 645
 646 /**
 647  * @brief Get a frame of video media. Not support for DRM Contents.
 648  *
 649  * @remarks @a frame must be released with @c free() by you
 650  *
 651  * @param [in] path The file path
 652  * @param [in] timestamp The timestamp in milliseconds
 653  * @param [in] is_accurate @a true, user can get an accurated frame for given the timestamp.\n
 654  * @a false, user can only get the nearest i-frame of video rapidly.
 655  * @param [out] frame raw frame data in RGB888
 656  * @param [out] size The frame data size
 657  * @param [out] width The frame width
 658  * @param [out] height The frame height
 659  * @return 0 on success, otherwise a negative error value
 660  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
 661  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
 662  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 663  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
 664  * @pre Set path to extract by calling metadata_extractor_set_path()
 665  * @see metadata_extractor_create(), metadata_extractor_destroy()
 666  */
 667
 668 int mm_file_get_video_frame(const char *path, double timestamp, bool is_accurate, unsigned char **frame, int *size, int *width, int *height);
 669
 670 int mm_file_get_video_frame_from_memory(const void *data, unsigned int datasize, double timestamp, bool is_accurate, unsigned char **frame, int *size, int *width, int *height);
 671
 672 int mm_file_check_uhqa(const char *filename, bool *is_uhqa);
 673
 674 /**
 675         @}
 676  */
 677
 678 #ifdef __cplusplus
 679 }
 680 #endif
 681
 682 #endif
 683