C++ library for reading and writing MP4/M4A/AAC (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Go to file
Martchus acfb9ef219 Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments
* Move those fields into their corresponding
  TRACKNUMBER/DISCNUMBER/PARTNUMBER fields after parsing so they are
  accessible via just one field as PositionInSet which is in line with
  other tag formats and also how other software like VLC expect the total
  to be specified
* NOT implemented yet: Move those fields optionally back into separate
  fields when serializing
2024-02-28 21:36:06 +01:00
.github Add stalebot config 2022-04-12 01:04:24 +02:00
aac Silence/fix GCC's maybe-uninitialized warnings 2023-10-31 20:05:13 +01:00
adts Determine "effective size" via file info instead of track implementations 2023-05-16 22:39:26 +02:00
av1 Adapt to changes in c++utilities 2019-06-12 20:40:45 +02:00
avc Fix spelling and typos 2021-07-02 11:12:39 +02:00
avi Adapt to changes in c++utilities 2019-06-10 23:11:39 +02:00
cmake/scripts Ease setting up build by downloading iso_639-2.json automatically 2023-03-04 19:00:24 +01:00
doc Improve various details of documentation 2024-01-23 00:29:11 +01:00
flac Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments 2024-02-28 21:36:06 +01:00
id3 Add ID3v2 frame definitions for publisher web page and user defined URLs 2023-12-29 17:07:14 +01:00
ivf Fix typo 2023-05-08 11:15:53 +02:00
matroska Fix unity builds 2024-01-30 23:31:15 +01:00
mp4 Fix unity builds 2024-01-30 23:31:15 +01:00
mpegaudio Fix duration and bitrate calculation of MP3 files via XING header 2023-08-21 12:09:07 +02:00
ogg Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments 2024-02-28 21:36:06 +01:00
opus Use generic `toInt()` function which relies less on compiler optimizations 2023-05-18 00:52:28 +02:00
scripts Extend Ogg related tests 2021-08-18 22:48:17 +02:00
testfiles Add MP4 testfile with chapters 2019-03-28 17:54:18 +01:00
tests Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments 2024-02-28 21:36:06 +01:00
vorbis Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments 2024-02-28 21:36:06 +01:00
wav Fix warnings 2021-03-20 21:26:25 +01:00
.gitignore Ignore iso_639-2.json 2023-05-11 22:59:09 +02:00
CMakeLists.txt Fix unity builds 2024-01-30 23:31:15 +01:00
LICENSE Initial commit 2015-04-22 19:11:19 +02:00
README.md Improve various details of documentation 2024-01-23 00:29:11 +01:00
abstractattachment.cpp Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
abstractattachment.h Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
abstractchapter.cpp Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
abstractchapter.h Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
abstractcontainer.cpp Improve dealing with muxing/writing application of Matroska files 2023-08-08 17:18:02 +02:00
abstractcontainer.h Improve dealing with muxing/writing application of Matroska files 2023-08-08 17:18:02 +02:00
abstracttrack.cpp Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
abstracttrack.h Determine "effective size" via file info instead of track implementations 2023-05-16 22:39:26 +02:00
aspectratio.cpp Adapt to c++utilities v5 2019-05-04 16:04:21 +02:00
aspectratio.h Make many constructors explicit to avoid unintended implicit conversions 2020-12-05 20:48:57 +01:00
backuphelper.cpp Use `makeNativePath()` instead of `u8path()` 2022-03-17 22:41:35 +01:00
backuphelper.h Use `std::filesystem` in backup helper code 2021-09-11 23:54:49 +02:00
basicfileinfo.cpp Fix spelling and typos 2021-07-02 11:12:39 +02:00
basicfileinfo.h Improve passing paths 2021-04-23 22:16:43 +02:00
caseinsensitivecomparer.h Fix spelling and typos 2021-07-02 11:12:39 +02:00
diagnostics.cpp Use std::string_view where it makes sense 2021-01-30 21:53:06 +01:00
diagnostics.h Use std::string_view where it makes sense 2021-01-30 21:53:06 +01:00
exceptions.cpp Improve documentation 2020-11-05 19:52:09 +01:00
exceptions.h Use noexcept directly 2019-02-17 17:14:07 +01:00
fieldbasedtag.h Apply clang-format 2023-02-03 13:31:40 +01:00
genericcontainer.h Simplify code 2021-12-31 00:30:11 +01:00
genericfileelement.h Generalize copy functions in GenericFileElement to eventually use sendfile64() 2023-05-16 22:58:04 +02:00
generictagfield.h Apply clang-format 2023-02-03 13:31:40 +01:00
global.h Apply change of `global.h` template 2024-02-27 01:57:17 +01:00
localeawarestring.cpp Apply clang-format 2018-03-07 01:17:50 +01:00
localeawarestring.h Add Locale class to deal with differently specified languages/countries 2020-12-16 17:48:08 +01:00
localehelper.cpp Fix spelling and typos 2021-07-02 11:12:39 +02:00
localehelper.h Remove unused optional header from localehelper.h 2021-01-20 20:10:56 +01:00
margin.h Make many constructors explicit to avoid unintended implicit conversions 2020-12-05 20:48:57 +01:00
mediafileinfo.cpp Use auto-syntax in places touched by previous commit consistently 2023-10-31 20:06:38 +01:00
mediafileinfo.h Handle TRACKTOTAL/DISCTOTAL/PARTTOTAL fields in Vorbis Comments 2024-02-28 21:36:06 +01:00
mediaformat.cpp Add media format entry for H.266 2023-02-18 21:43:16 +01:00
mediaformat.h Add media format entry for H.266 2023-02-18 21:43:16 +01:00
positioninset.h Allow setting position/total of PositionInSet 2023-08-01 00:24:28 +02:00
progressfeedback.cpp Document progress feedback 2018-06-03 20:32:35 +02:00
progressfeedback.h Apply clang-format 2023-02-03 13:31:40 +01:00
settings.h Use helper for flag enum from c++utilities 2019-08-12 20:22:57 +02:00
signature.cpp Use generic `toInt()` function which relies less on compiler optimizations 2023-05-18 00:52:28 +02:00
signature.h Fix typo in ContainerFormat enum 2023-05-16 23:00:32 +02:00
size.cpp Fix spelling and typos 2021-07-02 11:12:39 +02:00
size.h Fix spelling and typos 2021-07-02 11:12:39 +02:00
tag.cpp Allow extending important classes without ABI break 2023-05-16 22:20:48 +02:00
tag.h Support publisher webpage in Vorbis comments 2023-12-29 16:50:41 +01:00
tagtarget.cpp Avoid unqualified calls to `std::move` 2023-02-20 19:54:42 +01:00
tagtarget.h Add `TagTarget::matches()` 2021-12-31 00:31:32 +01:00
tagtype.h Move TagType into separate header 2022-06-20 21:21:11 +02:00
tagvalue.cpp Fix typo 2023-07-30 14:40:15 +02:00
tagvalue.h Expose tagDataTypeString() 2023-07-29 16:02:14 +02:00

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
    • mainly for use in MP3 files but can be added to any kind of file
  • 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

Further remarks:

  • Unsupported file contents (such as unsupported tag formats) are generally preserved as-is.
  • Note that APE tags are not supported. APE tags in the beginning of a file are strongly unrecommended and thus discarded when applying changes. APE tags at the end of the file are preserved as-is when applying changes.

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

Usage

  • For building/installing the library, checkout the build instructions below.
  • To use the library with CMake, use its find module (e.g. find_package(tagparser 10.1.0 REQUIRED)) which provides the imported target tagparser you can link against. Otherwise, use the pkg-config module tagparser to query the required compiler/linker flags.
  • For a code example that shows how to read and write tag fields in a format-independent way, have a look at example.cpp.
  • 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 might be aborted or might 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 cmake --build … --target 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, iso-codes and requires at least CMake 3.19. Tests depend on CppUnit. For checking integrity of testfiles, the OpenSSL crypto library is required.

The location of the JSON file from iso-codes can be specified via the CMake variable LANGUAGE_FILE_ISO_639_2.

For building multiple projects in one go (c++utilities, tagparser and the tag editor), checkout the "Building this straight" instructions.

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.

Copyright © 2015-2024 Marius Kittler

All code is licensed under GPL-2-or-later.