^ What's the point?
^ Usage
^ Functions

Download :: Topics on this subject on the Forum :: Top
Tags Library

Tags Library is a tag reader-writer component for Delphi (Win32, Win64, OSX, iOS and Android) and a .dll for developer environments supporting usage of Win32, Win64 or OSX32 .dlls (C++, VB, C#, VB.NET etc.).
The component reads and writes all common audio file tag formats additionaly tags in MP4 video files.

Features:
  • Loading of ID3v1, ID3v2, Lyrics3, APEv1, APEv2, Flac (including Ogg Flac), Ogg Vorbis, Opus, MP4 (including video files and 64bit atom size files), WAV LIST INFO, BEXT and CART (including RF64 WAV files) and WMA tags
  • Saving of ID3v1, ID3v2, Lyrics3, APEv2, Flac (including Ogg Flac), Ogg Vorbis, Opus, MP4 (including video files and 64bit atom size files), WAV LIST INFO, BEXT and CART (including RF64 WAV files) and WMA tags
  • Removing of all the supported tags
  • Functions for reading/writing/removing tags for a file in memory
  • Built in support for extracting and inserting album cover pictures for all the supported tag formats
  • Handle the tags transparently or call direct functions for particular tags
  • Integration with BASS, load tags from BASS channel handles (local or URL streams)
  • Get source audio file's attributes (MPEG, AIFF/AIFC, Flac, Ogg Vorbis, Opus, WAV, MusePack, WavPack)
  • Fully unicode
  • Pure Delphi code, no external dependencies (except the WMA format, which is available only on Windows), Delphi XE2 64bit and OSX32, Delphi XE5 iOS and Android compatible
  • .dll version provided for Win32, Win64 and OSX32 (.NET wrapper .dll also included)

The used Delphi tagging units are also available separatelly:
If you have any question, please use the forum: Tags Library @ un4seen forum
or write to: 3delite@3delite.hu


Tags Library in shareware and commercial software?

The component is free for use in free software. If you like it and use it in a shareware or commercial (or any other money making - advertising, in app. selling, etc.) product you have to buy a license.


Using the component, loading tags

TagsLibraryDefaultTagLoadPriority array holds the default values specifying the tag type preference (priority) when loading the tags (element 0 has the highest priority). These values are applied for the newly created TTags classes. So to have effect it has to be specified before creating a TTags class instance.
First create a TTags class, and then call the LoadFromFile() or the LoadFromBASS() function. If tags are found the .Loaded property is set to True.
To extract the tags you can use TTags.GetTag('TITLE') function to get the 'title' tag, returns an empty string if no such tag is present. To get more details use the TTags.Tag('TITLE') function which returns a TTag class or nil if no such tag is present. On how to iterate over the tags please see the tutorials.
To extract the cover arts, use the TTags.CoverArts[i] array, you can obtain the cover art count with TTags.CoverArtCount.
Note that the tag loading is 'joining' all the found tags by the specified preference, so if there's an ID3v1 tag with a title and there's an ID3v2 tag also with a title the title will be listed as by the ID3v2 tag's field as it has higher priority by the default TagsLibraryDefaultTagLoadPriority.
If you want to load a particular tag type directly, or access a particular tag class, you can always use the 'sub-classes', like TTags.APEv2Tag.LoadFromFile('FileName'), to read-in the tags use the TTags.LoadAPEv2Tags function after loading the tags directly.
To understand the functions and usage of these tagging 'sub-classes' please see the provided tutorials in the folders of the tagging libraries.


Saving tags

The library is designed to provide the functionality to load any tag and save to any tag format after. So you can load an ID3v2 taged file and then save this tag as a Flac or MP4 tag afterwards. As much information as possible is preserved.
To set a tag field use TTags.SetTag('TITLE', 'Song title'), the TTags.SetList() function can be used to set the 'TIPL' (involved people) and 'TMCL' (musician credits) tags.
The tags can be saved automatically (default behaviour) with TTags.SaveToFile('FileName.mp3'), or explicitly specifying the tag format to be written with TTags.SaveToFile('FileName.mp3', ttID3v2) for example.


Basic steps for using the .dll version

1. Load the library by calling 'InitTagsLibrary'
2. Create a tags object by calling 'TagsLibrary_Create', will return the object handle to be used in the next steps
3. Call 'TagsLibrary_Load' use 'ttAutomatic' for 'TagType' and use 'True' for 'ParseTags'
4. Get tag with the function 'TagsLibrary_GetTag'/ set tag with 'TagsLibrary_SetTag'
5. To save the tag use 'TagsLibrary_Save'
6. To free the resources used by the object call 'TagsLibrary_Free'
7. When exiting the application call 'FreeTagsLibrary'


Overview of the .dll functions
  • TagsLibrary_Create: HTags;

    Create a tag library object.
    Return value is a handle to the object.

  • TagsLibrary_Free(Tags: HTags): LongBool;

    Free the object created with 'TagsLibrary_Create'.
    Note: there's no clear function for the object, always re-create the tags library object if you want to clear it.

  • TagsLibrary_Load(Tags: HTags; FileName: PWideChar; TagType: TTagType; ParseTags: LongBool): Integer;

    Loads the tags from the specified 'FileName'. When 'TagType' is 'ttAutomatic' all the supported tag types are loaded (in the order specified by 'TagsLibrary_SetTagLoadPriority'), to load a particular tag type, specify 'TagType' to something other then 'ttAutomatic'.
    To check if tags are found use the function 'TagsLibrary_Loaded'.
    'ParseTags' should be always 'True', but if you want to load a particular tag type then this flag specifies wheather to parse the tags to be used by 'ttAutomatic'. In other words, set 'ParseTags' to 'False' if you will use for example 'ttID3v2' in all function calls (so then there's no need to parset the tags).
    Return value is an error code, '0' means success.

  • TagsLibrary_LoadFromBASS(Tags: HTags; Channel: Cardinal): Integer;

    Load the tags from a BASS channel handle. Usefull for URL (internet) streams. But can be used for local (file) streams also.
    Return value is an error code, '0' means success.

  • TagsLibrary_Save(Tags: HTags; FileName: PWideChar; TagType: TTagType): Integer;

    Save the tags to file specified by 'FileName'. Using 'TagType' 'ttAutomatic' will decide the format by the following:
    - If the 'FileName' is the same as the one used for loading, the tags will be saved in all formats which were present in the source file.
    - If the 'FileName' is different, format will be decided by the file extension.
    To save a particular tag type specify it with 'TagType' as eg. 'ttID3v2'.
    Return value is an error code, '0' means success.

  • TagsLibrary_SaveEx(Tags: HTags; FileName: PWideChar; TagType: TTagType): Integer;

    Save the tags without conversion ('ParseTag' and tags set with 'ttAutomatic' option will not have effect). Usefull if you want to work with a particular tag type.
    Return value is an error code, '0' means success.

  • TagsLibrary_RemoveTag(FileName: PWideChar; TagType: TTagType): Integer;

    Remove all tags from 'FileName', to delete a particular tags type set it with 'TagType'.
    Return value is an error code, '0' means success.

  • TagsLibrary_GetTag(Tags: HTags; Name: PWideChar; TagType: TTagType): PWideChar;

    Get a pointer to a unicode (wide) string tag specified by 'Name' (for example 'TITLE').
    Return value is pointing to an empty string if no such tag found.

  • TagsLibrary_Loaded(Tags: HTags; TagType: TTagType): LongBool;

    Test if tags are loaded. If 'TagType' is 'ttAutomatic' then the return value is 'False' if no tag exists in the file at all, 'True' otherwise.

  • TagsLibrary_GetTagEx(Tags: HTags; Name: PWideChar; TagType: TTagType; var ExtTag: TExtTag): LongBool;

    Get extended (detailed) information about a tag. Usefull for 'ttID3v2' TXXX, WXXX, COMM frames.
    Return value is 'False' if no tag specified by 'Name' (eg. 'TITLE') is present in the tags.

  • TagsLibrary_GetTagByIndexEx(Tags: HTags; Index: Integer; TagType: TTagType; var ExtTag: TExtTag): LongBool;

    Same as 'TagsLibrary_GetTagEx' just get the tag details by index. To iterate over all the tags use the 'TagsLibrary_TagCount' function and this function in a for loop.
    Return value is 'False' if 'Index' is invalid.

  • TagsLibrary_SetTag(Tags: HTags; Name: PWideChar; Value: PWideChar; TagType: TTagType): LongBool;

    Simply set a tag specified by 'Name' to value specified by 'Value'. If there's already a field with the specified name it will be replaced with the new value.
    When using with a particular tag type, eg. 'ttID3v2', 'Name' specifies an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example 'ŠART' (artist).
    Return value is 'True' on success.

  • TagsLibrary_SetTagEx(Tags: HTags; TagType: TTagType; ExtTag: TExtTag): LongBool;

    Set a tag with extended (detailed) attributes. 'ExtTag.Name' specifies the tag's name, an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example 'ŠART' (artist).
    ExtTag.ValueSize specifies ExtTag.Value length in bytes.
    For using it in 'ttAutomatic' mode, use 'ExtTag.Name' as 'TITLE'.
    This function is mostly usefull for 'ttID3v2' WXXX and TXXX frames.
    Return value is 'True' on success.

  • TagsLibrary_AddTag(Tags: HTags; Name: PWideChar; Value: PWideChar; TagType: TTagType): Integer;

    Add a tag specified by 'Name' to value specified by 'Value'. If there's already a field with the specified name a new one will added, and the previous is preserved.
    When using with a particular tag type, eg. 'ttID3v2', 'Name' specifies an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example 'ŠART' (artist).
    But be carefull because eg. MP4 tags canot contain multiple atoms of the same type.
    Return value is 'True' on success.

  • TagsLibrary_AddTagEx(Tags: HTags; TagType: TTagType; ExtTag: TExtTag): Integer;

    Add a tag with extended (detailed) attributes. 'ExtTag.Name' specifies the tag's name, an ID3v2 frame type, eg. 'TIT2' (which is title), or an MP4 tag atom name, for example 'ŠART' (artist).
    ExtTag.ValueSize specifies ExtTag.Value length in bytes.
    For using it in 'ttAutomatic' mode, use 'ExtTag.Name' as 'TITLE'.
    This function is mostly usefull for 'ttID3v2' WXXX and TXXX frames.
    Return value is 'True' on success.

  • TagsLibrary_TagCount(Tags: HTags; TagType: TTagType): Integer;

    Retrieve the tag count for the specified 'TagType' tag type.
    Note that for example for ID3v2 tags the cover art is also a tag (frame) so will be included in the return value.

  • TagsLibrary_CoverArtCount(Tags: HTags; TagType: TTagType): Integer;

    Retrieve the cover art count for the 'TagType'.

  • TagsLibrary_GetCoverArt(Tags: HTags; TagType: TTagType; Index: Integer; var CoverArt: TCoverArtData): LongBool;

    Extract the cover art specified by 'Index' into the 'CoverArt' structure.
    'CoverArt.Data' points to the cover art data bytes, 'CoverArt.DataSize' specifies the data size. You can use 'CoverArt.MIMEType' or 'CoverArt.PictureFormat' to identify the cover art picture format.
    Return value is 'True' on success.

  • TagsLibrary_DeleteCoverArt(Tags: HTags; TagType: TTagType; Index: Integer): LongBool;

    Delete a cover art specified by 'Index'. Use 'TagsLibrary_CoverArtCount' to check how many cover arts are in the tag.
    Return value is 'True' on success.

  • TagsLibrary_SetCoverArt(Tags: HTags; TagType: TTagType; Index: Integer; var CoverArt: TCoverArtData): LongBool;

    Set cover art specified by 'Index'.
    Try to fill in all the attributes in 'CoverArt', although not all are needed for all the tag types.
    Return value is 'True' on success.

  • TagsLibrary_AddCoverArt(Tags: HTags; TagType: TTagType; var CoverArt: TCoverArtData): Integer;

    Add a new cover art.
    Try to fill in all the attributes in 'CoverArt', although not all are needed for all the tag types.
    Return value is 'True' on success.

  • TagsLibrary_SetTagLoadPriority(Tags: HTags; TagPriorities: TTagPriority): LongBool;

    Set the tag loading priority array. The value in 'TagPriorities[0]' has the highest priority.
    Use 'Tags' = 'nil' or 'null' to set the global tag load priority. All tag library classes created after calling this function will use these settings.
    Return value should be always 'True'.

  • TagsLibrary_GetTagData(Tags: HTags; Index: Integer; TagType: TTagType; var TagData: TTagData): LongBool;

    Get binary data of a tag frame. Usefull for ID3v2 GEOB, etc. binary frames and MP4 binary atoms.
    When using 'TagType' = 'ttMP4', 'TagData.DataType' is for example:
    0: binary
    1: text
    13: cover art
    14: cover art
    21: binary
    Return value is 'True' on success.

  • TagsLibrary_SetTagData(Tags: HTags; Index: Integer; TagType: TTagType; TagData: TTagData): LongBool;

    Set binary data of a tag frame. Usefull for ID3v2 GEOB, APEv2 binary frames, etc. and MP4 tags.
    When using 'TagType' = 'ttMP4', 'TagData.DataType' is needed for example:
    0: binary
    1: text
    13: cover art
    14: cover art
    21: binary
    Return value is 'True' on success.

  • TagsLibrary_GetCARTPostTimer(Tags: HTags; Index: Integer; var PostTimer: TCARTPostTimer): LongBool;

    Get WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
    Result is 'False' if 'Index' is out of bounds.

  • TagsLibrary_SetCARTPostTimer(Tags: HTags; Index: Integer; PostTimer: TCARTPostTimer): LongBool;

    Set WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
    Result is 'False' if 'Index' is out of bounds.

  • TagsLibrary_ClearCARTPostTimer(Tags: HTags; Index: Integer): LongBool;

    Clear WAV CART post timer specified by 'Index'. There are 8 CART post timers, Index range is 0 to 7.
    Result is 'False' if 'Index' is out of bounds.

  • TagsLibrary_GetConfig(Tags: HTags; var Value: NativeUInt; Option: Integer; TagType: TTagType): LongBool;
  • TagsLibrary_SetConfig(Tags: HTags; Value: NativeUInt; Option: Integer; TagType: TTagType): LongBool;

    Get and set configuration settings. If 'Tags' = nil then means global parameters.
    'Option' can be:
    • TAGSLIBRARY_PADDING_SIZE_TO_WRITE: set padding size to write when saving the tags. When set as global, setting will affect all newly created Tags objects.
    • TAGSLIBRARY_PARSE_OGG_PLAYTIME: set getting of Ogg Vorbis and Opus audio file's play time. Setting to 'True' results longer loading time. Default is 'True'. When set as global, setting will affect all newly created Tags objects.
    • TAGSLIBRARY_PARSE_ID3v2_AUDIO_ATTRIBUTES: set getting of MPEG, WAV, AIFF/AIFC, DSD .dsf audio file's attributes. Setting to 'False' results quicker loading. Default is 'True'. When set as global, setting will affect all newly created Tags objects.

  • TagsLibrary_GetVendor(Tags: HTags; TagType: TTagType): PWideChar;
  • TagsLibrary_SetVendor(Tags: HTags; Vendor: PWideChar; TagType: TTagType): LongBool;

    Get and set vendor string. Applies to Ogg Vorbis, Opus and Flac.
    Return value is nil/False otherwise.

  • TagsLibrary_GetAudioAttributes(Tags: HTags; AudioType: TAudioType; Attributes: Pointer): Pointer;

    Get source audio file's attributes.
    Supported 'AudioTypes's:
    • atAutomatic: returns 'TAudioAttributes' structure (automatic source detection) in 'Attributes'
    • atFlac: returns a 'TFlacAudioAttributes' structure (Flac and Ogg Flac) in 'Attributes'
    • atMPEG: returns a 'TMPEGAudioAttributes' structure (.mp3, .mp2, .mp1, .mpa) in 'Attributes'
    • atDSDDSF: returns a 'TDSFAudioAttributes' structure (DSD .dsf) in 'Attributes'
    • atOpus: returns a 'TOpusAudioAttributes' structure (Opus) in 'Attributes'
    • atVorbis: returns a 'TVorbisAudioAttributes' structure (Vorbis) in 'Attributes'
    • atWAV: returns a 'TWAVEAudioAttributes' structure (WAV and RF64) in 'Attributes'
    • atAIFF: returns a 'TAIFFAudioAttributes' structure (AIFF and AIFC) in 'Attributes'
    • atWMA: returns a 'TWMAAudioAttributes' structure (WMA) in 'Attributes'

Notes for the .dll version

All pointers to tag data are valid only until changing the tag (setting the particular value, or loading new data), or as long as the tags library class is valid, so copy the returned strings if you need them afterwards.


Notes for WMA support

As WMA is supported through WMVCORE.DLL which is part of Windows, WMA reading/writing is only supported on the Windows platform.


Useful information

Links



[Top]