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)      (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 /* some default merging functions */
 122 void            gst_tag_merge_use_first         (GValue *               dest,
 123                                                  const GValue *         src);
 124 void            gst_tag_merge_strings_with_comma (GValue *              dest,
 125                                                  const GValue *         src);
 126
 127 /* basic tag support */
 128 gboolean        gst_tag_exists                  (const gchar *          tag);
 129 GType           gst_tag_get_type                (const gchar *          tag);
 130 G_CONST_RETURN gchar *
 131                 gst_tag_get_nick                (const gchar *          tag);
 132 G_CONST_RETURN gchar *
 133                 gst_tag_get_description         (const gchar *          tag);
 134 GstTagFlag      gst_tag_get_flag                (const gchar *          tag);
 135 gboolean        gst_tag_is_fixed                (const gchar *          tag);
 136
 137 /* tag lists */
 138 GstTagList *    gst_tag_list_new                (void);
 139 gboolean        gst_is_tag_list                 (gconstpointer          p);
 140 GstTagList *    gst_tag_list_copy               (const GstTagList *     list);
 141 void            gst_tag_list_insert             (GstTagList *           into,
 142                                                  const GstTagList *     from,
 143                                                  GstTagMergeMode        mode);
 144 GstTagList *    gst_tag_list_merge              (const GstTagList *     list1,
 145                                                  const GstTagList *     list2,
 146                                                  GstTagMergeMode        mode);
 147 void            gst_tag_list_free               (GstTagList *           list);
 148 guint           gst_tag_list_get_tag_size       (const GstTagList *     list,
 149                                                  const gchar *          tag);
 150 void            gst_tag_list_add                (GstTagList *           list,
 151                                                  GstTagMergeMode        mode,
 152                                                  const gchar *          tag,
 153                                                  ...) G_GNUC_NULL_TERMINATED;
 154 void            gst_tag_list_add_values         (GstTagList *           list,
 155                                                  GstTagMergeMode        mode,
 156                                                  const gchar *          tag,
 157                                                  ...) G_GNUC_NULL_TERMINATED;
 158 void            gst_tag_list_add_valist         (GstTagList *           list,
 159                                                  GstTagMergeMode        mode,
 160                                                  const gchar *          tag,
 161                                                  va_list                var_args);
 162 void            gst_tag_list_add_valist_values  (GstTagList *           list,
 163                                                  GstTagMergeMode        mode,
 164                                                  const gchar *          tag,
 165                                                  va_list                var_args);
 166 void            gst_tag_list_remove_tag         (GstTagList *           list,
 167                                                  const gchar *          tag);
 168 void            gst_tag_list_foreach            (const GstTagList *     list,
 169                                                  GstTagForeachFunc      func,
 170                                                  gpointer               user_data);
 171
 172 G_CONST_RETURN GValue *
 173                 gst_tag_list_get_value_index    (const GstTagList *     list,
 174                                                  const gchar *          tag,
 175                                                  guint                  index);
 176 gboolean        gst_tag_list_copy_value         (GValue *               dest,
 177                                                  const GstTagList *     list,
 178                                                  const gchar *          tag);
 179
 180 /* simplifications (FIXME: do we want them?) */
 181 gboolean        gst_tag_list_get_char           (const GstTagList *     list,
 182                                                  const gchar *          tag,
 183                                                  gchar *                value);
 184 gboolean        gst_tag_list_get_char_index     (const GstTagList *     list,
 185                                                  const gchar *          tag,
 186                                                  guint                  index,
 187                                                  gchar *                value);
 188 gboolean        gst_tag_list_get_uchar          (const GstTagList *     list,
 189                                                  const gchar *          tag,
 190                                                  guchar *               value);
 191 gboolean        gst_tag_list_get_uchar_index    (const GstTagList *     list,
 192                                                  const gchar *          tag,
 193                                                  guint                  index,
 194                                                  guchar *               value);
 195 gboolean        gst_tag_list_get_boolean        (const GstTagList *     list,
 196                                                  const gchar *          tag,
 197                                                  gboolean *             value);
 198 gboolean        gst_tag_list_get_boolean_index  (const GstTagList *     list,
 199                                                  const gchar *          tag,
 200                                                  guint                  index,
 201                                                  gboolean *             value);
 202 gboolean        gst_tag_list_get_int            (const GstTagList *     list,
 203                                                  const gchar *          tag,
 204                                                  gint *                 value);
 205 gboolean        gst_tag_list_get_int_index      (const GstTagList *     list,
 206                                                  const gchar *          tag,
 207                                                  guint                  index,
 208                                                  gint *                 value);
 209 gboolean        gst_tag_list_get_uint           (const GstTagList *     list,
 210                                                  const gchar *          tag,
 211                                                  guint *                value);
 212 gboolean        gst_tag_list_get_uint_index     (const GstTagList *     list,
 213                                                  const gchar *          tag,
 214                                                  guint                  index,
 215                                                  guint *                value);
 216 gboolean        gst_tag_list_get_long           (const GstTagList *     list,
 217                                                  const gchar *          tag,
 218                                                  glong *                value);
 219 gboolean        gst_tag_list_get_long_index     (const GstTagList *     list,
 220                                                  const gchar *          tag,
 221                                                  guint                  index,
 222                                                  glong *                value);
 223 gboolean        gst_tag_list_get_ulong          (const GstTagList *     list,
 224                                                  const gchar *          tag,
 225                                                  gulong *               value);
 226 gboolean        gst_tag_list_get_ulong_index    (const GstTagList *     list,
 227                                                  const gchar *          tag,
 228                                                  guint                  index,
 229                                                  gulong *               value);
 230 gboolean        gst_tag_list_get_int64          (const GstTagList *     list,
 231                                                  const gchar *          tag,
 232                                                  gint64 *               value);
 233 gboolean        gst_tag_list_get_int64_index    (const GstTagList *     list,
 234                                                  const gchar *          tag,
 235                                                  guint                  index,
 236                                                  gint64 *               value);
 237 gboolean        gst_tag_list_get_uint64         (const GstTagList *     list,
 238                                                  const gchar *          tag,
 239                                                  guint64 *              value);
 240 gboolean        gst_tag_list_get_uint64_index   (const GstTagList *     list,
 241                                                  const gchar *          tag,
 242                                                  guint                  index,
 243                                                  guint64 *              value);
 244 gboolean        gst_tag_list_get_float          (const GstTagList *     list,
 245                                                  const gchar *          tag,
 246                                                  gfloat *               value);
 247 gboolean        gst_tag_list_get_float_index    (const GstTagList *     list,
 248                                                  const gchar *          tag,
 249                                                  guint                  index,
 250                                                  gfloat *               value);
 251 gboolean        gst_tag_list_get_double         (const GstTagList *     list,
 252                                                  const gchar *          tag,
 253                                                  gdouble *              value);
 254 gboolean        gst_tag_list_get_double_index   (const GstTagList *     list,
 255                                                  const gchar *          tag,
 256                                                  guint                  index,
 257                                                  gdouble *              value);
 258 gboolean        gst_tag_list_get_string         (const GstTagList *     list,
 259                                                  const gchar *          tag,
 260                                                  gchar **               value);
 261 gboolean        gst_tag_list_get_string_index   (const GstTagList *     list,
 262                                                  const gchar *          tag,
 263                                                  guint                  index,
 264                                                  gchar **               value);
 265 gboolean        gst_tag_list_get_pointer        (const GstTagList *     list,
 266                                                  const gchar *          tag,
 267                                                  gpointer *             value);
 268 gboolean        gst_tag_list_get_pointer_index  (const GstTagList *     list,
 269                                                  const gchar *          tag,
 270                                                  guint                  index,
 271                                                  gpointer *             value);
 272 gboolean        gst_tag_list_get_date           (const GstTagList     * list,
 273                                                  const gchar          * tag,
 274                                                  GDate               ** value);
 275 gboolean        gst_tag_list_get_date_index     (const GstTagList     * list,
 276                                                  const gchar          * tag,
 277                                                  guint                  index,
 278                                                  GDate               ** value);
 279
 280 /* GStreamer core tags (need to be discussed) */
 281 /**
 282  * GST_TAG_TITLE:
 283  *
 284  * commonly used title
 285  */
 286 #define GST_TAG_TITLE                   "title"
 287 /**
 288  * GST_TAG_ARTIST:
 289  *
 290  * person(s) responsible for the recording
 291  */
 292 #define GST_TAG_ARTIST                  "artist"
 293 /**
 294  * GST_TAG_ALBUM:
 295  *
 296  * album containing this data
 297  */
 298 #define GST_TAG_ALBUM                   "album"
 299 /**
 300  * GST_TAG_DATE:
 301  *
 302  * date the data was created (#GDate structure)
 303  */
 304 #define GST_TAG_DATE                    "date"
 305 /**
 306  * GST_TAG_GENRE:
 307  *
 308  * genre this data belongs to
 309  */
 310 #define GST_TAG_GENRE                   "genre"
 311 /**
 312  * GST_TAG_COMMENT:
 313  *
 314  * free text commenting the data
 315  */
 316 #define GST_TAG_COMMENT                 "comment"
 317 /**
 318  * GST_TAG_TRACK_NUMBER:
 319  *
 320  * track number inside a collection
 321  */
 322 #define GST_TAG_TRACK_NUMBER            "track-number"
 323 /**
 324  * GST_TAG_TRACK_COUNT:
 325  *
 326  * count of tracks inside collection this track belongs to
 327  */
 328 #define GST_TAG_TRACK_COUNT             "track-count"
 329 /**
 330  * GST_TAG_ALBUM_VOLUME_NUMBER:
 331  *
 332  * disc number inside a collection
 333  */
 334 #define GST_TAG_ALBUM_VOLUME_NUMBER     "album-disc-number"
 335 /**
 336  * GST_TAG_ALBUM_VOLUME_COUNT:
 337  *
 338  * count of discs inside collection this disc belongs to
 339  */
 340 #define GST_TAG_ALBUM_VOLUME_COUNT      "album-disc-count"
 341 /**
 342  * GST_TAG_LOCATION:
 343  *
 344  * original location of file as a URI
 345  */
 346 #define GST_TAG_LOCATION                "location"
 347 /**
 348  * GST_TAG_DESCRIPTION:
 349  *
 350  * short text describing the content of the data
 351  */
 352 #define GST_TAG_DESCRIPTION             "description"
 353 /**
 354  * GST_TAG_VERSION:
 355  *
 356  * version of this data
 357  */
 358 #define GST_TAG_VERSION                 "version"
 359 /**
 360  * GST_TAG_ISRC:
 361  *
 362  * International Standard Recording Code - see http://www.ifpi.org/isrc/
 363  */
 364 #define GST_TAG_ISRC                    "isrc"
 365 /**
 366  * GST_TAG_ORGANIZATION:
 367  *
 368  * organization
 369  */
 370 #define GST_TAG_ORGANIZATION            "organization"
 371 /**
 372  * GST_TAG_COPYRIGHT:
 373  *
 374  * copyright notice of the data
 375  */
 376 #define GST_TAG_COPYRIGHT               "copyright"
 377 /**
 378  * GST_TAG_CONTACT:
 379  *
 380  * contact information
 381  */
 382 #define GST_TAG_CONTACT                 "contact"
 383 /**
 384  * GST_TAG_LICENSE:
 385  *
 386  * license of data
 387  */
 388 #define GST_TAG_LICENSE                 "license"
 389 /**
 390  * GST_TAG_PERFORMER:
 391  *
 392  * person(s) performing
 393  */
 394 #define GST_TAG_PERFORMER               "performer"
 395 /**
 396  * GST_TAG_DURATION:
 397  *
 398  * length in GStreamer time units (nanoseconds)
 399  */
 400 #define GST_TAG_DURATION                "duration"
 401 /**
 402  * GST_TAG_CODEC:
 403  *
 404  * codec the data is stored in
 405  */
 406 #define GST_TAG_CODEC                   "codec"
 407 /**
 408  * GST_TAG_VIDEO_CODEC:
 409  *
 410  * codec the video data is stored in
 411  */
 412 #define GST_TAG_VIDEO_CODEC             "video-codec"
 413 /**
 414  * GST_TAG_AUDIO_CODEC:
 415  *
 416  * codec the audio data is stored in
 417  */
 418 #define GST_TAG_AUDIO_CODEC             "audio-codec"
 419 /**
 420  * GST_TAG_BITRATE:
 421  *
 422  * exact or average bitrate in bits/s
 423  */
 424 #define GST_TAG_BITRATE                 "bitrate"
 425 /**
 426  * GST_TAG_NOMINAL_BITRATE:
 427  *
 428  * nominal bitrate in bits/s
 429  */
 430 #define GST_TAG_NOMINAL_BITRATE         "nominal-bitrate"
 431 /**
 432  * GST_TAG_MINIMUM_BITRATE:
 433  *
 434  * minimum bitrate in bits/s
 435  */
 436 #define GST_TAG_MINIMUM_BITRATE         "minimum-bitrate"
 437 /**
 438  * GST_TAG_MAXIMUM_BITRATE:
 439  *
 440  * maximum bitrate in bits/s
 441  */
 442 #define GST_TAG_MAXIMUM_BITRATE         "maximum-bitrate"
 443 /**
 444  * GST_TAG_SERIAL:
 445  *
 446  * serial number of track
 447  */
 448 #define GST_TAG_SERIAL                  "serial"
 449 /**
 450  * GST_TAG_ENCODER:
 451  *
 452  * encoder used to encode this stream
 453  */
 454 #define GST_TAG_ENCODER                 "encoder"
 455 /**
 456  * GST_TAG_ENCODER_VERSION:
 457  *
 458  * version of the encoder used to encode this stream
 459  */
 460 #define GST_TAG_ENCODER_VERSION         "encoder-version"
 461 /**
 462  * GST_TAG_TRACK_GAIN:
 463  *
 464  * track gain in db
 465  */
 466 #define GST_TAG_TRACK_GAIN              "replaygain-track-gain"
 467 /**
 468  * GST_TAG_TRACK_PEAK:
 469  *
 470  * peak of the track
 471  */
 472 #define GST_TAG_TRACK_PEAK              "replaygain-track-peak"
 473 /**
 474  * GST_TAG_ALBUM_GAIN:
 475  *
 476  * album gain in db
 477  */
 478 #define GST_TAG_ALBUM_GAIN              "replaygain-album-gain"
 479 /**
 480  * GST_TAG_ALBUM_PEAK:
 481  *
 482  * peak of the album
 483  */
 484 #define GST_TAG_ALBUM_PEAK              "replaygain-album-peak"
 485 /**
 486  * GST_TAG_LANGUAGE_CODE:
 487  *
 488  * Language code (ISO-639-1)
 489  */
 490 #define GST_TAG_LANGUAGE_CODE           "language-code"
 491
 492 G_END_DECLS
 493
 494 #endif /* __GST_TAGLIST_H__ */