C++ library for reading and writing MP4/M4A/AAC (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Martchus a59a01cfe9 Prevent warning when adding album artist to MP4 1 week ago
aac Fix warning in AacSbrInfo 4 months ago
adts Adapt to changes in c++utilities 4 months ago
av1 Adapt to changes in c++utilities 4 months ago
avc Adapt to changes in c++utilities 4 months ago
avi Adapt to changes in c++utilities 4 months ago
doc Improve refs in "Adding new fields" doc 9 months ago
flac Adapt to changes in c++utilities 4 months ago
id3 Rename Id2v2 frame ID "grouping" to "albumArtist" 4 months ago
ivf Adapt to changes in c++utilities 4 months ago
matroska Apply clang-format 4 months ago
mp4 Prevent warning when adding album artist to MP4 1 week ago
mpegaudio Adapt to changes in c++utilities 4 months ago
ogg Adapt to changes in c++utilities 4 months ago
opus Adapt to changes in c++utilities 4 months ago
scripts Detect Opus and FLAC in MP4 3 weeks ago
testfiles Add MP4 testfile with chapters 6 months ago
tests Add conversion from ISO-639-2/B codes to language names 2 months ago
vorbis Support lyrics in Vorbis/FLAC 2 months ago
wav Refactor WaveFormatHeader::parse() 4 months ago
.gitignore Apply clang-format later 2 years ago
CMakeLists.txt Prevent warning when adding album artist to MP4 1 week ago
LICENSE Initial commit 4 years ago
README.md Document handling different types and encodings 4 months ago
abstractattachment.cpp Adapt to changes in c++utilities 4 months ago
abstractattachment.h Adapt to c++utilities v5 5 months ago
abstractchapter.cpp Adapt to changes in c++utilities 4 months ago
abstractchapter.h Adapt to changes in c++utilities 4 months ago
abstractcontainer.cpp Adapt to changes in c++utilities 4 months ago
abstractcontainer.h Adapt to changes in c++utilities 4 months ago
abstracttrack.cpp Add conversion from ISO-639-2/B codes to language names 2 months ago
abstracttrack.h Adapt to changes in c++utilities 4 months ago
aspectratio.cpp Adapt to c++utilities v5 5 months ago
aspectratio.h Adapt to changes in c++utilities 4 months ago
backuphelper.cpp Adapt to changes in c++utilities 4 months ago
backuphelper.h Adapt to changes in c++utilities 4 months ago
basicfileinfo.cpp Adapt to changes in c++utilities 4 months ago
basicfileinfo.h Adapt to changes in c++utilities 4 months ago
caseinsensitivecomparer.h Apply clang-format 1 year ago
diagnostics.cpp Refactor formatting list of values 1 year ago
diagnostics.h Adapt to changes in c++utilities 4 months ago
exceptions.cpp Use noexcept directly 8 months ago
exceptions.h Use noexcept directly 8 months ago
fieldbasedtag.h Adjust values()/setValues() to handle multiple values per text frame 1 year ago
genericcontainer.h Adapt to c++utilities v5 5 months ago
genericfileelement.h Adapt to changes in c++utilities 4 months ago
generictagfield.h Replace typedef with using 1 year ago
global.h Adapt to changes in c++utilities 4 months ago
language.cpp Add conversion from ISO-639-2/B codes to language names 2 months ago
language.h Add conversion from ISO-639-2/B codes to language names 2 months ago
languages.csv Add conversion from ISO-639-2/B codes to language names 2 months ago
localeawarestring.cpp Apply clang-format 1 year ago
localeawarestring.h Apply clang-format 1 year ago
margin.h Adapt to changes in c++utilities 4 months ago
mediafileinfo.cpp Add conversion from ISO-639-2/B codes to language names 2 months ago
mediafileinfo.h Adapt to changes in c++utilities 4 months ago
mediaformat.cpp Distinguish text and "meta" tracks in MP4 6 months ago
mediaformat.h Distinguish text and "meta" tracks in MP4 6 months ago
positioninset.h Adapt to changes in c++utilities 4 months ago
progressfeedback.cpp Document progress feedback 1 year ago
progressfeedback.h Adapt to c++utilities v5 5 months ago
settings.h Use helper for flag enum from c++utilities 2 months ago
signature.cpp Adapt to changes in c++utilities 4 months ago
signature.h Adapt to changes in c++utilities 4 months ago
size.cpp Apply clang-format 1 year ago
size.h Adapt to changes in c++utilities 4 months ago
tag.cpp Add Tag::supportsMultipleValues() 1 year ago
tag.h Adapt to c++utilities v5 5 months ago
tagtarget.cpp Adapt to changes in c++utilities 4 months ago
tagtarget.h Adapt to c++utilities v5 5 months ago
tagvalue.cpp Fix old namespaces being mentioned in the documentation 1 month ago
tagvalue.h Add options for TagValue comparison 2 months ago

README.md

Tag Parser

C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags.

Supported formats

The tag library can read and write the following tag formats:

  • iTunes-style MP4/M4A tags (MP4-DASH is supported)
  • ID3v1 and ID3v2 tags
    • conversion between ID3v1 and different versions of ID3v2 is possible
  • Vorbis, Opus and FLAC comments in Ogg streams
    • cover art via “METADATA_BLOCK_PICTURE” is supported
  • Vorbis comments and “METADATA_BLOCK_PICTURE” in raw FLAC streams
  • Matroska/WebM tags and attachments

File layout options

Tag position

The library allows you to choose whether tags should be placed at the beginning or at the end of an MP4/Matroska file.

Padding

Padding allows adding additional tag information without rewriting the entire file or appending the tag. Usage of padding can be configured:

  • minimum/maximum padding: The file is rewritten if the padding would fall below/exceed the specifed limits.
  • preferred padding: If the file needs to be rewritten the preferred padding is used.

Default value for minimum and maximum padding is zero. Hence the library will almost always have to rewrite the entire file to apply changes. To prevent this, set at least the maximum padding to a higher value.

It is also possible to force rewriting the entire file always.

Taking advantage of padding is currently not supported when dealing with Ogg streams (it is supported when dealing with raw FLAC streams).

Additional features

The library can also display technical information such as the ID, format, language, bitrate, duration, size, timestamps, sampling frequency, FPS and other information of the tracks.

It also allows to inspect and validate the element structure of MP4 and Matroska files.

Text encoding, Unicode support

The library is aware of different text encodings and can convert between different encodings using iconv.

Windows specific

A workaround to support filenames containing non-ASCII characters (despite the lack of an UTF-8 supporting std::fstream under Windows) can be enabled by adding -DUSE_NATIVE_FILE_BUFFER=ON to the CMake arguments when building c++utilities. It is not sufficient to specify this option only when building tagparser.

Usage

This example shows how to read and write tag fields in a format-independent way:

#include <tagparser/mediafileinfo.h>
#include <tagparser/diagnostics.h>

// create a MediaFileInfo for high-level access to overall functionality of the library
TagParser::MediaFileInfo fileInfo;
// create container for errors, warnings, etc.
Diagnostics diag;

// open file (might throw ios_base::failure)
fileInfo.setPath("/path/to/some/file");
fileInfo.open();
// parse tags
// (might throw exception derived from TagParser::Failure for fatal parsing error or ios_base::failure for IO errors)
fileInfo.parseTags(diag);

// get first tag as an object derived from the Tag class
auto tag = fileInfo.tags().at(0);
// extract title and convert it to UTF-8 std::string
// (toString() might throw ConversionException)
auto title = tag->value(TagParser::KnownField::Title).toString(TagParser::TagTextEncoding::Utf8);

// change album using an encoding suitable for the tag format
tag->setValue(TagParser::KnownField::Album, TagParser::TagValue("some UTF-8 string", TagParser::TagTextEncoding::Utf8, tag->proposedTextEncoding()));

// create progress
TagParser::AbortableProgressFeedback progress([callback for status update], [callback for percentage-only updates]);

// apply changes to the file on disk
// (might throw exception derived from TagParser::Failure for fatal processing error or ios_base::failure for IO errors)
fileInfo.applyChanges(diag, progress);

Summary

  • The most important class is TagParser::MediaFileInfo providing access to everything else.
  • IO errors are propagated via standard std::ios_base::failure.
  • Fatal processing errors are propagated by throwing a class derived from TagParser::Failure.
  • All operations which might generate warnings, non-fatal errors, … take a TagParser::Diagnostics object to store those messages.
  • All operations which can be aborted or provide progress feedback take a TagParser::AbortableProgressFeedback object for callbacks and aborting.
  • Field values are stored using TagParser::TagValue objects. Those objects erase the actual type similar to QVariant from the Qt framework. The documentation of TagParser::TagValue covers how different types and encodings are handled.

Further documentation

For more examples check out the command line interface of Tag Editor. API documentation can be generated using Doxygen with make tagparser_apidoc.

Bugs, stability

Bugs can be reported on GitHub.

It is recommend to create backups before editing because I can not test whether the library works with all kinds of files. (When forcing rewrite a backup is always created.)

Build instructions

The tagparser library depends on c++utilities and is built in the same way. It also depends on zlib. For checking integrity of testfiles, the OpenSSL crypto library is required.

TODOs

  • Support more formats (EXIF, PDF metadata, Theora, …)
  • Support adding cue-sheet to FLAC files

More TODOs are tracked in the issue section at GitHub.