gst-libs/gst/tag/tag.h

   1 /* GStreamer
   2  * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20
  21 #ifndef __GST_TAG_TAG_H__
  22 #define __GST_TAG_TAG_H__
  23
  24 #include <gst/gst.h>
  25
  26 G_BEGIN_DECLS
  27
  28 /* Tag names */
  29
  30 /**
  31  * GST_TAG_MUSICBRAINZ_TRACKID
  32  *
  33  * MusicBrainz track ID
  34  */
  35 #define GST_TAG_MUSICBRAINZ_TRACKID     "musicbrainz-trackid"
  36 /**
  37  * GST_TAG_MUSICBRAINZ_ARTISTID
  38  *
  39  * MusicBrainz artist ID
  40  */
  41 #define GST_TAG_MUSICBRAINZ_ARTISTID    "musicbrainz-artistid"
  42 /**
  43  * GST_TAG_MUSICBRAINZ_ALBUMID
  44  *
  45  * MusicBrainz album ID
  46  */
  47 #define GST_TAG_MUSICBRAINZ_ALBUMID     "musicbrainz-albumid"
  48 /**
  49  * GST_TAG_MUSICBRAINZ_ALBUMARTISTID
  50  *
  51  * MusicBrainz album artist ID
  52  */
  53 #define GST_TAG_MUSICBRAINZ_ALBUMARTISTID       "musicbrainz-albumartistid"
  54 /**
  55  * GST_TAG_MUSICBRAINZ_TRMID
  56  *
  57  * MusicBrainz track TRM ID
  58  */
  59 #define GST_TAG_MUSICBRAINZ_TRMID       "musicbrainz-trmid"
  60
  61 /* FIXME 0.11: remove GST_TAG_MUSICBRAINZ_SORTNAME */
  62 #ifndef GST_DISABLE_DEPRECATED
  63 /**
  64  * GST_TAG_MUSICBRAINZ_SORTNAME
  65  *
  66  * MusicBrainz artist sort name
  67  *
  68  * Deprecated.  Use GST_TAG_ARTIST_SORTNAME instead.
  69  */
  70 #define GST_TAG_MUSICBRAINZ_SORTNAME    GST_TAG_ARTIST_SORTNAME
  71 #endif
  72
  73 /**
  74  * GST_TAG_CMML_STREAM
  75  *
  76  * Annodex CMML stream element tag
  77  */
  78 #define GST_TAG_CMML_STREAM "cmml-stream"
  79 /**
  80  * GST_TAG_CMML_HEAD
  81  *
  82  * Annodex CMML head element tag
  83  */
  84
  85 #define GST_TAG_CMML_HEAD "cmml-head"
  86 /**
  87  * GST_TAG_CMML_CLIP
  88  *
  89  * Annodex CMML clip element tag
  90  */
  91 #define GST_TAG_CMML_CLIP "cmml-clip"
  92
  93 /* CDDA tags */
  94
  95 /**
  96  * GST_TAG_CDDA_CDDB_DISCID:
  97  *
  98  * CDDB disc id in its short form (e.g. 'aa063d0f')
  99  */
 100 #define GST_TAG_CDDA_CDDB_DISCID              "discid"
 101
 102 /**
 103  * GST_TAG_CDDA_CDDB_DISCID_FULL:
 104  *
 105  * CDDB disc id including all details
 106  */
 107 #define GST_TAG_CDDA_CDDB_DISCID_FULL         "discid-full"
 108
 109 /**
 110  * GST_TAG_CDDA_MUSICBRAINZ_DISCID:
 111  *
 112  * Musicbrainz disc id (e.g. 'ahg7JUcfR3vCYBphSDIogOOWrr0-')
 113  */
 114 #define GST_TAG_CDDA_MUSICBRAINZ_DISCID       "musicbrainz-discid"
 115
 116 /**
 117  * GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL:
 118  *
 119  * Musicbrainz disc id details
 120  */
 121 #define GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL  "musicbrainz-discid-full"
 122
 123 /**
 124  * GST_TAG_CAPTURING_SHUTTER_SPEED:
 125  *
 126  * Shutter speed used when capturing an image, in seconds. (fraction)
 127  *
 128  * Since: 0.10.31
 129  */
 130 #define GST_TAG_CAPTURING_SHUTTER_SPEED        "capturing-shutter-speed"
 131
 132 /**
 133  * GST_TAG_CAPTURING_FOCAL_RATIO:
 134  *
 135  * Focal ratio (f-number) used when capturing an image. (double)
 136  *
 137  * The value stored is the denominator of the focal ratio (f-number).
 138  * For example, if this tag value is 2, the focal ratio is f/2.
 139  *
 140  * Since: 0.10.31
 141  */
 142 #define GST_TAG_CAPTURING_FOCAL_RATIO          "capturing-focal-ratio"
 143
 144 /**
 145  * GST_TAG_CAPTURING_FOCAL_LENGTH:
 146  *
 147  * Focal length used when capturing an image, in mm. (double)
 148  *
 149  * Since: 0.10.31
 150  */
 151 #define GST_TAG_CAPTURING_FOCAL_LENGTH         "capturing-focal-length"
 152
 153 /**
 154  * GST_TAG_CAPTURING_DIGITAL_ZOOM_RATIO:
 155  *
 156  * Digital zoom ratio used when capturing an image. (double)
 157  *
 158  * Since: 0.10.31
 159  */
 160 #define GST_TAG_CAPTURING_DIGITAL_ZOOM_RATIO   "capturing-digital-zoom-ratio"
 161
 162 /**
 163  * GST_TAG_CAPTURING_ISO_SPEED:
 164  *
 165  * ISO speed used when capturing an image. (integer)
 166  *
 167  * Since: 0.10.31
 168  */
 169 #define GST_TAG_CAPTURING_ISO_SPEED           "capturing-iso-speed"
 170
 171 /**
 172  * GST_TAG_CAPTURING_EXPOSURE_PROGRAM:
 173  *
 174  * Type of exposure control used when capturing an image. (string)
 175  *
 176  * The allowed values are:
 177  *   "undefined"
 178  *   "manual"
 179  *   "normal" - automatically controlled
 180  *   "aperture-priority" - user selects aperture value
 181  *   "shutter-priority" - user selects shutter speed
 182  *   "creative" - biased towards depth of field
 183  *   "action" - biased towards fast shutter speed
 184  *   "portrait" - closeup, leaving background out of focus
 185  *   "landscape" - landscape photos, background in focus
 186  *
 187  * Since: 0.10.31
 188  */
 189 #define GST_TAG_CAPTURING_EXPOSURE_PROGRAM     "capturing-exposure-program"
 190
 191 /**
 192  * GST_TAG_CAPTURING_EXPOSURE_MODE:
 193  *
 194  * Exposure mode used when capturing an image. (string)
 195  *
 196  * The allowed values are:
 197  *   "auto-exposure"
 198  *   "manual-exposure"
 199  *   "auto-bracket"
 200  *
 201  * Since: 0.10.31
 202  */
 203 #define GST_TAG_CAPTURING_EXPOSURE_MODE       "capturing-exposure-mode"
 204
 205 /**
 206  * GST_TAG_CAPTURING_EXPOSURE_COMPENSATION:
 207  *
 208  * Exposure compensation using when capturing an image in EV. (double)
 209  *
 210  * Since: 0.10.33
 211  */
 212 #define GST_TAG_CAPTURING_EXPOSURE_COMPENSATION "capturing-exposure-compensation"
 213
 214 /**
 215  * GST_TAG_CAPTURING_SCENE_CAPTURE_TYPE:
 216  *
 217  * Scene mode used when capturing an image. (string)
 218  *
 219  * The allowed values are:
 220  *   "standard"
 221  *   "landscape"
 222  *   "portrait"
 223  *   "night-scene"
 224  *
 225  * Since: 0.10.31
 226  */
 227 #define GST_TAG_CAPTURING_SCENE_CAPTURE_TYPE  "capturing-scene-capture-type"
 228
 229 /**
 230  * GST_TAG_CAPTURING_GAIN_ADJUSTMENT:
 231  *
 232  * Gain adjustment applied to an image. (string)
 233  *
 234  * The allowed values are:
 235  *   "none"
 236  *   "low-gain-up"
 237  *   "high-gain-up"
 238  *   "low-gain-down"
 239  *   "high-gain-down"
 240  *
 241  * Since: 0.10.31
 242  */
 243 #define GST_TAG_CAPTURING_GAIN_ADJUSTMENT     "capturing-gain-adjustment"
 244
 245 /**
 246  * GST_TAG_CAPTURING_WHITE_BALANCE:
 247  *
 248  * White balance mode used when capturing an image. (string)
 249  *
 250  * The allowed values are:
 251  *   "auto"
 252  *   "manual"
 253  *   "daylight"
 254  *   "cloudy"
 255  *   "tungsten"
 256  *   "fluorescent"
 257  *   "fluorescent h" (newer daylight-calibrated fluorescents)
 258  *   "flash"
 259  *
 260  * Since: 0.10.31
 261  */
 262 #define GST_TAG_CAPTURING_WHITE_BALANCE       "capturing-white-balance"
 263
 264 /**
 265  * GST_TAG_CAPTURING_CONTRAST:
 266  *
 267  * Direction of contrast processing applied when capturing an image. (string)
 268  *
 269  * The allowed values are:
 270  *  "normal"
 271  *  "soft"
 272  *  "hard"
 273  *
 274  * Since: 0.10.31
 275  */
 276 #define GST_TAG_CAPTURING_CONTRAST            "capturing-contrast"
 277
 278 /**
 279  * GST_TAG_CAPTURING_SATURATION:
 280  *
 281  * Direction of saturation processing applied when capturing an image. (string)
 282  *
 283  * The allowed values are:
 284  *  "normal"
 285  *  "low-saturation"
 286  *  "high-saturation"
 287  *
 288  * Since: 0.10.31
 289  */
 290 #define GST_TAG_CAPTURING_SATURATION          "capturing-saturation"
 291
 292 /**
 293  * GST_TAG_CAPTURING_SHARPNESS:
 294  *
 295  * Direction of sharpness processing applied when capturing an image. (string)
 296  *
 297  * The allowed values are:
 298  *  "normal"
 299  *  "soft"
 300  *  "hard"
 301  *
 302  * Since: 0.10.31
 303  */
 304 #define GST_TAG_CAPTURING_SHARPNESS          "capturing-sharpness"
 305
 306 /**
 307  * GST_TAG_CAPTURING_FLASH_FIRED:
 308  *
 309  * If flash was fired during the capture of an image. (boolean)
 310  *
 311  * Note that if this tag isn't present, it should not be assumed that
 312  * the flash did not fire. It should be treated as unknown.
 313  *
 314  * Since: 0.10.31
 315  */
 316 #define GST_TAG_CAPTURING_FLASH_FIRED         "capturing-flash-fired"
 317
 318 /**
 319  * GST_TAG_CAPTURING_FLASH_MODE:
 320  *
 321  * The flash mode selected during the capture of an image. (string)
 322  *
 323  * The allowed values are:
 324  *  "auto"
 325  *  "always"
 326  *  "never"
 327  *
 328  * Since: 0.10.31
 329  */
 330 #define GST_TAG_CAPTURING_FLASH_MODE         "capturing-flash-mode"
 331
 332 /**
 333  * GST_TAG_CAPTURING_METERING_MODE:
 334  *
 335  * Defines the way a camera determines the exposure. (string)
 336  *
 337  * The allowed values are:
 338  *   "unknown"
 339  *   "average"
 340  *   "center-weighted-average"
 341  *   "spot"
 342  *   "multi-spot"
 343  *   "pattern"
 344  *   "partial"
 345  *   "other"
 346  *
 347  * Since: 0.10.31
 348  */
 349 #define GST_TAG_CAPTURING_METERING_MODE      "capturing-metering-mode"
 350
 351 /**
 352  * GST_TAG_CAPTURING_SOURCE:
 353  *
 354  * Indicates the source of capture. The device/medium used to do the
 355  * capture. (string)
 356  *
 357  * Allowed values are:
 358  *   "dsc" (= digital still camera)
 359  *   "transparent-scanner"
 360  *   "reflex-scanner"
 361  *   "other"
 362  *
 363  * Since: 0.10.31
 364  */
 365 #define GST_TAG_CAPTURING_SOURCE             "capturing-source"
 366
 367 /**
 368  * GST_TAG_IMAGE_HORIZONTAL_PPI:
 369  *
 370  * Media (image/video) intended horizontal pixel density in ppi. (double)
 371  *
 372  * Since: 0.10.31
 373  */
 374 #define GST_TAG_IMAGE_HORIZONTAL_PPI         "image-horizontal-ppi"
 375 /**
 376  * GST_TAG_IMAGE_VERTICAL_PPI:
 377  *
 378  * Media (image/video) intended vertical pixel density in ppi. (double)
 379  *
 380  * Since: 0.10.31
 381  */
 382 #define GST_TAG_IMAGE_VERTICAL_PPI           "image-vertical-ppi"
 383
 384
 385 /* additional information for image tags */
 386
 387 /**
 388  * GstTagImageType:
 389  * @GST_TAG_IMAGE_TYPE_NONE                  : No image type. Can be used to
 390  *      tell functions such as gst_tag_image_data_to_image_buffer() that no
 391  *      image type should be set. (Since: 0.10.20)
 392  * @GST_TAG_IMAGE_TYPE_UNDEFINED             : Undefined/other image type
 393  * @GST_TAG_IMAGE_TYPE_FRONT_COVER           : Cover (front)
 394  * @GST_TAG_IMAGE_TYPE_BACK_COVER            : Cover (back)
 395  * @GST_TAG_IMAGE_TYPE_LEAFLET_PAGE          : Leaflet page
 396  * @GST_TAG_IMAGE_TYPE_MEDIUM                : Medium (e.g. label side of CD)
 397  * @GST_TAG_IMAGE_TYPE_LEAD_ARTIST           : Lead artist/lead performer/soloist
 398  * @GST_TAG_IMAGE_TYPE_ARTIST                : Artist/performer
 399  * @GST_TAG_IMAGE_TYPE_CONDUCTOR             : Conductor
 400  * @GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA        : Band/orchestra
 401  * @GST_TAG_IMAGE_TYPE_COMPOSER              : Composer
 402  * @GST_TAG_IMAGE_TYPE_LYRICIST              : Lyricist/text writer
 403  * @GST_TAG_IMAGE_TYPE_RECORDING_LOCATION    : Recording location
 404  * @GST_TAG_IMAGE_TYPE_DURING_RECORDING      : During recording
 405  * @GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE    : During performance
 406  * @GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE         : Movie/video screen capture
 407  * @GST_TAG_IMAGE_TYPE_FISH                  : A fish as funny as the ID3v2 spec
 408  * @GST_TAG_IMAGE_TYPE_ILLUSTRATION          : Illustration
 409  * @GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO      : Band/artist logotype
 410  * @GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO : Publisher/studio logotype
 411  *
 412  * Type of image contained in an image tag (specified as field in
 413  * the image buffer's caps structure)
 414  *
 415  * Since: 0.10.9
 416  */
 417 /* Note: keep in sync with register_tag_image_type_enum() */
 418 typedef enum {
 419   GST_TAG_IMAGE_TYPE_NONE = -1,
 420   GST_TAG_IMAGE_TYPE_UNDEFINED = 0,
 421   GST_TAG_IMAGE_TYPE_FRONT_COVER,
 422   GST_TAG_IMAGE_TYPE_BACK_COVER,
 423   GST_TAG_IMAGE_TYPE_LEAFLET_PAGE,
 424   GST_TAG_IMAGE_TYPE_MEDIUM,
 425   GST_TAG_IMAGE_TYPE_LEAD_ARTIST,
 426   GST_TAG_IMAGE_TYPE_ARTIST,
 427   GST_TAG_IMAGE_TYPE_CONDUCTOR,
 428   GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA,
 429   GST_TAG_IMAGE_TYPE_COMPOSER,
 430   GST_TAG_IMAGE_TYPE_LYRICIST,
 431   GST_TAG_IMAGE_TYPE_RECORDING_LOCATION,
 432   GST_TAG_IMAGE_TYPE_DURING_RECORDING,
 433   GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE,
 434   GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE,
 435   GST_TAG_IMAGE_TYPE_FISH,
 436   GST_TAG_IMAGE_TYPE_ILLUSTRATION,
 437   GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO,
 438   GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO
 439 } GstTagImageType;
 440
 441 #define GST_TYPE_TAG_IMAGE_TYPE  (gst_tag_image_type_get_type ())
 442 GType   gst_tag_image_type_get_type (void);
 443
 444
 445 /* functions for vorbis comment manipulation */
 446
 447 G_CONST_RETURN gchar *  gst_tag_from_vorbis_tag                 (const gchar *          vorbis_tag);
 448 G_CONST_RETURN gchar *  gst_tag_to_vorbis_tag                   (const gchar *          gst_tag);
 449 void                    gst_vorbis_tag_add                      (GstTagList *           list,
 450                                                                  const gchar *          tag,
 451                                                                  const gchar *          value);
 452
 453 GList *                 gst_tag_to_vorbis_comments              (const GstTagList *     list,
 454                                                                  const gchar *          tag);
 455
 456 /* functions to convert GstBuffers with vorbiscomment contents to GstTagLists and back */
 457 GstTagList *            gst_tag_list_from_vorbiscomment         (const guint8 *         data,
 458                                                                  gsize                  size,
 459                                                                  const guint8 *         id_data,
 460                                                                  const guint            id_data_length,
 461                                                                  gchar **               vendor_string);
 462 GstTagList *            gst_tag_list_from_vorbiscomment_buffer  (GstBuffer *            buffer,
 463                                                                  const guint8 *         id_data,
 464                                                                  const guint            id_data_length,
 465                                                                  gchar **               vendor_string);
 466 GstBuffer *             gst_tag_list_to_vorbiscomment_buffer    (const GstTagList *     list,
 467                                                                  const guint8 *         id_data,
 468                                                                  const guint            id_data_length,
 469                                                                  const gchar *          vendor_string);
 470
 471 /* functions for ID3 tag manipulation */
 472
 473 guint                   gst_tag_id3_genre_count                 (void);
 474 G_CONST_RETURN gchar *  gst_tag_id3_genre_get                   (const guint            id);
 475 GstTagList *            gst_tag_list_new_from_id3v1             (const guint8 *         data);
 476
 477 G_CONST_RETURN gchar *  gst_tag_from_id3_tag                    (const gchar *          id3_tag);
 478 G_CONST_RETURN gchar *  gst_tag_from_id3_user_tag               (const gchar *          type,
 479                                                                  const gchar *          id3_user_tag);
 480 G_CONST_RETURN gchar *  gst_tag_to_id3_tag                      (const gchar *          gst_tag);
 481
 482 gboolean                gst_tag_list_add_id3_image (GstTagList   * tag_list,
 483                                                     const guint8 * image_data,
 484                                                     guint          image_data_len,
 485                                                     guint          id3_picture_type);
 486
 487 /* functions to  convert GstBuffers with xmp packets contents to GstTagLists and back */
 488 GstTagList *            gst_tag_list_from_xmp_buffer  (GstBuffer *  buffer);
 489 GstBuffer *             gst_tag_list_to_xmp_buffer    (const GstTagList * list,
 490                                                        gboolean           read_only);
 491 GstBuffer *             gst_tag_list_to_xmp_buffer_full (const GstTagList * list,
 492                                                         gboolean read_only, const gchar ** schemas);
 493 const gchar**           gst_tag_xmp_list_schemas      (void);
 494
 495 /* functions related to exif */
 496 GstBuffer *             gst_tag_list_to_exif_buffer (const GstTagList * taglist,
 497                                                      gint byte_order,
 498                                                      guint32 base_offset);
 499
 500 GstBuffer *             gst_tag_list_to_exif_buffer_with_tiff_header (const GstTagList * taglist);
 501
 502 GstTagList *            gst_tag_list_from_exif_buffer (GstBuffer * buffer,
 503                                                        gint byte_order,
 504                                                        guint32 base_offset);
 505
 506 GstTagList *            gst_tag_list_from_exif_buffer_with_tiff_header (
 507                                                       GstBuffer * buffer);
 508
 509 /* other tag-related functions */
 510
 511 gboolean                gst_tag_parse_extended_comment (const gchar  * ext_comment,
 512                                                         gchar       ** key,
 513                                                         gchar       ** lang,
 514                                                         gchar       ** value,
 515                                                         gboolean       fail_if_no_key);
 516
 517 gchar                 * gst_tag_freeform_string_to_utf8 (const gchar  * data,
 518                                                          gint           size,
 519                                                          const gchar ** env_vars);
 520
 521 GstBuffer             * gst_tag_image_data_to_image_buffer (const guint8   * image_data,
 522                                                             guint            image_data_len,
 523                                                             GstTagImageType  image_type);
 524
 525 /* FIXME 0.11: replace with a more general gst_tag_library_init() */
 526 void                    gst_tag_register_musicbrainz_tags (void);
 527
 528
 529 /* language tag related functions */
 530
 531 gchar **       gst_tag_get_language_codes (void);
 532
 533 const gchar *  gst_tag_get_language_name (const gchar * language_code);
 534
 535 const gchar *  gst_tag_get_language_code_iso_639_1 (const gchar * lang_code);
 536
 537 const gchar *  gst_tag_get_language_code_iso_639_2B (const gchar * lang_code);
 538
 539 const gchar *  gst_tag_get_language_code_iso_639_2T (const gchar * lang_code);
 540
 541 /**
 542  * gst_tag_get_language_code:
 543  * @lang_code: ISO-639 language code (e.g. "deu" or "ger" or "de")
 544  *
 545  * Convenience macro wrapping gst_tag_get_language_code_iso_639_1().
 546  *
 547  * Since: 0.10.26
 548  */
 549 #define gst_tag_get_language_code(lang_code) \
 550     gst_tag_get_language_code_iso_639_1(lang_code)
 551
 552 G_END_DECLS
 553
 554 #endif /* __GST_TAG_TAG_H__ */