Tag Parser 12.0.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Loading...
Searching...
No Matches
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
76struct MediaFileInfoPrivate;
77
79public:
80 // constructor, destructor
81 explicit MediaFileInfo();
82 explicit MediaFileInfo(std::string_view path);
83 explicit MediaFileInfo(std::string &&path);
84 MediaFileInfo(const MediaFileInfo &) = delete;
86 ~MediaFileInfo() override;
87
88 // methods to parse file
89 void parseContainerFormat(Diagnostics &diag, AbortableProgressFeedback &progress);
90 void parseTracks(Diagnostics &diag, AbortableProgressFeedback &progress);
91 void parseTags(Diagnostics &diag, AbortableProgressFeedback &progress);
92 void parseChapters(Diagnostics &diag, AbortableProgressFeedback &progress);
93 void parseAttachments(Diagnostics &diag, AbortableProgressFeedback &progress);
94 void parseEverything(Diagnostics &diag, AbortableProgressFeedback &progress);
95
96 // methods to apply changes
97 void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
98
99 // methods to get parsed information regarding ...
100 // ... the container
101 ContainerFormat containerFormat() const;
102 std::string_view containerFormatName() const;
103 std::string_view containerFormatAbbreviation() const;
104 std::string_view containerFormatSubversion() const;
105 std::string_view mimeType() const;
106 std::uint64_t containerOffset() const;
107 std::uint64_t paddingSize() const;
108 std::uint64_t effectiveSize() const;
109 AbstractContainer *container() const;
110 ParsingStatus containerParsingStatus() const;
111 // ... the chapters
112 ParsingStatus chaptersParsingStatus() const;
113 std::vector<AbstractChapter *> chapters() const;
114 bool areChaptersSupported() const;
115 // ... the attachments
116 ParsingStatus attachmentsParsingStatus() const;
117 std::vector<AbstractAttachment *> attachments() const;
118 bool areAttachmentsSupported() const;
119 // ... the tracks
120 ParsingStatus tracksParsingStatus() const;
121 std::size_t trackCount() const;
122 std::vector<AbstractTrack *> tracks() const;
123 bool hasTracksOfType(TagParser::MediaType type) const;
124 CppUtilities::TimeSpan duration() const;
125 double overallAverageBitrate() const;
126 std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
127 std::string technicalSummary() const;
128 bool areTracksSupported() const;
129 // ... the tags
130 ParsingStatus tagsParsingStatus() const;
131 bool hasId3v1Tag() const;
132 bool hasId3v2Tag() const;
133 bool hasAnyTag() const;
134 Id3v1Tag *id3v1Tag() const;
135 const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
136 void tags(std::vector<Tag *> &tags) const;
137 std::vector<Tag *> tags() const;
138 void parsedTags(std::vector<Tag *> &tags) const;
139 std::vector<Tag *> parsedTags() const;
140 Mp4Tag *mp4Tag() const;
141 const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
142 VorbisComment *vorbisComment() const;
143 bool areTagsSupported() const;
144
145 // methods to create/remove tags
146 bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
147 bool removeId3v1Tag();
148 Id3v1Tag *createId3v1Tag();
149 bool removeId3v2Tag(Id3v2Tag *tag);
150 bool removeAllId3v2Tags();
151 Id3v2Tag *createId3v2Tag();
152 bool removeTag(Tag *tag);
153 void removeAllTags();
154 void mergeId3v2Tags();
155 bool id3v1ToId3v2();
156 bool id3v2ToId3v1();
157 VorbisComment *createVorbisComment();
158 bool removeVorbisComment();
159 void clearParsingResults();
160
161 // methods to get, set object behaviour
162 const std::string &backupDirectory() const;
163 void setBackupDirectory(std::string_view backupDirectory);
164 void setBackupDirectory(std::string &&backupDirectory);
165 const std::string &saveFilePath() const;
166 void setSaveFilePath(std::string_view saveFilePath);
167 void setSaveFilePath(std::string &&saveFilePath);
168 const std::string &writingApplication() const;
169 void setWritingApplication(std::string_view writingApplication);
170 MediaFileHandlingFlags fileHandlingFlags();
171 void setFileHandlingFlags(MediaFileHandlingFlags flags);
172 bool isForcingFullParse() const;
173 void setForceFullParse(bool forceFullParse);
174 bool isForcingRewrite() const;
175 void setForceRewrite(bool forceRewrite);
176 std::size_t minPadding() const;
177 void setMinPadding(std::size_t minPadding);
178 std::size_t maxPadding() const;
179 void setMaxPadding(std::size_t maxPadding);
180 std::size_t preferredPadding() const;
181 void setPreferredPadding(std::size_t preferredPadding);
182 ElementPosition tagPosition() const;
183 void setTagPosition(ElementPosition tagPosition);
184 bool forceTagPosition() const;
185 void setForceTagPosition(bool forceTagPosition);
186 ElementPosition indexPosition() const;
187 void setIndexPosition(ElementPosition indexPosition);
188 bool forceIndexPosition() const;
189 void setForceIndexPosition(bool forceTagPosition);
190 std::uint64_t maxFullParseSize() const;
191 void setMaxFullParseSize(std::uint64_t maxFullParseSize);
192
193protected:
194 void invalidated() override;
195
196private:
197 // private methods internally used when rewriting the file to apply new tag information
198 // currently only the makeMp3File() methods is present; corresponding methods for
199 // other formats are outsourced to container classes
200 void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
201
202 // fields related to the container
203 ParsingStatus m_containerParsingStatus;
204 ContainerFormat m_containerFormat;
205 std::streamoff m_containerOffset;
206 std::uint64_t m_paddingSize;
207 std::uint64_t m_effectiveSize;
208 std::vector<std::streamoff> m_actualId3v2TagOffsets;
209 std::unique_ptr<AbstractContainer> m_container;
210 MediaFileStructureFlags m_fileStructureFlags;
211
212 // fields related to the tracks
213 ParsingStatus m_tracksParsingStatus;
214 std::unique_ptr<AbstractTrack> m_singleTrack;
215
216 // fields related to the tag
217 ParsingStatus m_tagsParsingStatus;
218 std::unique_ptr<Id3v1Tag> m_id3v1Tag;
219 std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
220
221 // fields related to the chapters and the attachments
222 ParsingStatus m_chaptersParsingStatus;
223 ParsingStatus m_attachmentsParsingStatus;
224
225 // fields specifying object behaviour
226 std::string m_backupDirectory;
227 std::string m_saveFilePath;
228 std::string m_writingApplication;
229 std::size_t m_minPadding;
230 std::size_t m_maxPadding;
231 std::size_t m_preferredPadding;
232 ElementPosition m_tagPosition;
233 ElementPosition m_indexPosition;
234 MediaFileHandlingFlags m_fileHandlingFlags;
235 std::uint64_t m_maxFullParseSize;
236 std::unique_ptr<MediaFileInfoPrivate> m_p;
237};
238
243{
244 return m_containerParsingStatus;
245}
246
254{
255 return m_containerFormat;
256}
257
268inline std::string_view MediaFileInfo::containerFormatName() const
269{
270 return TagParser::containerFormatName(m_containerFormat);
271}
272
283inline std::string_view MediaFileInfo::containerFormatSubversion() const
284{
285 return TagParser::containerFormatSubversion(m_containerFormat);
286}
287
291inline std::uint64_t MediaFileInfo::containerOffset() const
292{
293 return static_cast<std::uint64_t>(m_containerOffset);
294}
295
299inline std::uint64_t MediaFileInfo::paddingSize() const
300{
301 return m_paddingSize;
302}
303
308inline std::uint64_t MediaFileInfo::effectiveSize() const
309{
310 return m_effectiveSize;
311}
312
317{
318 return m_tagsParsingStatus;
319}
320
325{
326 return m_tracksParsingStatus;
327}
328
337inline std::size_t MediaFileInfo::trackCount() const
338{
339 return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
340}
341
346{
347 return m_chaptersParsingStatus;
348}
349
354{
355 return m_attachmentsParsingStatus;
356}
357
361inline bool MediaFileInfo::hasId3v1Tag() const
362{
363 return m_id3v1Tag != nullptr;
364}
365
369inline bool MediaFileInfo::hasId3v2Tag() const
370{
371 return !m_id3v2Tags.empty();
372}
373
382{
383 return m_id3v1Tag.get();
384}
385
393inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
394{
395 return m_id3v2Tags;
396}
397
403inline const std::string &MediaFileInfo::backupDirectory() const
404{
405 return m_backupDirectory;
406}
407
412inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
413{
414 m_backupDirectory = backupDirectory;
415}
416
421inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
422{
423 m_backupDirectory = std::move(backupDirectory);
424}
425
430inline const std::string &MediaFileInfo::saveFilePath() const
431{
432 return m_saveFilePath;
433}
434
449inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
450{
451 m_saveFilePath = saveFilePath;
452}
453
457inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
458{
459 m_saveFilePath = std::move(saveFilePath);
460}
461
467inline const std::string &MediaFileInfo::writingApplication() const
468{
469 return m_writingApplication;
470}
471
476inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
477{
478 m_writingApplication = writingApplication;
479}
480
492{
493 return m_container.get();
494}
495
500{
501 return m_fileHandlingFlags;
502}
503
508{
509 m_fileHandlingFlags = flags;
510}
511
521{
522 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
523}
524
530inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
531{
532 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
533}
534
539{
540 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
541}
542
546inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
547{
548 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
549}
550
563inline std::size_t MediaFileInfo::minPadding() const
564{
565 return m_minPadding;
566}
567
573inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
574{
575 m_minPadding = minPadding;
576}
577
591inline std::size_t MediaFileInfo::maxPadding() const
592{
593 return m_maxPadding;
594}
595
601inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
602{
603 m_maxPadding = maxPadding;
604}
605
612inline std::size_t MediaFileInfo::preferredPadding() const
613{
614 return m_preferredPadding;
615}
616
622inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
623{
624 m_preferredPadding = preferredPadding;
625}
626
633{
634 return m_tagPosition;
635}
636
648{
649 m_tagPosition = tagPosition;
650}
651
658{
659 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
660}
661
667inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
668{
669 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
670}
671
678{
679 return m_indexPosition;
680}
681
688{
689 m_indexPosition = indexPosition;
690}
691
698{
699 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
700}
701
707inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
708{
709 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
710}
711
725inline std::uint64_t MediaFileInfo::maxFullParseSize() const
726{
727 return m_maxFullParseSize;
728}
729
734inline void MediaFileInfo::setMaxFullParseSize(std::uint64_t maxFullParseSize)
735{
736 m_maxFullParseSize = maxFullParseSize;
737}
738
739} // namespace TagParser
740
741#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,...
The Diagnostics class is a container for DiagMessage.
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...
std::uint64_t maxFullParseSize() const
Returns the maximal file size for a "full parse" in byte.
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 setMaxFullParseSize(std::uint64_t maxFullParseSize)
Sets the maximal file size for a "full parse" in byte.
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.
std::uint64_t effectiveSize() const
Returns the "effective size" of the file if know; otherwise returns 0.
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:166
Implementation of TagParser::Tag for Vorbis comments.
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
Definition global.h:13
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.
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...
TAG_PARSER_EXPORT std::string_view containerFormatName(ContainerFormat containerFormat)
Returns the name of the specified container format as C-style string.
TagType
Specifies the tag type.
Definition tagtype.h:11
ParsingStatus
The ParsingStatus enum specifies whether a certain part of the file (tracks, tags,...
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.
ContainerFormat
Specifies the container format.
Definition signature.h:18
MediaFileHandlingFlags
The MediaFileHandlingFlags enum specifies flags which controls the behavior of MediaFileInfo objects.
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