Tag Parser  6.2.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 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 <memory>
11 
12 namespace Media {
13 
14 class Tag;
15 class Id3v1Tag;
16 class Id3v2Tag;
17 class Mp4Container;
18 class Mp4Atom;
19 class Mp4Tag;
20 class MatroskaContainer;
21 class OggContainer;
22 class EbmlElement;
23 class MatroskaTag;
24 class AbstractTrack;
25 class VorbisComment;
26 
27 enum class MediaType;
28 DECLARE_ENUM_CLASS(TagType, unsigned int);
29 
33 enum class TagUsage
34 {
35  Always,
36  KeepExisting,
37  Never
38 };
39 
44 enum class ParsingStatus : byte
45 {
46  NotParsedYet,
47  Ok,
48  NotSupported,
50 };
51 
53 {
54 public:
55  // constructor, destructor
56  MediaFileInfo();
57  MediaFileInfo(const std::string &path);
58  MediaFileInfo(const MediaFileInfo &) = delete;
59  MediaFileInfo &operator=(const MediaFileInfo &) = delete;
60  ~MediaFileInfo();
61 
62  // methods to parse file
63  void parseContainerFormat();
64  void parseTracks();
65  void parseTags();
66  void parseChapters();
67  void parseAttachments();
68  void parseEverything();
69 
70  // methods to apply changes
71  void applyChanges();
72 
73  // methods to get parsed information regarding ...
74  // ... the container
75  ContainerFormat containerFormat() const;
76  const char *containerFormatName() const;
77  const char *containerFormatAbbreviation() const;
78  const char *containerFormatSubversion() const;
79  const char *mimeType() const;
80  uint64 containerOffset() const;
81  uint64 paddingSize() const;
82  AbstractContainer *container() const;
83  ParsingStatus containerParsingStatus() const;
84  // ... the capters
85  ParsingStatus chaptersParsingStatus() const;
86  std::vector<AbstractChapter *> chapters() const;
87  bool areChaptersSupported() const;
88  // ... the attachments
89  ParsingStatus attachmentsParsingStatus() const;
90  std::vector<AbstractAttachment *> attachments() const;
91  bool areAttachmentsSupported() const;
92  // ... the tracks
93  ParsingStatus tracksParsingStatus() const;
94  std::size_t trackCount() const;
95  std::vector<AbstractTrack *> tracks() const;
96  bool hasTracksOfType(Media::MediaType type) const;
98  bool areTracksSupported() const;
99  // ... the tags
100  ParsingStatus tagsParsingStatus() const;
101  bool hasId3v1Tag() const;
102  bool hasId3v2Tag() const;
103  bool hasAnyTag() const;
104  Id3v1Tag *id3v1Tag() const;
105  const std::vector<std::unique_ptr<Id3v2Tag> > &id3v2Tags() const;
106  void tags(std::vector<Tag *> &tags) const;
107  std::vector<Tag *> tags() const;
108  Mp4Tag *mp4Tag() const;
109  const std::vector<std::unique_ptr<MatroskaTag> > &matroskaTags() const;
110  VorbisComment *vorbisComment() const;
111  bool areTagsSupported() const;
112 
113  // methods to create/remove tags
114  bool createAppropriateTags(bool treatUnknownFilesAsMp3Files = false, TagUsage id3v1usage = TagUsage::KeepExisting,
115  TagUsage id3v2usage = TagUsage::Always, bool id3InitOnCreate = false, bool id3TransferValuesOnRemoval = true, bool mergeMultipleSuccessiveId3v2Tags = true,
116  bool keepExistingId3v2version = true, byte id3v2MajorVersion = 3, const std::vector<TagTarget> &requiredTargets = std::vector<TagTarget>());
117  bool removeId3v1Tag();
118  Id3v1Tag *createId3v1Tag();
119  bool removeId3v2Tag(Id3v2Tag *tag);
120  bool removeAllId3v2Tags();
121  Id3v2Tag *createId3v2Tag();
122  void removeTag(Tag *tag);
123  void removeAllTags();
124  void mergeId3v2Tags();
125  bool id3v1ToId3v2();
126  bool id3v2ToId3v1();
127  VorbisComment *createVorbisComment();
128  bool removeVorbisComment();
129 
130  // methods to get/wipe notifications
131  bool haveRelatedObjectsNotifications() const;
132  NotificationType worstNotificationTypeIncludingRelatedObjects() const;
133  void gatherRelatedNotifications(NotificationList &notifications) const;
134  NotificationList gatherRelatedNotifications() const;
135  void clearParsingResults();
136 
137  // methods to get, set object behaviour
138  const std::string &saveFilePath() const;
139  void setSaveFilePath(const std::string &saveFilePath);
140  bool isForcingFullParse() const;
141  void setForceFullParse(bool forceFullParse);
142  bool isForcingRewrite() const;
143  void setForceRewrite(bool forceRewrite);
144  size_t minPadding() const;
145  void setMinPadding(size_t minPadding);
146  size_t maxPadding() const;
147  void setMaxPadding(size_t maxPadding);
148  size_t preferredPadding() const;
149  void setPreferredPadding(size_t preferredPadding);
150  ElementPosition tagPosition() const;
151  void setTagPosition(ElementPosition tagPosition);
152  bool forceTagPosition() const;
153  void setForceTagPosition(bool forceTagPosition);
154  ElementPosition indexPosition() const;
155  void setIndexPosition(ElementPosition indexPosition);
156  bool forceIndexPosition() const;
157  void setForceIndexPosition(bool forceTagPosition);
158 
159 protected:
160  virtual void invalidated();
161 
162 private:
163  // private methods internally used when rewriting the file to apply new tag information
164  // currently only the makeMp3File() methods is present; corresponding methods for
165  // other formats are outsourced to container classes
166  void makeMp3File();
167 
168  // fields related to the container
169  ParsingStatus m_containerParsingStatus;
170  ContainerFormat m_containerFormat;
171  std::streamoff m_containerOffset;
172  uint64 m_paddingSize;
173  bool m_actualExistingId3v1Tag;
174  std::list<std::streamoff> m_actualId3v2TagOffsets;
175  std::unique_ptr<AbstractContainer> m_container;
176 
177  // fields related to the tracks
178  ParsingStatus m_tracksParsingStatus;
179  std::unique_ptr<AbstractTrack> m_singleTrack;
180 
181  // fields related to the tag
182  ParsingStatus m_tagsParsingStatus;
183  std::unique_ptr<Id3v1Tag> m_id3v1Tag;
184  std::vector<std::unique_ptr<Id3v2Tag> > m_id3v2Tags;
185 
186  // fields related to the chapters and the attachments
187  ParsingStatus m_chaptersParsingStatus;
188  ParsingStatus m_attachmentsParsingStatus;
189 
190  // fields specifying object behaviour
191  std::string m_saveFilePath;
192  bool m_forceFullParse;
193  bool m_forceRewrite;
194  size_t m_minPadding;
195  size_t m_maxPadding;
196  size_t m_preferredPadding;
197  ElementPosition m_tagPosition;
198  bool m_forceTagPosition;
199  ElementPosition m_indexPosition;
200  bool m_forceIndexPosition;
201 };
202 
207 {
208  return m_containerParsingStatus;
209 }
210 
218 {
219  return m_containerFormat;
220 }
221 
232 inline const char *MediaFileInfo::containerFormatName() const
233 {
234  return Media::containerFormatName(m_containerFormat);
235 }
236 
248 {
249  return Media::containerFormatSubversion(m_containerFormat);
250 }
251 
255 inline uint64 MediaFileInfo::containerOffset() const
256 {
257  return m_containerOffset;
258 }
259 
263 inline uint64 MediaFileInfo::paddingSize() const
264 {
265  return m_paddingSize;
266 }
267 
272 {
273  return m_tagsParsingStatus;
274 }
275 
280 {
281  return m_tracksParsingStatus;
282 }
283 
292 inline size_t MediaFileInfo::trackCount() const
293 {
294  return m_singleTrack ? 1 : 0 + m_container->trackCount();
295 }
296 
301 {
302  return m_chaptersParsingStatus;
303 }
304 
309 {
310  return m_attachmentsParsingStatus;
311 }
312 
316 inline bool MediaFileInfo::hasId3v1Tag() const
317 {
318  return m_id3v1Tag != nullptr;
319 }
320 
324 inline bool MediaFileInfo::hasId3v2Tag() const
325 {
326  return !m_id3v2Tags.empty();
327 }
328 
337 {
338  return m_id3v1Tag.get();
339 }
340 
348 inline const std::vector<std::unique_ptr<Id3v2Tag> > &MediaFileInfo::id3v2Tags() const
349 {
350  return m_id3v2Tags;
351 }
352 
357 inline const std::string &MediaFileInfo::saveFilePath() const
358 {
359  return m_saveFilePath;
360 }
361 
376 inline void MediaFileInfo::setSaveFilePath(const std::string &saveFilePath)
377 {
378  m_saveFilePath = saveFilePath;
379 }
380 
392 {
393  return m_container.get();
394 }
395 
405 {
406  return m_forceFullParse;
407 }
408 
414 inline void MediaFileInfo::setForceFullParse(bool forceFullParse)
415 {
416  m_forceFullParse = forceFullParse;
417 }
418 
423 {
424  return m_forceRewrite;
425 }
426 
430 inline void MediaFileInfo::setForceRewrite(bool forceRewrite)
431 {
432  m_forceRewrite = forceRewrite;
433 }
434 
447 inline size_t MediaFileInfo::minPadding() const
448 {
449  return m_minPadding;
450 }
451 
457 inline void MediaFileInfo::setMinPadding(size_t minPadding)
458 {
459  m_minPadding = minPadding;
460 }
461 
475 inline size_t MediaFileInfo::maxPadding() const
476 {
477  return m_maxPadding;
478 }
479 
485 inline void MediaFileInfo::setMaxPadding(size_t maxPadding)
486 {
487  m_maxPadding = maxPadding;
488 }
489 
496 inline size_t MediaFileInfo::preferredPadding() const
497 {
498  return m_preferredPadding;
499 }
500 
506 inline void MediaFileInfo::setPreferredPadding(size_t preferredPadding)
507 {
508  m_preferredPadding = preferredPadding;
509 }
510 
517 {
518  return m_tagPosition;
519 }
520 
532 {
533  m_tagPosition = tagPosition;
534 }
535 
542 {
543  return m_forceTagPosition;
544 }
545 
551 inline void MediaFileInfo::setForceTagPosition(bool forceTagPosition)
552 {
553  m_forceTagPosition = forceTagPosition;
554 }
555 
562 {
563  return m_indexPosition;
564 }
565 
572 {
573  m_indexPosition = indexPosition;
574 }
575 
582 {
583  return m_forceIndexPosition;
584 }
585 
591 inline void MediaFileInfo::setForceIndexPosition(bool forceIndexPosition)
592 {
593  m_forceIndexPosition = forceIndexPosition;
594 }
595 
596 }
597 
598 #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:240
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:411
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:44
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:318
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:52
TagUsage
The TagUsage enum specifies the usage of a certain tag type.
Definition: mediafileinfo.h:33
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.