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
  28 G_BEGIN_DECLS
  29
  30 typedef enum {
  31   GST_TAG_MERGE_UNDEFINED,
  32   GST_TAG_MERGE_REPLACE_ALL,
  33   GST_TAG_MERGE_REPLACE,
  34   GST_TAG_MERGE_APPEND,
  35   GST_TAG_MERGE_PREPEND,
  36   GST_TAG_MERGE_KEEP,
  37   GST_TAG_MERGE_KEEP_ALL,
  38   /* add more */
  39   GST_TAG_MERGE_COUNT
  40 } GstTagMergeMode;
  41
  42 #define GST_TAG_MODE_IS_VALID(mode)     (((mode) > GST_TAG_MERGE_UNDEFINED) && ((mode) < GST_TAG_MERGE_COUNT))
  43
  44 typedef enum {
  45   GST_TAG_FLAG_UNDEFINED,
  46   GST_TAG_FLAG_META,
  47   GST_TAG_FLAG_ENCODED,
  48   GST_TAG_FLAG_DECODED,
  49   GST_TAG_FLAG_COUNT
  50 } GstTagFlag;
  51
  52 #define GST_TAG_FLAG_IS_VALID(flag)     (((flag) > GST_TAG_FLAG_UNDEFINED) && ((flag) < GST_TAG_FLAG_COUNT))
  53
  54 typedef GstStructure GstTagList;
  55 #define GST_TAG_LIST(x)         ((GstTagList *) (x))
  56 #define GST_IS_TAG_LIST(x)      (gst_is_tag_list (GST_TAG_LIST (x)))
  57 #define GST_TYPE_TAG_LIST       (gst_tag_list_get_type ())
  58
  59 /**
  60  * GstTagForeachFunc:
  61  * @list: the #GstTagList
  62  * @tag: a name of a tag in @list
  63  * @user_data: user data
  64  *
  65  * A function that will be called in gst_tag_list_foreach(). The function may
  66  * not modify the tag list.
  67  *
  68  * Returns: TRUE if the foreach operation should continue, FALSE if
  69  * the foreach operation should stop with FALSE.
  70  */
  71 typedef gboolean (*GstTagForeachFunc) (const GstTagList *list,
  72                                        const gchar * tag,
  73                                        gpointer user_data);
  74
  75 typedef void            (* GstTagMergeFunc)     (GValue *dest, const GValue *src);
  76
  77 /* initialize tagging system */
  78 void            _gst_tag_initialize             (void);
  79 GType           gst_tag_list_get_type           (void);
  80
  81 void            gst_tag_register                (const gchar *          name,
  82                                                  GstTagFlag             flag,
  83                                                  GType                  type,
  84                                                  const gchar *          nick,
  85                                                  const gchar *          blurb,
  86                                                  GstTagMergeFunc        func);
  87 /* some default merging functions */
  88 void            gst_tag_merge_use_first         (GValue *               dest,
  89                                                  const GValue *         src);
  90 void            gst_tag_merge_strings_with_comma (GValue *              dest,
  91                                                  const GValue *         src);
  92
  93 /* basic tag support */
  94 gboolean        gst_tag_exists                  (const gchar *          tag);
  95 GType           gst_tag_get_type                (const gchar *          tag);
  96 G_CONST_RETURN gchar *
  97                 gst_tag_get_nick                (const gchar *          tag);
  98 G_CONST_RETURN gchar *
  99                 gst_tag_get_description         (const gchar *          tag);
 100 GstTagFlag      gst_tag_get_flag                (const gchar *          tag);
 101 gboolean        gst_tag_is_fixed                (const gchar *          tag);
 102
 103 /* tag lists */
 104 GstTagList *    gst_tag_list_new                (void);
 105 gboolean        gst_is_tag_list                 (gconstpointer          p);
 106 GstTagList *    gst_tag_list_copy               (const GstTagList *     list);
 107 void            gst_tag_list_insert             (GstTagList *           into,
 108                                                  const GstTagList *     from,
 109                                                  GstTagMergeMode        mode);
 110 GstTagList *    gst_tag_list_merge              (const GstTagList *     list1,
 111                                                  const GstTagList *     list2,
 112                                                  GstTagMergeMode        mode);
 113 void            gst_tag_list_free               (GstTagList *           list);
 114 guint           gst_tag_list_get_tag_size       (const GstTagList *     list,
 115                                                  const gchar *          tag);
 116 void            gst_tag_list_add                (GstTagList *           list,
 117                                                  GstTagMergeMode        mode,
 118                                                  const gchar *          tag,
 119                                                  ...);
 120 void            gst_tag_list_add_values         (GstTagList *           list,
 121                                                  GstTagMergeMode        mode,
 122                                                  const gchar *          tag,
 123                                                  ...);
 124 void            gst_tag_list_add_valist         (GstTagList *           list,
 125                                                  GstTagMergeMode        mode,
 126                                                  const gchar *          tag,
 127                                                  va_list                var_args);
 128 void            gst_tag_list_add_valist_values  (GstTagList *           list,
 129                                                  GstTagMergeMode        mode,
 130                                                  const gchar *          tag,
 131                                                  va_list                var_args);
 132 void            gst_tag_list_remove_tag         (GstTagList *           list,
 133                                                  const gchar *          tag);
 134 void            gst_tag_list_foreach            (const GstTagList *     list,
 135                                                  GstTagForeachFunc      func,
 136                                                  gpointer               user_data);
 137
 138 G_CONST_RETURN GValue *
 139                 gst_tag_list_get_value_index    (const GstTagList *     list,
 140                                                  const gchar *          tag,
 141                                                  guint                  index);
 142 gboolean        gst_tag_list_copy_value         (GValue *               dest,
 143                                                  const GstTagList *     list,
 144                                                  const gchar *          tag);
 145
 146 /* simplifications (FIXME: do we want them?) */
 147 gboolean        gst_tag_list_get_char           (const GstTagList *     list,
 148                                                  const gchar *          tag,
 149                                                  gchar *                value);
 150 gboolean        gst_tag_list_get_char_index     (const GstTagList *     list,
 151                                                  const gchar *          tag,
 152                                                  guint                  index,
 153                                                  gchar *                value);
 154 gboolean        gst_tag_list_get_uchar          (const GstTagList *     list,
 155                                                  const gchar *          tag,
 156                                                  guchar *               value);
 157 gboolean        gst_tag_list_get_uchar_index    (const GstTagList *     list,
 158                                                  const gchar *          tag,
 159                                                  guint                  index,
 160                                                  guchar *               value);
 161 gboolean        gst_tag_list_get_boolean        (const GstTagList *     list,
 162                                                  const gchar *          tag,
 163                                                  gboolean *             value);
 164 gboolean        gst_tag_list_get_boolean_index  (const GstTagList *     list,
 165                                                  const gchar *          tag,
 166                                                  guint                  index,
 167                                                  gboolean *             value);
 168 gboolean        gst_tag_list_get_int            (const GstTagList *     list,
 169                                                  const gchar *          tag,
 170                                                  gint *                 value);
 171 gboolean        gst_tag_list_get_int_index      (const GstTagList *     list,
 172                                                  const gchar *          tag,
 173                                                  guint                  index,
 174                                                  gint *                 value);
 175 gboolean        gst_tag_list_get_uint           (const GstTagList *     list,
 176                                                  const gchar *          tag,
 177                                                  guint *                value);
 178 gboolean        gst_tag_list_get_uint_index     (const GstTagList *     list,
 179                                                  const gchar *          tag,
 180                                                  guint                  index,
 181                                                  guint *                value);
 182 gboolean        gst_tag_list_get_long           (const GstTagList *     list,
 183                                                  const gchar *          tag,
 184                                                  glong *                value);
 185 gboolean        gst_tag_list_get_long_index     (const GstTagList *     list,
 186                                                  const gchar *          tag,
 187                                                  guint                  index,
 188                                                  glong *                value);
 189 gboolean        gst_tag_list_get_ulong          (const GstTagList *     list,
 190                                                  const gchar *          tag,
 191                                                  gulong *               value);
 192 gboolean        gst_tag_list_get_ulong_index    (const GstTagList *     list,
 193                                                  const gchar *          tag,
 194                                                  guint                  index,
 195                                                  gulong *               value);
 196 gboolean        gst_tag_list_get_int64          (const GstTagList *     list,
 197                                                  const gchar *          tag,
 198                                                  gint64 *               value);
 199 gboolean        gst_tag_list_get_int64_index    (const GstTagList *     list,
 200                                                  const gchar *          tag,
 201                                                  guint                  index,
 202                                                  gint64 *               value);
 203 gboolean        gst_tag_list_get_uint64         (const GstTagList *     list,
 204                                                  const gchar *          tag,
 205                                                  guint64 *              value);
 206 gboolean        gst_tag_list_get_uint64_index   (const GstTagList *     list,
 207                                                  const gchar *          tag,
 208                                                  guint                  index,
 209                                                  guint64 *              value);
 210 gboolean        gst_tag_list_get_float          (const GstTagList *     list,
 211                                                  const gchar *          tag,
 212                                                  gfloat *               value);
 213 gboolean        gst_tag_list_get_float_index    (const GstTagList *     list,
 214                                                  const gchar *          tag,
 215                                                  guint                  index,
 216                                                  gfloat *               value);
 217 gboolean        gst_tag_list_get_double         (const GstTagList *     list,
 218                                                  const gchar *          tag,
 219                                                  gdouble *              value);
 220 gboolean        gst_tag_list_get_double_index   (const GstTagList *     list,
 221                                                  const gchar *          tag,
 222                                                  guint                  index,
 223                                                  gdouble *              value);
 224 gboolean        gst_tag_list_get_string         (const GstTagList *     list,
 225                                                  const gchar *          tag,
 226                                                  gchar **               value);
 227 gboolean        gst_tag_list_get_string_index   (const GstTagList *     list,
 228                                                  const gchar *          tag,
 229                                                  guint                  index,
 230                                                  gchar **               value);
 231 gboolean        gst_tag_list_get_pointer        (const GstTagList *     list,
 232                                                  const gchar *          tag,
 233                                                  gpointer *             value);
 234 gboolean        gst_tag_list_get_pointer_index  (const GstTagList *     list,
 235                                                  const gchar *          tag,
 236                                                  guint                  index,
 237                                                  gpointer *             value);
 238 gboolean        gst_tag_list_get_date           (const GstTagList     * list,
 239                                                  const gchar          * tag,
 240                                                  GDate               ** value);
 241 gboolean        gst_tag_list_get_date_index     (const GstTagList     * list,
 242                                                  const gchar          * tag,
 243                                                  guint                  index,
 244                                                  GDate               ** value);
 245
 246 /* GStreamer core tags (need to be discussed) */
 247 /**
 248  * GST_TAG_TITLE:
 249  *
 250  * commonly used title
 251  */
 252 #define GST_TAG_TITLE                   "title"
 253 /**
 254  * GST_TAG_ARTIST:
 255  *
 256  * person(s) responsible for the recording
 257  */
 258 #define GST_TAG_ARTIST                  "artist"
 259 /**
 260  * GST_TAG_ALBUM:
 261  *
 262  * album containing this data
 263  */
 264 #define GST_TAG_ALBUM                   "album"
 265 /**
 266  * GST_TAG_DATE:
 267  *
 268  * date the data was created (#GDate structure)
 269  */
 270 #define GST_TAG_DATE                    "date"
 271 /**
 272  * GST_TAG_GENRE:
 273  *
 274  * genre this data belongs to
 275  */
 276 #define GST_TAG_GENRE                   "genre"
 277 /**
 278  * GST_TAG_COMMENT:
 279  *
 280  * free text commenting the data
 281  */
 282 #define GST_TAG_COMMENT                 "comment"
 283 /**
 284  * GST_TAG_TRACK_NUMBER:
 285  *
 286  * track number inside a collection
 287  */
 288 #define GST_TAG_TRACK_NUMBER            "track-number"
 289 /**
 290  * GST_TAG_TRACK_COUNT:
 291  *
 292  * count of tracks inside collection this track belongs to
 293  */
 294 #define GST_TAG_TRACK_COUNT             "track-count"
 295 /**
 296  * GST_TAG_ALBUM_VOLUME_NUMBER:
 297  *
 298  * disc number inside a collection
 299  */
 300 #define GST_TAG_ALBUM_VOLUME_NUMBER     "album-disc-number"
 301 /**
 302  * GST_TAG_ALBUM_VOLUME_COUNT:
 303  *
 304  * count of discs inside collection this disc belongs to
 305  */
 306 #define GST_TAG_ALBUM_VOLUME_COUNT      "album-disc-count"
 307 /**
 308  * GST_TAG_LOCATION:
 309  *
 310  * original location of file as a URI
 311  */
 312 #define GST_TAG_LOCATION                "location"
 313 /**
 314  * GST_TAG_DESCRIPTION:
 315  *
 316  * short text describing the content of the data
 317  */
 318 #define GST_TAG_DESCRIPTION             "description"
 319 /**
 320  * GST_TAG_VERSION:
 321  *
 322  * version of this data
 323  */
 324 #define GST_TAG_VERSION                 "version"
 325 /**
 326  * GST_TAG_ISRC:
 327  *
 328  * International Standard Recording Code - see http://www.ifpi.org/isrc/
 329  */
 330 #define GST_TAG_ISRC                    "isrc"
 331 /**
 332  * GST_TAG_ORGANIZATION:
 333  *
 334  * organization
 335  */
 336 #define GST_TAG_ORGANIZATION            "organization"
 337 /**
 338  * GST_TAG_COPYRIGHT:
 339  *
 340  * copyright notice of the data
 341  */
 342 #define GST_TAG_COPYRIGHT               "copyright"
 343 /**
 344  * GST_TAG_CONTACT:
 345  *
 346  * contact information
 347  */
 348 #define GST_TAG_CONTACT                 "contact"
 349 /**
 350  * GST_TAG_LICENSE:
 351  *
 352  * license of data
 353  */
 354 #define GST_TAG_LICENSE                 "license"
 355 /**
 356  * GST_TAG_PERFORMER:
 357  *
 358  * person(s) performing
 359  */
 360 #define GST_TAG_PERFORMER               "performer"
 361 /**
 362  * GST_TAG_DURATION:
 363  *
 364  * length in GStreamer time units (nanoseconds)
 365  */
 366 #define GST_TAG_DURATION                "duration"
 367 /**
 368  * GST_TAG_CODEC:
 369  *
 370  * codec the data is stored in
 371  */
 372 #define GST_TAG_CODEC                   "codec"
 373 /**
 374  * GST_TAG_VIDEO_CODEC:
 375  *
 376  * codec the video data is stored in
 377  */
 378 #define GST_TAG_VIDEO_CODEC             "video-codec"
 379 /**
 380  * GST_TAG_AUDIO_CODEC:
 381  *
 382  * codec the audio data is stored in
 383  */
 384 #define GST_TAG_AUDIO_CODEC             "audio-codec"
 385 /**
 386  * GST_TAG_BITRATE:
 387  *
 388  * exact or average bitrate in bits/s
 389  */
 390 #define GST_TAG_BITRATE                 "bitrate"
 391 /**
 392  * GST_TAG_NOMINAL_BITRATE:
 393  *
 394  * nominal bitrate in bits/s
 395  */
 396 #define GST_TAG_NOMINAL_BITRATE         "nominal-bitrate"
 397 /**
 398  * GST_TAG_MINIMUM_BITRATE:
 399  *
 400  * minimum bitrate in bits/s
 401  */
 402 #define GST_TAG_MINIMUM_BITRATE         "minimum-bitrate"
 403 /**
 404  * GST_TAG_MAXIMUM_BITRATE:
 405  *
 406  * maximum bitrate in bits/s
 407  */
 408 #define GST_TAG_MAXIMUM_BITRATE         "maximum-bitrate"
 409 /**
 410  * GST_TAG_SERIAL:
 411  *
 412  * serial number of track
 413  */
 414 #define GST_TAG_SERIAL                  "serial"
 415 /**
 416  * GST_TAG_ENCODER:
 417  *
 418  * encoder used to encode this stream
 419  */
 420 #define GST_TAG_ENCODER                 "encoder"
 421 /**
 422  * GST_TAG_ENCODER_VERSION:
 423  *
 424  * version of the encoder used to encode this stream
 425  */
 426 #define GST_TAG_ENCODER_VERSION         "encoder-version"
 427 /**
 428  * GST_TAG_TRACK_GAIN:
 429  *
 430  * track gain in db
 431  */
 432 #define GST_TAG_TRACK_GAIN              "replaygain-track-gain"
 433 /**
 434  * GST_TAG_TRACK_PEAK:
 435  *
 436  * peak of the track
 437  */
 438 #define GST_TAG_TRACK_PEAK              "replaygain-track-peak"
 439 /**
 440  * GST_TAG_ALBUM_GAIN:
 441  *
 442  * album gain in db
 443  */
 444 #define GST_TAG_ALBUM_GAIN              "replaygain-album-gain"
 445 /**
 446  * GST_TAG_ALBUM_PEAK:
 447  *
 448  * peak of the album
 449  */
 450 #define GST_TAG_ALBUM_PEAK              "replaygain-album-peak"
 451 /**
 452  * GST_TAG_LANGUAGE_CODE:
 453  *
 454  * Language code (ISO-639-1)
 455  */
 456 #define GST_TAG_LANGUAGE_CODE           "language-code"
 457
 458 G_END_DECLS
 459
 460 #endif /* __GST_TAGLIST_H__ */