GstTagList

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

## Synopsis

    #include <gst/gst.h>

    typedef             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_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_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_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);
    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_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);

## Description

List of tags and values used to describe media metadata.

Last reviewed on 2005-11-23 (0.9.5)

## Details

### GstTagList

    typedef GstStructure 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 `gst_tag_setter_merge_tags()` or `gst_tag_setter_add_tags()`, 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_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_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 data is stored in (string)

### GST_TAG_VIDEO_CODEC

    #define GST_TAG_VIDEO_CODEC            "video-codec"

codec the video data is stored in (string)

### GST_TAG_AUDIO_CODEC

    #define GST_TAG_AUDIO_CODEC            "audio-codec"

codec the audio data is stored in (string)

### GST_TAG_BITRATE

    #define GST_TAG_BITRATE                "bitrate"

exact or average bitrate in bits/s (unsigned integer)

### GST_TAG_NOMINAL_BITRATE

    #define GST_TAG_NOMINAL_BITRATE        "nominal-bitrate"

nominal bitrate in bits/s (unsigned integer)

### GST_TAG_MINIMUM_BITRATE

    #define GST_TAG_MINIMUM_BITRATE        "minimum-bitrate"

minimum bitrate in bits/s (unsigned integer)

### GST_TAG_MAXIMUM_BITRATE

    #define GST_TAG_MAXIMUM_BITRATE        "maximum-bitrate"

maximum bitrate in bits/s (unsigned integer)

### GST_TAG_SERIAL

    #define GST_TAG_SERIAL                 "serial"

serial number of track (unsigned integer)

### GST_TAG_ENCODER

    #define GST_TAG_ENCODER                "encoder"

encoder used to encode this stream (string)

### GST_TAG_ENCODER_VERSION

    #define GST_TAG_ENCODER_VERSION        "encoder-version"

version of the encoder used to encode this stream (unsigned integer)

### GST_TAG_TRACK_GAIN

    #define GST_TAG_TRACK_GAIN             "replaygain-track-gain"

track gain in db (double)

### GST_TAG_TRACK_PEAK

    #define GST_TAG_TRACK_PEAK             "replaygain-track-peak"

peak of the track (double)

### GST_TAG_ALBUM_GAIN

    #define GST_TAG_ALBUM_GAIN             "replaygain-album-gain"

album gain in db (double)

### GST_TAG_ALBUM_PEAK

    #define GST_TAG_ALBUM_PEAK             "replaygain-album-peak"

peak of the album (double)

### GST_TAG_REFERENCE_LEVEL

    #define GST_TAG_REFERENCE_LEVEL        "replaygain-reference-level"

reference level of track and album gain values (double)

Since 0.10.12

### GST_TAG_LANGUAGE_CODE

    #define GST_TAG_LANGUAGE_CODE          "language-code"

Language code (ISO-639-1) (string) of the content

### GST_TAG_IMAGE

    #define GST_TAG_IMAGE                  "image"

image (buffer) (buffer caps should specify the content type and preferably also set "image-type" field as GstTagImageType)

Since 0.10.6

### GST_TAG_PREVIEW_IMAGE

    #define GST_TAG_PREVIEW_IMAGE          "preview-image"

image that is meant for preview purposes, e.g. small icon-sized version (buffer) (buffer caps should specify the content type)

Since 0.10.7

### GST_TAG_ATTACHMENT

    #define GST_TAG_ATTACHMENT             "attachment"

generic file attachment (buffer) (buffer caps should specify the content type and if possible set "filename" to the file name of the attachment)

Since 0.10.21

### GST_TAG_BEATS_PER_MINUTE

    #define GST_TAG_BEATS_PER_MINUTE       "beats-per-minute"

number of beats per minute in audio (double)

Since 0.10.12

### GST_TAG_KEYWORDS

    #define GST_TAG_KEYWORDS               "keywords"

comma separated keywords describing the content (string).

Since 0.10.21

### GST_TAG_GEO_LOCATION_NAME

    #define GST_TAG_GEO_LOCATION_NAME               "geo-location-name"

human readable descriptive location of where the media has been recorded or produced. (string).

Since 0.10.21

### GST_TAG_GEO_LOCATION_LATITUDE

    #define GST_TAG_GEO_LOCATION_LATITUDE               "geo-location-latitude"

geo latitude location of where the media has been recorded or produced in degrees according to WGS84 (zero at the equator, negative values for southern latitudes) (double).

Since 0.10.21

### GST_TAG_GEO_LOCATION_LONGITUDE

    #define GST_TAG_GEO_LOCATION_LONGITUDE               "geo-location-longitude"

geo longitude location of where the media has been recorded or produced in degrees according to WGS84 (zero at the prime meridian in Greenwich/UK, negative values for western longitudes). (double).

Since 0.10.21

### GST_TAG_GEO_LOCATION_ELEVATION

    #define GST_TAG_GEO_LOCATION_ELEVATION               "geo-location-elevation"

geo elevation of where the media has been recorded or produced in meters according to WGS84 (zero is average sea level) (double).

Since 0.10.21

### gst_tag_register ()

    void                gst_tag_register                    (const gchar *name,
                                                             GstTagFlag flag,
                                                             GType type,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GstTagMergeFunc func);

Registers a new tag type for the use with GStreamer's type system. If a type with that name is already registered, that one is used. The old registration may have used a different type however. So don't rely on your supplied values.

Important: if you do not supply a merge function the implication will be that there can only be one single value for this tag in a tag list and any additional values will silenty be discarded when being added (unless GST_TAG_MERGE_REPLACE, GST_TAG_MERGE_REPLACE_ALL, or GST_TAG_MERGE_PREPEND is used as merge mode, in which case the new value will replace the old one in the list).

The merge function will be called from `gst_tag_list_copy_value()` when it is required that one or more values for a tag be condensed into one single value. This may happen from `gst_tag_list_get_string()`, `gst_tag_list_get_int()`, `gst_tag_list_get_double()` etc. What will happen exactly in that case depends on how the tag was registered and if a merge function was supplied and if so which one.

Two default merge functions are provided: `gst_tag_merge_use_first()` and `gst_tag_merge_strings_with_commas()`.

`name` : | the name or identifier string
`flag` : | a flag describing the type of tag info
`type` : | the type this data is in
`nick` : | human-readable name
`blurb` : | a human-readable description about this tag
`func` : | function for merging multiple values of this tag, or NULL

### gst_tag_merge_use_first ()

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

This is a convenience function for the func argument of `gst_tag_register()`. It creates a copy of the first value from the list.

`dest` : | uninitialized GValue to store result in
`src` : | GValue to copy from

### gst_tag_merge_strings_with_comma ()

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

This is a convenience function for the func argument of `gst_tag_register()`. It concatenates all given strings using a comma. The tag must be registered as a G_TYPE_STRING or this function will fail.

`dest` : | uninitialized GValue to store result in
`src` : | GValue to copy from

### gst_tag_exists ()

    gboolean            gst_tag_exists                      (const gchar *tag);

Checks if the given type is already registered.

`tag` : | name of the tag
Returns : | TRUE if the type is already registered

### gst_tag_get_type ()

    GType               gst_tag_get_type                    (const gchar *tag);

Gets the GType used for this tag.

`tag` : | the tag
Returns : | the GType of this tag

### gst_tag_get_nick ()

    const gchar*        gst_tag_get_nick                    (const gchar *tag);

Returns the human-readable name of this tag, You must not change or free this string.

`tag` : | the tag
Returns : | the human-readable name of this tag

### gst_tag_get_description ()

    const gchar*        gst_tag_get_description             (const gchar *tag);

Returns the human-readable description of this tag, You must not change or free this string.

`tag` : | the tag
Returns : | the human-readable description of this tag

### gst_tag_get_flag ()

    GstTagFlag          gst_tag_get_flag                    (const gchar *tag);

Gets the flag of `tag`.

`tag` : | the tag
Returns : | the flag of this tag.

### gst_tag_is_fixed ()

    gboolean            gst_tag_is_fixed                    (const gchar *tag);

Checks if the given tag is fixed. A fixed tag can only contain one value. Unfixed tags can contain lists of values.

`tag` : | tag to check
Returns : | TRUE, if the given tag is fixed.

### gst_tag_list_new ()

    GstTagList*         gst_tag_list_new                    (void);

Creates a new empty GstTagList.

Returns : | An empty tag list

### gst_is_tag_list ()

    gboolean            gst_is_tag_list                     (gconstpointer p);

Checks if the given pointer is a taglist.

`p` : | Object that might be a taglist
Returns : | TRUE, if the given pointer is a taglist

### gst_tag_list_is_empty ()

    gboolean            gst_tag_list_is_empty               (const GstTagList *list);

Checks if the given taglist is empty.

`list` : | A GstTagList.
Returns : | TRUE if the taglist is empty, otherwise FALSE.

Since 0.10.11

### gst_tag_list_copy ()

    GstTagList*         gst_tag_list_copy                   (const GstTagList *list);

Copies a given GstTagList.

`list` : | list to copy
Returns : | copy of the given list

### gst_tag_list_insert ()

    void                gst_tag_list_insert                 (GstTagList *into,
                                                             const GstTagList *from,
                                                             GstTagMergeMode mode);

Inserts the tags of the second list into the first list using the given mode.

`into` : | list to merge into
`from` : | list to merge from
`mode` : | the mode to use

### gst_tag_list_merge ()

    GstTagList*         gst_tag_list_merge                  (const GstTagList *list1,
                                                             const GstTagList *list2,
                                                             GstTagMergeMode mode);

Merges the two given lists into a new list. If one of the lists is NULL, a copy of the other is returned. If both lists are NULL, NULL is returned.

`list1` : | first list to merge
`list2` : | second list to merge
`mode` : | the mode to use
Returns : | the new list

### gst_tag_list_free ()

    void                gst_tag_list_free                   (GstTagList *list);

Frees the given list and all associated values.

`list` : | the list to free

### gst_tag_list_get_tag_size ()

    guint               gst_tag_list_get_tag_size           (const GstTagList *list,
                                                             const gchar *tag);

Checks how many value are stored in this tag list for the given tag.

`list` : | a taglist
`tag` : | the tag to query
Returns : | The number of tags stored

### gst_tag_list_add ()

    void                gst_tag_list_add                    (GstTagList *list,
                                                             GstTagMergeMode mode,
                                                             const gchar *tag,
                                                             ...);

Sets the values for the given tags using the specified mode.

`list` : | list to set tags in
`mode` : | the mode to use
`tag` : | tag
`...` : | NULL-terminated list of values to set

### gst_tag_list_add_values ()

    void                gst_tag_list_add_values             (GstTagList *list,
                                                             GstTagMergeMode mode,
                                                             const gchar *tag,
                                                             ...);

Sets the GValues for the given tags using the specified mode.

`list` : | list to set tags in
`mode` : | the mode to use
`tag` : | tag
`...` : | GValues to set

### gst_tag_list_add_valist ()

    void                gst_tag_list_add_valist             (GstTagList *list,
                                                             GstTagMergeMode mode,
                                                             const gchar *tag,
                                                             va_list var_args);

Sets the values for the given tags using the specified mode.

`list` : | list to set tags in
`mode` : | the mode to use
`tag` : | tag
`var_args` : | tag / value pairs to set

### gst_tag_list_add_valist_values ()

    void                gst_tag_list_add_valist_values      (GstTagList *list,
                                                             GstTagMergeMode mode,
                                                             const gchar *tag,
                                                             va_list var_args);

Sets the GValues for the given tags using the specified mode.

`list` : | list to set tags in
`mode` : | the mode to use
`tag` : | tag
`var_args` : | tag / GValue pairs to set

### gst_tag_list_remove_tag ()

    void                gst_tag_list_remove_tag             (GstTagList *list,
                                                             const gchar *tag);

Removes the given tag from the taglist.

`list` : | list to remove tag from
`tag` : | tag to remove

### gst_tag_list_foreach ()

    void                gst_tag_list_foreach                (const GstTagList *list,
                                                             GstTagForeachFunc func,
                                                             gpointer user_data);

Calls the given function for each tag inside the tag list. Note that if there is no tag, the function won't be called at all.

`list` : | list to iterate over
`func` : | function to be called for each tag
`user_data` : | user specified data

### gst_tag_list_get_value_index ()

    const GValue*       gst_tag_list_get_value_index        (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList
`tag` : | tag to read out
`index` : | number of entry to read out
Returns : | The GValue for the specified entry or NULL if the tag wasn't available or the tag doesn't have as many entries

### gst_tag_list_copy_value ()

    gboolean            gst_tag_list_copy_value             (GValue *dest,
                                                             const GstTagList *list,
                                                             const gchar *tag);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag. You must `g_value_unset()` the value after use.

`dest` : | uninitialized GValue to copy into
`list` : | list to get the tag from
`tag` : | tag to read out
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_char ()

    gboolean            gst_tag_list_get_char               (const GstTagList *list,
                                                             const gchar *tag,
                                                             gchar *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_char_index ()

    gboolean            gst_tag_list_get_char_index         (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gchar *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uchar ()

    gboolean            gst_tag_list_get_uchar              (const GstTagList *list,
                                                             const gchar *tag,
                                                             guchar *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uchar_index ()

    gboolean            gst_tag_list_get_uchar_index        (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             guchar *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_boolean ()

    gboolean            gst_tag_list_get_boolean            (const GstTagList *list,
                                                             const gchar *tag,
                                                             gboolean *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_boolean_index ()

    gboolean            gst_tag_list_get_boolean_index      (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gboolean *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_int ()

    gboolean            gst_tag_list_get_int                (const GstTagList *list,
                                                             const gchar *tag,
                                                             gint *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_int_index ()

    gboolean            gst_tag_list_get_int_index          (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gint *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uint ()

    gboolean            gst_tag_list_get_uint               (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uint_index ()

    gboolean            gst_tag_list_get_uint_index         (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             guint *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_long ()

    gboolean            gst_tag_list_get_long               (const GstTagList *list,
                                                             const gchar *tag,
                                                             glong *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_long_index ()

    gboolean            gst_tag_list_get_long_index         (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             glong *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_ulong ()

    gboolean            gst_tag_list_get_ulong              (const GstTagList *list,
                                                             const gchar *tag,
                                                             gulong *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_ulong_index ()

    gboolean            gst_tag_list_get_ulong_index        (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gulong *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_int64 ()

    gboolean            gst_tag_list_get_int64              (const GstTagList *list,
                                                             const gchar *tag,
                                                             gint64 *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_int64_index ()

    gboolean            gst_tag_list_get_int64_index        (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gint64 *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uint64 ()

    gboolean            gst_tag_list_get_uint64             (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint64 *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_uint64_index ()

    gboolean            gst_tag_list_get_uint64_index       (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             guint64 *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_float ()

    gboolean            gst_tag_list_get_float              (const GstTagList *list,
                                                             const gchar *tag,
                                                             gfloat *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_float_index ()

    gboolean            gst_tag_list_get_float_index        (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gfloat *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_double ()

    gboolean            gst_tag_list_get_double             (const GstTagList *list,
                                                             const gchar *tag,
                                                             gdouble *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_double_index ()

    gboolean            gst_tag_list_get_double_index       (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gdouble *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_string ()

    gboolean            gst_tag_list_get_string             (const GstTagList *list,
                                                             const gchar *tag,
                                                             gchar **value);

Copies the contents for the given tag into the value, possibly merging multiple values into one if multiple values are associated with the tag.

Use gst_tag_list_get_string_index (list, tag, 0, value) if you want to retrieve the first string associated with this tag unmodified.

The resulting string in `value` will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_string_index ()

    gboolean            gst_tag_list_get_string_index       (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gchar **value);

Gets the value that is at the given index for the given tag in the given list.

The resulting string in `value` will be in UTF-8 encoding and should be freed by the caller using g_free when no longer needed.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_pointer ()

    gboolean            gst_tag_list_get_pointer            (const GstTagList *list,
                                                             const gchar *tag,
                                                             gpointer *value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_pointer_index ()

    gboolean            gst_tag_list_get_pointer_index      (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             gpointer *value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list.

### gst_tag_list_get_date ()

    gboolean            gst_tag_list_get_date               (const GstTagList *list,
                                                             const gchar *tag,
                                                             GDate **value);

Copies the contents for the given tag into the value, merging multiple values into one if multiple values are associated with the tag.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list or if it was NULL.

### gst_tag_list_get_date_index ()

    gboolean            gst_tag_list_get_date_index         (const GstTagList *list,
                                                             const gchar *tag,
                                                             guint index,
                                                             GDate **value);

Gets the value that is at the given index for the given tag in the given list.

`list` : | a GstTagList to get the tag from
`tag` : | tag to read out
`index` : | number of entry to read out
`value` : | location for the result
Returns : | TRUE, if a value was copied, FALSE if the tag didn't exist in the given list or if it was NULL.