Tag Parser  7.1.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
README.md
Go to the documentation of this file.
1 # Tag Parser
2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags.
3 
4 ## Supported formats
5 The tag library can read and write the following tag formats:
6 
7 * iTunes-style MP4/M4A tags (MP4-DASH is supported)
8 * ID3v1 and ID3v2 tags
9  * conversion between ID3v1 and different versions of ID3v2 is possible
10 * Vorbis, Opus and FLAC comments in Ogg streams
11  * cover art via "METADATA_BLOCK_PICTURE" is supported
12 * Vorbis comments and "METADATA_BLOCK_PICTURE" in raw FLAC streams
13 * Matroska/WebM tags and attachments
14 
15 ## File layout options
16 ### Tag position
17 The library allows you to choose whether tags should be placed at the beginning or at
18 the end of an MP4/Matroska file.
19 
20 ### Padding
21 Padding allows adding additional tag information without rewriting the entire file
22 or appending the tag. Usage of padding can be configured:
23 * minimum/maximum padding: The file is rewritten if the padding would fall below/exceed the specifed limits.
24 * preferred padding: If the file needs to be rewritten the preferred padding is used.
25 
26 Default value for minimum and maximum padding is zero. Hence the library will almost always have to rewrite
27 the entire file to apply changes. To prevent this, set at least the maximum padding to a higher value.
28 
29 It is also possible to force rewriting the entire file always.
30 
31 Taking advantage of padding is currently not supported when dealing with Ogg streams (it is supported when dealing with raw FLAC streams).
32 
33 ## Additional features
34 The library can also display technical information such as the ID, format, language, bitrate,
35 duration, size, timestamps, sampling frequency, FPS and other information of the tracks.
36 
37 It also allows to inspect and validate the element structure of MP4 and Matroska files.
38 
39 ## Text encoding, Unicode support
40 The library is aware of different text encodings and can convert between different encodings using iconv.
41 
42 ### Windows specific
43 A workaround to support filenames containing non-ASCII characters (despite the lack of an UTF-8
44 supporting `std::fstream` under Windows) can be enabled by adding `-DUSE_NATIVE_FILE_BUFFER=ON`
45 to the CMake arguments **when building `c++utilities`**. It is *not* sufficient to specify this
46 option only when building `tagparser`.
47 
48 ## Usage
49 This example shows how to read and write tag fields in a format-independent way:
50 
51 ```
52 #include <tagparser/mediafileinfo.h>
53 #include <tagparser/diagnostics.h>
54 
55 using namespace TagParser;
56 
57 // create a MediaFileInfo for high-level access to overall functionality of the library
58 MediaFileInfo fileInfo;
59 // create container for errors, warnings, etc.
60 Diagnostics diag;
61 
62 // open file (might throw ios_base::failure)
63 fileInfo.setPath("/path/to/some/file");
64 fileInfo.open();
65 // parse tags
66 // (might throw exception derived from Failure for fatal parsing error or ios_base::failure for IO errors)
67 fileInfo.parseTags(diag);
68 
69 // get first tag as an object derived from the Tag class
70 auto tag = fileInfo.tags().at(0);
71 // extract title and convert it to UTF-8 std::string
72 // (toString() might throw ConversionException)
73 auto title = tag->value(KnownField::Title).toString(TagTextEncoding::Utf8);
74 
75 // change album using an encoding suitable for the tag format
76 tag->setValue(KnownField::Album, TagValue("some UTF-8 string", TagTextEncoding::Utf8, tag->proposedTextEncoding()));
77 
78 // create progress
79 AbortableProgressFeedback progress([callback for status update], [callback for percentage-only updates]);
80 
81 // apply changes to the file on disk
82 // (might throw exception derived from Failure for fatal processing error or ios_base::failure for IO errors)
83 fileInfo.applyChanges(diag, progress);
84 ```
85 
86 ### Summary
87 
88 * So the most important class is `MediaFileInfo` providing access to everything else.
89 * IO errors are propagated via standard `std::ios_base::failure`.
90 * Fatal processing errors are propagated by throwing a class derived from Failure.
91 * All operations which might generate warnings, non-fatal errors, ... take a `Diagnostics` object to store
92  those messages.
93 * All operations which can be aborted or provide progress feedback take a `AbortableProgressFeedback` object
94  for callbacks and aborting.
95 * Field values are stored using `TagValue` objects. Those objects erase the actual type similar to `QVariant`
96  from the Qt framework.
97 
98 ### Further documentation
99 For more examples check out the command line interface of [Tag Editor](https://github.com/Martchus/tageditor).
100 API documentation can be generated using Doxygen with `make tagparser_apidoc`.
101 
102 ## Bugs, stability
103 It is recommend to create backups before editing because I can not test whether the library
104 works with all kinds of files (when forcing rewrite a backup is always created).
105 
106 ## Build instructions
107 The tagparser library depends on [c++utilities](https://github.com/Martchus/cpp-utilities) and is built
108 in the same way.
109 It also depends on zlib. For checking integrity of testfiles, the OpenSSL crypto
110 library is required.
111 
112 ## TODOs
113 * Support more formats (EXIF, PDF metadata, Theora, ...)
114 * Support adding cue-sheet to FLAC files
115 
116 More TODOs are tracked in the [issue section at GitHub](https://github.com/Martchus/tagparser/issues).