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                                                         MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 211                                                         MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 212                                                         MM_FILE_TAG_TITLE, &ctag.title.value.s_val, &ctag.title.len,
 213                                                         MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 214                                                         MM_FILE_TAG_GENRE, &ctag.genre.value.s_val, &ctag.genre.len,
 215                                                         NULL);
 216 if (ret != MM_ERROR_NONE)
 217 {
 218         printf("failed to get %s attrs\n", *err_attr_name);
 219         return -1;
 220 }
 221
 222 // Use tag information
 223
 224 // Release tag
 225 mm_file_destroy_tag_attrs(tag_attrs);
 226
 227  *      @endcode
 228  */
 229 int mm_file_create_tag_attrs(MMHandleType *tag_attrs, const char *filename);
 230
 231 /**
 232  * This function is to destory the tag attribute handle which is created by mm_file_create_tag_attrs().<BR>
 233  * Handle should be destroyed using mm_file_destroy_tag_attrs() after use.
 234  *
 235  * @param        tag_attrs      [in]    tag attribute handle
 236  *
 237  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 238  *
 239  * @remark      None.
 240  *      @pre            Handle should be valid.
 241  *      @post   Handle is not valid any more.
 242  * @see         mm_file_create_tag_attrs, mm_file_get_attrs
 243  * @par Example:
 244  * @code
 245 #include <mm_file.h>
 246
 247 MMHandleType tag_attrs = NULL;
 248 // get tag handle
 249 mm_file_create_tag_attrs(&tag_attrs, filename);
 250
 251 // get attributes of tag
 252 ret = mm_file_get_attrs(tag_attrs,
 253                                                         MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 254                                                         MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 255                                                         MM_FILE_TAG_TITLE, &ctag.title.value.s_val, &ctag.title.len,
 256                                                         MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 257                                                         MM_FILE_TAG_GENRE, &ctag.genre.value.s_val, &ctag.genre.len,
 258                                                         NULL);
 259 if (ret != MM_ERROR_NONE)
 260 {
 261         printf("failed to get %s attrs\n", *err_attr_name);
 262         return -1;
 263 }
 264
 265 // Use tag information
 266
 267 // Release tag
 268 mm_file_destroy_tag_attrs(tag_attrs);
 269
 270  *      @endcode
 271  */
 272 int mm_file_destroy_tag_attrs(MMHandleType tag_attrs);
 273
 274 /**
 275  * This function is to create content attribute from media file.<BR>
 276  * Handle can be used to get actual content information by mm_file_get_attrs() after this function.<BR>
 277  * Handle should be destroyed using mm_file_destroy_content_attrs() after use.<BR>
 278  *
 279  * @param        content_attrs          [out]   content attribute handle.
 280  * @param        filename       [in]    file path.
 281  *
 282  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 283  *
 284  * @remark      Filename must be UTF-8 format.
 285  *
 286  * @pre File should be exists.
 287  * @post        Handle is ready to use.
 288  * @see mm_file_destroy_content_attrs, mm_file_get_attrs
 289  * @par Example:
 290  * @code
 291 #include <mm_file.h>
 292
 293 // get track info
 294 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 295 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 296
 297 // create content handle
 298 mm_file_create_content_attrs(&content_attrs, filename);
 299
 300 // get duration information
 301 ret = mm_file_get_attrs(content_attrs, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 302 printf("duration: %d\n", ccontent.duration);
 303
 304 if (ret != MM_ERROR_NONE)
 305 {
 306         printf("failed to get %s\n", *err_attr_name);
 307         free(err_attr_name);
 308 }
 309
 310 // if audio track exists, get audio related information
 311 if (audio_track_num)
 312 {
 313         mm_file_get_attrs(content_attrs,
 314                                         NULL,
 315                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 316                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 317                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 318                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 319                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 320                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 321                                         NULL);
 322
 323         // Use audio information
 324 }
 325
 326 // if video track exists, get video related information
 327 if (video_track_num)
 328 {
 329          void *thumbnail = NULL;
 330
 331         mm_file_get_attrs(content_attrs,
 332                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 333                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 334                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 335                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 336                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 337                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 338                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 339                                         NULL);
 340
 341         // Use video information
 342 }
 343
 344 // Destory content handle
 345 mm_file_destroy_content_attrs(content_attrs);
 346  * @endcode
 347  */
 348 int mm_file_create_content_attrs(MMHandleType *content_attrs, const char *filename);
 349
 350 /**
 351   * This function is to destroy content attribute handle.<BR>
 352   * Handle should be destroyed using mm_file_destroy_content_attrs() after use.<BR>
 353   *
 354   * @param      content_attrs   [in]    content attribute handle.
 355   *
 356   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 357   *
 358   * @remark     None.
 359   *
 360   * @pre                Handle should be valid.
 361   * @post       Handle is not valid anymore.
 362   * @see                mm_file_create_content_attrs, mm_file_get_attrs
 363   * @par Example:
 364   * @code
 365 #include <mm_file.h>
 366
 367 // get track info
 368 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 369 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 370
 371 // create content handle
 372 mm_file_create_content_attrs(&content_attrs, filename);
 373
 374 // get duration information
 375 ret = mm_file_get_attrs(content_attrs, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 376 printf("duration: %d\n", ccontent.duration);
 377
 378 if (ret != MM_ERROR_NONE)
 379 {
 380         printf("failed to get %s\n", *err_attr_name);
 381         free(err_attr_name);
 382 }
 383
 384 // if audio track exists, get audio related information
 385 if (audio_track_num)
 386 {
 387         mm_file_get_attrs(content_attrs,
 388                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 389                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 390                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 391                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 392                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 393                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 394                                         NULL);
 395
 396         // Use audio information
 397 }
 398
 399 // if video track exists, get video related information
 400 if (video_track_num)
 401 {
 402         void *thumbnail = NULL;
 403
 404         mm_file_get_attrs(content_attrs,
 405                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 406                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 407                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 408                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 409                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 410                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 411                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 412                                         NULL);
 413
 414         // Use video information
 415 }
 416
 417 // Destory content handle
 418 mm_file_destroy_content_attrs(content_attrs);
 419 * @endcode
 420 */
 421 int mm_file_destroy_content_attrs(MMHandleType content_attrs);
 422
 423 /**
 424   * This function is to get the attributes from media tag or content.<BR>
 425   * Handle should be valid and created by using create functions such as mm_file_create_content_attrs(), mm_file_create_tag_attrs().<BR>
 426   * Handle should be destroyed after use.
 427   *
 428   * @param      attrs           [in]    tag or content attribute handle.
 429   * @param   first_attribute_name [in]  Name of the first attribute to get
 430   * @param   ...                                         [in]           Value for the first attribute, followed optionally by more name/value pairs, terminated by NULL.
 431   *                                                                             But, in the case of data or string type, it should be name/value/size.
 432   *
 433   * @return     This function returns MM_ERROR_NONE on success, or negative value.
 434   *
 435   * @remark     This function must be terminated by NULL argument.<BR>
 436   *                     And, if this function is failed, err_attr_name param must be free.
 437   * @pre                Handle should be valid.
 438   * @post       Every input parameters are set by each information attributes.
 439   * @see                mm_file_create_content_attrs, mm_file_create_tag_attrs
 440   * @par Example:
 441   * @code
 442 #include <mm_file.h>
 443
 444 // get track info
 445 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 446 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 447
 448 // create content handle
 449 mm_file_create_content_attrs(&content_attrs, filename);
 450
 451 // get duration information
 452 ret = mm_file_get_attrs(content_attrs, MM_FILE_CONTENT_DURATION, &ccontent.duration, NULL);
 453 printf("duration: %d\n", ccontent.duration);
 454
 455 if (ret != MM_ERROR_NONE)
 456 {
 457         printf("failed to get %s\n", *err_attr_name);
 458         free(err_attr_name);
 459 }
 460
 461 // if audio track exists, get audio related information
 462 if (audio_track_num)
 463 {
 464         mm_file_get_attrs(content_attrs,
 465                                         MM_FILE_CONTENT_AUDIO_CODEC, &ccontent.audio_codec,
 466                                         MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 467                                         MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 468                                         MM_FILE_CONTENT_AUDIO_CHANNELS, &ccontent.audio_channel,
 469                                         MM_FILE_CONTENT_AUDIO_TRACK_INDEX, &ccontent.audio_track_id,
 470                                         MM_FILE_CONTENT_AUDIO_TRACK_COUNT, &ccontent.audio_track_num,
 471                                         NULL);
 472
 473         // Use audio information
 474 }
 475
 476 // if video track exists, get video related information
 477 if (video_track_num)
 478 {
 479          void *thumbnail = NULL;
 480
 481         mm_file_get_attrs(content_attrs,
 482                                         MM_FILE_CONTENT_VIDEO_CODEC, &ccontent.video_codec,
 483                                         MM_FILE_CONTENT_VIDEO_BITRATE, &ccontent.video_bitrate,
 484                                         MM_FILE_CONTENT_VIDEO_FPS, &ccontent.video_fps,
 485                                         MM_FILE_CONTENT_VIDEO_TRACK_INDEX, &ccontent.video_track_id,
 486                                         MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 487                                         MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 488                                         MM_FILE_CONTENT_VIDEO_THUMBNAIL, &ccontent.thumbnail.value.p_val, &ccontent.thumbnail.len,
 489                                         NULL);
 490
 491         // Use video information
 492 }
 493
 494 // Destory content handle
 495 mm_file_destroy_content_attrs(content_attrs);
 496   * @endcode
 497   */
 498
 499 int mm_file_get_attrs(MMHandleType attrs, const char *first_attribute_name, ...)G_GNUC_NULL_TERMINATED;
 500
 501 /**
 502   * This function is to get the tag attributes from media data on memory while mm_file_create_tag_attrs() extracts from file.<BR>
 503   * This function acts same functionality as mm_file_create_tag_attrs() except media source format (file/memory).
 504   *
 505   * @param      tag_attrs       [out]   tag attributes handle.
 506   * @param      data    [in]    memory pointer of media data.
 507   * @param      size    [in]    size of media data.
 508   * @param      format  [in]    file format of media data.
 509   *
 510   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 511   *
 512   * @remark     Must be free return value.
 513   *
 514   * @pre        Input data pointer and input size should be valid. format should be matched with actual data.
 515   * @post       Tag attribute handle is ready to use.
 516   * @see                mm_file_destroy_tag_attrs
 517   * @code
 518 #include <mm_file.h>
 519
 520 // create tag handle from memory
 521 mm_file_create_tag_attrs_from_memory(&tag_attrs, data, size, MM_FILE_FORMAT_MP3);
 522
 523 // get audio artist & album tag
 524 mm_file_get_attrs(tag_attrs,
 525                                 MM_FILE_TAG_ARTIST, &ctag.artist.value.s_val, &ctag.artist.len,
 526                                 MM_FILE_TAG_ALBUM, &ctag.album.value.s_val, &ctag.album.len,
 527                                 MM_FILE_TAG_ALBUM_ARTIST, &ctag.album_artist.value.s_val, &ctag.album_artist.len,
 528                                 NULL);
 529
 530 // Destory tag handle
 531 mm_file_destroy_tag_attrs(tag_attrs);
 532   * @endcode
 533  */
 534 int mm_file_create_tag_attrs_from_memory(MMHandleType *tag_attrs, const void *data, unsigned int size, int format);
 535
 536 /**
 537   * This function is to get the content attributes from media data on memory while mm_file_create_content_attrs() extracts from file.<BR>
 538   * This function acts same functionality as mm_file_create_content_attrs() except media source format (file/memory).
 539   *
 540   * @param      content_attrs   [out]   content attributes handle.
 541   * @param      data    [in]    memory pointer of media data.
 542   * @param      size    [in]    size of media data.
 543   * @param      format  [in]    file format of media data.
 544   *
 545   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 546   *
 547   * @remark     Must be free return value.
 548   *
 549   * @pre        Input data pointer and input size should be valid. format should be matched with actual data.
 550   * @post       Content attribute handle is ready to use.
 551   * @see                mm_file_destroy_content_attrs
 552   * @par Example::
 553   * @code
 554 #include <mm_file.h>
 555
 556 // create content handle from memory
 557 mm_file_create_content_attrs_from_memory(&content_attrs, data, size, MM_FILE_FORMAT_MP3);
 558
 559 // get audio bit rate and sample rate
 560 mm_file_get_attrs(content_attrs,
 561                                 MM_FILE_CONTENT_AUDIO_SAMPLERATE, &ccontent.audio_samplerate,
 562                                 MM_FILE_CONTENT_AUDIO_BITRATE, &ccontent.audio_bitrate,
 563                                 NULL);
 564
 565 // Destory content handle
 566 mm_file_destroy_content_attrs(content_attrs);
 567    * @endcode
 568    */
 569 int mm_file_create_content_attrs_from_memory(MMHandleType *content_attrs, const void *data, unsigned int size, int format);
 570
 571 /**
 572  * This function is to get the count of audio/video stream from media file.<BR>
 573  * This function is useful for determining whether content is audio or video file.<BR>
 574  * For example, If content contains video streams, then content can be treat as video contents.
 575  *
 576  * @param filename              [in]    file path
 577  * @param audio_stream_num      [out]   number of audio stream of media file
 578  * @param        video_stream_num       [out]   number of video stream of media file
 579  *
 580  * @return      This function returns MM_ERROR_NONE on success, or negative value with error code.
 581  * @remark      None.
 582  * @pre         File path should be exists and input param should be valid.
 583  * @post        Audio/Video stream count will be set
 584  * @see None.
 585  * @par Example::
 586  * @code
 587 #include <mm_file.h>
 588
 589 // get track info
 590 mm_file_get_stream_info(filename, &audio_track_num, &video_track_num);
 591 printf ("Testing mm_file_get_stream_info()....audio=%d, video=%d\n", audio_track_num, video_track_num);
 592  * @endcode
 593  */
 594
 595 int mm_file_get_stream_info(const char *filename, int *audio_stream_num, int *video_stream_num);
 596
 597 /**
 598   * This function is to get the content attributes without thumbnail from media file.<BR>
 599   * This function is almost same as mm_file_create_content_attrs() except extracting thumbnail feature.<BR>
 600   * As this function is not extracting thumbnail, this is faster than mm_file_create_content_attrs().
 601   *
 602   * @param       content_attrs          [out]   content attribute handle.
 603   * @param       filename       [in]    file path.
 604   *
 605   * @return     This function returns MM_ERROR_NONE on success, or negative value with error code.
 606   *
 607   * @remark     Filename must be UTF-8 format.
 608   *
 609   * @pre        File should be exists.
 610   * @post       Handle is ready to use.
 611   * @see                mm_file_destroy_content_attrs, mm_file_get_attrs
 612   * @par Example::
 613   * @code
 614 #include <mm_file.h>
 615
 616 // create content handle
 617 mm_file_create_content_attrs_simple(&content_attrs, filename);
 618
 619 // get width, height information
 620 mm_file_get_attrs(content_attrs,
 621                                 MM_FILE_CONTENT_VIDEO_WIDTH, &ccontent.video_w,
 622                                 MM_FILE_CONTENT_VIDEO_HEIGHT, &ccontent.video_h,
 623                                 NULL);
 624
 625 // Destory content handle
 626 mm_file_destroy_content_attrs(content_attrs);
 627   * @endcode
 628   */
 629 int mm_file_create_content_attrs_simple(MMHandleType *content_attrs, const char *filename);
 630
 631 int mm_file_create_content_attrs_safe(MMHandleType *content_attrs, const char *filename);
 632
 633 int mm_file_get_synclyrics_info(MMHandleType tag_attrs, int index, unsigned long *time_info, char **lyrics);
 634
 635 /**
 636  * @brief Get a frame of video media. Not support for DRM Contents.
 637  *
 638  * @remarks @a frame must be released with @c free() by you
 639  *
 640  * @param [in] path The file path
 641  * @param [in] timestamp The timestamp in milliseconds
 642  * @param [in] is_accurate @a true, user can get an accurated frame for given the timestamp.\n
 643  * @a false, user can only get the nearest i-frame of video rapidly.
 644  * @param [out] frame raw frame data in RGB888
 645  * @param [out] size The frame data size
 646  * @param [out] width The frame width
 647  * @param [out] height The frame height
 648  * @return 0 on success, otherwise a negative error value
 649  * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
 650  * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
 651  * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 652  * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
 653  * @pre Set path to extract by calling metadata_extractor_set_path()
 654  * @see metadata_extractor_create(), metadata_extractor_destroy()
 655  */
 656
 657 int mm_file_get_video_frame(const char *path, double timestamp, bool is_accurate, unsigned char **frame, int *size, int *width, int *height);
 658
 659 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);
 660
 661 int mm_file_check_uhqa(const char *filename, bool *is_uhqa);
 662
 663 /**
 664         @}
 665  */
 666
 667 #ifdef __cplusplus
 668 }
 669 #endif
 670
 671 #endif
 672