Functions¶

	`tag_check_language_code` (lang_code)
	`tag_freeform_string_to_utf8` (data, env_vars)
	`tag_from_id3_tag` (id3_tag)
	`tag_from_id3_user_tag` (type, id3_user_tag)
	`tag_from_vorbis_tag` (vorbis_tag)
	`tag_get_id3v2_tag_size` (buffer)
	`tag_get_language_code_iso_639_1` (lang_code)
	`tag_get_language_code_iso_639_2B` (lang_code)
	`tag_get_language_code_iso_639_2T` (lang_code)
	`tag_get_language_codes` ()
	`tag_get_language_name` (language_code)
	`tag_get_license_description` (license_ref)
	`tag_get_license_flags` (license_ref)
	`tag_get_license_jurisdiction` (license_ref)
	`tag_get_license_nick` (license_ref)
	`tag_get_license_title` (license_ref)
	`tag_get_license_version` (license_ref)
	`tag_get_licenses` ()
	`tag_id3_genre_count` ()
	`tag_id3_genre_get` (id)
	`tag_image_data_to_image_sample` (image_data, image_type)
	`tag_list_add_id3_image` (tag_list, image_data, id3_picture_type)
	`tag_list_from_exif_buffer` (buffer, byte_order, base_offset)
	`tag_list_from_exif_buffer_with_tiff_header` (buffer)
	`tag_list_from_id3v2_tag` (buffer)
	`tag_list_from_vorbiscomment` (data, id_data)
	`tag_list_from_vorbiscomment_buffer` (buffer, id_data)
	`tag_list_from_xmp_buffer` (buffer)
	`tag_list_new_from_id3v1` (data)
	`tag_list_to_exif_buffer` (taglist, byte_order, base_offset)
	`tag_list_to_exif_buffer_with_tiff_header` (taglist)
	`tag_list_to_vorbiscomment_buffer` (list, id_data, vendor_string)
	`tag_list_to_xmp_buffer` (list, read_only, schemas)
	`tag_parse_extended_comment` (ext_comment, fail_if_no_key)
	`tag_register_musicbrainz_tags` ()
	`tag_to_id3_tag` (gst_tag)
	`tag_to_vorbis_comments` (list, tag)
	`tag_to_vorbis_tag` (gst_tag)
	`tag_xmp_list_schemas` ()
	`vorbis_tag_add` (list, tag, value)

Details¶

GstTag.tag_check_language_code(lang_code)[source]¶

Parameters:	lang_code (`str`) – ISO-639 language code (e.g. “deu” or “ger” or “de”)
Returns:	`True` if the two- or three-letter language code in lang_code is a valid ISO-639 language code.
Return type:	`bool`

Check if a given string contains a known ISO 639 language code.

This is useful in situations where it’s not clear whether a given string is a language code (which should be put into a Gst.TAG_LANGUAGE_CODE tag) or a free-form language name descriptor (which should be put into a Gst.TAG_LANGUAGE_NAME tag instead).

GstTag.tag_freeform_string_to_utf8(data, env_vars)[source]¶

Parameters:	data ([`int`]) – string data env_vars ([`str`]) – a `None`-terminated string array of environment variable names, or `None`
Returns:	a newly-allocated string in UTF-8 encoding, or `None`
Return type:	`str`

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 None-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).

GstTag.tag_from_id3_tag(id3_tag)[source]¶

Parameters:	id3_tag (`str`) – ID3v2 tag to convert to GStreamer tag
Returns:	The corresponding GStreamer tag or `None` if none exists.
Return type:	`str`

Looks up the GStreamer tag for a ID3v2 tag.

GstTag.tag_from_id3_user_tag(type, id3_user_tag)[source]¶

Parameters:	type (`str`) – the type of ID3v2 user tag (e.g. “TXXX” or “UDIF”) id3_user_tag (`str`) – ID3v2 user tag to convert to GStreamer tag
Returns:	The corresponding GStreamer tag or `None` if none exists.
Return type:	`str`

Looks up the GStreamer tag for an ID3v2 user tag (e.g. description in TXXX frame or owner in UFID frame).

GstTag.tag_from_vorbis_tag(vorbis_tag)[source]¶

Parameters:	vorbis_tag (`str`) – vorbiscomment tag to convert to GStreamer tag
Returns:	The corresponding GStreamer tag or `None` if none exists.
Return type:	`str`

Looks up the GStreamer tag for a vorbiscomment tag.

GstTag.tag_get_id3v2_tag_size(buffer)[source]¶

Parameters:	buffer (`Gst.Buffer`) – buffer holding ID3v2 tag (or at least the start of one)
Returns:	Size of tag, or 0 if header is invalid or too small.
Return type:	`int`

Determines size of an ID3v2 tag on buffer containing at least ID3v2 header, i.e. at least GstTag.TAG_ID3V2_HEADER_SIZE (10) bytes;

GstTag.tag_get_language_code_iso_639_1(lang_code)[source]¶

Parameters:	lang_code (`str`) – ISO-639 language code (e.g. “deu” or “ger” or “de”)
Returns:	two-letter ISO-639-1 language code string that maps to lang_code, or `None` if no mapping is known. The returned string must not be modified or freed.
Return type:	`str`

Returns two-letter ISO-639-1 language code given a three-letter ISO-639-2 language code or two-letter ISO-639-1 language code (both are accepted for convenience).

Language codes are case-sensitive and expected to be lower case.

GstTag.tag_get_language_code_iso_639_2B(lang_code)[source]¶

Parameters:	lang_code (`str`) – ISO-639 language code (e.g. “deu” or “ger” or “de”)
Returns:	three-letter ISO-639-2 language code string that maps to lang_code, or `None` if no mapping is known. The returned string must not be modified or freed.
Return type:	`str`

Returns three-letter ISO-639-2 “bibliographic” language code given a two-letter ISO-639-1 language code or a three-letter ISO-639-2 language code (both are accepted for convenience).

The “bibliographic” code is derived from the English name of the language (e.g. “ger” for German instead of “de” or “deu”). In most scenarios, the “terminological” codes are preferred.

Language codes are case-sensitive and expected to be lower case.

GstTag.tag_get_language_code_iso_639_2T(lang_code)[source]¶

Parameters:	lang_code (`str`) – ISO-639 language code (e.g. “deu” or “ger” or “de”)
Returns:	three-letter ISO-639-2 language code string that maps to lang_code, or `None` if no mapping is known. The returned string must not be modified or freed.
Return type:	`str`

Returns three-letter ISO-639-2 “terminological” language code given a two-letter ISO-639-1 language code or a three-letter ISO-639-2 language code (both are accepted for convenience).

The “terminological” code is derived from the local name of the language (e.g. “deu” for German instead of “ger”). In most scenarios, the “terminological” codes are preferred over the “bibliographic” ones.

Language codes are case-sensitive and expected to be lower case.

GstTag.tag_get_language_codes()[source]¶

Returns:	`None`-terminated string array with two-letter language codes. Free with `GLib.strfreev`() when no longer needed.
Return type:	[`str`]

Returns a list of known language codes (in form of two-letter ISO-639-1 codes). This is useful for UIs to build a list of available languages for tagging purposes (e.g. to tag an audio track appropriately in a video or audio editor).

GstTag.tag_get_language_name(language_code)[source]¶

Parameters:	language_code (`str`) – two or three-letter ISO-639 language code
Returns:	language name in UTF-8 format, or `None` if language_code could not be mapped to a language name. The returned string must not be modified and does not need to freed; it will stay valid until the application is terminated.
Return type:	`str`

Returns the name of the language given an ISO-639 language code as found in a Gst.TAG_LANGUAGE_CODE tag. The name will be translated according to the current locale (if the library was built against the iso-codes package, otherwise the English name will be returned).

Language codes are case-sensitive and expected to be lower case.

GstTag.tag_get_license_description(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the description of the license, or `None` if the license is unknown or a description is not available.
Return type:	`str`

Get the description of a license, which is a translated description of the license’s main features.

GstTag.tag_get_license_flags(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the flags of the license, or 0 if the license is unknown
Return type:	`GstTag.TagLicenseFlags`

Get the flags of a license, which describe most of the features of a license in their most general form.

GstTag.tag_get_license_jurisdiction(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the jurisdiction code of the license, or `None` if the license is unknown or is not specific to a particular jurisdiction.
Return type:	`str`

Get the jurisdiction code of a license. This is usually a two-letter ISO 3166-1 alpha-2 code, but there is also the special case of Scotland, for which no code exists and which is thus represented as “scotland”.

Known jurisdictions: ar, at, au, be, bg, br, ca, ch, cl, cn, co, de, dk, es, fi, fr, hr, hu, il, in, it, jp, kr, mk, mt, mx, my, nl, pe, pl, pt, scotland, se, si, tw, uk, us, za.

GstTag.tag_get_license_nick(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the nick name of the license, or `None` if the license is unknown
Return type:	`str`

Get the nick name of a license, which is a short (untranslated) string such as e.g. “CC BY-NC-ND 2.0 UK”.

GstTag.tag_get_license_title(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the title of the license, or `None` if the license is unknown or no title is available.
Return type:	`str`

Get the title of a license, which is a short translated description of the license’s features (generally not very pretty though).

GstTag.tag_get_license_version(license_ref)[source]¶

Parameters:	license_ref (`str`) – a license reference string in form of a URI, e.g. “http://creativecommons.org/licenses/by-nc-nd/2.0/”
Returns:	the version of the license, or `None` if the license is not known or has no version
Return type:	`str`

Get the version of a license.

GstTag.tag_get_licenses()[source]¶

Returns:	`None`-terminated array of license strings. Free with `GLib.strfreev`() when no longer needed.
Return type:	[`str`]

Returns a list of known license references (in form of URIs). This is useful for UIs to build a list of available licenses for tagging purposes (e.g. to tag an audio track appropriately in a video or audio editor, or an image in a camera application).

GstTag.tag_id3_genre_count()[source]¶

Returns:	the number of ID3v1 genres that can be identified
Return type:	`int`

Gets the number of ID3v1 genres that can be identified. Winamp genres are included.

GstTag.tag_id3_genre_get(id)[source]¶

Parameters:	id (`int`) – ID of genre to query
Returns:	the genre or `None` if no genre is associated with that ID.
Return type:	`str`

Gets the ID3v1 genre name for a given ID.

GstTag.tag_image_data_to_image_sample(image_data, image_type)[source]¶

Parameters:	image_data (`bytes`) – the (encoded) image 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:	a newly-allocated image sample for use in tag lists, or `None`
Return type:	`Gst.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.Sample s 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).

GstTag.tag_list_add_id3_image(tag_list, image_data, id3_picture_type)[source]¶

Parameters:	tag_list (`Gst.TagList`) – a tag list image_data (`bytes`) – the (encoded) image id3_picture_type (`int`) – picture type as per the ID3 (v2.4.0) specification for the APIC frame (0 = unknown/other)
Returns:	`True` if the image was processed, otherwise `False`
Return type:	`bool`

Adds an image from an ID3 APIC frame (or similar, such as used in FLAC) to the given tag list. Also see GstTag.tag_image_data_to_image_sample() for more information on image tags in GStreamer.

GstTag.tag_list_from_exif_buffer(buffer, byte_order, base_offset)[source]¶

Parameters:	buffer (`Gst.Buffer`) – The exif buffer byte_order (`int`) – byte order of the data base_offset (`int`) – Offset from the tiff header to this buffer
Returns:	The parsed taglist
Return type:	`Gst.TagList`

Parses the IFD and IFD tags data contained in the buffer and puts it on a taglist. The base_offset is used to subtract from the offset in the tag entries and be able to get the offset relative to the buffer start

GstTag.tag_list_from_exif_buffer_with_tiff_header(buffer)[source]¶

Parameters:	buffer (`Gst.Buffer`) – The exif buffer
Returns:	The taglist
Return type:	`Gst.TagList`

Parses the exif tags starting with a tiff header structure.

GstTag.tag_list_from_id3v2_tag(buffer)[source]¶

Parameters:	buffer (`Gst.Buffer`) – buffer to convert
Returns:	A new `Gst.TagList` with all tags that could be extracted from the given vorbiscomment buffer or `None` on error.
Return type:	`Gst.TagList`

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

GstTag.tag_list_from_vorbiscomment(data, id_data)[source]¶

Parameters:

data (bytes) – data to convert
id_data (bytes) – identification data at start of stream

Returns:

A new Gst.TagList with all tags that could be extracted from the given vorbiscomment buffer or None on error.

vendor_string:	pointer to a string that should take the vendor string of this vorbis comment or `None` if you don’t need it.

Return type:

(Gst.TagList, vendor_string: str)

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

GstTag.tag_list_from_vorbiscomment_buffer(buffer, id_data)[source]¶

Parameters:

buffer (Gst.Buffer) – buffer to convert
id_data (bytes) – identification data at start of stream

Returns:

A new Gst.TagList with all tags that could be extracted from the given vorbiscomment buffer or None on error.

vendor_string:	pointer to a string that should take the vendor string of this vorbis comment or `None` if you don’t need it.

Return type:

(Gst.TagList, vendor_string: str)

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

GstTag.tag_list_from_xmp_buffer(buffer)[source]¶

Parameters:	buffer (`Gst.Buffer`) – buffer
Returns:	new taglist or `None`, free the list when done
Return type:	`Gst.TagList`

Parse a xmp packet into a taglist.

GstTag.tag_list_new_from_id3v1(data)[source]¶

Parameters:	data (`bytes`) – 128 bytes of data containing the ID3v1 tag
Returns:	A new tag list or `None` if the data was not an ID3v1 tag.
Return type:	`Gst.TagList`

Parses the data containing an ID3v1 tag and returns a Gst.TagList from the parsed data.

GstTag.tag_list_to_exif_buffer(taglist, byte_order, base_offset)[source]¶

Parameters:	taglist (`Gst.TagList`) – The taglist byte_order (`int`) – byte order used in writing (`GLib.LITTLE_ENDIAN` or `GLib.BIG_ENDIAN`) base_offset (`int`) – Offset from the tiff header first byte
Returns:	A `Gst.Buffer` containing the tag entries followed by the tag data
Return type:	`Gst.Buffer`

Formats the tags in taglist on exif format. The resulting buffer contains the tags IFD and is followed by the data pointed by the tag entries.

GstTag.tag_list_to_exif_buffer_with_tiff_header(taglist)[source]¶

Parameters:	taglist (`Gst.TagList`) – The taglist
Returns:	A `Gst.Buffer` containing the data
Return type:	`Gst.Buffer`

Formats the tags in taglist into exif structure, a tiff header is put in the beginning of the buffer.

GstTag.tag_list_to_vorbiscomment_buffer(list, id_data, vendor_string)[source]¶

Parameters:	list (`Gst.TagList`) – tag list to convert id_data (`bytes`) – identification data at start of stream vendor_string (`str` or `None`) – string that describes the vendor string or `None`
Returns:	A new `Gst.Buffer` containing a vorbiscomment buffer with all tags that could be converted from the given tag list.
Return type:	`Gst.Buffer`

Creates a new vorbiscomment buffer from a tag list.

GstTag.tag_list_to_xmp_buffer(list, read_only, schemas)[source]¶

Parameters:	list (`Gst.TagList`) – tags read_only (`bool`) – does the container forbid inplace editing schemas ([`str`]) – `None` terminated array of schemas to be used on serialization
Returns:	new buffer or `None`, unref the buffer when done
Return type:	`Gst.Buffer`

Formats a taglist as a xmp packet using only the selected schemas. An empty list (None) means that all schemas should be used

GstTag.tag_parse_extended_comment(ext_comment, fail_if_no_key)[source]¶

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:

True if the string could be parsed, otherwise False

key:	return location for the comment description key, or `None`
lang:	return location for the comment ISO-639 language code, or `None`
value:	return location for the actual comment string, or `None`

Return type:

(bool, key: str or None, lang: str or None, value: str)

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 None by this function if there is no key or no language code in the extended comment string.

GstTag.tag_register_musicbrainz_tags()[source]¶: 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_to_id3_tag(gst_tag)[source]¶

Parameters:	gst_tag (`str`) – GStreamer tag to convert to vorbiscomment tag
Returns:	The corresponding ID3v2 tag or `None` if none exists.
Return type:	`str`

Looks up the ID3v2 tag for a GStreamer tag.

GstTag.tag_to_vorbis_comments(list, tag)[source]¶

Parameters:	list (`Gst.TagList`) – a `Gst.TagList` tag (`str`) – a GStreamer tag identifier, such as `Gst.TAG_ARTIST`
Returns:	A `GLib.List` of newly-allocated key=value strings. Free with g_list_foreach (list, (`GLib.Func`) `GLib.free`, `None`) plus g_list_free (list)
Return type:	[`str`]

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

GstTag.tag_to_vorbis_tag(gst_tag)[source]¶

Parameters:	gst_tag (`str`) – GStreamer tag to convert to vorbiscomment tag
Returns:	The corresponding vorbiscomment tag or `None` if none exists.
Return type:	`str`

Looks up the vorbiscomment tag for a GStreamer tag.

GstTag.tag_xmp_list_schemas()[source]¶

Returns:	a `None` terminated array of strings with the schema names
Return type:	[`str`]

Gets the list of supported schemas in the xmp lib

GstTag.vorbis_tag_add(list, tag, value)[source]¶

Parameters:	list (`Gst.TagList`) – a `Gst.TagList` tag (`str`) – a vorbiscomment tag string (key in key=value), must be valid UTF-8 value (`str`) – a vorbiscomment value string (value in key=value), must be valid UTF-8

Convenience function using GstTag.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.