# Tags

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

## Functions

### 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, WINDOWS-1252/ISO-8859-1 is assumed (which will almost always succeed).

Parameters:

`data` ( [array length=size][element-type gchar]) –

string data

`size` –

length of string data, or -1 if the string is NUL-terminated

`env_vars` –

(array zero-terminated=1) a NULL-terminated string array of environment variable names, or NULL

Returns ( [nullable]) –

a newly-allocated string in UTF-8 encoding, or NULL

### GstTag.prototype.tag_freeform_string_to_utf8

    function GstTag.prototype.tag_freeform_string_to_utf8(data: [ String ], size: Number, env_vars: [ String ]): {
        // javascript wrapper for 'gst_tag_freeform_string_to_utf8'
    }

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, WINDOWS-1252/ISO-8859-1 is assumed (which will almost always succeed).

Parameters:

`data` ([ String ]) –

string data

`size` (Number) –

length of string data, or -1 if the string is NUL-terminated

`env_vars` ([ String ]) –

(array zero-terminated=1) a NULL-terminated string array of environment variable names, or NULL

Returns (String) –

a newly-allocated string in UTF-8 encoding, or NULL

### GstTag.tag_freeform_string_to_utf8

    def GstTag.tag_freeform_string_to_utf8 (data, size, env_vars):
        #python wrapper for 'gst_tag_freeform_string_to_utf8'

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, WINDOWS-1252/ISO-8859-1 is assumed (which will almost always succeed).

Parameters:

`data` ([ int ]) –

string data

`size` (int) –

length of string data, or -1 if the string is NUL-terminated

`env_vars` ([ str ]) –

(array zero-terminated=1) a NULL-terminated string array of environment variable names, or NULL

Returns (str) –

a newly-allocated string in UTF-8 encoding, or NULL

### gst_tag_image_data_to_image_sample

    GstSample *
    gst_tag_image_data_to_image_sample (const guint8 * image_data,
                                        guint image_data_len,
                                        GstTagImageType image_type)

Helper function for tag-reading plugins to create a GstSample 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 GstSamples containing the raw image data, with the sample caps describing the content type of the image (e.g. image/jpeg, image/png, text/uri-list). The sample info may contain an additional 'image-type' field of GstTagImageType 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).

Parameters:

`image_data` ( [array length=image_data_len]) –

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 ( [transfer: full][nullable]) –

a newly-allocated image sample for use in tag lists, or NULL

### GstTag.prototype.tag_image_data_to_image_sample

    function GstTag.prototype.tag_image_data_to_image_sample(image_data: [ Number ], image_data_len: Number, image_type: GstTag.TagImageType): {
        // javascript wrapper for 'gst_tag_image_data_to_image_sample'
    }

Helper function for tag-reading plugins to create a Gst.Sample suitable to add to a Gst.TagList 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 Gst.Samples containing the raw image data, with the sample caps describing the content type of the image (e.g. image/jpeg, image/png, text/uri-list). The sample info may contain an additional 'image-type' field of GstTag.TagImageType 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).

Parameters:

`image_data` ([ Number ]) –

the (encoded) image

`image_data_len` (Number) –

the length of the encoded image data at image_data

`image_type` (GstTag.TagImageType) –

type of the image, or GstTag.TagImageType.UNDEFINED. Pass GstTag.TagImageType.NONE if no image type should be set at all (e.g. for preview images)

Returns (Gst.Sample) –

a newly-allocated image sample for use in tag lists, or NULL

### GstTag.tag_image_data_to_image_sample

    def GstTag.tag_image_data_to_image_sample (image_data, image_data_len, image_type):
        #python wrapper for 'gst_tag_image_data_to_image_sample'

Helper function for tag-reading plugins to create a Gst.Sample suitable to add to a Gst.TagList 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 Gst.Samples containing the raw image data, with the sample caps describing the content type of the image (e.g. image/jpeg, image/png, text/uri-list). The sample info may contain an additional 'image-type' field of GstTag.TagImageType 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).

Parameters:

`image_data` ([ int ]) –

the (encoded) image

`image_data_len` (int) –

the length of the encoded image data at image_data

`image_type` (GstTag.TagImageType) –

type of the image, or GstTag.TagImageType.UNDEFINED. Pass GstTag.TagImageType.NONE if no image type should be set at all (e.g. for preview images)

Returns (Gst.Sample) –

a newly-allocated image sample for use in tag lists, or NULL

### 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.

Parameters:

`ext_comment` –

an extended comment string, see GST_TAG_EXTENDED_COMMENT

`key` –

(out) (nullable): return location for the comment description key, or NULL

`lang` –

(out) (nullable): return location for the comment ISO-639 language code, or NULL

`value` ( [out]) –

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

### GstTag.prototype.tag_parse_extended_comment

    function GstTag.prototype.tag_parse_extended_comment(ext_comment: String, fail_if_no_key: Number): {
        // javascript wrapper for 'gst_tag_parse_extended_comment'
    }

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 GLib.prototype.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.

Parameters:

`ext_comment` (String) –

an extended comment string, see Gst.TAG_EXTENDED_COMMENT

`fail_if_no_key` (Number) –

whether to fail if strings are not in key=value form

Returns a tuple made of:

(Number ) –

TRUE if the string could be parsed, otherwise FALSE

`key` (String ) –

TRUE if the string could be parsed, otherwise FALSE

`lang` (String ) –

TRUE if the string could be parsed, otherwise FALSE

`value` (String ) –

TRUE if the string could be parsed, otherwise FALSE

### GstTag.tag_parse_extended_comment

    def GstTag.tag_parse_extended_comment (ext_comment, fail_if_no_key):
        #python wrapper for 'gst_tag_parse_extended_comment'

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 GLib.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.

Parameters:

`ext_comment` (str) –

an extended comment string, see Gst.TAG_EXTENDED_COMMENT

`fail_if_no_key` (bool) –

whether to fail if strings are not in key=value form

Returns a tuple made of:

(bool ) –

TRUE if the string could be parsed, otherwise FALSE

`key` (str ) –

TRUE if the string could be parsed, otherwise FALSE

`lang` (str ) –

TRUE if the string could be parsed, otherwise FALSE

`value` (str ) –

TRUE if the string could be parsed, otherwise FALSE

### gst_tag_register_musicbrainz_tags

    gst_tag_register_musicbrainz_tags ()

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.

### GstTag.prototype.tag_register_musicbrainz_tags

    function GstTag.prototype.tag_register_musicbrainz_tags(): {
        // javascript wrapper for 'gst_tag_register_musicbrainz_tags'
    }

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.

### GstTag.tag_register_musicbrainz_tags

    def GstTag.tag_register_musicbrainz_tags ():
        #python wrapper for 'gst_tag_register_musicbrainz_tags'

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.

The results of the search are