## gsttag

gsttag — additional tag definitions for plugins and applications

## Synopsis

    #include <gst/tag/tag.h>

    #define             GST_TAG_MUSICBRAINZ_TRACKID
    #define             GST_TAG_MUSICBRAINZ_ARTISTID
    #define             GST_TAG_MUSICBRAINZ_ALBUMID
    #define             GST_TAG_MUSICBRAINZ_ALBUMARTISTID
    #define             GST_TAG_MUSICBRAINZ_TRMID
    #define             GST_TAG_MUSICBRAINZ_SORTNAME
    #define             GST_TAG_CDDA_CDDB_DISCID
    #define             GST_TAG_CDDA_CDDB_DISCID_FULL
    #define             GST_TAG_CDDA_MUSICBRAINZ_DISCID
    #define             GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL
    #define             GST_TAG_CDDA_TRACK_TAGS
    #define             GST_TAG_CMML_CLIP
    #define             GST_TAG_CMML_HEAD
    #define             GST_TAG_CMML_STREAM
    void                gst_tag_register_musicbrainz_tags   (void);
    gchar *             gst_tag_freeform_string_to_utf8     (const gchar *data,
                                                             gint size,
                                                             const gchar **env_vars);
    gboolean            gst_tag_parse_extended_comment      (const gchar *ext_comment,
                                                             gchar **key,
                                                             gchar **lang,
                                                             gchar **value,
                                                             gboolean fail_if_no_key);
    GstBuffer *         gst_tag_image_data_to_image_buffer  (const guint8 *image_data,
                                                             guint image_data_len,
                                                             GstTagImageType image_type);
    enum                GstTagImageType;

## Description

Contains additional standardized GStreamer tag definitions for plugins and applications, and functions to register them with the GStreamer tag system.

## Details

### GST_TAG_MUSICBRAINZ_TRACKID

    #define GST_TAG_MUSICBRAINZ_TRACKID "musicbrainz-trackid"

MusicBrainz track ID

### GST_TAG_MUSICBRAINZ_ARTISTID

    #define GST_TAG_MUSICBRAINZ_ARTISTID "musicbrainz-artistid"

MusicBrainz artist ID

### GST_TAG_MUSICBRAINZ_ALBUMID

    #define GST_TAG_MUSICBRAINZ_ALBUMID "musicbrainz-albumid"

MusicBrainz album ID

### GST_TAG_MUSICBRAINZ_ALBUMARTISTID

    #define GST_TAG_MUSICBRAINZ_ALBUMARTISTID "musicbrainz-albumartistid"

MusicBrainz album artist ID

### GST_TAG_MUSICBRAINZ_TRMID

    #define GST_TAG_MUSICBRAINZ_TRMID "musicbrainz-trmid"

MusicBrainz track TRM ID

### GST_TAG_MUSICBRAINZ_SORTNAME

    #define GST_TAG_MUSICBRAINZ_SORTNAME GST_TAG_ARTIST_SORTNAME

### Warning

`GST_TAG_MUSICBRAINZ_SORTNAME` is deprecated and should not be used in newly-written code.

MusicBrainz artist sort name

Deprecated. Use GST_TAG_ARTIST_SORTNAME instead.

### GST_TAG_CDDA_CDDB_DISCID

    #define GST_TAG_CDDA_CDDB_DISCID              "discid"

CDDB disc id in its short form (e.g. 'aa063d0f')

### GST_TAG_CDDA_CDDB_DISCID_FULL

    #define GST_TAG_CDDA_CDDB_DISCID_FULL         "discid-full"

CDDB disc id including all details

### GST_TAG_CDDA_MUSICBRAINZ_DISCID

    #define GST_TAG_CDDA_MUSICBRAINZ_DISCID       "musicbrainz-discid"

Musicbrainz disc id (e.g. 'ahg7JUcfR3vCYBphSDIogOOWrr0-')

### GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL

    #define GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL  "musicbrainz-discid-full"

Musicbrainz disc id details

### GST_TAG_CDDA_TRACK_TAGS

    #define GST_TAG_CDDA_TRACK_TAGS               "track-tags"

### GST_TAG_CMML_CLIP

    #define GST_TAG_CMML_CLIP "cmml-clip"

Annodex CMML clip element tag

### GST_TAG_CMML_HEAD

    #define GST_TAG_CMML_HEAD "cmml-head"

Annodex CMML head element tag

### GST_TAG_CMML_STREAM

    #define GST_TAG_CMML_STREAM "cmml-stream"

Annodex CMML stream element tag

### gst_tag_register_musicbrainz_tags ()

    void                gst_tag_register_musicbrainz_tags   (void);

Registers additional musicbrainz-specific tags with the GStreamer tag system. Plugins and applications that use these tags should call this function before using them. Can be called multiple times.

### gst_tag_freeform_string_to_utf8 ()

    gchar *             gst_tag_freeform_string_to_utf8     (const gchar *data,
                                                             gint size,
                                                             const gchar **env_vars);

Convenience function to read a string with unknown character encoding. If the string is already in UTF-8 encoding, it will be returned right away. If not it tries to detect byte-order-mark for UTF-16/32 cases and use that. Otherwise, the environment will be searched for a number of environment variables (whose names are specified in the NULL-terminated string array `env_vars`) containing a list of character encodings to try/use. If none are specified, the current locale will be tried. If that also doesn't work, ISO-8859-1 is assumed (which will almost always succeed).

`data` : | string data
`size` : | length of string data, or -1 if the string is NUL-terminated
`env_vars` : | a NULL-terminated string array of environment variable names, or NULL
Returns : | a newly-allocated string in UTF-8 encoding, or NULL

Since 0.10.13

### gst_tag_parse_extended_comment ()

    gboolean            gst_tag_parse_extended_comment      (const gchar *ext_comment,
                                                             gchar **key,
                                                             gchar **lang,
                                                             gchar **value,
                                                             gboolean fail_if_no_key);

Convenience function to parse a GST_TAG_EXTENDED_COMMENT string and separate it into its components.

If successful, `key`, `lang` and/or `value` will be set to newly allocated strings that you need to free with `g_free()` when done. `key` and `lang` may also be set to NULL by this function if there is no key or no language code in the extended comment string.

`ext_comment` : | an extended comment string, see GST_TAG_EXTENDED_COMMENT
`key` : | return location for the comment description key, or NULL
`lang` : | return location for the comment ISO-639 language code, or NULL
`value` : | return location for the actual comment string, or NULL
`fail_if_no_key` : | whether to fail if strings are not in key=value form
Returns : | TRUE if the string could be parsed, otherwise FALSE

Since 0.10.10

### gst_tag_image_data_to_image_buffer ()

    GstBuffer *         gst_tag_image_data_to_image_buffer  (const guint8 *image_data,
                                                             guint image_data_len,
                                                             GstTagImageType image_type);

Helper function for tag-reading plugins to create a GstBuffer suitable to add to a GstTagList as an image tag (such as GST_TAG_IMAGE or GST_TAG_PREVIEW_IMAGE) from the encoded image data and an (optional) image type.

Background: cover art and other images in tags are usually stored as a blob of binary image data, often accompanied by a MIME type or some other content type string (e.g. 'png', 'jpeg', 'jpg'). Sometimes there is also an 'image type' to indicate what kind of image this is (e.g. front cover, back cover, artist, etc.). The image data may also be an URI to the image rather than the image itself.

In GStreamer, image tags are GstBuffers containing the raw image data, with the buffer caps describing the content type of the image (e.g. image/jpeg, image/png, text/uri-list). The buffer caps may contain an additional 'image-type' field of GST_TYPE_TAG_IMAGE_TYPE to describe the type of image (front cover, back cover etc.). GST_TAG_PREVIEW_IMAGE tags should not carry an image type, their type is already indicated via the special tag name.

This function will do various checks and typefind the encoded image data (we can't trust the declared mime type).

`image_data` : | the (encoded) image
`image_data_len` : | the length of the encoded image data at `image_data`
`image_type` : | type of the image, or GST_TAG_IMAGE_TYPE_UNDEFINED. Pass GST_TAG_IMAGE_TYPE_NONE if no image type should be set at all (e.g. for preview images)
Returns : | a newly-allocated image buffer for use in tag lists, or NULL

Since 0.10.20

### enum GstTagImageType

    typedef enum {
      GST_TAG_IMAGE_TYPE_NONE = -1,
      GST_TAG_IMAGE_TYPE_UNDEFINED = 0,
      GST_TAG_IMAGE_TYPE_FRONT_COVER,
      GST_TAG_IMAGE_TYPE_BACK_COVER,
      GST_TAG_IMAGE_TYPE_LEAFLET_PAGE,
      GST_TAG_IMAGE_TYPE_MEDIUM,
      GST_TAG_IMAGE_TYPE_LEAD_ARTIST,
      GST_TAG_IMAGE_TYPE_ARTIST,
      GST_TAG_IMAGE_TYPE_CONDUCTOR,
      GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA,
      GST_TAG_IMAGE_TYPE_COMPOSER,
      GST_TAG_IMAGE_TYPE_LYRICIST,
      GST_TAG_IMAGE_TYPE_RECORDING_LOCATION,
      GST_TAG_IMAGE_TYPE_DURING_RECORDING,
      GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE,
      GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE,
      GST_TAG_IMAGE_TYPE_FISH,
      GST_TAG_IMAGE_TYPE_ILLUSTRATION,
      GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO,
      GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO
    } GstTagImageType;

Type of image contained in an image tag (specified as field in the image buffer's caps structure)

`GST_TAG_IMAGE_TYPE_NONE` | No image type. Can be used to tell functions such as `gst_tag_image_data_to_image_buffer()` that no image type should be set. (Since: 0.10.20)
`GST_TAG_IMAGE_TYPE_UNDEFINED` | Undefined/other image type
`GST_TAG_IMAGE_TYPE_FRONT_COVER` | Cover (front)
`GST_TAG_IMAGE_TYPE_BACK_COVER` | Cover (back)
`GST_TAG_IMAGE_TYPE_LEAFLET_PAGE` | Leaflet page
`GST_TAG_IMAGE_TYPE_MEDIUM` | Medium (e.g. label side of CD)
`GST_TAG_IMAGE_TYPE_LEAD_ARTIST` | Lead artist/lead performer/soloist
`GST_TAG_IMAGE_TYPE_ARTIST` | Artist/performer
`GST_TAG_IMAGE_TYPE_CONDUCTOR` | Conductor
`GST_TAG_IMAGE_TYPE_BAND_ORCHESTRA` | Band/orchestra
`GST_TAG_IMAGE_TYPE_COMPOSER` | Composer
`GST_TAG_IMAGE_TYPE_LYRICIST` | Lyricist/text writer
`GST_TAG_IMAGE_TYPE_RECORDING_LOCATION` | Recording location
`GST_TAG_IMAGE_TYPE_DURING_RECORDING` | During recording
`GST_TAG_IMAGE_TYPE_DURING_PERFORMANCE` | During performance
`GST_TAG_IMAGE_TYPE_VIDEO_CAPTURE` | Movie/video screen capture
`GST_TAG_IMAGE_TYPE_FISH` | A fish as funny as the ID3v2 spec
`GST_TAG_IMAGE_TYPE_ILLUSTRATION` | Illustration
`GST_TAG_IMAGE_TYPE_BAND_ARTIST_LOGO` | Band/artist logotype
`GST_TAG_IMAGE_TYPE_PUBLISHER_STUDIO_LOGO` | Publisher/studio logotype

Since 0.10.9

## See Also

GstTagList