GstTagList

GstTagList — List of tags and values used to describe media metadata

Synopsis


#include <gst/gst.h>

                    GstTagList;
enum                GstTagMergeMode;
enum                GstTagFlag;
void                (*GstTagForeachFunc)                (const GstTagList *list,
                                                         const gchar *tag,
                                                         gpointer user_data);
void                (*GstTagMergeFunc)                  (GValue *dest,
                                                         const GValue *src);
#define             GST_TAG_TITLE
#define             GST_TAG_TITLE_SORTNAME
#define             GST_TAG_ARTIST
#define             GST_TAG_ARTIST_SORTNAME
#define             GST_TAG_ALBUM
#define             GST_TAG_ALBUM_SORTNAME
#define             GST_TAG_ALBUM_ARTIST
#define             GST_TAG_ALBUM_ARTIST_SORTNAME
#define             GST_TAG_DATE
#define             GST_TAG_GENRE
#define             GST_TAG_COMMENT
#define             GST_TAG_EXTENDED_COMMENT
#define             GST_TAG_TRACK_NUMBER
#define             GST_TAG_TRACK_COUNT
#define             GST_TAG_ALBUM_VOLUME_NUMBER
#define             GST_TAG_ALBUM_VOLUME_COUNT
#define             GST_TAG_LOCATION
#define             GST_TAG_HOMEPAGE
#define             GST_TAG_DESCRIPTION
#define             GST_TAG_VERSION
#define             GST_TAG_ISRC
#define             GST_TAG_ORGANIZATION
#define             GST_TAG_COPYRIGHT
#define             GST_TAG_COPYRIGHT_URI
#define             GST_TAG_COMPOSER
#define             GST_TAG_CONTACT
#define             GST_TAG_LICENSE
#define             GST_TAG_LICENSE_URI
#define             GST_TAG_PERFORMER
#define             GST_TAG_DURATION
#define             GST_TAG_CODEC
#define             GST_TAG_VIDEO_CODEC
#define             GST_TAG_AUDIO_CODEC
#define             GST_TAG_SUBTITLE_CODEC
#define             GST_TAG_CONTAINER_FORMAT
#define             GST_TAG_BITRATE
#define             GST_TAG_NOMINAL_BITRATE
#define             GST_TAG_MINIMUM_BITRATE
#define             GST_TAG_MAXIMUM_BITRATE
#define             GST_TAG_SERIAL
#define             GST_TAG_ENCODER
#define             GST_TAG_ENCODER_VERSION
#define             GST_TAG_TRACK_GAIN
#define             GST_TAG_TRACK_PEAK
#define             GST_TAG_ALBUM_GAIN
#define             GST_TAG_ALBUM_PEAK
#define             GST_TAG_REFERENCE_LEVEL
#define             GST_TAG_LANGUAGE_CODE
#define             GST_TAG_IMAGE
#define             GST_TAG_PREVIEW_IMAGE
#define             GST_TAG_ATTACHMENT
#define             GST_TAG_BEATS_PER_MINUTE
#define             GST_TAG_KEYWORDS
#define             GST_TAG_GEO_LOCATION_NAME
#define             GST_TAG_GEO_LOCATION_LATITUDE
#define             GST_TAG_GEO_LOCATION_LONGITUDE
#define             GST_TAG_GEO_LOCATION_ELEVATION
void                gst_tag_register                    (const gchar *name,
                                                         GstTagFlag flag,
                                                         GType type,
                                                         const gchar *nick,
                                                         const gchar *blurb,
                                                         GstTagMergeFunc func);
void                gst_tag_merge_use_first             (GValue *dest,
                                                         const GValue *src);
void                gst_tag_merge_strings_with_comma    (GValue *dest,
                                                         const GValue *src);
gboolean            gst_tag_exists                      (const gchar *tag);
GType               gst_tag_get_type                    (const gchar *tag);
const gchar*        gst_tag_get_nick                    (const gchar *tag);
const gchar*        gst_tag_get_description             (const gchar *tag);
GstTagFlag          gst_tag_get_flag                    (const gchar *tag);
gboolean            gst_tag_is_fixed                    (const gchar *tag);
GstTagList*         gst_tag_list_new                    (void);
GstTagList*         gst_tag_list_new_full               (const gchar *tag,
                                                         ...);
GstTagList*         gst_tag_list_new_full_valist        (va_list var_args);
gboolean            gst_is_tag_list                     (gconstpointer p);
gboolean            gst_tag_list_is_empty               (const GstTagList *list);
GstTagList*         gst_tag_list_copy                   (const GstTagList *list);
void                gst_tag_list_insert                 (GstTagList *into,
                                                         const GstTagList *from,
                                                         GstTagMergeMode mode);
GstTagList*         gst_tag_list_merge                  (const GstTagList *list1,
                                                         const GstTagList *list2,
                                                         GstTagMergeMode mode);
void                gst_tag_list_free                   (GstTagList *list);
guint               gst_tag_list_get_tag_size           (const GstTagList *list,
                                                         const gchar *tag);
void                gst_tag_list_add                    (GstTagList *list,
                                                         GstTagMergeMode mode,
                                                         const gchar *tag,
                                                         ...);
void                gst_tag_list_add_value              (GstTagList *list,
                                                         GstTagMergeMode mode,
                                                         const gchar *tag,
                                                         const GValue *value);
void                gst_tag_list_add_values             (GstTagList *list,
                                                         GstTagMergeMode mode,
                                                         const gchar *tag,
                                                         ...);
void                gst_tag_list_add_valist             (GstTagList *list,
                                                         GstTagMergeMode mode,
                                                         const gchar *tag,
                                                         va_list var_args);
void                gst_tag_list_add_valist_values      (GstTagList *list,
                                                         GstTagMergeMode mode,
                                                         const gchar *tag,
                                                         va_list var_args);
void                gst_tag_list_remove_tag             (GstTagList *list,
                                                         const gchar *tag);
void                gst_tag_list_foreach                (const GstTagList *list,
                                                         GstTagForeachFunc func,
                                                         gpointer user_data);
const GValue*       gst_tag_list_get_value_index        (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index);
gboolean            gst_tag_list_copy_value             (GValue *dest,
                                                         const GstTagList *list,
                                                         const gchar *tag);
gboolean            gst_tag_list_get_char               (const GstTagList *list,
                                                         const gchar *tag,
                                                         gchar *value);
gboolean            gst_tag_list_get_char_index         (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gchar *value);
gboolean            gst_tag_list_get_uchar              (const GstTagList *list,
                                                         const gchar *tag,
                                                         guchar *value);
gboolean            gst_tag_list_get_uchar_index        (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         guchar *value);
gboolean            gst_tag_list_get_boolean            (const GstTagList *list,
                                                         const gchar *tag,
                                                         gboolean *value);
gboolean            gst_tag_list_get_boolean_index      (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gboolean *value);
gboolean            gst_tag_list_get_int                (const GstTagList *list,
                                                         const gchar *tag,
                                                         gint *value);
gboolean            gst_tag_list_get_int_index          (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gint *value);
gboolean            gst_tag_list_get_uint               (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint *value);
gboolean            gst_tag_list_get_uint_index         (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         guint *value);
gboolean            gst_tag_list_get_long               (const GstTagList *list,
                                                         const gchar *tag,
                                                         glong *value);
gboolean            gst_tag_list_get_long_index         (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         glong *value);
gboolean            gst_tag_list_get_ulong              (const GstTagList *list,
                                                         const gchar *tag,
                                                         gulong *value);
gboolean            gst_tag_list_get_ulong_index        (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gulong *value);
gboolean            gst_tag_list_get_int64              (const GstTagList *list,
                                                         const gchar *tag,
                                                         gint64 *value);
gboolean            gst_tag_list_get_int64_index        (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gint64 *value);
gboolean            gst_tag_list_get_uint64             (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint64 *value);
gboolean            gst_tag_list_get_uint64_index       (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         guint64 *value);
gboolean            gst_tag_list_get_float              (const GstTagList *list,
                                                         const gchar *tag,
                                                         gfloat *value);
gboolean            gst_tag_list_get_float_index        (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gfloat *value);
gboolean            gst_tag_list_get_double             (const GstTagList *list,
                                                         const gchar *tag,
                                                         gdouble *value);
gboolean            gst_tag_list_get_double_index       (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gdouble *value);
gboolean            gst_tag_list_get_string             (const GstTagList *list,
                                                         const gchar *tag,
                                                         gchar **value);
gboolean            gst_tag_list_get_string_index       (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gchar **value);
gboolean            gst_tag_list_get_pointer            (const GstTagList *list,
                                                         const gchar *tag,
                                                         gpointer *value);
gboolean            gst_tag_list_get_pointer_index      (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         gpointer *value);
gboolean            gst_tag_list_get_date               (const GstTagList *list,
                                                         const gchar *tag,
                                                         GDate **value);
gboolean            gst_tag_list_get_date_index         (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         GDate **value);
gboolean            gst_tag_list_get_buffer             (const GstTagList *list,
                                                         const gchar *tag,
                                                         GstBuffer **value);
gboolean            gst_tag_list_get_buffer_index       (const GstTagList *list,
                                                         const gchar *tag,
                                                         guint index,
                                                         GstBuffer **value);

Description

List of tags and values used to describe media metadata.

Strings must be in ASCII or UTF-8 encoding. No other encodings are allowed.

Last reviewed on 2009-06-09 (0.10.23)

Details

GstTagList

typedef struct _GstTagList GstTagList;

Opaque GstTagList data structure.


enum GstTagMergeMode

typedef enum {
  GST_TAG_MERGE_UNDEFINED,
  GST_TAG_MERGE_REPLACE_ALL,
  GST_TAG_MERGE_REPLACE,
  GST_TAG_MERGE_APPEND,
  GST_TAG_MERGE_PREPEND,
  GST_TAG_MERGE_KEEP,
  GST_TAG_MERGE_KEEP_ALL,
  /* add more */
  GST_TAG_MERGE_COUNT
} GstTagMergeMode;

The different tag merging modes are basically replace, overwrite and append, but they can be seen from two directions. Given two taglists: (A) the tags already in the element and (B) the ones that are supplied to the element ( e.g. via gst_tag_setter_merge_tags() / gst_tag_setter_add_tags() or a GST_EVENT_TAG), how are these tags merged? In the table below this is shown for the cases that a tag exists in the list (A) or does not exists (!A) and combinations thereof.

Table 1. merge mode

merge mode A + B A + !B !A + B !A + !B
REPLACE_ALL B - B -
REPLACE B A B -
APPEND A, B A B -
PREPEND B, A A B -
KEEP A A B -
KEEP_ALL A A - -


GST_TAG_MERGE_UNDEFINED undefined merge mode
GST_TAG_MERGE_REPLACE_ALL replace all tags (clear list and append)
GST_TAG_MERGE_REPLACE replace tags
GST_TAG_MERGE_APPEND append tags
GST_TAG_MERGE_PREPEND prepend tags
GST_TAG_MERGE_KEEP keep existing tags
GST_TAG_MERGE_KEEP_ALL keep all existing tags
GST_TAG_MERGE_COUNT the number of merge modes

enum GstTagFlag

typedef enum {
  GST_TAG_FLAG_UNDEFINED,
  GST_TAG_FLAG_META,
  GST_TAG_FLAG_ENCODED,
  GST_TAG_FLAG_DECODED,
  GST_TAG_FLAG_COUNT
} GstTagFlag;

Extra tag flags used when registering tags.

GST_TAG_FLAG_UNDEFINED undefined flag
GST_TAG_FLAG_META tag is meta data
GST_TAG_FLAG_ENCODED tag is encoded
GST_TAG_FLAG_DECODED tag is decoded
GST_TAG_FLAG_COUNT number of tag flags

GstTagForeachFunc ()

void                (*GstTagForeachFunc)                (const GstTagList *list,
                                                         const gchar *tag,
                                                         gpointer user_data);

A function that will be called in gst_tag_list_foreach(). The function may not modify the tag list.

list : the GstTagList
tag : a name of a tag in list
user_data : user data

GstTagMergeFunc ()

void                (*GstTagMergeFunc)                  (GValue *dest,
                                                         const GValue *src);

A function for merging multiple values of a tag used when registering tags.

dest : the destination GValue
src : the source GValue

GST_TAG_TITLE

#define GST_TAG_TITLE                  "title"

commonly used title (string)

The title as it should be displayed, e.g. 'The Doll House'


GST_TAG_TITLE_SORTNAME

#define GST_TAG_TITLE_SORTNAME         "title-sortname"

commonly used title, as used for sorting (string)

The title as it should be sorted, e.g. 'Doll House, The'

Since 0.10.15


GST_TAG_ARTIST

#define GST_TAG_ARTIST                 "artist"

person(s) responsible for the recording (string)

The artist name as it should be displayed, e.g. 'Jimi Hendrix' or 'The Guitar Heroes'


GST_TAG_ARTIST_SORTNAME

#define GST_TAG_ARTIST_SORTNAME        "musicbrainz-sortname"

person(s) responsible for the recording, as used for sorting (string)

The artist name as it should be sorted, e.g. 'Hendrix, Jimi' or 'Guitar Heroes, The'

Since 0.10.15


GST_TAG_ALBUM

#define GST_TAG_ALBUM                  "album"

album containing this data (string)

The album name as it should be displayed, e.g. 'The Jazz Guitar'


GST_TAG_ALBUM_SORTNAME

#define GST_TAG_ALBUM_SORTNAME         "album-sortname"

album containing this data, as used for sorting (string)

The album name as it should be sorted, e.g. 'Jazz Guitar, The'

Since 0.10.15


GST_TAG_ALBUM_ARTIST

#define GST_TAG_ALBUM_ARTIST           "album-artist"

The artist of the entire album, as it should be displayed.

Since 0.10.25


GST_TAG_ALBUM_ARTIST_SORTNAME

#define GST_TAG_ALBUM_ARTIST_SORTNAME  "album-artist-sortname"

The artist of the entire album, as it should be sorted.

Since 0.10.25


GST_TAG_DATE

#define GST_TAG_DATE                   "date"

date the data was created (GDate structure)


GST_TAG_GENRE

#define GST_TAG_GENRE                  "genre"

genre this data belongs to (string)


GST_TAG_COMMENT

#define GST_TAG_COMMENT                "comment"

free text commenting the data (string)


GST_TAG_EXTENDED_COMMENT

#define GST_TAG_EXTENDED_COMMENT       "extended-comment"

key/value text commenting the data (string)

Must be in the form of 'key=comment' or 'key[lc]=comment' where 'lc' is an ISO-639 language code.

This tag is used for unknown Vorbis comment tags, unknown APE tags and certain ID3v2 comment fields.

Since 0.10.10


GST_TAG_TRACK_NUMBER

#define GST_TAG_TRACK_NUMBER           "track-number"

track number inside a collection (unsigned integer)


GST_TAG_TRACK_COUNT

#define GST_TAG_TRACK_COUNT            "track-count"

count of tracks inside collection this track belongs to (unsigned integer)


GST_TAG_ALBUM_VOLUME_NUMBER

#define GST_TAG_ALBUM_VOLUME_NUMBER    "album-disc-number"

disc number inside a collection (unsigned integer)


GST_TAG_ALBUM_VOLUME_COUNT

#define GST_TAG_ALBUM_VOLUME_COUNT    "album-disc-count"

count of discs inside collection this disc belongs to (unsigned integer)


GST_TAG_LOCATION

#define GST_TAG_LOCATION               "location"

Origin of media as a URI (location, where the original of the file or stream is hosted) (string)


GST_TAG_HOMEPAGE

#define GST_TAG_HOMEPAGE               "homepage"

Homepage for this media (i.e. artist or movie homepage) (string)

Since 0.10.23


GST_TAG_DESCRIPTION

#define GST_TAG_DESCRIPTION            "description"

short text describing the content of the data (string)


GST_TAG_VERSION

#define GST_TAG_VERSION                "version"

version of this data (string)


GST_TAG_ISRC

#define GST_TAG_ISRC                   "isrc"

International Standard Recording Code - see http://www.ifpi.org/isrc/ (string)


GST_TAG_ORGANIZATION

#define GST_TAG_ORGANIZATION           "organization"

organization (string)


GST_TAG_COPYRIGHT

#define GST_TAG_COPYRIGHT              "copyright"

copyright notice of the data (string)


GST_TAG_COPYRIGHT_URI

#define GST_TAG_COPYRIGHT_URI          "copyright-uri"

URI to location where copyright details can be found (string)

Since 0.10.14


GST_TAG_COMPOSER

#define GST_TAG_COMPOSER               "composer"

person(s) who composed the recording (string)

Since 0.10.15


GST_TAG_CONTACT

#define GST_TAG_CONTACT                "contact"

contact information (string)


GST_TAG_LICENSE

#define GST_TAG_LICENSE                "license"

license of data (string)


GST_TAG_LICENSE_URI

#define GST_TAG_LICENSE_URI            "license-uri"

URI to location where license details can be found (string)

Since 0.10.14


GST_TAG_PERFORMER

#define GST_TAG_PERFORMER              "performer"

person(s) performing (string)


GST_TAG_DURATION

#define GST_TAG_DURATION               "duration"

length in GStreamer time units (nanoseconds) (unsigned 64-bit integer)


GST_TAG_CODEC

#define GST_TAG_CODEC                  "codec"

codec the