Tag Parser  10.1.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  void parsedTags(std::vector<Tag *> &tags) const;
134  std::vector<Tag *> parsedTags() const;
135  Mp4Tag *mp4Tag() const;
136  const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
137  VorbisComment *vorbisComment() const;
138  bool areTagsSupported() const;
139 
140  // methods to create/remove tags
141  bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
142  bool removeId3v1Tag();
143  Id3v1Tag *createId3v1Tag();
144  bool removeId3v2Tag(Id3v2Tag *tag);
145  bool removeAllId3v2Tags();
146  Id3v2Tag *createId3v2Tag();
147  bool removeTag(Tag *tag);
148  void removeAllTags();
149  void mergeId3v2Tags();
150  bool id3v1ToId3v2();
151  bool id3v2ToId3v1();
152  VorbisComment *createVorbisComment();
153  bool removeVorbisComment();
154  void clearParsingResults();
155 
156  // methods to get, set object behaviour
157  const std::string &backupDirectory() const;
158  void setBackupDirectory(std::string_view backupDirectory);
159  void setBackupDirectory(std::string &&backupDirectory);
160  const std::string &saveFilePath() const;
161  void setSaveFilePath(std::string_view saveFilePath);
162  void setSaveFilePath(std::string &&saveFilePath);
163  const std::string &writingApplication() const;
164  void setWritingApplication(std::string_view writingApplication);
165  bool isForcingFullParse() const;
166  void setForceFullParse(bool forceFullParse);
167  bool isForcingRewrite() const;
168  void setForceRewrite(bool forceRewrite);
169  std::size_t minPadding() const;
170  void setMinPadding(std::size_t minPadding);
171  std::size_t maxPadding() const;
172  void setMaxPadding(std::size_t maxPadding);
173  std::size_t preferredPadding() const;
174  void setPreferredPadding(std::size_t preferredPadding);
175  ElementPosition tagPosition() const;
176  void setTagPosition(ElementPosition tagPosition);
177  bool forceTagPosition() const;
178  void setForceTagPosition(bool forceTagPosition);
179  ElementPosition indexPosition() const;
180  void setIndexPosition(ElementPosition indexPosition);
181  bool forceIndexPosition() const;
182  void setForceIndexPosition(bool forceTagPosition);
183 
184 protected:
185  void invalidated() override;
186 
187 private:
188  // private methods internally used when rewriting the file to apply new tag information
189  // currently only the makeMp3File() methods is present; corresponding methods for
190  // other formats are outsourced to container classes
191  void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
192 
193  // fields related to the container
194  ParsingStatus m_containerParsingStatus;
195  ContainerFormat m_containerFormat;
196  std::streamoff m_containerOffset;
197  std::uint64_t m_paddingSize;
198  std::vector<std::streamoff> m_actualId3v2TagOffsets;
199  std::unique_ptr<AbstractContainer> m_container;
200  MediaFileStructureFlags m_fileStructureFlags;
201 
202  // fields related to the tracks
203  ParsingStatus m_tracksParsingStatus;
204  std::unique_ptr<AbstractTrack> m_singleTrack;
205 
206  // fields related to the tag
207  ParsingStatus m_tagsParsingStatus;
208  std::unique_ptr<Id3v1Tag> m_id3v1Tag;
209  std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
210 
211  // fields related to the chapters and the attachments
212  ParsingStatus m_chaptersParsingStatus;
213  ParsingStatus m_attachmentsParsingStatus;
214 
215  // fields specifying object behaviour
216  std::string m_backupDirectory;
217  std::string m_saveFilePath;
218  std::string m_writingApplication;
219  std::size_t m_minPadding;
220  std::size_t m_maxPadding;
221  std::size_t m_preferredPadding;
222  ElementPosition m_tagPosition;
223  ElementPosition m_indexPosition;
224  MediaFileHandlingFlags m_fileHandlingFlags;
225 };
226 
231 {
232  return m_containerParsingStatus;
233 }
234 
242 {
243  return m_containerFormat;
244 }
245 
256 inline std::string_view MediaFileInfo::containerFormatName() const
257 {
258  return TagParser::containerFormatName(m_containerFormat);
259 }
260 
271 inline std::string_view MediaFileInfo::containerFormatSubversion() const
272 {
273  return TagParser::containerFormatSubversion(m_containerFormat);
274 }
275 
279 inline std::uint64_t MediaFileInfo::containerOffset() const
280 {
281  return static_cast<std::uint64_t>(m_containerOffset);
282 }
283 
287 inline std::uint64_t MediaFileInfo::paddingSize() const
288 {
289  return m_paddingSize;
290 }
291 
296 {
297  return m_tagsParsingStatus;
298 }
299 
304 {
305  return m_tracksParsingStatus;
306 }
307 
316 inline std::size_t MediaFileInfo::trackCount() const
317 {
318  return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
319 }
320 
325 {
326  return m_chaptersParsingStatus;
327 }
328 
333 {
334  return m_attachmentsParsingStatus;
335 }
336 
340 inline bool MediaFileInfo::hasId3v1Tag() const
341 {
342  return m_id3v1Tag != nullptr;
343 }
344 
348 inline bool MediaFileInfo::hasId3v2Tag() const
349 {
350  return !m_id3v2Tags.empty();
351 }
352 
361 {
362  return m_id3v1Tag.get();
363 }
364 
372 inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
373 {
374  return m_id3v2Tags;
375 }
376 
382 inline const std::string &MediaFileInfo::backupDirectory() const
383 {
384  return m_backupDirectory;
385 }
386 
391 inline void MediaFileInfo::setBackupDirectory(std::string_view backupDirectory)
392 {
393  m_backupDirectory = backupDirectory;
394 }
395 
400 inline void MediaFileInfo::setBackupDirectory(std::string &&backupDirectory)
401 {
402  m_backupDirectory = std::move(backupDirectory);
403 }
404 
409 inline const std::string &MediaFileInfo::saveFilePath() const
410 {
411  return m_saveFilePath;
412 }
413 
428 inline void MediaFileInfo::setSaveFilePath(std::string_view saveFilePath)
429 {
430  m_saveFilePath = saveFilePath;
431 }
432 
436 inline void MediaFileInfo::setSaveFilePath(std::string &&saveFilePath)
437 {
438  m_saveFilePath = std::move(saveFilePath);
439 }
440 
446 inline const std::string &MediaFileInfo::writingApplication() const
447 {
448  return m_writingApplication;
449 }
450 
455 inline void MediaFileInfo::setWritingApplication(std::string_view writingApplication)
456 {
457  m_writingApplication = writingApplication;
458 }
459 
471 {
472  return m_container.get();
473 }
474 
484 {
485  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceFullParse;
486 }
487 
493 inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
494 {
495  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceFullParse, forceFullParse);
496 }
497 
502 {
503  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceRewrite;
504 }
505 
509 inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
510 {
511  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceRewrite, forceRewrite);
512 }
513 
526 inline std::size_t MediaFileInfo::minPadding() const
527 {
528  return m_minPadding;
529 }
530 
536 inline void MediaFileInfo::setMinPadding(std::size_t minPadding)
537 {
538  m_minPadding = minPadding;
539 }
540 
554 inline std::size_t MediaFileInfo::maxPadding() const
555 {
556  return m_maxPadding;
557 }
558 
564 inline void MediaFileInfo::setMaxPadding(std::size_t maxPadding)
565 {
566  m_maxPadding = maxPadding;
567 }
568 
575 inline std::size_t MediaFileInfo::preferredPadding() const
576 {
577  return m_preferredPadding;
578 }
579 
585 inline void MediaFileInfo::setPreferredPadding(std::size_t preferredPadding)
586 {
587  m_preferredPadding = preferredPadding;
588 }
589 
596 {
597  return m_tagPosition;
598 }
599 
611 {
612  m_tagPosition = tagPosition;
613 }
614 
621 {
622  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceTagPosition;
623 }
624 
630 inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
631 {
632  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceTagPosition, forceTagPosition);
633 }
634 
641 {
642  return m_indexPosition;
643 }
644 
651 {
652  m_indexPosition = indexPosition;
653 }
654 
661 {
662  return m_fileHandlingFlags & MediaFileHandlingFlags::ForceIndexPosition;
663 }
664 
670 inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
671 {
672  CppUtilities::modFlagEnum(m_fileHandlingFlags, MediaFileHandlingFlags::ForceIndexPosition, forceIndexPosition);
673 }
674 
675 } // namespace TagParser
676 
677 #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