gst/gsttaglist.h

   1 /* GStreamer
   2  * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
   3  *
   4  * gsttaglist.h: Header for tag support
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22
  23 #ifndef __GST_TAGLIST_H__
  24 #define __GST_TAGLIST_H__
  25
  26 #include <gst/gststructure.h>
  27 #include <gst/glib-compat.h>
  28
  29 G_BEGIN_DECLS
  30
  31 /**
  32  * GstTagMergeMode:
  33  * @GST_TAG_MERGE_UNDEFINED: undefined merge mode
  34  * @GST_TAG_MERGE_REPLACE_ALL: replace all tags
  35  * @GST_TAG_MERGE_REPLACE: replace tags
  36  * @GST_TAG_MERGE_APPEND: append tags
  37  * @GST_TAG_MERGE_PREPEND: prepend tags
  38  * @GST_TAG_MERGE_KEEP: keep existing tags
  39  * @GST_TAG_MERGE_KEEP_ALL: keep all existing tags
  40  * @GST_TAG_MERGE_COUNT: the number of merge modes
  41  *
  42  * The different tag merging modes.
  43  */
  44 typedef enum {
  45   GST_TAG_MERGE_UNDEFINED,
  46   GST_TAG_MERGE_REPLACE_ALL,
  47   GST_TAG_MERGE_REPLACE,
  48   GST_TAG_MERGE_APPEND,
  49   GST_TAG_MERGE_PREPEND,
  50   GST_TAG_MERGE_KEEP,
  51   GST_TAG_MERGE_KEEP_ALL,
  52   /* add more */
  53   GST_TAG_MERGE_COUNT
  54 } GstTagMergeMode;
  55
  56 #define GST_TAG_MODE_IS_VALID(mode)     (((mode) > GST_TAG_MERGE_UNDEFINED) && ((mode) < GST_TAG_MERGE_COUNT))
  57
  58 /**
  59  * GstTagFlag:
  60  * @GST_TAG_FLAG_UNDEFINED: undefined flag
  61  * @GST_TAG_FLAG_META: tag is meta data
  62  * @GST_TAG_FLAG_ENCODED: tag is encoded
  63  * @GST_TAG_FLAG_DECODED: tag is decoded
  64  * @GST_TAG_FLAG_COUNT: number of tag flags
  65  *
  66  * Extra tag flags used when registering tags.
  67  */
  68 typedef enum {
  69   GST_TAG_FLAG_UNDEFINED,
  70   GST_TAG_FLAG_META,
  71   GST_TAG_FLAG_ENCODED,
  72   GST_TAG_FLAG_DECODED,
  73   GST_TAG_FLAG_COUNT
  74 } GstTagFlag;
  75
  76 #define GST_TAG_FLAG_IS_VALID(flag)     (((flag) > GST_TAG_FLAG_UNDEFINED) && ((flag) < GST_TAG_FLAG_COUNT))
  77
  78 /**
  79  * GstTagList:
  80  *
  81  * Opaque #GstTagList data structure.
  82  */
  83 typedef GstStructure GstTagList;
  84 #define GST_TAG_LIST(x)       ((GstTagList *) (x))
  85 #define GST_IS_TAG_LIST(x)    ((x) != NULL && gst_is_tag_list (GST_TAG_LIST (x)))
  86 #define GST_TYPE_TAG_LIST     (gst_tag_list_get_type ())
  87
  88 /**
  89  * GstTagForeachFunc:
  90  * @list: the #GstTagList
  91  * @tag: a name of a tag in @list
  92  * @user_data: user data
  93  *
  94  * A function that will be called in gst_tag_list_foreach(). The function may
  95  * not modify the tag list.
  96  */
  97 typedef void (*GstTagForeachFunc) (const GstTagList * list,
  98                                    const gchar      * tag,
  99                                    gpointer           user_data);
 100
 101 /**
 102  * GstTagMergeFunc:
 103  * @dest: the destination #GValue
 104  * @src: the source #GValue
 105  *
 106  * A function for merging multiple values of a tag used when registering
 107  * tags.
 108  */
 109 typedef void (* GstTagMergeFunc) (GValue *dest, const GValue *src);
 110
 111 /* initialize tagging system */
 112 void         _gst_tag_initialize   (void);
 113 GType        gst_tag_list_get_type (void);
 114
 115 void         gst_tag_register      (const gchar     * name,
 116                                     GstTagFlag        flag,
 117                                     GType             type,
 118                                     const gchar     * nick,
 119                                     const gchar     * blurb,
 120                                     GstTagMergeFunc   func);
 121
 122 /* some default merging functions */
 123 void      gst_tag_merge_use_first          (GValue * dest, const GValue * src);
 124 void      gst_tag_merge_strings_with_comma (GValue * dest, const GValue * src);
 125
 126 /* basic tag support */
 127 gboolean               gst_tag_exists          (const gchar * tag);
 128 GType                  gst_tag_get_type        (const gchar * tag);
 129 G_CONST_RETURN gchar * gst_tag_get_nick        (const gchar * tag);
 130 G_CONST_RETURN gchar * gst_tag_get_description (const gchar * tag);
 131 GstTagFlag             gst_tag_get_flag        (const gchar * tag);
 132 gboolean               gst_tag_is_fixed        (const gchar * tag);
 133
 134 /* tag lists */
 135 GstTagList * gst_tag_list_new               (void);
 136 gboolean     gst_is_tag_list                (gconstpointer p);
 137 GstTagList * gst_tag_list_copy              (const GstTagList * list);
 138 gboolean     gst_tag_list_is_empty          (const GstTagList * list);
 139 void         gst_tag_list_insert            (GstTagList       * into,
 140                                              const GstTagList * from,
 141                                              GstTagMergeMode    mode);
 142 GstTagList * gst_tag_list_merge             (const GstTagList * list1,
 143                                              const GstTagList * list2,
 144                                              GstTagMergeMode    mode);
 145 void         gst_tag_list_free              (GstTagList       * list);
 146 guint        gst_tag_list_get_tag_size      (const GstTagList * list,
 147                                              const gchar      * tag);
 148 void         gst_tag_list_add               (GstTagList       * list,
 149                                              GstTagMergeMode    mode,
 150                                              const gchar      * tag,
 151                                              ...) G_GNUC_NULL_TERMINATED;
 152 void         gst_tag_list_add_values        (GstTagList       * list,
 153                                              GstTagMergeMode    mode,
 154                                              const gchar      * tag,
 155                                              ...) G_GNUC_NULL_TERMINATED;
 156 void         gst_tag_list_add_valist        (GstTagList       * list,
 157                                              GstTagMergeMode    mode,
 158                                              const gchar      * tag,
 159                                              va_list        var_args);
 160 void         gst_tag_list_add_valist_values (GstTagList       * list,
 161                                              GstTagMergeMode    mode,
 162                                              const gchar      * tag,
 163                                              va_list            var_args);
 164 void         gst_tag_list_remove_tag        (GstTagList       * list,
 165                                              const gchar      * tag);
 166 void         gst_tag_list_foreach           (const GstTagList * list,
 167                                              GstTagForeachFunc  func,
 168                                              gpointer           user_data);
 169
 170 G_CONST_RETURN GValue *
 171              gst_tag_list_get_value_index   (const GstTagList * list,
 172                                              const gchar      * tag,
 173                                              guint              index);
 174 gboolean     gst_tag_list_copy_value        (GValue           * dest,
 175                                              const GstTagList * list,
 176                                              const gchar      * tag);
 177
 178 /* simplifications (FIXME: do we want them?) */
 179 gboolean     gst_tag_list_get_char          (const GstTagList * list,
 180                                              const gchar      * tag,
 181                                              gchar            * value);
 182 gboolean     gst_tag_list_get_char_index    (const GstTagList * list,
 183                                              const gchar      * tag,
 184                                              guint              index,
 185                                              gchar            * value);
 186 gboolean     gst_tag_list_get_uchar         (const GstTagList * list,
 187                                              const gchar      * tag,
 188                                              guchar           * value);
 189 gboolean     gst_tag_list_get_uchar_index   (const GstTagList * list,
 190                                              const gchar      * tag,
 191                                              guint              index,
 192                                              guchar           * value);
 193 gboolean     gst_tag_list_get_boolean       (const GstTagList * list,
 194                                              const gchar      * tag,
 195                                              gboolean         * value);
 196 gboolean     gst_tag_list_get_boolean_index (const GstTagList * list,
 197                                              const gchar      * tag,
 198                                              guint              index,
 199                                              gboolean         * value);
 200 gboolean     gst_tag_list_get_int           (const GstTagList * list,
 201                                              const gchar      * tag,
 202                                              gint             * value);
 203 gboolean     gst_tag_list_get_int_index     (const GstTagList * list,
 204                                              const gchar      * tag,
 205                                              guint              index,
 206                                              gint             * value);
 207 gboolean     gst_tag_list_get_uint          (const GstTagList * list,
 208                                              const gchar      * tag,
 209                                              guint            * value);
 210 gboolean     gst_tag_list_get_uint_index    (const GstTagList * list,
 211                                              const gchar      * tag,
 212                                              guint              index,
 213                                              guint            * value);
 214 gboolean     gst_tag_list_get_long          (const GstTagList * list,
 215                                              const gchar      * tag,
 216                                              glong            * value);
 217 gboolean     gst_tag_list_get_long_index    (const GstTagList * list,
 218                                              const gchar      * tag,
 219                                              guint              index,
 220                                              glong            * value);
 221 gboolean     gst_tag_list_get_ulong         (const GstTagList * list,
 222                                              const gchar      * tag,
 223                                              gulong           * value);
 224 gboolean     gst_tag_list_get_ulong_index   (const GstTagList * list,
 225                                              const gchar      * tag,
 226                                              guint              index,
 227                                              gulong           * value);
 228 gboolean     gst_tag_list_get_int64         (const GstTagList * list,
 229                                              const gchar      * tag,
 230                                              gint64           * value);
 231 gboolean     gst_tag_list_get_int64_index   (const GstTagList * list,
 232                                              const gchar      * tag,
 233                                              guint              index,
 234                                              gint64           * value);
 235 gboolean     gst_tag_list_get_uint64        (const GstTagList * list,
 236                                              const gchar      * tag,
 237                                              guint64          * value);
 238 gboolean     gst_tag_list_get_uint64_index  (const GstTagList * list,
 239                                              const gchar      * tag,
 240                                              guint              index,
 241                                              guint64          * value);
 242 gboolean     gst_tag_list_get_float         (const GstTagList * list,
 243                                              const gchar      * tag,
 244                                              gfloat           * value);
 245 gboolean     gst_tag_list_get_float_index   (const GstTagList * list,
 246                                              const gchar      * tag,
 247                                              guint              index,
 248                                              gfloat           * value);
 249 gboolean     gst_tag_list_get_double        (const GstTagList * list,
 250                                              const gchar      * tag,
 251                                              gdouble          * value);
 252 gboolean     gst_tag_list_get_double_index  (const GstTagList * list,
 253                                              const gchar      * tag,
 254                                              guint              index,
 255                                              gdouble          * value);
 256 gboolean     gst_tag_list_get_string        (const GstTagList * list,
 257                                              const gchar      * tag,
 258                                              gchar           ** value);
 259 gboolean     gst_tag_list_get_string_index  (const GstTagList * list,
 260                                              const gchar      * tag,
 261                                              guint              index,
 262                                              gchar           ** value);
 263 gboolean     gst_tag_list_get_pointer       (const GstTagList * list,
 264                                              const gchar      * tag,
 265                                              gpointer         * value);
 266 gboolean     gst_tag_list_get_pointer_index (const GstTagList * list,
 267                                              const gchar      * tag,
 268                                              guint              index,
 269                                              gpointer         * value);
 270 gboolean     gst_tag_list_get_date          (const GstTagList * list,
 271                                              const gchar      * tag,
 272                                              GDate           ** value);
 273 gboolean     gst_tag_list_get_date_index    (const GstTagList * list,
 274                                              const gchar      * tag,
 275                                              guint              index,
 276                                              GDate           ** value);
 277
 278 /* GStreamer core tags */
 279 /**
 280  * GST_TAG_TITLE:
 281  *
 282  * commonly used title (string)
 283  */
 284 #define GST_TAG_TITLE                  "title"
 285 /**
 286  * GST_TAG_ARTIST:
 287  *
 288  * person(s) responsible for the recording (string)
 289  */
 290 #define GST_TAG_ARTIST                 "artist"
 291 /**
 292  * GST_TAG_ALBUM:
 293  *
 294  * album containing this data (string)
 295  */
 296 #define GST_TAG_ALBUM                  "album"
 297 /**
 298  * GST_TAG_DATE:
 299  *
 300  * date the data was created (#GDate structure)
 301  */
 302 #define GST_TAG_DATE                   "date"
 303 /**
 304  * GST_TAG_GENRE:
 305  *
 306  * genre this data belongs to (string)
 307  */
 308 #define GST_TAG_GENRE                  "genre"
 309 /**
 310  * GST_TAG_COMMENT:
 311  *
 312  * free text commenting the data (string)
 313  */
 314 #define GST_TAG_COMMENT                "comment"
 315 /**
 316  * GST_TAG_EXTENDED_COMMENT:
 317  *
 318  * key/value text commenting the data (string)
 319  *
 320  * Must be in the form of 'key=comment' or
 321  * 'key[lc]=comment' where 'lc' is an ISO-639
 322  * language code.
 323  *
 324  * This tag is used for unknown Vorbis comment tags,
 325  * unknown APE tags and certain ID3v2 comment fields.
 326  *
 327  * Since: 0.10.10
 328  */
 329 #define GST_TAG_EXTENDED_COMMENT       "extended-comment"
 330 /**
 331  * GST_TAG_TRACK_NUMBER:
 332  *
 333  * track number inside a collection (unsigned integer)
 334  */
 335 #define GST_TAG_TRACK_NUMBER           "track-number"
 336 /**
 337  * GST_TAG_TRACK_COUNT:
 338  *
 339  * count of tracks inside collection this track belongs to (unsigned integer)
 340  */
 341 #define GST_TAG_TRACK_COUNT            "track-count"
 342 /**
 343  * GST_TAG_ALBUM_VOLUME_NUMBER:
 344  *
 345  * disc number inside a collection (unsigned integer)
 346  */
 347 #define GST_TAG_ALBUM_VOLUME_NUMBER    "album-disc-number"
 348 /**
 349  * GST_TAG_ALBUM_VOLUME_COUNT:
 350  *
 351  * count of discs inside collection this disc belongs to (unsigned integer)
 352  */
 353 #define GST_TAG_ALBUM_VOLUME_COUNT    "album-disc-count"
 354 /**
 355  * GST_TAG_LOCATION:
 356  *
 357  * original location of file as a URI (string)
 358  */
 359 #define GST_TAG_LOCATION               "location"
 360 /**
 361  * GST_TAG_DESCRIPTION:
 362  *
 363  * short text describing the content of the data (string)
 364  */
 365 #define GST_TAG_DESCRIPTION            "description"
 366 /**
 367  * GST_TAG_VERSION:
 368  *
 369  * version of this data (string)
 370  */
 371 #define GST_TAG_VERSION                "version"
 372 /**
 373  * GST_TAG_ISRC:
 374  *
 375  * International Standard Recording Code - see http://www.ifpi.org/isrc/ (string)
 376  */
 377 #define GST_TAG_ISRC                   "isrc"
 378 /**
 379  * GST_TAG_ORGANIZATION:
 380  *
 381  * organization (string)
 382  */
 383 #define GST_TAG_ORGANIZATION           "organization"
 384 /**
 385  * GST_TAG_COPYRIGHT:
 386  *
 387  * copyright notice of the data (string)
 388  */
 389 #define GST_TAG_COPYRIGHT              "copyright"
 390 /**
 391  * GST_TAG_CONTACT:
 392  *
 393  * contact information (string)
 394  */
 395 #define GST_TAG_CONTACT                "contact"
 396 /**
 397  * GST_TAG_LICENSE:
 398  *
 399  * license of data (string)
 400  */
 401 #define GST_TAG_LICENSE                "license"
 402 /**
 403  * GST_TAG_PERFORMER:
 404  *
 405  * person(s) performing (string)
 406  */
 407 #define GST_TAG_PERFORMER              "performer"
 408 /**
 409  * GST_TAG_DURATION:
 410  *
 411  * length in GStreamer time units (nanoseconds) (unsigned 64-bit integer)
 412  */
 413 #define GST_TAG_DURATION               "duration"
 414 /**
 415  * GST_TAG_CODEC:
 416  *
 417  * codec the data is stored in (string)
 418  */
 419 #define GST_TAG_CODEC                  "codec"
 420 /**
 421  * GST_TAG_VIDEO_CODEC:
 422  *
 423  * codec the video data is stored in (string)
 424  */
 425 #define GST_TAG_VIDEO_CODEC            "video-codec"
 426 /**
 427  * GST_TAG_AUDIO_CODEC:
 428  *
 429  * codec the audio data is stored in (string)
 430  */
 431 #define GST_TAG_AUDIO_CODEC            "audio-codec"
 432 /**
 433  * GST_TAG_BITRATE:
 434  *
 435  * exact or average bitrate in bits/s (unsigned integer)
 436  */
 437 #define GST_TAG_BITRATE                "bitrate"
 438 /**
 439  * GST_TAG_NOMINAL_BITRATE:
 440  *
 441  * nominal bitrate in bits/s (unsigned integer)
 442  */
 443 #define GST_TAG_NOMINAL_BITRATE        "nominal-bitrate"
 444 /**
 445  * GST_TAG_MINIMUM_BITRATE:
 446  *
 447  * minimum bitrate in bits/s (unsigned integer)
 448  */
 449 #define GST_TAG_MINIMUM_BITRATE        "minimum-bitrate"
 450 /**
 451  * GST_TAG_MAXIMUM_BITRATE:
 452  *
 453  * maximum bitrate in bits/s (unsigned integer)
 454  */
 455 #define GST_TAG_MAXIMUM_BITRATE        "maximum-bitrate"
 456 /**
 457  * GST_TAG_SERIAL:
 458  *
 459  * serial number of track (unsigned integer)
 460  */
 461 #define GST_TAG_SERIAL                 "serial"
 462 /**
 463  * GST_TAG_ENCODER:
 464  *
 465  * encoder used to encode this stream (string)
 466  */
 467 #define GST_TAG_ENCODER                "encoder"
 468 /**
 469  * GST_TAG_ENCODER_VERSION:
 470  *
 471  * version of the encoder used to encode this stream (unsigned integer)
 472  */
 473 #define GST_TAG_ENCODER_VERSION        "encoder-version"
 474 /**
 475  * GST_TAG_TRACK_GAIN:
 476  *
 477  * track gain in db (double)
 478  */
 479 #define GST_TAG_TRACK_GAIN             "replaygain-track-gain"
 480 /**
 481  * GST_TAG_TRACK_PEAK:
 482  *
 483  * peak of the track (double)
 484  */
 485 #define GST_TAG_TRACK_PEAK             "replaygain-track-peak"
 486 /**
 487  * GST_TAG_ALBUM_GAIN:
 488  *
 489  * album gain in db (double)
 490  */
 491 #define GST_TAG_ALBUM_GAIN             "replaygain-album-gain"
 492 /**
 493  * GST_TAG_ALBUM_PEAK:
 494  *
 495  * peak of the album (double)
 496  */
 497 #define GST_TAG_ALBUM_PEAK             "replaygain-album-peak"
 498 /**
 499  * GST_TAG_LANGUAGE_CODE:
 500  *
 501  * Language code (ISO-639-1) (string)
 502  */
 503 #define GST_TAG_LANGUAGE_CODE          "language-code"
 504 /**
 505  * GST_TAG_IMAGE:
 506  *
 507  * image (buffer) (buffer caps should specify the content type)
 508  *
 509  * Since: 0.10.6
 510  */
 511 #define GST_TAG_IMAGE                  "image"
 512 /**
 513  * GST_TAG_PREVIEW_IMAGE:
 514  *
 515  * image that is meant for preview purposes (buffer)
 516  * (buffer caps should specify the content type)
 517  *
 518  * Since: 0.10.7
 519  */
 520 #define GST_TAG_PREVIEW_IMAGE          "preview-image"
 521
 522 G_END_DECLS
 523
 524 #endif /* __GST_TAGLIST_H__ */