Tag Parser 10.3.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};
67
68} // namespace TagParser
69
72
73namespace TagParser {
74
76public:
77 // constructor, destructor
78 explicit MediaFileInfo();
79 explicit MediaFileInfo(std::string_view path);
80 explicit MediaFileInfo(std::string &&path);
81 MediaFileInfo(const MediaFileInfo &) = delete;
83 ~MediaFileInfo() override;
84
85 // methods to parse file
86 void parseContainerFormat(Diagnostics &diag, AbortableProgressFeedback &progress);
87 void parseTracks(Diagnostics &diag, AbortableProgressFeedback &progress);
88 void parseTags(Diagnostics &diag, AbortableProgressFeedback &progress);
89 void parseChapters(Diagnostics &diag, AbortableProgressFeedback &progress);
90 void parseAttachments(Diagnostics &diag, AbortableProgressFeedback &progress);
91 void parseEverything(Diagnostics &diag, AbortableProgressFeedback &progress);
92
93 // methods to apply changes
94 void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
95
96 // methods to get parsed information regarding ...
97 // ... the container
98 ContainerFormat containerFormat() const;
99 std::string_view containerFormatName() const;
100 std::string_view containerFormatAbbreviation() const;
101 std::string_view containerFormatSubversion() const;
102 std::string_view mimeType() const;
103 std::uint64_t containerOffset() const;
104 std::uint64_t paddingSize() const;
105 AbstractContainer *container() const;
106 ParsingStatus containerParsingStatus() const;
107 // ... the capters
108 ParsingStatus chaptersParsingStatus() const;
109 std::vector<AbstractChapter *> chapters() const;
110 bool areChaptersSupported() const;
111 // ... the attachments
112 ParsingStatus attachmentsParsingStatus() const;
113 std::vector<AbstractAttachment *> attachments() const;
114 bool areAttachmentsSupported() const;
115 // ... the tracks
116 ParsingStatus tracksParsingStatus() const;
117 std::size_t trackCount() const;
118 std::vector<AbstractTrack *> tracks() const;
119 bool hasTracksOfType(TagParser::MediaType type) const;
120 CppUtilities::TimeSpan duration() const;
121 double overallAverageBitrate() const;
122 std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
123 std::string technicalSummary() const;
124 bool areTracksSupported() const;
125 // ... the tags
126 ParsingStatus tagsParsingStatus() const;
127 bool hasId3v1Tag() const;
128 bool hasId3v2Tag() const;
129 bool hasAnyTag() const;
130 Id3v1Tag *id3v1Tag() const;
131 const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
132 void tags(std::vector<Tag *> &tags) const;
133 std::vector<Tag *> tags() const;
134 void parsedTags(std::vector<Tag *> &tags) const;
135 std::vector<Tag *> parsedTags() const;
136 Mp4Tag *mp4Tag() const;
137 const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
138 VorbisComment *vorbisComment() const;
139 bool areTagsSupported() const;
140
141 // methods to create/remove tags
142 bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
143 bool removeId3v1Tag();
144 Id3v1Tag *createId3v1Tag();
145 bool removeId3v2Tag(Id3v2Tag *tag);
146 bool removeAllId3v2Tags();
147 Id3v2Tag *createId3v2Tag();
148 bool removeTag(Tag *tag);
149 void removeAllTags();
150 void mergeId3v2Tags();
151 bool id3v1ToId3v2();
152 bool id3v2ToId3v1();
153 VorbisComment *createVorbisComment();
154 bool removeVorbisComment();
155 void clearParsingResults();
156
157 // methods to get, set object behaviour
158 const std::string &backupDirectory() const;
159 void setBackupDirectory(std::string_view backupDirectory);
160 void setBackupDirectory(std::string &&backupDirectory);
161 const std::string &saveFilePath() const;
162 void setSaveFilePath(std::string_view saveFilePath);
163 void setSaveFilePath(std::string &&saveFilePath);
164 const std::string &writingApplication() const;
165 void setWritingApplication(std::string_view writingApplication);
166 MediaFileHandlingFlags fileHandlingFlags();
167 void setFileHandlingFlags(MediaFileHandlingFlags flags);
168 bool isForcingFullParse() const;
169 void setForceFullParse(bool forceFullParse);
170 bool isForcingRewrite() const;
171 void setForceRewrite(bool forceRewrite);
172 std::size_t minPadding() const;
173 void setMinPadding(std::size_t minPadding);
174 std::size_t maxPadding() const;
175 void setMaxPadding(std::size_t maxPadding);
176 std::size_t preferredPadding() const;
177 void setPreferredPadding(std::size_t preferredPadding);
178 ElementPosition tagPosition() const;
179 void setTagPosition(ElementPosition tagPosition);
180 bool forceTagPosition() const;
181 void setForceTagPosition(bool forceTagPosition);
182 ElementPosition indexPosition() const;
183 void setIndexPosition(ElementPosition indexPosition);
184 bool forceIndexPosition() const;
185 void setForceIndexPosition(bool forceTagPosition);
186
187protected:
188 void invalidated() override;
189
190private:
191 // private methods internally used when rewriting the file to apply new tag information
192 // currently only the makeMp3File() methods is present; corresponding methods for
193 // other formats are outsourced to container classes
194 void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
195
196 // fields related to the container
197 ParsingStatus m_containerParsingStatus;
198 ContainerFormat m_containerFormat;
199 std::streamoff m_containerOffset;
200 std::uint64_t m_paddingSize;
201 std::vector<std::streamoff> m_actualId3v2TagOffsets;
202 std::unique_ptr<AbstractContainer> m_container;
203 MediaFileStructureFlags m_fileStructureFlags;
204
205 // fields related to the tracks
206 ParsingStatus m_tracksParsingStatus;
207 std::unique_ptr<AbstractTrack> m_singleTrack;
208
209 // fields related to the tag
210 ParsingStatus m_tagsParsingStatus;
211 std::unique_ptr<Id3v1Tag> m_id3v1Tag;
212 std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
213
214 // fields related to the chapters and the attachments
215 ParsingStatus m_chaptersParsingStatus;
216 ParsingStatus m_attachmentsParsingStatus;
217
218 // fields specifying object behaviour
219 std::string m_backupDirectory;
220 std::string m_saveFilePath;
221 std::string m_writingApplication;
222 std::size_t m_minPadding;
223 std::size_t m_maxPadding;
224 std::size_t m_preferredPadding;
225 ElementPosition m_tagPosition;
226 ElementPosition m_indexPosition;
227 MediaFileHandlingFlags m_fileHandlingFlags;
228};
229
234{
235 return m_containerParsingStatus;
236}
237
245{
246 return m_containerFormat;
247}
248
259inline std::string_view MediaFileInfo::containerFormatName() const
260{
261 return TagParser::containerFormatName(m_containerFormat);
262}
263
274inline std::string_view MediaFileInfo::containerFormatSubversion() const
275{
276 return TagParser::containerFormatSubversion(m_containerFormat);
277}
278
282inline std::uint64_t MediaFileInfo::containerOffset() const
283{
284 return static_cast<std::uint64_t>(m_containerOffset);
285}
286
290inline std::uint64_t MediaFileInfo::paddingSize() const
291{
292 return m_paddingSize;
293}
294
299{
300 return m_tagsParsingStatus;
301}
302
307{
308 return m_tracksParsingStatus;
309}
310
319inline std::size_t MediaFileInfo::trackCount() const
320{
321 return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
322}
323
328{
329 return m_chaptersParsingStatus;
330}
331
336{
337 return m_attachmentsParsingStatus;
338}
339
343inline bool MediaFileInfo::hasId3v1Tag() const
344{
345 return m_id3v1Tag != nullptr;
346}
347
351inline bool MediaFileInfo::hasId3v2Tag() const
352{
353 return !m_id3v2Tags.empty();
354}
355
364{
365 return m_id3v1Tag.get();
366}
367
375inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
376{
377 return m_id3v2Tags;
378}
379
385inline const std::string &MediaFileInfo::backupDirectory() const
386{
387 return m_backupDirectory;
388}
389
394inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
395{
396 m_backupDirectory = backupDirectory;
397}
398
403inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
404{
405 m_backupDirectory = std::move(backupDirectory);
406}
407
412inline const std::string &MediaFileInfo::saveFilePath() const
413{
414 return m_saveFilePath;
415}
416
431inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
432{
433 m_saveFilePath = saveFilePath;
434}
435
439inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
440{
441 m_saveFilePath = std::move(saveFilePath);
442}
443
449inline const std::string &MediaFileInfo::writingApplication() const
450{
451 return m_writingApplication;
452}
453
458inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
459{
460 m_writingApplication = writingApplication;
461}
462
474{
475 return m_container.get();
476}
477
482{
483 return m_fileHandlingFlags;
484}
485
490{
491 m_fileHandlingFlags = flags;
492}
493
503{
504 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
505}
506
512inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
513{
514 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
515}
516
521{
522 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
523}
524
528inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
529{
530 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
531}
532
545inline std::size_t MediaFileInfo::minPadding() const
546{
547 return m_minPadding;
548}
549
555inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
556{
557 m_minPadding = minPadding;
558}
559
573inline std::size_t MediaFileInfo::maxPadding() const
574{
575 return m_maxPadding;
576}
577
583inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
584{
585 m_maxPadding = maxPadding;
586}
587
594inline std::size_t MediaFileInfo::preferredPadding() const
595{
596 return m_preferredPadding;
597}
598
604inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
605{
606 m_preferredPadding = preferredPadding;
607}
608
615{
616 return m_tagPosition;
617}
618
630{
631 m_tagPosition = tagPosition;
632}
633
640{
641 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
642}
643
649inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
650{
651 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
652}
653
660{
661 return m_indexPosition;
662}
663
670{
671 m_indexPosition = indexPosition;
672}
673
680{
681 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
682}
683
689inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
690{
691 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
692}
693
694} // namespace TagParser
695
696#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:75
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:108
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