Tag Parser  9.1.2
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 namespace TagParser {
15 
16 class Tag;
17 class Id3v1Tag;
18 class Id3v2Tag;
19 class Mp4Container;
20 class Mp4Atom;
21 class Mp4Tag;
22 class MatroskaContainer;
23 class OggContainer;
24 class EbmlElement;
25 class MatroskaTag;
26 class AbstractTrack;
27 class VorbisComment;
28 class Diagnostics;
29 class AbortableProgressFeedback;
30 
31 enum class MediaType : unsigned int;
32 enum class TagType : unsigned int;
33 
38 enum class ParsingStatus : std::uint8_t {
39  NotParsedYet,
40  Ok,
41  NotSupported,
43 };
44 
46 public:
47  // constructor, destructor
48  MediaFileInfo();
49  MediaFileInfo(const std::string &path);
50  MediaFileInfo(const MediaFileInfo &) = delete;
51  MediaFileInfo &operator=(const MediaFileInfo &) = delete;
52  ~MediaFileInfo() override;
53 
54  // methods to parse file
55  void parseContainerFormat(Diagnostics &diag);
56  void parseTracks(Diagnostics &diag);
57  void parseTags(Diagnostics &diag);
58  void parseChapters(Diagnostics &diag);
59  void parseAttachments(Diagnostics &diag);
60  void parseEverything(Diagnostics &diag);
61 
62  // methods to apply changes
63  void applyChanges(Diagnostics &diag, AbortableProgressFeedback &progress);
64 
65  // methods to get parsed information regarding ...
66  // ... the container
67  ContainerFormat containerFormat() const;
68  const char *containerFormatName() const;
69  const char *containerFormatAbbreviation() const;
70  const char *containerFormatSubversion() const;
71  const char *mimeType() const;
72  std::uint64_t containerOffset() const;
73  std::uint64_t paddingSize() const;
74  AbstractContainer *container() const;
75  ParsingStatus containerParsingStatus() const;
76  // ... the capters
77  ParsingStatus chaptersParsingStatus() const;
78  std::vector<AbstractChapter *> chapters() const;
79  bool areChaptersSupported() const;
80  // ... the attachments
81  ParsingStatus attachmentsParsingStatus() const;
82  std::vector<AbstractAttachment *> attachments() const;
83  bool areAttachmentsSupported() const;
84  // ... the tracks
85  ParsingStatus tracksParsingStatus() const;
86  std::size_t trackCount() const;
87  std::vector<AbstractTrack *> tracks() const;
88  bool hasTracksOfType(TagParser::MediaType type) const;
89  CppUtilities::TimeSpan duration() const;
90  double overallAverageBitrate() const;
91  std::unordered_set<std::string> availableLanguages(TagParser::MediaType type = TagParser::MediaType::Audio) const;
92  std::string technicalSummary() const;
93  bool areTracksSupported() const;
94  // ... the tags
95  ParsingStatus tagsParsingStatus() const;
96  bool hasId3v1Tag() const;
97  bool hasId3v2Tag() const;
98  bool hasAnyTag() const;
99  Id3v1Tag *id3v1Tag() const;
100  const std::vector<std::unique_ptr<Id3v2Tag>> &id3v2Tags() const;
101  void tags(std::vector<Tag *> &tags) const;
102  std::vector<Tag *> tags() const;
103  Mp4Tag *mp4Tag() const;
104  const std::vector<std::unique_ptr<MatroskaTag>> &matroskaTags() const;
105  VorbisComment *vorbisComment() const;
106  bool areTagsSupported() const;
107 
108  // methods to create/remove tags
109  bool createAppropriateTags(const TagCreationSettings &settings = TagCreationSettings());
110  bool removeId3v1Tag();
111  Id3v1Tag *createId3v1Tag();
112  bool removeId3v2Tag(Id3v2Tag *tag);
113  bool removeAllId3v2Tags();
114  Id3v2Tag *createId3v2Tag();
115  bool removeTag(Tag *tag);
116  void removeAllTags();
117  void mergeId3v2Tags();
118  bool id3v1ToId3v2();
119  bool id3v2ToId3v1();
120  VorbisComment *createVorbisComment();
121  bool removeVorbisComment();
122  void clearParsingResults();
123 
124  // methods to get, set object behaviour
125  const std::string &backupDirectory() const;
126  void setBackupDirectory(const std::string &backupDirectory);
127  const std::string &saveFilePath() const;
128  void setSaveFilePath(const std::string &saveFilePath);
129  const std::string writingApplication() const;
130  void setWritingApplication(const std::string &writingApplication);
131  void setWritingApplication(const char *writingApplication);
132  bool isForcingFullParse() const;
133  void setForceFullParse(bool forceFullParse);
134  bool isForcingRewrite() const;
135  void setForceRewrite(bool forceRewrite);
136  size_t minPadding() const;
137  void setMinPadding(size_t minPadding);
138  size_t maxPadding() const;
139  void setMaxPadding(size_t maxPadding);
140  size_t preferredPadding() const;
141  void setPreferredPadding(size_t preferredPadding);
142  ElementPosition tagPosition() const;
143  void setTagPosition(ElementPosition tagPosition);
144  bool forceTagPosition() const;
145  void setForceTagPosition(bool forceTagPosition);
146  ElementPosition indexPosition() const;
147  void setIndexPosition(ElementPosition indexPosition);
148  bool forceIndexPosition() const;
149  void setForceIndexPosition(bool forceTagPosition);
150 
151 protected:
152  void invalidated() override;
153 
154 private:
155  // private methods internally used when rewriting the file to apply new tag information
156  // currently only the makeMp3File() methods is present; corresponding methods for
157  // other formats are outsourced to container classes
158  void makeMp3File(Diagnostics &diag, AbortableProgressFeedback &progress);
159 
160  // fields related to the container
161  ParsingStatus m_containerParsingStatus;
162  ContainerFormat m_containerFormat;
163  std::streamoff m_containerOffset;
164  std::uint64_t m_paddingSize;
165  bool m_actualExistingId3v1Tag;
166  std::vector<std::streamoff> m_actualId3v2TagOffsets;
167  std::unique_ptr<AbstractContainer> m_container;
168 
169  // fields related to the tracks
170  ParsingStatus m_tracksParsingStatus;
171  std::unique_ptr<AbstractTrack> m_singleTrack;
172 
173  // fields related to the tag
174  ParsingStatus m_tagsParsingStatus;
175  std::unique_ptr<Id3v1Tag> m_id3v1Tag;
176  std::vector<std::unique_ptr<Id3v2Tag>> m_id3v2Tags;
177 
178  // fields related to the chapters and the attachments
179  ParsingStatus m_chaptersParsingStatus;
180  ParsingStatus m_attachmentsParsingStatus;
181 
182  // fields specifying object behaviour
183  std::string m_backupDirectory;
184  std::string m_saveFilePath;
185  std::string m_writingApplication;
186  size_t m_minPadding;
187  size_t m_maxPadding;
188  size_t m_preferredPadding;
189  ElementPosition m_tagPosition;
190  ElementPosition m_indexPosition;
191  bool m_forceFullParse;
192  bool m_forceRewrite;
193  bool m_forceTagPosition;
194  bool m_forceIndexPosition;
195 };
196 
201 {
202  return m_containerParsingStatus;
203 }
204 
212 {
213  return m_containerFormat;
214 }
215 
226 inline const char *MediaFileInfo::containerFormatName() const
227 {
228  return TagParser::containerFormatName(m_containerFormat);
229 }
230 
242 {
243  return TagParser::containerFormatSubversion(m_containerFormat);
244 }
245 
249 inline std::uint64_t MediaFileInfo::containerOffset() const
250 {
251  return static_cast<std::uint64_t>(m_containerOffset);
252 }
253 
257 inline std::uint64_t MediaFileInfo::paddingSize() const
258 {
259  return m_paddingSize;
260 }
261 
266 {
267  return m_tagsParsingStatus;
268 }
269 
274 {
275  return m_tracksParsingStatus;
276 }
277 
286 inline size_t MediaFileInfo::trackCount() const
287 {
288  return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
289 }
290 
295 {
296  return m_chaptersParsingStatus;
297 }
298 
303 {
304  return m_attachmentsParsingStatus;
305 }
306 
310 inline bool MediaFileInfo::hasId3v1Tag() const
311 {
312  return m_id3v1Tag != nullptr;
313 }
314 
318 inline bool MediaFileInfo::hasId3v2Tag() const
319 {
320  return !m_id3v2Tags.empty();
321 }
322 
331 {
332  return m_id3v1Tag.get();
333 }
334 
342 inline const std::vector<std::unique_ptr<Id3v2Tag>> &MediaFileInfo::id3v2Tags() const
343 {
344  return m_id3v2Tags;
345 }
346 
352 inline const std::string &MediaFileInfo::backupDirectory() const
353 {
354  return m_backupDirectory;
355 }
356 
361 inline void MediaFileInfo::setBackupDirectory(const std::string &backupDirectory)
362 {
363  m_backupDirectory = backupDirectory;
364 }
365 
370 inline const std::string &MediaFileInfo::saveFilePath() const
371 {
372  return m_saveFilePath;
373 }
374 
389 inline void MediaFileInfo::setSaveFilePath(const std::string &saveFilePath)
390 {
391  m_saveFilePath = saveFilePath;
392 }
393 
399 inline const std::string MediaFileInfo::writingApplication() const
400 {
401  return m_writingApplication;
402 }
403 
408 inline void MediaFileInfo::setWritingApplication(const std::string &writingApplication)
409 {
410  m_writingApplication = writingApplication;
411 }
412 
417 inline void MediaFileInfo::setWritingApplication(const char *writingApplication)
418 {
419  m_writingApplication = writingApplication;
420 }
421 
433 {
434  return m_container.get();
435 }
436 
446 {
447  return m_forceFullParse;
448 }
449 
455 inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
456 {
457  m_forceFullParse = forceFullParse;
458 }
459 
464 {
465  return m_forceRewrite;
466 }
467 
471 inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
472 {
473  m_forceRewrite = forceRewrite;
474 }
475 
488 inline size_t MediaFileInfo::minPadding() const
489 {
490  return m_minPadding;
491 }
492 
498 inline void MediaFileInfo::setMinPadding(size_t minPadding)
499 {
500  m_minPadding = minPadding;
501 }
502 
516 inline size_t MediaFileInfo::maxPadding() const
517 {
518  return m_maxPadding;
519 }
520 
526 inline void MediaFileInfo::setMaxPadding(size_t maxPadding)
527 {
528  m_maxPadding = maxPadding;
529 }
530 
537 inline size_t MediaFileInfo::preferredPadding() const
538 {
539  return m_preferredPadding;
540 }
541 
547 inline void MediaFileInfo::setPreferredPadding(size_t preferredPadding)
548 {
549  m_preferredPadding = preferredPadding;
550 }
551 
558 {
559  return m_tagPosition;
560 }
561 
573 {
574  m_tagPosition = tagPosition;
575 }
576 
583 {
584  return m_forceTagPosition;
585 }
586 
592 inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
593 {
594  m_forceTagPosition = forceTagPosition;
595 }
596 
603 {
604  return m_indexPosition;
605 }
606 
613 {
614  m_indexPosition = indexPosition;
615 }
616 
623 {
624  return m_forceIndexPosition;
625 }
626 
632 inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
633 {
634  m_forceIndexPosition = forceIndexPosition;
635 }
636 
637 } // namespace TagParser
638 
639 #endif // TAG_PARSER_MEDIAINFO_H
TagParser::MediaFileInfo::writingApplication
const std::string writingApplication() const
Sets the writing application as container-level meta-data.
Definition: mediafileinfo.h:399
TagParser::ParsingStatus::NotSupported
@ NotSupported
TagParser::MediaFileInfo::forceIndexPosition
bool forceIndexPosition() const
Returns whether indexPosition() is forced.
Definition: mediafileinfo.h:622
TagParser::MediaType::Audio
@ Audio
TagParser::TagCreationSettings
The TagSettings struct contains settings which can be passed to MediaFileInfo::createAppropriateTags(...
Definition: settings.h:50
settings.h
TagParser::AbortableProgressFeedback
The AbortableProgressFeedback class provides feedback about an ongoing operation via callbacks....
Definition: progressfeedback.h:186
TagParser::MediaFileInfo::forceTagPosition
bool forceTagPosition() const
Returns whether tagPosition() is forced.
Definition: mediafileinfo.h:582
TagParser::MediaFileInfo::setForceRewrite
void setForceRewrite(bool forceRewrite)
Sets whether forcing rewriting (when applying changes) is enabled.
Definition: mediafileinfo.h:471
TagParser::MediaFileInfo::saveFilePath
const std::string & saveFilePath() const
Returns the "save file path" which has been set using setSaveFilePath().
Definition: mediafileinfo.h:370
TagParser::ParsingStatus::Ok
@ Ok
TagParser::Tag
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
TagParser::containerFormatName
const TAG_PARSER_EXPORT char * containerFormatName(ContainerFormat containerFormat)
Returns the name of the specified container format as C-style string.
Definition: signature.cpp:373
TagParser::MediaFileInfo::preferredPadding
size_t preferredPadding() const
Returns the padding to be written before the data block when applying changes and the file needs to b...
Definition: mediafileinfo.h:537
TagParser::MediaFileInfo::id3v1Tag
Id3v1Tag * id3v1Tag() const
Returns a pointer to the assigned ID3v1 tag or nullptr if none is assigned.
Definition: mediafileinfo.h:330
TagParser::Diagnostics
The Diagnostics class is a container for DiagMessage.
Definition: diagnostics.h:156
TagParser::MediaFileInfo::chaptersParsingStatus
ParsingStatus chaptersParsingStatus() const
Returns whether the chapters have been parsed yet.
Definition: mediafileinfo.h:294
TagParser
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TagParser::TagType::MatroskaTag
@ MatroskaTag
TagParser::MediaFileInfo::setTagPosition
void setTagPosition(ElementPosition tagPosition)
Sets the position (in the output file) where the tag information is written when applying changes.
Definition: mediafileinfo.h:572
TagParser::MediaFileInfo::setBackupDirectory
void setBackupDirectory(const std::string &backupDirectory)
Sets the directory used to store backup files.
Definition: mediafileinfo.h:361
TagParser::FlacMetaDataBlockType::VorbisComment
@ VorbisComment
TagParser::containerFormatAbbreviation
const TAG_PARSER_EXPORT char * 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
TagParser::MediaFileInfo::minPadding
size_t minPadding() const
Returns the minimum padding to be written before the data blocks when applying changes.
Definition: mediafileinfo.h:488
TagParser::MatroskaTagIds::duration
constexpr const TAG_PARSER_EXPORT char * duration()
Definition: matroskatagid.h:342
TagParser::MediaFileInfo::setMinPadding
void setMinPadding(size_t minPadding)
Sets the minimum padding to be written before the data blocks when applying changes.
Definition: mediafileinfo.h:498
signature.h
TagParser::MediaFileInfo::setIndexPosition
void setIndexPosition(ElementPosition indexPosition)
Sets the position (in the output file) where the index is written when applying changes.
Definition: mediafileinfo.h:612
TagParser::MediaFileInfo::setForceFullParse
void setForceFullParse(bool forceFullParse)
Sets whether forcing a full parse is enabled.
Definition: mediafileinfo.h:455
TagParser::MediaFileInfo::setWritingApplication
void setWritingApplication(const std::string &writingApplication)
Sets the writing application as container-level meta-data.
Definition: mediafileinfo.h:408
TagParser::MediaFileInfo::isForcingFullParse
bool isForcingFullParse() const
Returns an indication whether forcing a full parse is enabled.
Definition: mediafileinfo.h:445
TagParser::containerFormatSubversion
const TAG_PARSER_EXPORT char * containerFormatSubversion(ContainerFormat containerFormat)
Returns the subversion of the container format as C-style string.
Definition: signature.cpp:478
TagParser::TagType::Mp4Tag
@ Mp4Tag
TagParser::MediaType
MediaType
The MediaType enum specifies the type of media data (audio, video, text, ...).
Definition: mediaformat.h:13
TagParser::MediaFileInfo::tagPosition
ElementPosition tagPosition() const
Returns the position (in the output file) where the tag information is written when applying changes.
Definition: mediafileinfo.h:557
TagParser::AbstractContainer
The AbstractContainer class provides an interface and common functionality to parse and make a certai...
Definition: abstractcontainer.h:29
TagParser::MediaFileInfo::setMaxPadding
void setMaxPadding(size_t maxPadding)
Sets the maximum padding to be written before the data blocks when applying changes.
Definition: mediafileinfo.h:526
TagParser::MediaFileInfo::container
AbstractContainer * container() const
Returns the container for the current file.
Definition: mediafileinfo.h:432
basicfileinfo.h
TagParser::BasicFileInfo
The BasicFileInfo class provides basic file information such as file name, extension,...
Definition: basicfileinfo.h:14
TagParser::MediaFileInfo::containerParsingStatus
ParsingStatus containerParsingStatus() const
Returns an indication whether the container format has been parsed yet.
Definition: mediafileinfo.h:200
TagParser::MediaFileInfo::hasId3v2Tag
bool hasId3v2Tag() const
Returns an indication whether an ID3v2 tag is assigned.
Definition: mediafileinfo.h:318
TagParser::ParsingStatus::CriticalFailure
@ CriticalFailure
TagParser::MediaFileInfo::tagsParsingStatus
ParsingStatus tagsParsingStatus() const
Returns an indication whether tag information has been parsed yet.
Definition: mediafileinfo.h:265
TagParser::MediaFileInfo::hasId3v1Tag
bool hasId3v1Tag() const
Returns an indication whether an ID3v1 tag is assigned.
Definition: mediafileinfo.h:310
TagParser::MediaFileInfo::maxPadding
size_t maxPadding() const
Returns the maximum padding to be written before the data blocks when applying changes.
Definition: mediafileinfo.h:516
TagParser::ParsingStatus
ParsingStatus
The ParsingStatus enum specifies whether a certain part of the file (tracks, tags,...
Definition: mediafileinfo.h:38
TagParser::Id3v2Tag
Implementation of TagParser::Tag for ID3v2 tags.
Definition: id3v2tag.h:61
TagParser::ContainerFormat
ContainerFormat
Specifies the container format.
Definition: signature.h:17
TagParser::Id3v1Tag
Implementation of TagParser::Tag for ID3v1 tags.
Definition: id3v1tag.h:10
TagParser::MediaFileInfo::setPreferredPadding
void setPreferredPadding(size_t preferredPadding)
Sets the padding to be written before the data block when applying changes and the file needs to be r...
Definition: mediafileinfo.h:547
TagParser::MediaFileInfo::id3v2Tags
const std::vector< std::unique_ptr< Id3v2Tag > > & id3v2Tags() const
Returns pointers to the assigned ID3v2 tags.
Definition: mediafileinfo.h:342
TagParser::ParsingStatus::NotParsedYet
@ NotParsedYet
TagParser::ElementPosition
ElementPosition
Definition: settings.h:13
TagParser::Mp4Tag
Implementation of TagParser::Tag for the MP4 container.
Definition: mp4tag.h:97
TagParser::MatroskaIds::Tag
@ Tag
Definition: matroskaid.h:204
TagParser::MediaFileInfo::containerOffset
std::uint64_t containerOffset() const
Returns the actual container start offset.
Definition: mediafileinfo.h:249
TagParser::MediaFileInfo::setSaveFilePath
void setSaveFilePath(const std::string &saveFilePath)
Sets the "save file path".
Definition: mediafileinfo.h:389
TagParser::TagType::Id3v2Tag
@ Id3v2Tag
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TagParser::MediaFileInfo::attachmentsParsingStatus
ParsingStatus attachmentsParsingStatus() const
Returns whether the attachments have been parsed yet.
Definition: mediafileinfo.h:302
TagParser::MediaFileInfo::paddingSize
std::uint64_t paddingSize() const
Returns the padding size.
Definition: mediafileinfo.h:257
TagParser::MediaFileInfo::tracksParsingStatus
ParsingStatus tracksParsingStatus() const
Returns an indication whether tracks have been parsed yet.
Definition: mediafileinfo.h:273
abstractcontainer.h
TagParser::VorbisComment
Implementation of TagParser::Tag for Vorbis comments.
Definition: vorbiscomment.h:25
TagParser::MediaFileInfo::indexPosition
ElementPosition indexPosition() const
Returns the position (in the output file) where the index is written when applying changes.
Definition: mediafileinfo.h:602
TagParser::MediaFileInfo::containerFormatSubversion
const char * containerFormatSubversion() const
Returns the subversion of the container format as C-style string.
Definition: mediafileinfo.h:241
TagParser::MediaFileInfo::backupDirectory
const std::string & backupDirectory() const
Returns the directory used to store backup files.
Definition: mediafileinfo.h:352
TagParser::MediaFileInfo
The MediaFileInfo class allows to read and write tag information providing a container/tag format ind...
Definition: mediafileinfo.h:45
TagParser::MediaFileInfo::containerFormat
ContainerFormat containerFormat() const
Returns the container format of the current file.
Definition: mediafileinfo.h:211
TagParser::TagType::Id3v1Tag
@ Id3v1Tag
TagParser::MediaFileInfo::isForcingRewrite
bool isForcingRewrite() const
Returns whether forcing rewriting (when applying changes) is enabled.
Definition: mediafileinfo.h:463
TagParser::MediaFileInfo::setForceIndexPosition
void setForceIndexPosition(bool forceTagPosition)
Sets whether indexPosition() is forced.
Definition: mediafileinfo.h:632
TagParser::MediaFileInfo::setForceTagPosition
void setForceTagPosition(bool forceTagPosition)
Sets whether tagPosition() is forced.
Definition: mediafileinfo.h:592
TagParser::MediaFileInfo::trackCount
std::size_t trackCount() const
Returns the number of tracks that could be parsed.
Definition: mediafileinfo.h:286
TagParser::MediaFileInfo::containerFormatName
const char * containerFormatName() const
Returns the name of the container format as C-style string.
Definition: mediafileinfo.h:226
TagParser::TagType
TagType
Specifies the tag type.
Definition: tag.h:20