Tag Parser 12.2.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 PreserveMuxingApplication = (1 << 9),
68 PreserveWritingApplication = (1 << 10),
69 ConvertTotalFields = (1 << 11),
72};
73
74} // namespace TagParser
75
78
79namespace TagParser {
80
81struct MediaFileInfoPrivate;
82
83class TAG_PARSER_EXPORT MediaFileInfo : public BasicFileInfo {
84public:
85 // constructor, destructor
86 explicit MediaFileInfo();
87 explicit MediaFileInfo(std::string_view path);
88 explicit MediaFileInfo(std::string &&path);
89 MediaFileInfo(const MediaFileInfo &) = delete;
91 ~MediaFileInfo() override;
92
93 // methods to parse file
94 void parseContainerFormat(Diagnostics &diag, AbortableProgressFeedback &progress);
95 void parseTracks(Diagnostics &diag, AbortableProgressFeedback &progress);
96 void parseTags(Diagnostics &diag, AbortableProgressFeedback &progress);
97 void parseChapters(Diagnostics &diag, AbortableProgressFeedback &progress);
98 void parseAttachments(Diagnostics &diag, AbortableProgressFeedback &progress);
99 void parseEverything(Diagnostics &diag, AbortableProgressFeedback &progress);
100
101 // methods to apply changes
102 void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
103
104 // methods to get parsed information regarding ...
105 // ... the container
106 ContainerFormat containerFormat() const;
107 std::string_view containerFormatName() const;
108 std::string_view containerFormatAbbreviation() const;
109 std::string_view containerFormatSubversion() const;
110 std::string_view mimeType() const;
111 std::uint64_t containerOffset() const;
112 std::uint64_t paddingSize() const;
113 std::uint64_t effectiveSize() const;
114 AbstractContainer *container() const;
115 ParsingStatus containerParsingStatus() const;
116 // ... the chapters
117 ParsingStatus chaptersParsingStatus() const;
118 std::vector<AbstractChapter *> chapters() const;
119 bool areChaptersSupported() const;
120 // ... the attachments
121 ParsingStatus attachmentsParsingStatus() const;
122 std::vector<AbstractAttachment *> attachments() const;
123 bool areAttachmentsSupported() const;
124 // ... the tracks
125 ParsingStatus tracksParsingStatus() const;
126 std::size_t trackCount() const;
127 std::vector<AbstractTrack *> tracks() const;
128 bool hasTracksOfType(TagParser::MediaType type) const;
129 CppUtilities::TimeSpan duration() const;
130 double overallAverageBitrate() const;
131 std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
132 std::string technicalSummary() const;
133 bool areTracksSupported() const;
134 // ... the tags
135 ParsingStatus tagsParsingStatus() const;
136 bool hasId3v1Tag() const;
137 bool hasId3v2Tag() const;
138 bool hasAnyTag() const;
139 Id3v1Tag *id3v1Tag() const;
140 const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
141 void tags(std::vector<Tag *> &tags) const;
142 std::vector<Tag *> tags() const;
143 void parsedTags(std::vector<Tag *> &tags) const;
144 std::vector<Tag *> parsedTags() const;
145 Mp4Tag *mp4Tag() const;
146 const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
147 VorbisComment *vorbisComment() const;
148 bool areTagsSupported() const;
149
150 // methods to create/remove tags
151 bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
152 bool removeId3v1Tag();
153 Id3v1Tag *createId3v1Tag();
154 bool removeId3v2Tag(Id3v2Tag *tag);
155 bool removeAllId3v2Tags();
156 Id3v2Tag *createId3v2Tag();
157 bool removeTag(Tag *tag);
158 void removeAllTags();
159 void mergeId3v2Tags();
160 bool id3v1ToId3v2();
161 bool id3v2ToId3v1();
162 VorbisComment *createVorbisComment();
163 bool removeVorbisComment();
164 void clearParsingResults();
165 void reportPaddingSizeChanged(std::uint64_t newPaddingSize);
166
167 // methods to get, set object behaviour
168 const std::string &backupDirectory() const;
169 void setBackupDirectory(std::string_view backupDirectory);
170 void setBackupDirectory(std::string &&backupDirectory);
171 const std::string &saveFilePath() const;
172 void setSaveFilePath(std::string_view saveFilePath);
173 void setSaveFilePath(std::string &&saveFilePath);
174 const std::string &writingApplication() const;
175 void setWritingApplication(std::string_view writingApplication);
176 MediaFileHandlingFlags fileHandlingFlags();
177 void setFileHandlingFlags(MediaFileHandlingFlags flags);
178 bool isForcingFullParse() const;
179 void setForceFullParse(bool forceFullParse);
180 bool isForcingRewrite() const;
181 void setForceRewrite(bool forceRewrite);
182 std::size_t minPadding() const;
183 void setMinPadding(std::size_t minPadding);
184 std::size_t maxPadding() const;
185 void setMaxPadding(std::size_t maxPadding);
186 std::size_t preferredPadding() const;
187 void setPreferredPadding(std::size_t preferredPadding);
188 ElementPosition tagPosition() const;
189 void setTagPosition(ElementPosition tagPosition);
190 bool forceTagPosition() const;
191 void setForceTagPosition(bool forceTagPosition);
192 ElementPosition indexPosition() const;
193 void setIndexPosition(ElementPosition indexPosition);
194 bool forceIndexPosition() const;
195 void setForceIndexPosition(bool forceTagPosition);
196 std::uint64_t maxFullParseSize() const;
197 void setMaxFullParseSize(std::uint64_t maxFullParseSize);
198
199protected:
200 void invalidated() override;
201
202private:
203 // private methods internally used when rewriting the file to apply new tag information
204 // currently only the makeMp3File() methods is present; corresponding methods for
205 // other formats are outsourced to container classes
206 void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
207
208 // fields related to the container
209 ParsingStatus m_containerParsingStatus;
210 ContainerFormat m_containerFormat;
211 std::streamoff m_containerOffset;
212 std::uint64_t m_paddingSize;
213 std::uint64_t m_effectiveSize;
214 std::vector<std::streamoff> m_actualId3v2TagOffsets;
215 std::unique_ptr<AbstractContainer> m_container;
216 MediaFileStructureFlags m_fileStructureFlags;
217
218 // fields related to the tracks
219 ParsingStatus m_tracksParsingStatus;
220 std::unique_ptr<AbstractTrack> m_singleTrack;
221
222 // fields related to the tag
223 ParsingStatus m_tagsParsingStatus;
224 std::unique_ptr<Id3v1Tag> m_id3v1Tag;
225 std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
226
227 // fields related to the chapters and the attachments
228 ParsingStatus m_chaptersParsingStatus;
229 ParsingStatus m_attachmentsParsingStatus;
230
231 // fields specifying object behaviour
232 std::string m_backupDirectory;
233 std::string m_saveFilePath;
234 std::string m_writingApplication;
235 std::size_t m_minPadding;
236 std::size_t m_maxPadding;
237 std::size_t m_preferredPadding;
238 ElementPosition m_tagPosition;
239 ElementPosition m_indexPosition;
240 MediaFileHandlingFlags m_fileHandlingFlags;
241 std::uint64_t m_maxFullParseSize;
242 std::unique_ptr<MediaFileInfoPrivate> m_p;
243};
244
249{
250 return m_containerParsingStatus;
251}
252
260{
261 return m_containerFormat;
262}
263
274inline std::string_view MediaFileInfo::containerFormatName() const
275{
276 return TagParser::containerFormatName(m_containerFormat);
277}
278
289inline std::string_view MediaFileInfo::containerFormatSubversion() const
290{
291 return TagParser::containerFormatSubversion(m_containerFormat);
292}
293
297inline std::uint64_t MediaFileInfo::containerOffset() const
298{
299 return static_cast<std::uint64_t>(m_containerOffset);
300}
301
305inline std::uint64_t MediaFileInfo::paddingSize() const
306{
307 return m_paddingSize;
308}
309
314inline std::uint64_t MediaFileInfo::effectiveSize() const
315{
316 return m_effectiveSize;
317}
318
323{
324 return m_tagsParsingStatus;
325}
326
331{
332 return m_tracksParsingStatus;
333}
334
343inline std::size_t MediaFileInfo::trackCount() const
344{
345 return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
346}
347
352{
353 return m_chaptersParsingStatus;
354}
355
360{
361 return m_attachmentsParsingStatus;
362}
363
367inline bool MediaFileInfo::hasId3v1Tag() const
368{
369 return m_id3v1Tag != nullptr;
370}
371
375inline bool MediaFileInfo::hasId3v2Tag() const
376{
377 return !m_id3v2Tags.empty();
378}
379
388{
389 return m_id3v1Tag.get();
390}
391
399inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
400{
401 return m_id3v2Tags;
402}
403
408inline void MediaFileInfo::reportPaddingSizeChanged(uint64_t newPaddingSize)
409{
410 m_paddingSize = newPaddingSize;
411}
412
418inline const std::string &MediaFileInfo::backupDirectory() const
419{
420 return m_backupDirectory;
421}
422
427inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
428{
429 m_backupDirectory = backupDirectory;
430}
431
436inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
437{
438 m_backupDirectory = std::move(backupDirectory);
439}
440
445inline const std::string &MediaFileInfo::saveFilePath() const
446{
447 return m_saveFilePath;
448}
449
464inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
465{
466 m_saveFilePath = saveFilePath;
467}
468
472inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
473{
474 m_saveFilePath = std::move(saveFilePath);
475}
476
482inline const std::string &MediaFileInfo::writingApplication() const
483{
484 return m_writingApplication;
485}
486
493inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
494{
495 m_writingApplication = writingApplication;
496}
497
509{
510 return m_container.get();
511}
512
517{
518 return m_fileHandlingFlags;
519}
520
525{
526 m_fileHandlingFlags = flags;
527}
528
538{
539 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
540}
541
547inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
548{
549 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
550}
551
556{
557 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
558}
559
563inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
564{
565 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
566}
567
580inline std::size_t MediaFileInfo::minPadding() const
581{
582 return m_minPadding;
583}
584
590inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
591{
592 m_minPadding = minPadding;
593}
594
608inline std::size_t MediaFileInfo::maxPadding() const
609{
610 return m_maxPadding;
611}
612
618inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
619{
620 m_maxPadding = maxPadding;
621}
622
629inline std::size_t MediaFileInfo::preferredPadding() const
630{
631 return m_preferredPadding;
632}
633
639inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
640{
641 m_preferredPadding = preferredPadding;
642}
643
650{
651 return m_tagPosition;
652}
653
665{
666 m_tagPosition = tagPosition;
667}
668
675{
676 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
677}
678
684inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
685{
686 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
687}
688
695{
696 return m_indexPosition;
697}
698
705{
706 m_indexPosition = indexPosition;
707}
708
715{
716 return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
717}
718
724inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
725{
726 CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
727}
728
742inline std::uint64_t MediaFileInfo::maxFullParseSize() const
743{
744 return m_maxFullParseSize;
745}
746
751inline void MediaFileInfo::setMaxFullParseSize(std::uint64_t maxFullParseSize)
752{
753 m_maxFullParseSize = maxFullParseSize;
754}
755
756} // namespace TagParser
757
758#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 Diagnostics class is a container for DiagMessage.
Implementation of TagParser::Tag for ID3v1 tags.
Implementation of TagParser::Tag for ID3v2 tags.
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.
void reportPaddingSizeChanged(std::uint64_t newPaddingSize)
Sets the padding size.
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.
The Tag class is used to store, read and write tag information.
Implementation of TagParser::Tag for Vorbis comments.
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
Definition global.h:14
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