Copyright	Will Thompson and Iñaki García Etxebarria
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria
Safe Haskell	Safe-Inferred
Language	Haskell2010

GI.GstTag.Functions

Contents

Methods

Description

Synopsis

tagCheckLanguageCode :: (HasCallStack, MonadIO m) => Text -> m Bool
tagFreeformStringToUtf8 :: (HasCallStack, MonadIO m) => [Int8] -> [Text] -> m Text
tagFromId3Tag :: (HasCallStack, MonadIO m) => Text -> m Text
tagFromId3UserTag :: (HasCallStack, MonadIO m) => Text -> Text -> m Text
tagFromVorbisTag :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetId3v2TagSize :: (HasCallStack, MonadIO m) => Buffer -> m Word32
tagGetLanguageCodeIso6391 :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLanguageCodeIso6392B :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLanguageCodeIso6392T :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLanguageCodes :: (HasCallStack, MonadIO m) => m [Text]
tagGetLanguageName :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenseDescription :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenseFlags :: (HasCallStack, MonadIO m) => Text -> m [TagLicenseFlags]
tagGetLicenseJurisdiction :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenseNick :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenseTitle :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenseVersion :: (HasCallStack, MonadIO m) => Text -> m Text
tagGetLicenses :: (HasCallStack, MonadIO m) => m [Text]
tagId3GenreCount :: (HasCallStack, MonadIO m) => m Word32
tagId3GenreGet :: (HasCallStack, MonadIO m) => Word32 -> m Text
tagImageDataToImageSample :: (HasCallStack, MonadIO m) => ByteString -> TagImageType -> m Sample
tagListAddId3Image :: (HasCallStack, MonadIO m) => TagList -> ByteString -> Word32 -> m Bool
tagListFromExifBuffer :: (HasCallStack, MonadIO m) => Buffer -> Int32 -> Word32 -> m TagList
tagListFromExifBufferWithTiffHeader :: (HasCallStack, MonadIO m) => Buffer -> m TagList
tagListFromId3v2Tag :: (HasCallStack, MonadIO m) => Buffer -> m TagList
tagListFromVorbiscomment :: (HasCallStack, MonadIO m) => ByteString -> ByteString -> m (TagList, Text)
tagListFromVorbiscommentBuffer :: (HasCallStack, MonadIO m) => Buffer -> ByteString -> m (TagList, Text)
tagListFromXmpBuffer :: (HasCallStack, MonadIO m) => Buffer -> m TagList
tagListNewFromId3v1 :: (HasCallStack, MonadIO m) => ByteString -> m TagList
tagListToExifBuffer :: (HasCallStack, MonadIO m) => TagList -> Int32 -> Word32 -> m Buffer
tagListToExifBufferWithTiffHeader :: (HasCallStack, MonadIO m) => TagList -> m Buffer
tagListToVorbiscommentBuffer :: (HasCallStack, MonadIO m) => TagList -> ByteString -> Maybe Text -> m Buffer
tagListToXmpBuffer :: (HasCallStack, MonadIO m) => TagList -> Bool -> [Text] -> m Buffer
tagParseExtendedComment :: (HasCallStack, MonadIO m) => Text -> Bool -> m (Bool, Maybe Text, Maybe Text, Text)
tagRegisterMusicbrainzTags :: (HasCallStack, MonadIO m) => m ()
tagToId3Tag :: (HasCallStack, MonadIO m) => Text -> m Text
tagToVorbisComments :: (HasCallStack, MonadIO m) => TagList -> Text -> m [Text]
tagToVorbisTag :: (HasCallStack, MonadIO m) => Text -> m Text
tagXmpListSchemas :: (HasCallStack, MonadIO m) => m [Text]
vorbisTagAdd :: (HasCallStack, MonadIO m) => TagList -> Text -> Text -> m ()

Methods

tagCheckLanguageCode

tagCheckLanguageCode Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`langCode`: ISO-639 language code (e.g. "deu" or "ger" or "de")
-> m Bool	Returns: TRUE if the two- or three-letter language code in `langCode` is a valid ISO-639 language code.

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 TAG_LANGUAGE_CODE tag) or a free-form language name descriptor (which should be put into a TAG_LANGUAGE_NAME tag instead).

tagFreeformStringToUtf8

tagFreeformStringToUtf8 Source #

Arguments

:: (HasCallStack, MonadIO m)
=> [Int8]	`data`: string data
-> [Text]	`envVars`: a NULL-terminated string array of environment variable names, or NULL
-> m Text	Returns: a newly-allocated string in UTF-8 encoding, or NULL

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

tagFromId3Tag

tagFromId3Tag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`id3Tag`: ID3v2 tag to convert to GStreamer tag
-> m Text	Returns: The corresponding GStreamer tag or NULL if none exists.

Looks up the GStreamer tag for a ID3v2 tag.

tagFromId3UserTag

tagFromId3UserTag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`type`: the type of ID3v2 user tag (e.g. "TXXX" or "UDIF")
-> Text	`id3UserTag`: ID3v2 user tag to convert to GStreamer tag
-> m Text	Returns: The corresponding GStreamer tag or NULL if none exists.

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

tagFromVorbisTag

tagFromVorbisTag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`vorbisTag`: vorbiscomment tag to convert to GStreamer tag
-> m Text	Returns: The corresponding GStreamer tag or NULL if none exists.

Looks up the GStreamer tag for a vorbiscomment tag.

tagGetId3v2TagSize

tagGetId3v2TagSize Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: buffer holding ID3v2 tag (or at least the start of one)
-> m Word32	Returns: Size of tag, or 0 if header is invalid or too small.

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

tagGetLanguageCodeIso6391

tagGetLanguageCodeIso6391 Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`langCode`: ISO-639 language code (e.g. "deu" or "ger" or "de")
-> m Text	Returns: two-letter ISO-639-1 language code string that maps to `langCode`, or NULL if no mapping is known. The returned string must not be modified or freed.

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.

tagGetLanguageCodeIso6392B

tagGetLanguageCodeIso6392B Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`langCode`: ISO-639 language code (e.g. "deu" or "ger" or "de")
-> m Text	Returns: three-letter ISO-639-2 language code string that maps to `langCode`, or NULL if no mapping is known. The returned string must not be modified or freed.

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.

tagGetLanguageCodeIso6392T

tagGetLanguageCodeIso6392T Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`langCode`: ISO-639 language code (e.g. "deu" or "ger" or "de")
-> m Text	Returns: three-letter ISO-639-2 language code string that maps to `langCode`, or NULL if no mapping is known. The returned string must not be modified or freed.

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.

tagGetLanguageCodes

tagGetLanguageCodes Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m [Text]	Returns: NULL-terminated string array with two-letter language codes. Free with `strfreev` when no longer needed.

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

tagGetLanguageName

tagGetLanguageName Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`languageCode`: two or three-letter ISO-639 language code
-> m Text	Returns: language name in UTF-8 format, or NULL if `languageCode` 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.

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.

tagGetLicenseDescription

tagGetLicenseDescription Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m Text	Returns: the description of the license, or NULL if the license is unknown or a description is not available.

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

tagGetLicenseFlags

tagGetLicenseFlags Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m [TagLicenseFlags]	Returns: the flags of the license, or 0 if the license is unknown

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

tagGetLicenseJurisdiction

tagGetLicenseJurisdiction Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m Text	Returns: the jurisdiction code of the license, or NULL if the license is unknown or is not specific to a particular jurisdiction.

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.

tagGetLicenseNick

tagGetLicenseNick Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m Text	Returns: the nick name of the license, or NULL if the license is unknown

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

tagGetLicenseTitle

tagGetLicenseTitle Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m Text	Returns: the title of the license, or NULL if the license is unknown or no title is available.

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

tagGetLicenseVersion

tagGetLicenseVersion Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`licenseRef`: a license reference string in form of a URI, e.g. "http://creativecommons.org/licenses/by-nc-nd/2.0/"
-> m Text	Returns: the version of the license, or NULL if the license is not known or has no version

Get the version of a license.

tagGetLicenses

tagGetLicenses Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m [Text]	Returns: NULL-terminated array of license strings. Free with `strfreev` when no longer needed.

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

tagId3GenreCount

tagId3GenreCount Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m Word32	Returns: the number of ID3v1 genres that can be identified

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

tagId3GenreGet

tagId3GenreGet Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Word32	`id`: ID of genre to query
-> m Text	Returns: the genre or NULL if no genre is associated with that ID.

Gets the ID3v1 genre name for a given ID.

tagImageDataToImageSample

tagImageDataToImageSample Source #

Arguments

:: (HasCallStack, MonadIO m)
=> ByteString	`imageData`: the (encoded) image
-> TagImageType	`imageType`: 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)
-> m Sample	Returns: a newly-allocated image sample for use in tag lists, or NULL

Helper function for tag-reading plugins to create a Sample suitable to add to a TagList as an image tag (such as TAG_IMAGE or 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 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 TagImageType to describe the type of image (front cover, back cover etc.). 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).

tagListAddId3Image

tagListAddId3Image Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`tagList`: a tag list
-> ByteString	`imageData`: the (encoded) image
-> Word32	`id3PictureType`: picture type as per the ID3 (v2.4.0) specification for the APIC frame (0 = unknown/other)
-> m Bool	Returns: `True` if the image was processed, otherwise `False`

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

tagListFromExifBuffer

tagListFromExifBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: The exif buffer
-> Int32	`byteOrder`: byte order of the data
-> Word32	`baseOffset`: Offset from the tiff header to this buffer
-> m TagList	Returns: The parsed 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

tagListFromExifBufferWithTiffHeader

tagListFromExifBufferWithTiffHeader Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: The exif buffer
-> m TagList	Returns: The taglist

Parses the exif tags starting with a tiff header structure.

tagListFromId3v2Tag

tagListFromId3v2Tag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: buffer to convert
-> m TagList	Returns: A new `TagList` with all tags that could be extracted from the given vorbiscomment buffer or NULL on error.

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

tagListFromVorbiscomment

tagListFromVorbiscomment Source #

Arguments

:: (HasCallStack, MonadIO m)
=> ByteString	`data`: data to convert
-> ByteString	`idData`: identification data at start of stream
-> m (TagList, Text)	Returns: A new `TagList` with all tags that could be extracted from the given vorbiscomment buffer or NULL on error.

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

tagListFromVorbiscommentBuffer

tagListFromVorbiscommentBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: buffer to convert
-> ByteString	`idData`: identification data at start of stream
-> m (TagList, Text)	Returns: A new `TagList` with all tags that could be extracted from the given vorbiscomment buffer or NULL on error.

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

tagListFromXmpBuffer

tagListFromXmpBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Buffer	`buffer`: buffer
-> m TagList	Returns: new taglist or `Nothing`, free the list when done

Parse a xmp packet into a taglist.

tagListNewFromId3v1

tagListNewFromId3v1 Source #

Arguments

:: (HasCallStack, MonadIO m)
=> ByteString	`data`: 128 bytes of data containing the ID3v1 tag
-> m TagList	Returns: A new tag list or NULL if the data was not an ID3v1 tag.

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

tagListToExifBuffer

tagListToExifBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`taglist`: The taglist
-> Int32	`byteOrder`: byte order used in writing (G_LITTLE_ENDIAN or G_BIG_ENDIAN)
-> Word32	`baseOffset`: Offset from the tiff header first byte
-> m Buffer	Returns: A GstBuffer containing the tag entries followed by the tag data

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.

tagListToExifBufferWithTiffHeader

tagListToExifBufferWithTiffHeader Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`taglist`: The taglist
-> m Buffer	Returns: A GstBuffer containing the data

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

tagListToVorbiscommentBuffer

tagListToVorbiscommentBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`list`: tag list to convert
-> ByteString	`idData`: identification data at start of stream
-> Maybe Text	`vendorString`: string that describes the vendor string or NULL
-> m Buffer	Returns: A new `Buffer` containing a vorbiscomment buffer with all tags that could be converted from the given tag list.

Creates a new vorbiscomment buffer from a tag list.

tagListToXmpBuffer

tagListToXmpBuffer Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`list`: tags
-> Bool	`readOnly`: does the container forbid inplace editing
-> [Text]	`schemas`: `Nothing` terminated array of schemas to be used on serialization
-> m Buffer	Returns: new buffer or `Nothing`, unref the buffer when done

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

tagParseExtendedComment

tagParseExtendedComment Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`extComment`: an extended comment string, see `TAG_EXTENDED_COMMENT`
-> Bool	`failIfNoKey`: whether to fail if strings are not in key=value form
-> m (Bool, Maybe Text, Maybe Text, Text)	Returns: TRUE if the string could be parsed, otherwise FALSE

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

tagRegisterMusicbrainzTags

tagRegisterMusicbrainzTags :: (HasCallStack, MonadIO m) => m () 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.

tagToId3Tag

tagToId3Tag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`gstTag`: GStreamer tag to convert to vorbiscomment tag
-> m Text	Returns: The corresponding ID3v2 tag or NULL if none exists.

Looks up the ID3v2 tag for a GStreamer tag.

tagToVorbisComments

tagToVorbisComments Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`list`: a `TagList`
-> Text	`tag`: a GStreamer tag identifier, such as `TAG_ARTIST`
-> m [Text]	Returns: A `List` of newly-allocated key=value strings. Free with g_list_foreach (list, (GFunc) g_free, NULL) plus g_list_free (list)

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

tagToVorbisTag

tagToVorbisTag Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`gstTag`: GStreamer tag to convert to vorbiscomment tag
-> m Text	Returns: The corresponding vorbiscomment tag or NULL if none exists.

Looks up the vorbiscomment tag for a GStreamer tag.

tagXmpListSchemas

tagXmpListSchemas Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m [Text]	Returns: a `Nothing` terminated array of strings with the schema names

Gets the list of supported schemas in the xmp lib

vorbisTagAdd

vorbisTagAdd Source #

Arguments

:: (HasCallStack, MonadIO m)
=> TagList	`list`: a `TagList`
-> Text	`tag`: a vorbiscomment tag string (key in key=value), must be valid UTF-8
-> Text	`value`: a vorbiscomment value string (value in key=value), must be valid UTF-8
-> m ()

Convenience function using tagFromVorbisTag, 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 TAG_EXTENDED_COMMENT.