Tag Parser 11.2.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
mediafileinfo.h
Go to the documentation of this file.
1#ifndef TAG_PARSER_MEDIAINFO_H
2#define TAG_PARSER_MEDIAINFO_H
3
5#include "./basicfileinfo.h"
6#include "./settings.h"
7#include "./signature.h"
8
9#include <cstdint>
10#include <memory>
11#include <unordered_set>
12#include <vector>
13
14#include <c++utilities/misc/flagenumclass.h>
15
16namespace TagParser {
17
18class Tag;
19class Id3v1Tag;
20class Id3v2Tag;
21class Mp4Container;
22class Mp4Atom;
23class Mp4Tag;
24class MatroskaContainer;
25class OggContainer;
26class EbmlElement;
27class MatroskaTag;
28class AbstractTrack;
29class VorbisComment;
30class Diagnostics;
31class AbortableProgressFeedback;
32
33enum class MediaType : unsigned int;
34enum class TagType : unsigned int;
35
40enum class ParsingStatus : std::uint8_t {
42 Ok,
45};
46
50enum class MediaFileStructureFlags : std::uint64_t {
51 None,
52 ActualExistingId3v1Tag = (1 << 0),
53};
54
58enum class MediaFileHandlingFlags : std::uint64_t {
59 None,
61 = (1 << 0),
62 ForceRewrite = (1 << 1),
63 ForceTagPosition = (1 << 2),
64 ForceIndexPosition = (1 << 3),
65 NormalizeKnownTagFieldIds = (1 << 4),
66 PreserveRawTimingValues = (1 << 8),
67};
68
69} // namespace TagParser
70
73
74namespace TagParser {
75
77public:
78 // constructor, destructor
79 explicit MediaFileInfo();
80 explicit MediaFileInfo(std::string_view path);
81 explicit MediaFileInfo(std::string &&path);
82 MediaFileInfo(const MediaFileInfo &) = delete;
84 ~MediaFileInfo() override;
85
86 // methods to parse file
87 void parseContainerFormat(Diagnostics &diag, AbortableProgressFeedback &progress);
88 void parseTracks(Diagnostics &diag, AbortableProgressFeedback &progress);
89 void parseTags(Diagnostics &diag, AbortableProgressFeedback &progress);
90 void parseChapters(Diagnostics &diag, AbortableProgressFeedback &progress);
91 void parseAttachments(Diagnostics &diag, AbortableProgressFeedback &progress);
92 void parseEverything(Diagnostics &diag, AbortableProgressFeedback &progress);
93
94 // methods to apply changes
95 void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
96
97 // methods to get parsed information regarding ...
98 // ... the container
99 ContainerFormat containerFormat() const;
100 std::string_view containerFormatName() const;
101 std::string_view containerFormatAbbreviation() const;
102 std::string_view containerFormatSubversion() const;
103 std::string_view mimeType() const;
104 std::uint64_t containerOffset() const;
105 std::uint64_t paddingSize() const;
106 AbstractContainer *container() const;
107 ParsingStatus containerParsingStatus() const;
108 // ... the capters
109 ParsingStatus chaptersParsingStatus() const;
110 std::vector<AbstractChapter *> chapters() const;
111 bool areChaptersSupported() const;
112 // ... the attachments
113 ParsingStatus attachmentsParsingStatus() const;
114 std::vector<AbstractAttachment *> attachments() const;
115 bool areAttachmentsSupported() const;
116 // ... the tracks
117 ParsingStatus tracksParsingStatus() const;
118 std::size_t trackCount() const;
119 std::vector<AbstractTrack *> tracks() const;
120 bool hasTracksOfType(TagParser::MediaType type) const;
121 CppUtilities::TimeSpan duration() const;
122 double overallAverageBitrate() const;
123 std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
124 std::string technicalSummary() const;
125 bool areTracksSupported() const;
126 // ... the tags
127 ParsingStatus tagsParsingStatus() const;
128 bool hasId3v1Tag() const;
129 bool hasId3v2Tag() const;
130 bool hasAnyTag() const;
131 Id3v1Tag *id3v1Tag() const;
132 const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
133 void tags(std::vector<Tag *> &tags) const;
134 std::vector<Tag *> tags() const;
135 void parsedTags(std::vector<Tag *> &tags) const;
136 std::vector<Tag *> parsedTags() const;
137 Mp4Tag *mp4Tag() const;
138 const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
139 VorbisComment *vorbisComment() const;
140 bool areTagsSupported() const;
141
142 // methods to create/remove tags
143 bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
144 bool removeId3v1Tag();
145 Id3v1Tag *createId3v1Tag();
146 bool removeId3v2Tag(Id3v2Tag *tag);
147 bool removeAllId3v2Tags();
148 Id3v2Tag *createId3v2Tag();
149 bool removeTag(Tag *tag);
150 void removeAllTags();
151 void mergeId3v2Tags();
152 bool id3v1ToId3v2();
153 bool id3v2ToId3v1();
154 VorbisComment *createVorbisComment();
155 bool removeVorbisComment();
156 void clearParsingResults();
157
158 // methods to get, set object behaviour
159 const std::string &backupDirectory() const;
160 void setBackupDirectory(std::string_view backupDirectory);
161 void setBackupDirectory(std::string &&backupDirectory);
162 const std::string &saveFilePath() const;
163 void setSaveFilePath(std::string_view saveFilePath);
164 void setSaveFilePath(std::string &&saveFilePath);
165 const std::string &writingApplication() const;
166 void setWritingApplication(std::string_view writingApplication);
167 MediaFileHandlingFlags fileHandlingFlags();
168 void setFileHandlingFlags(MediaFileHandlingFlags flags);
169 bool isForcingFullParse() const;
170 void setForceFullParse(bool forceFullParse);
171 bool isForcingRewrite() const;
172 void setForceRewrite(bool forceRewrite);
173 std::size_t minPadding() const;
174 void setMinPadding(std::size_t minPadding);
175 std::size_t maxPadding() const;
176 void setMaxPadding(std::size_t maxPadding);
177 std::size_t preferredPadding() const;
178 void setPreferredPadding(std::size_t preferredPadding);
179 ElementPosition tagPosition() const;
180 void setTagPosition(ElementPosition tagPosition);
181 bool forceTagPosition() const;
182 void setForceTagPosition(bool forceTagPosition);
183 ElementPosition indexPosition() const;
184 void setIndexPosition(ElementPosition indexPosition);
185 bool forceIndexPosition() const;
186 void setForceIndexPosition(bool forceTagPosition);
187
188protected:
189 void invalidated() override;
190
191private:
192 // private methods internally used when rewriting the file to apply new tag information
193 // currently only the makeMp3File() methods is present; corresponding methods for
194 // other formats are outsourced to container classes
195 void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
196
197 // fields related to the container
198 ParsingStatus m_containerParsingStatus;
199 ContainerFormat m_containerFormat;
200 std::streamoff m_containerOffset;
201 std::uint64_t m_paddingSize;
202 std::vector<std::streamoff> m_actualId3v2TagOffsets;
203 std::unique_ptr<AbstractContainer> m_container;
204 MediaFileStructureFlags m_fileStructureFlags;
205
206 // fields related to the tracks
207 ParsingStatus m_tracksParsingStatus;
208 std::unique_ptr<AbstractTrack> m_singleTrack;
209
210 // fields related to the tag
211 ParsingStatus m_tagsParsingStatus;
212 std::unique_ptr<Id3v1Tag> m_id3v1Tag;
213 std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
214
215 // fields related to the chapters and the attachments
216 ParsingStatus m_chaptersParsingStatus;
217 ParsingStatus m_attachmentsParsingStatus;
218
219 // fields specifying object behaviour
220 std::string m_backupDirectory;
221 std::string m_saveFilePath;
222 std::string m_writingApplication;
223 std::size_t m_minPadding;
224 std::size_t m_maxPadding;
225 std::size_t m_preferredPadding;
226 ElementPosition m_tagPosition;
227 ElementPosition m_indexPosition;
228 MediaFileHandlingFlags m_fileHandlingFlags;
229};
230
235{
236 return m_containerParsingStatus;
237}
238
246{
247 return m_containerFormat;
248}
249
260inline std::string_view MediaFileInfo::containerFormatName() const
261{
262 return TagParser::containerFormatName(m_containerFormat);
263}
264
275inline std::string_view MediaFileInfo::containerFormatSubversion() const
276{
277 return TagParser::containerFormatSubversion(m_containerFormat);
278}
279
283inline std::uint64_t MediaFileInfo::containerOffset() const
284{
285 return static_cast<std::uint64_t>(m_containerOffset);
286}
287
291inline std::uint64_t MediaFileInfo::paddingSize() const
292{
293 return m_paddingSize;
294}
295
300{
301 return m_tagsParsingStatus;
302}
303
308{
309 return m_tracksParsingStatus;
310}
311
320inline std::size_t MediaFileInfo::trackCount() const
321{
322 return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
323}
324
329{
330 return m_chaptersParsingStatus;
331}
332
337{
338 return m_attachmentsParsingStatus;
339}
340
344inline bool MediaFileInfo::hasId3v1Tag() const
345{
346 return m_id3v1Tag != nullptr;
347}
348
352inline bool MediaFileInfo::hasId3v2Tag() const
353{
354 return !m_id3v2Tags.empty();
355}
356
365{
366 return m_id3v1Tag.get();
367}
368
376inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
377{
378 return m_id3v2Tags;
379}
380
386inline const std::string &MediaFileInfo::backupDirectory() const
387{
388 return m_backupDirectory;
389}
390
395inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
396{
397 m_backupDirectory = backupDirectory;
398}
399
404inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
405{
406 m_backupDirectory = std::move(backupDirectory);
407}
408
413inline const std::string &MediaFileInfo::saveFilePath() const
414{
415 return m_saveFilePath;
416}
417
432inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
433{
434 m_saveFilePath = saveFilePath;
435}
436
440inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
441{
442 m_saveFilePath = std::move(saveFilePath);
443}
444
450inline const std::string &MediaFileInfo::writingApplication() const
451{
452 return m_writingApplication;
453}
454
459inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
460{
461 m_writingApplication = writingApplication;
462}
463
475{
476 return m_container.get();
477}
478
483{
484 return m_fileHandlingFlags;
485}
486
491{
492 m_fileHandlingFlags = flags;
493}
494
504{
505 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
506}
507
513inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
514{
515 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
516}
517
522{
523 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
524}
525
529inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
530{
531 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
532}
533
546inline std::size_t MediaFileInfo::minPadding() const
547{
548 return m_minPadding;
549}
550
556inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
557{
558 m_minPadding = minPadding;
559}
560
574inline std::size_t MediaFileInfo::maxPadding() const
575{
576 return m_maxPadding;
577}
578
584inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
585{
586 m_maxPadding = maxPadding;
587}
588
595inline std::size_t MediaFileInfo::preferredPadding() const
596{
597 return m_preferredPadding;
598}
599
605inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
606{
607 m_preferredPadding = preferredPadding;
608}
609
616{
617 return m_tagPosition;
618}
619
631{
632 m_tagPosition = tagPosition;
633}
634
641{
642 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
643}
644
650inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
651{
652 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
653}
654
661{
662 return m_indexPosition;
663}
664
671{
672 m_indexPosition = indexPosition;
673}
674
681{
682 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
683}
684
690inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
691{
692 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
693}
694
695} // namespace TagParser
696
697#endif // TAG_PARSER_MEDIAINFO_H
The AbortableProgressFeedback class provides feedback about an ongoing operation via callbacks.
The AbstractContainer class provides an interface and common functionality to parse and make a certai...
The BasicFileInfo class provides basic file information such as file name, extension,...
Definition: basicfileinfo.h:14
The Diagnostics class is a container for DiagMessage.
Definition: diagnostics.h:156
Implementation of TagParser::Tag for ID3v1 tags.
Definition: id3v1tag.h:10
Implementation of TagParser::Tag for ID3v2 tags.
Definition: id3v2tag.h:78
The MediaFileInfo class allows to read and write tag information providing a container/tag format ind...
Definition: mediafileinfo.h:76
bool isForcingRewrite() const
Returns whether forcing rewriting (when applying changes) is enabled.
const std::vector< std::unique_ptr< Id3v2Tag > > & id3v2Tags() const
Returns pointers to the assigned ID3v2 tags.
std::uint64_t paddingSize() const
Returns the padding size.
std::string_view containerFormatName() const
Returns the name of the container format as C-style string.
void setSaveFilePath(std::string_view saveFilePath)
Sets the "save file path".
std::string_view containerFormatSubversion() const
Returns the subversion of the container format as C-style string.
bool forceIndexPosition() const
Returns whether indexPosition() is forced.
MediaFileHandlingFlags fileHandlingFlags()
Returns the currently configured file handling flags.
ParsingStatus tagsParsingStatus() const
Returns an indication whether tag information has been parsed yet.
void setForceRewrite(bool forceRewrite)
Sets whether forcing rewriting (when applying changes) is enabled.
const std::string & saveFilePath() const
Returns the "save file path" which has been set using setSaveFilePath().
void setFileHandlingFlags(MediaFileHandlingFlags flags)
Replaces all currently configured file handling flags with the specified flags.
void setMaxPadding(std::size_t maxPadding)
Sets the maximum padding to be written before the data blocks when applying changes.
std::size_t trackCount() const
Returns the number of tracks that could be parsed.
void setMinPadding(std::size_t minPadding)
Sets the minimum padding to be written before the data blocks when applying changes.
MediaFileInfo & operator=(const MediaFileInfo &)=delete
std::size_t maxPadding() const
Returns the maximum padding to be written before the data blocks when applying changes.
ParsingStatus tracksParsingStatus() const
Returns an indication whether tracks have been parsed yet.
Id3v1Tag * id3v1Tag() const
Returns a pointer to the assigned ID3v1 tag or nullptr if none is assigned.
std::size_t preferredPadding() const
Returns the padding to be written before the data block when applying changes and the file needs to b...
const std::string & writingApplication() const
Sets the writing application as container-level meta-data.
void setForceTagPosition(bool forceTagPosition)
Sets whether tagPosition() is forced.
void setForceFullParse(bool forceFullParse)
Sets whether forcing a full parse is enabled.
std::size_t minPadding() const
Returns the minimum padding to be written before the data blocks when applying changes.
ParsingStatus attachmentsParsingStatus() const
Returns whether the attachments have been parsed yet.
bool hasId3v2Tag() const
Returns an indication whether an ID3v2 tag is assigned.
void setTagPosition(ElementPosition tagPosition)
Sets the position (in the output file) where the tag information is written when applying changes.
void setWritingApplication(std::string_view writingApplication)
Sets the writing application as container-level meta-data.
bool isForcingFullParse() const
Returns an indication whether forcing a full parse is enabled.
ElementPosition tagPosition() const
Returns the position (in the output file) where the tag information is written when applying changes.
void setBackupDirectory(std::string_view backupDirectory)
Sets the directory used to store backup files.
AbstractContainer * container() const
Returns the container for the current file.
ContainerFormat containerFormat() const
Returns the container format of the current file.
ParsingStatus containerParsingStatus() const
Returns an indication whether the container format has been parsed yet.
MediaFileInfo(const MediaFileInfo &)=delete
std::uint64_t containerOffset() const
Returns the actual container start offset.
bool forceTagPosition() const
Returns whether tagPosition() is forced.
bool hasId3v1Tag() const
Returns an indication whether an ID3v1 tag is assigned.
ParsingStatus chaptersParsingStatus() const
Returns whether the chapters have been parsed yet.
void setIndexPosition(ElementPosition indexPosition)
Sets the position (in the output file) where the index is written when applying changes.
void setPreferredPadding(std::size_t preferredPadding)
Sets the padding to be written before the data block when applying changes and the file needs to be r...
ElementPosition indexPosition() const
Returns the position (in the output file) where the index is written when applying changes.
void setForceIndexPosition(bool forceTagPosition)
Sets whether indexPosition() is forced.
const std::string & backupDirectory() const
Returns the directory used to store backup files.
Implementation of TagParser::Tag for the MP4 container.
Definition: mp4tag.h:97
The Tag class is used to store, read and write tag information.
Definition: tag.h:177
Implementation of TagParser::Tag for Vorbis comments.
Definition: vorbiscomment.h:25
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
constexpr TAG_PARSER_EXPORT std::string_view duration()
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TAG_PARSER_EXPORT std::string_view containerFormatSubversion(ContainerFormat containerFormat)
Returns the subversion of the container format as C-style string.
Definition: signature.cpp:478
ElementPosition
Definition: settings.h:13
TAG_PARSER_EXPORT std::string_view containerFormatAbbreviation(ContainerFormat containerFormat, MediaType mediaType=MediaType::Unknown, unsigned int version=0)
Returns the abbreviation of the container format as C-style string considering the specified media ty...
Definition: signature.cpp:251
TAG_PARSER_EXPORT std::string_view containerFormatName(ContainerFormat containerFormat)
Returns the name of the specified container format as C-style string.
Definition: signature.cpp:373
TagType
Specifies the tag type.
Definition: tag.h:20
ParsingStatus
The ParsingStatus enum specifies whether a certain part of the file (tracks, tags,...
Definition: mediafileinfo.h:40
MediaType
The MediaType enum specifies the type of media data (audio, video, text, ...).
Definition: mediaformat.h:14
MediaFileStructureFlags
The MediaFileStructureFlags enum specifies flags which describing the structure of a media file.
Definition: mediafileinfo.h:50
ContainerFormat
Specifies the container format.
Definition: signature.h:18
MediaFileHandlingFlags
The MediaFileHandlingFlags enum specifies flags which controls the behavior of MediaFileInfo objects.
Definition: mediafileinfo.h:58
CPP_UTILITIES_MARK_FLAG_ENUM_CLASS(TagParser, TagParser::TagCreationFlags)
The TagSettings struct contains settings which can be passed to MediaFileInfo::createAppropriateTags(...
Definition: settings.h:50