Introduction

TagLib is a library for reading and editing audio metadata, commonly known as tags.

Features:

A clean, high level, C++ API for handling audio metadata.
Format specific APIs for advanced API users.
ID3v1, ID3v2, APE, FLAC, Xiph, iTunes-style MP4 and WMA tag formats.
MP3, MPC, FLAC, MP4, ASF, AIFF, WAV, DSF, DFF, TrueAudio, WavPack, Ogg FLAC, Ogg Vorbis, Speex and Opus file formats.
Basic audio file properties such as length, sample rate, etc.
Long term binary and source compatibility.
Extensible design, notably the ability to add other formats or extend current formats as a library user.
Full support for unicode and internationalized tags.
Dual MPL and LGPL licenses.
No external toolkit dependencies.

Why TagLib?

TagLib originally was written to provide an updated and improved ID3v2 implementation in C++ for use in a variety of Open Source projects. Since development began in 2002 and the 1.0 release in 2004 it has expanded to cover a wide variety of tag and file formats and is used in a wide variety of Open Source and proprietary applications. It now supports a variety of UNIXes, including Apple's macOS, as well as Microsoft Windows.

Usage in Commercial Applications

TagLib's licenses do allow usage within proprietary (closed) applications, however TagLib is not public domain. Please note the requirements of the LGPL or MPL, and adhere to at least one of them. In simple terms, you must at a minimum note your usage of TagLib, note the licensing terms of TagLib and if you make changes to TagLib publish them. Please review the licenses above before using TagLib in your software. Note that you may choose either the MPL or the LGPL, you do not have to fulfill the requirements of both.

Installing TagLib

Please see the TagLib website for the latest downloads.

TagLib can be built using the CMake build system. TagLib installs a CMake configuration and a taglib-config and pkg-config file to make it easier to integrate into various build systems. Note that TagLib's include install directory must be included in the header include path. Simply adding <taglib/tag.h> will not work.

Detailed instructions about building TagLib itself and building with TagLib can be found in INSTALL.md

Getting Started

TagLib provides both simple, abstract APIs which make it possible to ignore the differences between tagging formats and format specific APIs which allow programmers to work with the features of specific tagging schemes. There is a similar abstraction mechanism for AudioProperties .

The best place to start is with the Class Hierarchy linked at the top of the page. The File and AudioProperties classes and their subclasses are the core of TagLib. The FileRef class is also a convenient way for using a value-based handle.

Note: When working with FileRef please consider that it has only the most basic (extension-based) file type resolution. Please see its documentation on how to plug in more advanced file type resolution. (Such resolution may be part of later TagLib releases by default.)

Here's a very simple example with TagLib:

TagLib::FileRef f("Latex Solar Beef.mp3");
TagLib::String artist = f.tag()->artist(); // artist == "Frank Zappa"
 
f.tag()->setAlbum("Fillmore East");
f.save();
 
TagLib::FileRef g("Free City Rhymes.ogg");
TagLib::String album = g.tag()->album(); // album == "NYC Ghosts & Flowers"
 
g.tag()->setTrack(1);
g.save();

If the basic tag interface, which provides methods like title() , artist() , album() , comment() , genre() , year() , track() and the corresponding setters, is not enough, the PropertyMap interface offers a flexible abstraction for textual metadata. See Mapping of Properties to Various Formats for details about the mapping of tags to properties.

TagLib::PropertyMap props = f.properties();
TagLib::StringList artists = props["ARTIST"];
artists.append("Jim Pons");
props["ARTIST"] = artists;
f.setProperties(props);
f.save();

An additional abstraction is provided to handle complex (i.e. non textual) properties.

TagLib::ByteVector data = ...;
f.setComplexProperties("PICTURE", {
  {
    {"data", data},
    {"pictureType", "Front Cover"},
    {"mimeType", "image/jpeg"}
  }
});

Finally, for full control, there are specific types for all supported metadata formats.

if(auto file = dynamic_cast<TagLib::MPEG::File *>(f.file())) {
  if(auto id3v2Tag = file->ID3v2Tag()) {
    auto frames = id3v2Tag->frameList("SYLT");
    if(!frames.isEmpty()) {
      if(auto syltFrame = dynamic_cast<TagLib::ID3v2::SynchronizedLyricsFrame *>(
          frames.front())) {
        auto text = syltFrame->synchedText();
        // ...
      }
    }
  }
}

More examples can be found in the examples directory of the source distribution.

Contact

Questions about TagLib should be directed to the TagLib mailing list, not directly to the author.

Author: TagLib authors.