Tag Parser  6.5.1
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 MEDIAINFO_H
2 #define MEDIAINFO_H
3 
4 #include "./signature.h"
5 #include "./statusprovider.h"
6 #include "./basicfileinfo.h"
7 #include "./abstractcontainer.h"
8 
9 #include <vector>
10 #include <unordered_set>
11 #include <memory>
12 
13 namespace Media {
14 
15 class Tag;
16 class Id3v1Tag;
17 class Id3v2Tag;
18 class Mp4Container;
19 class Mp4Atom;
20 class Mp4Tag;
21 class MatroskaContainer;
22 class OggContainer;
23 class EbmlElement;
24 class MatroskaTag;
25 class AbstractTrack;
26 class VorbisComment;
27 
28 enum class MediaType;
29 DECLARE_ENUM_CLASS(TagType, unsigned int);
30 
34 enum class TagUsage
35 {
36  Always,
37  KeepExisting,
38  Never
39 };
40 
45 enum class ParsingStatus : byte
46 {
47  NotParsedYet,
48  Ok,
49  NotSupported,
51 };
52 
54 {
55 public:
56  // constructor, destructor
57  MediaFileInfo();
58  MediaFileInfo(const std::string &path);
59  MediaFileInfo(const MediaFileInfo &) = delete;
60  MediaFileInfo &operator=(const MediaFileInfo &) = delete;
61  ~MediaFileInfo();
62 
63  // methods to parse file
64  void parseContainerFormat();
65  void parseTracks();
66  void parseTags();
67  void parseChapters();
68  void parseAttachments();
69  void parseEverything();
70 
71  // methods to apply changes
72  void applyChanges();
73 
74  // methods to get parsed information regarding ...
75  // ... the container
76  ContainerFormat containerFormat() const;
77  const char *containerFormatName() const;
78  const char *containerFormatAbbreviation() const;
79  const char *containerFormatSubversion() const;
80  const char *mimeType() const;
81  uint64 containerOffset() const;
82  uint64 paddingSize() const;
83  AbstractContainer *container() const;
84  ParsingStatus containerParsingStatus() const;
85  // ... the capters
86  ParsingStatus chaptersParsingStatus() const;
87  std::vector<AbstractChapter *> chapters() const;
88  bool areChaptersSupported() const;
89  // ... the attachments
90  ParsingStatus attachmentsParsingStatus() const;
91  std::vector<AbstractAttachment *> attachments() const;
92  bool areAttachmentsSupported() const;
93  // ... the tracks
94  ParsingStatus tracksParsingStatus() const;
95  std::size_t trackCount() const;
96  std::vector<AbstractTrack *> tracks() const;
97  bool hasTracksOfType(Media::MediaType type) const;
99  std::unordered_set<std::string> availableLanguages(Media::MediaType type = Media::MediaType::Audio) const;
100  std::string technicalSummary() const;
101  bool areTracksSupported() const;
102  // ... the tags
103  ParsingStatus tagsParsingStatus() const;
104  bool hasId3v1Tag() const;
105  bool hasId3v2Tag() const;
106  bool hasAnyTag() const;
107  Id3v1Tag *id3v1Tag() const;
108  const std::vector<std::unique_ptr<Id3v2Tag> > &id3v2Tags() const;
109  void tags(std::vector<Tag *> &tags) const;
110  std::vector<Tag *> tags() const;
111  Mp4Tag *mp4Tag() const;
112  const std::vector<std::unique_ptr<MatroskaTag> > &matroskaTags() const;
113  VorbisComment *vorbisComment() const;
114  bool areTagsSupported() const;
115 
116  // methods to create/remove tags
117  bool createAppropriateTags(bool treatUnknownFilesAsMp3Files = false, TagUsage id3v1usage = TagUsage::KeepExisting,
118  TagUsage id3v2usage = TagUsage::Always, bool id3InitOnCreate = false, bool id3TransferValuesOnRemoval = true, bool mergeMultipleSuccessiveId3v2Tags = true,
119  bool keepExistingId3v2version = true, byte id3v2MajorVersion = 3, const std::vector<TagTarget> &requiredTargets = std::vector<TagTarget>());
120  bool removeId3v1Tag();
121  Id3v1Tag *createId3v1Tag();
122  bool removeId3v2Tag(Id3v2Tag *tag);
123  bool removeAllId3v2Tags();
124  Id3v2Tag *createId3v2Tag();
125  void removeTag(Tag *tag);
126  void removeAllTags();
127  void mergeId3v2Tags();
128  bool id3v1ToId3v2();
129  bool id3v2ToId3v1();
130  VorbisComment *createVorbisComment();
131  bool removeVorbisComment();
132 
133  // methods to get/wipe notifications
134  bool haveRelatedObjectsNotifications() const;
135  NotificationType worstNotificationTypeIncludingRelatedObjects() const;
136  void gatherRelatedNotifications(NotificationList &notifications) const;
137  NotificationList gatherRelatedNotifications() const;
138  void clearParsingResults();
139 
140  // methods to get, set object behaviour
141  const std::string &saveFilePath() const;
142  void setSaveFilePath(const std::string &saveFilePath);
143  bool isForcingFullParse() const;
144  void setForceFullParse(bool forceFullParse);
145  bool isForcingRewrite() const;
146  void setForceRewrite(bool forceRewrite);
147  size_t minPadding() const;
148  void setMinPadding(size_t minPadding);
149  size_t maxPadding() const;
150  void setMaxPadding(size_t maxPadding);
151  size_t preferredPadding() const;
152  void setPreferredPadding(size_t preferredPadding);
153  ElementPosition tagPosition() const;
154  void setTagPosition(ElementPosition tagPosition);
155  bool forceTagPosition() const;
156  void setForceTagPosition(bool forceTagPosition);
157  ElementPosition indexPosition() const;
158  void setIndexPosition(ElementPosition indexPosition);
159  bool forceIndexPosition() const;
160  void setForceIndexPosition(bool forceTagPosition);
161 
162 protected:
163  virtual void invalidated();
164 
165 private:
166  // private methods internally used when rewriting the file to apply new tag information
167  // currently only the makeMp3File() methods is present; corresponding methods for
168  // other formats are outsourced to container classes
169  void makeMp3File();
170 
171  // fields related to the container
172  ParsingStatus m_containerParsingStatus;
173  ContainerFormat m_containerFormat;
174  std::streamoff m_containerOffset;
175  uint64 m_paddingSize;
176  bool m_actualExistingId3v1Tag;
177  std::list<std::streamoff> m_actualId3v2TagOffsets;
178  std::unique_ptr<AbstractContainer> m_container;
179 
180  // fields related to the tracks
181  ParsingStatus m_tracksParsingStatus;
182  std::unique_ptr<AbstractTrack> m_singleTrack;
183 
184  // fields related to the tag
185  ParsingStatus m_tagsParsingStatus;
186  std::unique_ptr<Id3v1Tag> m_id3v1Tag;
187  std::vector<std::unique_ptr<Id3v2Tag> > m_id3v2Tags;
188 
189  // fields related to the chapters and the attachments
190  ParsingStatus m_chaptersParsingStatus;
191  ParsingStatus m_attachmentsParsingStatus;
192 
193  // fields specifying object behaviour
194  std::string m_saveFilePath;
195  bool m_forceFullParse;
196  bool m_forceRewrite;
197  size_t m_minPadding;
198  size_t m_maxPadding;
199  size_t m_preferredPadding;
200  ElementPosition m_tagPosition;
201  bool m_forceTagPosition;
202  ElementPosition m_indexPosition;
203  bool m_forceIndexPosition;
204 };
205 
210 {
211  return m_containerParsingStatus;
212 }
213 
221 {
222  return m_containerFormat;
223 }
224 
235 inline const char *MediaFileInfo::containerFormatName() const
236 {
237  return Media::containerFormatName(m_containerFormat);
238 }
239 
251 {
252  return Media::containerFormatSubversion(m_containerFormat);
253 }
254 
258 inline uint64 MediaFileInfo::containerOffset() const
259 {
260  return m_containerOffset;
261 }
262 
266 inline uint64 MediaFileInfo::paddingSize() const
267 {
268  return m_paddingSize;
269 }
270 
275 {
276  return m_tagsParsingStatus;
277 }
278 
283 {
284  return m_tracksParsingStatus;
285 }
286 
295 inline size_t MediaFileInfo::trackCount() const
296 {
297  return m_singleTrack ? 1 : (m_container ? m_container->trackCount() : 0);
298 }
299 
304 {
305  return m_chaptersParsingStatus;
306 }
307 
312 {
313  return m_attachmentsParsingStatus;
314 }
315 
319 inline bool MediaFileInfo::hasId3v1Tag() const
320 {
321  return m_id3v1Tag != nullptr;
322 }
323 
327 inline bool MediaFileInfo::hasId3v2Tag() const
328 {
329  return !m_id3v2Tags.empty();
330 }
331 
340 {
341  return m_id3v1Tag.get();
342 }
343 
351 inline const std::vector<std::unique_ptr<Id3v2Tag> > &MediaFileInfo::id3v2Tags() const
352 {
353  return m_id3v2Tags;
354 }
355 
360 inline const std::string &MediaFileInfo::saveFilePath() const
361 {
362  return m_saveFilePath;
363 }
364 
379 inline void MediaFileInfo::setSaveFilePath(const std::string &saveFilePath)
380 {
381  m_saveFilePath = saveFilePath;
382 }
383 
395 {
396  return m_container.get();
397 }
398 
408 {
409  return m_forceFullParse;
410 }
411 
417 inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
418 {
419  m_forceFullParse = forceFullParse;
420 }
421 
426 {
427  return m_forceRewrite;
428 }
429 
433 inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
434 {
435  m_forceRewrite = forceRewrite;
436 }
437 
450 inline size_t MediaFileInfo::minPadding() const
451 {
452  return m_minPadding;
453 }
454 
460 inline void MediaFileInfo::setMinPadding(size_t minPadding)
461 {
462  m_minPadding = minPadding;
463 }
464 
478 inline size_t MediaFileInfo::maxPadding() const
479 {
480  return m_maxPadding;
481 }
482 
488 inline void MediaFileInfo::setMaxPadding(size_t maxPadding)
489 {
490  m_maxPadding = maxPadding;
491 }
492 
499 inline size_t MediaFileInfo::preferredPadding() const
500 {
501  return m_preferredPadding;
502 }
503 
509 inline void MediaFileInfo::setPreferredPadding(size_t preferredPadding)
510 {
511  m_preferredPadding = preferredPadding;
512 }
513 
520 {
521  return m_tagPosition;
522 }
523 
535 {
536  m_tagPosition = tagPosition;
537 }
538 
545 {
546  return m_forceTagPosition;
547 }
548 
554 inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
555 {
556  m_forceTagPosition = forceTagPosition;
557 }
558 
565 {
566  return m_indexPosition;
567 }
568 
575 {
576  m_indexPosition = indexPosition;
577 }
578 
585 {
586  return m_forceIndexPosition;
587 }
588 
594 inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
595 {
596  m_forceIndexPosition = forceIndexPosition;
597 }
598 
599 }
600 
601 #endif // MEDIAINFO_H
TAG_PARSER_EXPORT const char * duration()
MediaType
The MediaType enum specifies the type of media data (audio, video, text, ...).
Definition: mediaformat.h:13
ContainerFormat
Specifies the container format.
Definition: signature.h:17
void setForceRewrite(bool forceRewrite)
Sets whether forcing rewriting (when applying changes) is enabled.
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...
AbstractContainer * container() const
Returns the container for the current file.
Implementation of Media::Tag for Vorbis comments.
Definition: vorbiscomment.h:15
NotificationType
Specifies the notification type.
Definition: notification.h:18
ParsingStatus tagsParsingStatus() const
Returns an indication whether tag information has been parsed yet.
const std::vector< std::unique_ptr< Id3v2Tag > > & id3v2Tags() const
Returns pointers to the assigned ID3v2 tags.
Id3v1Tag * id3v1Tag() const
Returns a pointer to the assigned ID3v1 tag or nullptr if none is assigned.
TAG_PARSER_EXPORT const 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:255
bool isForcingFullParse() const
Returns an indication whether forcing a full parse is enabled.
void setMaxPadding(size_t maxPadding)
Sets the maximum padding to be written before the data blocks when applying changes.
uint64 containerOffset() const
Returns the actual container start offset.
bool forceIndexPosition() const
Returns whether indexPosition() is forced.
TAG_PARSER_EXPORT const char * containerFormatSubversion(ContainerFormat containerFormat)
Returns the subversion of the container format as C-style string.
Definition: signature.cpp:440
void setIndexPosition(ElementPosition indexPosition)
Sets the position (in the output file) where the index is written when applying changes.
size_t minPadding() const
Returns the minimum padding to be written before the data blocks when applying changes.
void setForceTagPosition(bool forceTagPosition)
Sets whether tagPosition() is forced.
DECLARE_ENUM_CLASS(TagTargetLevel, byte)
ParsingStatus
The ParsingStatus enum specifies whether a certain part of the file (tracks, tags, ...) has been parsed yet and if what the parsing result is.
Definition: mediafileinfo.h:45
bool isForcingRewrite() const
Returns whether forcing rewriting (when applying changes) is enabled.
const char * containerFormatSubversion() const
Returns the subversion of the container format as C-style string.
const std::string & saveFilePath() const
Returns the "save file path" which has been set using setSaveFilePath().
void setSaveFilePath(const std::string &saveFilePath)
Sets the "save file path".
TAG_PARSER_EXPORT const char * containerFormatName(ContainerFormat containerFormat)
Returns the name of the specified container format as C-style string.
Definition: signature.cpp:339
size_t preferredPadding() const
Returns the padding to be written before the data block when applying changes and the file needs to b...
Implementation of Media::Tag for the MP4 container.
Definition: mp4tag.h:90
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
ParsingStatus attachmentsParsingStatus() const
Returns whether the attachments have been parsed yet.
ElementPosition indexPosition() const
Returns the position (in the output file) where the index is written when applying changes...
uint64 paddingSize() const
Returns the padding size.
bool hasId3v2Tag() const
Returns an indication whether an ID3v2 tag is assigned.
The AbstractContainer class provides an interface and common functionality to parse and make a certai...
ParsingStatus tracksParsingStatus() const
Returns an indication whether tracks have been parsed yet.
Implementation of Media::Tag for ID3v2 tags.
Definition: id3v2tag.h:55
void setForceIndexPosition(bool forceTagPosition)
Sets whether indexPosition() is forced.
ParsingStatus containerParsingStatus() const
Returns an indication whether the container format has been parsed yet.
std::list< Notification > NotificationList
Definition: notification.h:39
Implementation of Media::Tag for ID3v1 tags.
Definition: id3v1tag.h:9
size_t maxPadding() const
Returns the maximum padding to be written before the data blocks when applying changes.
The MediaFileInfo class allows to read and write tag information providing a container/tag format ind...
Definition: mediafileinfo.h:53
TagUsage
The TagUsage enum specifies the usage of a certain tag type.
Definition: mediafileinfo.h:34
TagType
Specifies the tag type.
Definition: tag.h:21
bool forceTagPosition() const
Returns whether tagPosition() is forced.
void setMinPadding(size_t minPadding)
Sets the minimum padding to be written before the data blocks when applying changes.
ElementPosition tagPosition() const
Returns the position (in the output file) where the tag information is written when applying changes...
Contains all classes and functions of the TagInfo library.
Definition: exceptions.h:9
The StatusProvider class acts as a base class for objects providing status information.
void setForceFullParse(bool forceFullParse)
Sets whether forcing a full parse is enabled.
The BasicFileInfo class provides basic file information such as file name, extension, directory and size for a specified file.
Definition: basicfileinfo.h:13
ContainerFormat containerFormat() const
Returns the container format of the current file.
void setTagPosition(ElementPosition tagPosition)
Sets the position (in the output file) where the tag information is written when applying changes...
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
const char * containerFormatName() const
Returns the name of the container format as C-style string.
std::size_t trackCount() const
Returns the number of tracks that could be parsed.
bool hasId3v1Tag() const
Returns an indication whether an ID3v1 tag is assigned.
ParsingStatus chaptersParsingStatus() const
Returns whether the chapters have been parsed yet.