Tag Parser  10.0.0
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 
4 #include "./abstractcontainer.h"
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 
16 namespace TagParser {
17 
18 class Tag;
19 class Id3v1Tag;
20 class Id3v2Tag;
21 class Mp4Container;
22 class Mp4Atom;
23 class Mp4Tag;
24 class MatroskaContainer;
25 class OggContainer;
26 class EbmlElement;
27 class MatroskaTag;
28 class AbstractTrack;
29 class VorbisComment;
30 class Diagnostics;
31 class AbortableProgressFeedback;
32 
33 enum class MediaType : unsigned int;
34 enum class TagType : unsigned int;
35 
40 enum class ParsingStatus : std::uint8_t {
41  NotParsedYet,
42  Ok,
43  NotSupported,
45 };
46 
50 enum class MediaFileStructureFlags : std::uint64_t {
51  None,
52  ActualExistingId3v1Tag = (1 << 0),
53 };
54 
58 enum class MediaFileHandlingFlags : std::uint64_t {
59  None,
61  = (1 << 0),
62  ForceRewrite = (1 << 1),
63  ForceTagPosition = (1 << 2),
64  ForceIndexPosition = (1 << 3),
65 };
66 
67 } // namespace TagParser
68 
71 
72 namespace TagParser {
73 
75 public:
76  // constructor, destructor
77  explicit MediaFileInfo();
78  explicit MediaFileInfo(std::string_view path);
79  explicit MediaFileInfo(std::string &&path);
80  MediaFileInfo(const MediaFileInfo &) = delete;
82  ~MediaFileInfo() override;
83 
84  // methods to parse file
85  void parseContainerFormat(Diagnostics &diag, AbortableProgressFeedback &progress);
86  void parseTracks(Diagnostics &diag, AbortableProgressFeedback &progress);
87  void parseTags(Diagnostics &diag, AbortableProgressFeedback &progress);
88  void parseChapters(Diagnostics &diag, AbortableProgressFeedback &progress);
89  void parseAttachments(Diagnostics &diag, AbortableProgressFeedback &progress);
90  void parseEverything(Diagnostics &diag, AbortableProgressFeedback &progress);
91 
92  // methods to apply changes
93  void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
94 
95  // methods to get parsed information regarding ...
96  // ... the container
97  ContainerFormat containerFormat() const;
98  std::string_view containerFormatName() const;
99  std::string_view containerFormatAbbreviation() const;
100  std::string_view containerFormatSubversion() const;
101  std::string_view mimeType() const;
102  std::uint64_t containerOffset() const;
103  std::uint64_t paddingSize() const;
104  AbstractContainer *container() const;
105  ParsingStatus containerParsingStatus() const;
106  // ... the capters
107  ParsingStatus chaptersParsingStatus() const;
108  std::vector<AbstractChapter *> chapters() const;
109  bool areChaptersSupported() const;
110  // ... the attachments
111  ParsingStatus attachmentsParsingStatus() const;
112  std::vector<AbstractAttachment *> attachments() const;
113  bool areAttachmentsSupported() const;
114  // ... the tracks
115  ParsingStatus tracksParsingStatus() const;
116  std::size_t trackCount() const;
117  std::vector<AbstractTrack *> tracks() const;
118  bool hasTracksOfType(TagParser::MediaType type) const;
119  CppUtilities::TimeSpan duration() const;
120  double overallAverageBitrate() const;
121  std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
122  std::string technicalSummary() const;
123  bool areTracksSupported() const;
124  // ... the tags
125  ParsingStatus tagsParsingStatus() const;
126  bool hasId3v1Tag() const;
127  bool hasId3v2Tag() const;
128  bool hasAnyTag() const;
129  Id3v1Tag *id3v1Tag() const;
130  const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
131  void tags(std::vector<Tag *> &tags) const;
132  std::vector<Tag *> tags() const;
133  Mp4Tag *mp4Tag() const;
134  const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
135  VorbisComment *vorbisComment() const;
136  bool areTagsSupported() const;
137 
138  // methods to create/remove tags
139  bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
140  bool removeId3v1Tag();
141  Id3v1Tag *createId3v1Tag();
142  bool removeId3v2Tag(Id3v2Tag *tag);
143  bool removeAllId3v2Tags();
144  Id3v2Tag *createId3v2Tag();
145  bool removeTag(Tag *tag);
146  void removeAllTags();
147  void mergeId3v2Tags();
148  bool id3v1ToId3v2();
149  bool id3v2ToId3v1();
150  VorbisComment *createVorbisComment();
151  bool removeVorbisComment();
152  void clearParsingResults();
153 
154  // methods to get, set object behaviour
155  const std::string &backupDirectory() const;
156  void setBackupDirectory(std::string_view backupDirectory);
157  void setBackupDirectory(std::string &&backupDirectory);
158  const std::string &saveFilePath() const;
159  void setSaveFilePath(std::string_view saveFilePath);
160  void setSaveFilePath(std::string &&saveFilePath);
161  const std::string &writingApplication() const;
162  void setWritingApplication(std::string_view writingApplication);
163  bool isForcingFullParse() const;
164  void setForceFullParse(bool forceFullParse);
165  bool isForcingRewrite() const;
166  void setForceRewrite(bool forceRewrite);
167  std::size_t minPadding() const;
168  void setMinPadding(std::size_t minPadding);
169  std::size_t maxPadding() const;
170  void setMaxPadding(std::size_t maxPadding);
171  std::size_t preferredPadding() const;
172  void setPreferredPadding(std::size_t preferredPadding);
173  ElementPosition tagPosition() const;
174  void setTagPosition(ElementPosition tagPosition);
175  bool forceTagPosition() const;
176  void setForceTagPosition(bool forceTagPosition);
177  ElementPosition indexPosition() const;
178  void setIndexPosition(ElementPosition indexPosition);
179  bool forceIndexPosition() const;
180  void setForceIndexPosition(bool forceTagPosition);
181 
182 protected:
183  void invalidated() override;
184 
185 private:
186  // private methods internally used when rewriting the file to apply new tag information
187  // currently only the makeMp3File() methods is present; corresponding methods for
188  // other formats are outsourced to container classes
189  void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
190 
191  // fields related to the container
192  ParsingStatus m_containerParsingStatus;
193  ContainerFormat m_containerFormat;
194  std::streamoff m_containerOffset;
195  std::uint64_t m_paddingSize;
196  std::vector<std::streamoff> m_actualId3v2TagOffsets;
197  std::unique_ptr<AbstractContainer> m_container;
198  MediaFileStructureFlags m_fileStructureFlags;
199 
200  // fields related to the tracks
201  ParsingStatus m_tracksParsingStatus;
202  std::unique_ptr<AbstractTrack> m_singleTrack;
203 
204  // fields related to the tag
205  ParsingStatus m_tagsParsingStatus;
206  std::unique_ptr<Id3v1Tag> m_id3v1Tag;
207  std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
208 
209  // fields related to the chapters and the attachments
210  ParsingStatus m_chaptersParsingStatus;
211  ParsingStatus m_attachmentsParsingStatus;
212 
213  // fields specifying object behaviour
214  std::string m_backupDirectory;
215  std::string m_saveFilePath;
216  std::string m_writingApplication;
217  std::size_t m_minPadding;
218  std::size_t m_maxPadding;
219  std::size_t m_preferredPadding;
220  ElementPosition m_tagPosition;
221  ElementPosition m_indexPosition;
222  MediaFileHandlingFlags m_fileHandlingFlags;
223 };
224 
229 {
230  return m_containerParsingStatus;
231 }
232 
240 {
241  return m_containerFormat;
242 }
243 
254 inline std::string_view MediaFileInfo::containerFormatName() const
255 {
256  return TagParser::containerFormatName(m_containerFormat);
257 }
258 
269 inline std::string_view MediaFileInfo::containerFormatSubversion() const
270 {
271  return TagParser::containerFormatSubversion(m_containerFormat);
272 }
273 
277 inline std::uint64_t MediaFileInfo::containerOffset() const
278 {
279  return static_cast<std::uint64_t>(m_containerOffset);
280 }
281 
285 inline std::uint64_t MediaFileInfo::paddingSize() const
286 {
287  return m_paddingSize;
288 }
289 
294 {
295  return m_tagsParsingStatus;
296 }
297 
302 {
303  return m_tracksParsingStatus;
304 }
305 
314 inline std::size_t MediaFileInfo::trackCount() const
315 {
316  return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
317 }
318 
323 {
324  return m_chaptersParsingStatus;
325 }
326 
331 {
332  return m_attachmentsParsingStatus;
333 }
334 
338 inline bool MediaFileInfo::hasId3v1Tag() const
339 {
340  return m_id3v1Tag != nullptr;
341 }
342 
346 inline bool MediaFileInfo::hasId3v2Tag() const
347 {
348  return !m_id3v2Tags.empty();
349 }
350 
359 {
360  return m_id3v1Tag.get();
361 }
362 
370 inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
371 {
372  return m_id3v2Tags;
373 }
374 
380 inline const std::string &MediaFileInfo::backupDirectory() const
381 {
382  return m_backupDirectory;
383 }
384 
389 inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
390 {
391  m_backupDirectory = backupDirectory;
392 }
393 
398 inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
399 {
400  m_backupDirectory = std::move(backupDirectory);
401 }
402 
407 inline const std::string &MediaFileInfo::saveFilePath() const
408 {
409  return m_saveFilePath;
410 }
411 
426 inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
427 {
428  m_saveFilePath = saveFilePath;
429 }
430 
434 inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
435 {
436  m_saveFilePath = std::move(saveFilePath);
437 }
438 
444 inline const std::string &MediaFileInfo::writingApplication() const
445 {
446  return m_writingApplication;
447 }
448 
453 inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
454 {
455  m_writingApplication = writingApplication;
456 }
457 
469 {
470  return m_container.get();
471 }
472 
482 {
483  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
484 }
485 
491 inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
492 {
493  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
494 }
495 
500 {
501  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
502 }
503 
507 inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
508 {
509  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
510 }
511 
524 inline std::size_t MediaFileInfo::minPadding() const
525 {
526  return m_minPadding;
527 }
528 
534 inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
535 {
536  m_minPadding = minPadding;
537 }
538 
552 inline std::size_t MediaFileInfo::maxPadding() const
553 {
554  return m_maxPadding;
555 }
556 
562 inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
563 {
564  m_maxPadding = maxPadding;
565 }
566 
573 inline std::size_t MediaFileInfo::preferredPadding() const
574 {
575  return m_preferredPadding;
576 }
577 
583 inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
584 {
585  m_preferredPadding = preferredPadding;
586 }
587 
594 {
595  return m_tagPosition;
596 }
597 
609 {
610  m_tagPosition = tagPosition;
611 }
612 
619 {
620  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
621 }
622 
628 inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
629 {
630  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
631 }
632 
639 {
640  return m_indexPosition;
641 }
642 
649 {
650  m_indexPosition = indexPosition;
651 }
652 
659 {
660  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
661 }
662 
668 inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
669 {
670  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
671 }
672 
673 } // namespace TagParser
674 
675 #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:74
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.
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 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.
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.
MediaFileInfo & operator=(const MediaFileInfo &)=delete
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