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