## gsttagvorbis gsttagvorbis — tag mappings and support functions for plugins dealing with vorbiscomments |

## Synopsis

    #include <gst/tag/tag.h>

    const gchar *            gst_tag_from_vorbis_tag        (const gchar *vorbis_tag);
    const gchar *            gst_tag_to_vorbis_tag          (const gchar *gst_tag);
    void                gst_vorbis_tag_add                  (GstTagList *list,
                                                             const gchar *tag,
                                                             const gchar *value);
    GList *                  gst_tag_to_vorbis_comments     (const GstTagList *list,
                                                             const gchar *tag);

    GstTagList *             gst_tag_list_from_vorbiscomment_buffer
                                                            (const GstBuffer *buffer,
                                                             const guint8 *id_data,
                                                             const guint id_data_length,
                                                             gchar **vendor_string);
    GstBuffer *              gst_tag_list_to_vorbiscomment_buffer
                                                            (const GstTagList *list,
                                                             const guint8 *id_data,
                                                             const guint id_data_length,
                                                             const gchar *vendor_string);

## Description

Contains various utility functions for plugins to parse or create vorbiscomments and map them to and from GstTagLists.

## Details

### gst_tag_from_vorbis_tag ()

    const gchar *            gst_tag_from_vorbis_tag        (const gchar *vorbis_tag);

Looks up the GStreamer tag for a vorbiscomment tag.

`vorbis_tag` : | vorbiscomment tag to convert to GStreamer tag
Returns : | The corresponding GStreamer tag or NULL if none exists.

### gst_tag_to_vorbis_tag ()

    const gchar *            gst_tag_to_vorbis_tag          (const gchar *gst_tag);

Looks up the vorbiscomment tag for a GStreamer tag.

`gst_tag` : | GStreamer tag to convert to vorbiscomment tag
Returns : | The corresponding vorbiscomment tag or NULL if none exists.

### gst_vorbis_tag_add ()

    void                gst_vorbis_tag_add                  (GstTagList *list,
                                                             const gchar *tag,
                                                             const gchar *value);

Convenience function using `gst_tag_from_vorbis_tag()`, parsing a vorbis comment string into the right type and adding it to the given taglist `list`.

Unknown vorbiscomment tags will be added to the tag list in form of a GST_TAG_EXTENDED_COMMENT (since 0.10.10 at least).

`list` : | a GstTagList
`tag` : | a vorbiscomment tag string (key in key=value), must be valid UTF-8
`value` : | a vorbiscomment value string (value in key=value), must be valid UTF-8

### gst_tag_to_vorbis_comments ()

    GList *                  gst_tag_to_vorbis_comments     (const GstTagList *list,
                                                             const gchar *tag);

Creates a new tag list that contains the information parsed out of a vorbiscomment packet.

`list` : | a GstTagList
`tag` : | a GStreamer tag identifier, such as GST_TAG_ARTIST
Returns : | A GList of newly-allowcated key=value strings. Free with g_list_foreach (list, (GFunc) g_free, NULL) plus g_list_free (list)

### gst_tag_list_from_vorbiscomment_buffer ()

    GstTagList *             gst_tag_list_from_vorbiscomment_buffer
                                                            (const GstBuffer *buffer,
                                                             const guint8 *id_data,
                                                             const guint id_data_length,
                                                             gchar **vendor_string);

Creates a new tag list that contains the information parsed out of a vorbiscomment packet.

`buffer` : | buffer to convert
`id_data` : | identification data at start of stream
`id_data_length` : | length of identification data
`vendor_string` : | pointer to a string that should take the vendor string of this vorbis comment or NULL if you don't need it.
Returns : | A new GstTagList with all tags that could be extracted from the given vorbiscomment buffer or NULL on error.

### gst_tag_list_to_vorbiscomment_buffer ()

    GstBuffer *              gst_tag_list_to_vorbiscomment_buffer
                                                            (const GstTagList *list,
                                                             const guint8 *id_data,
                                                             const guint id_data_length,
                                                             const gchar *vendor_string);

Creates a new vorbiscomment buffer from a tag list.

`list` : | tag list to convert
`id_data` : | identification data at start of stream
`id_data_length` : | length of identification data, may be 0 if `id_data` is NULL
`vendor_string` : | string that describes the vendor string or NULL
Returns : | A new GstBuffer containing a vorbiscomment buffer with all tags that could be converted from the given tag list.

## See Also

GstTagList