Tag Parser  8.2.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
tag.h
Go to the documentation of this file.
1 #ifndef TAG_PARSER_TAG_H
2 #define TAG_PARSER_TAG_H
3 
4 #include "./tagtarget.h"
5 #include "./tagvalue.h"
6 
7 #include <c++utilities/conversion/types.h>
8 #include <c++utilities/io/binaryreader.h>
9 
10 #include <string>
11 #include <type_traits>
12 
13 namespace TagParser {
14 
20 enum class TagType : unsigned int {
21  Unspecified = 0x00,
22  Id3v1Tag = 0x01,
23  Id3v2Tag = 0x02,
24  Mp4Tag = 0x04,
25  MatroskaTag = 0x08,
26  VorbisComment = 0x10,
27  OggVorbisComment = 0x20
28 };
29 
42 enum class KnownField : unsigned int {
43  Invalid = std::numeric_limits<unsigned int>::max(),
44  Title = 0,
45  Album,
46  Artist,
47  Genre,
48  Year,
49  Comment,
50  Bpm,
51  Bps,
52  Lyricist,
54  DiskPosition,
55  PartNumber,
56  TotalParts,
57  Encoder,
58  RecordDate,
59  Performers,
60  Length,
61  Language,
63  Lyrics,
65  Grouping,
66  RecordLabel,
67  Cover,
68  Composer,
69  Rating,
70  Description,
71  Vendor,
72  AlbumArtist,
73 };
74 
79 
84 
88 constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
89 
94 {
95  return field == lastKnownField ? KnownField::Invalid : static_cast<KnownField>(static_cast<int>(field) + 1);
96 }
97 
99 public:
100  virtual ~Tag();
101 
102  virtual TagType type() const;
103  virtual const char *typeName() const;
104  std::string toString() const;
105  virtual TagTextEncoding proposedTextEncoding() const;
106  virtual bool canEncodingBeUsed(TagTextEncoding encoding) const;
107  virtual const TagValue &value(KnownField field) const = 0;
108  virtual std::vector<const TagValue *> values(KnownField field) const;
109  virtual bool setValue(KnownField field, const TagValue &value) = 0;
110  virtual bool setValues(KnownField field, const std::vector<TagValue> &values);
111  virtual bool hasField(KnownField field) const = 0;
112  virtual void removeAllFields() = 0;
113  const std::string &version() const;
114  uint32 size() const;
115  virtual bool supportsTarget() const;
116  const TagTarget &target() const;
117  void setTarget(const TagTarget &target);
118  virtual TagTargetLevel targetLevel() const;
119  const char *targetLevelName() const;
120  bool isTargetingLevel(TagTargetLevel tagTargetLevel) const;
121  std::string targetString() const;
122  virtual unsigned int fieldCount() const = 0;
123  virtual bool supportsField(KnownField field) const = 0;
124  virtual TagDataType proposedDataType(KnownField field) const;
125  virtual bool supportsDescription(KnownField field) const;
126  virtual bool supportsMimeType(KnownField field) const;
127  virtual bool supportsMultipleValues(KnownField field) const;
128  virtual unsigned int insertValues(const Tag &from, bool overwrite);
129  virtual void ensureTextValuesAreProperlyEncoded() = 0;
130 
131 protected:
132  Tag();
133 
134  std::string m_version;
135  uint32 m_size;
137 };
138 
139 inline TagType Tag::type() const
140 {
141  return TagType::Unspecified;
142 }
143 
144 inline const char *Tag::typeName() const
145 {
146  return "unspecified";
147 }
148 
150 {
152 }
153 
154 inline bool Tag::canEncodingBeUsed(TagTextEncoding encoding) const
155 {
156  return encoding == proposedTextEncoding();
157 }
158 
159 inline const std::string &Tag::version() const
160 {
161  return m_version;
162 }
163 
164 inline uint32 Tag::size() const
165 {
166  return m_size;
167 }
168 
169 inline bool Tag::supportsTarget() const
170 {
171  return false;
172 }
173 
174 inline const TagTarget &Tag::target() const
175 {
176  return m_target;
177 }
178 
179 inline void Tag::setTarget(const TagTarget &target)
180 {
181  m_target = target;
182 }
183 
185 {
187 }
188 
189 inline const char *Tag::targetLevelName() const
190 {
191  return supportsTarget() ? tagTargetLevelName(targetLevel()) : nullptr;
192 }
193 
194 inline bool Tag::isTargetingLevel(TagTargetLevel tagTargetLevel) const
195 {
196  return !supportsTarget() || static_cast<byte>(targetLevel()) >= static_cast<byte>(tagTargetLevel);
197 }
198 
199 inline std::string Tag::targetString() const
200 {
201  return target().toString(targetLevel());
202 }
203 
205 {
206  switch (field) {
207  case KnownField::Bpm:
208  case KnownField::Bps:
209  case KnownField::Rating:
212  return TagDataType::Integer;
213  case KnownField::Cover:
214  return TagDataType::Picture;
215  case KnownField::Length:
216  return TagDataType::TimeSpan;
220  case KnownField::Genre:
223  return TagDataType::Undefined; // not supported so far
224  default:
225  return TagDataType::Text;
226  }
227 }
228 
230 {
231  return false;
232 }
233 
235 {
236  return false;
237 }
238 
240 {
241  return false;
242 }
243 
244 } // namespace TagParser
245 
246 #endif // TAG_PARSER_TAG_H
virtual bool supportsMultipleValues(KnownField field) const
Returns an indications whether the specified field supports multiple values.
Definition: tag.h:239
Implementation of TagParser::Tag for the MP4 container.
Definition: mp4tag.h:97
Specialization of TagParser::VorbisComment for Vorbis comments inside an OGG stream.
Definition: oggcontainer.h:67
std::string toString(const std::function< TagTargetLevel(uint64)> &tagTargetMapping) const
Returns the string representation of the current instance.
Definition: tagtarget.h:201
TagTargetLevel
The TagTargetLevel enum specifies tag target levels.
Definition: tagtarget.h:17
std::string targetString() const
Returns the string representation for the assigned tag target.
Definition: tag.h:199
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
constexpr TAG_PARSER_EXPORT const char * version()
bool isTargetingLevel(TagTargetLevel tagTargetLevel) const
Returns whether the tag is targeting the specified tagTargetLevel.
Definition: tag.h:194
virtual TagTextEncoding proposedTextEncoding() const
Returns the proposed text encoding.
Definition: tag.h:149
virtual const char * typeName() const
Returns the type name of the tag as C-style string.
Definition: tag.h:144
TagDataType
Specifies the data type.
Definition: tagvalue.h:53
virtual bool supportsMimeType(KnownField field) const
Returns an indications whether the specified field supports mime types.
Definition: tag.h:234
KnownField
Specifies the field.
Definition: tag.h:42
virtual TagType type() const
Returns the type of the tag as TagParser::TagType.
Definition: tag.h:139
constexpr KnownField firstKnownField
The first valid entry in the TagParser::KnownField enum.
Definition: tag.h:78
virtual bool supportsTarget() const
Returns an indication whether a target is supported by the tag.
Definition: tag.h:169
TAG_PARSER_EXPORT const char * tagTargetLevelName(TagTargetLevel tagTargetLevel)
Returns a string representation for the specified tagTargetLevel.
Definition: tagtarget.cpp:17
Implementation of TagParser::Tag for Vorbis comments.
Definition: vorbiscomment.h:25
const char * targetLevelName() const
Returns the name of the current target level.
Definition: tag.h:189
The TagTarget class specifies the target of a tag.
Definition: tagtarget.h:21
virtual TagTargetLevel targetLevel() const
Returns the name of the current tag target level.
Definition: tag.h:184
constexpr KnownField lastKnownField
The last valid entry in the TagParser::KnownField enum.
Definition: tag.h:83
const std::string & version() const
Returns the version of the tag as std::string.
Definition: tag.h:159
Implementation of TagParser::Tag for the Matroska container.
Definition: matroskatag.h:58
uint32 m_size
Definition: tag.h:135
constexpr unsigned int knownFieldArraySize
The number of valid entries in the TagParser::KnownField enum.
Definition: tag.h:88
Implementation of TagParser::Tag for ID3v2 tags.
Definition: id3v2tag.h:61
Implementation of TagParser::Tag for ID3v1 tags.
Definition: id3v1tag.h:10
TagTarget m_target
Definition: tag.h:136
uint32 size() const
Returns the size of the tag in bytes.
Definition: tag.h:164
void setTarget(const TagTarget &target)
Sets the target of tag.
Definition: tag.h:179
virtual TagDataType proposedDataType(KnownField field) const
Returns the proposed data type for the specified field as TagDataType.
Definition: tag.h:204
virtual bool supportsDescription(KnownField field) const
Returns an indications whether the specified field supports descriptions.
Definition: tag.h:229
constexpr KnownField nextKnownField(KnownField field)
Returns the next known field.
Definition: tag.h:93
The TagValue class wraps values of different types.
Definition: tagvalue.h:65
TagType
Specifies the tag type.
Definition: tag.h:20
const TagTarget & target() const
Returns the target of tag.
Definition: tag.h:174
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:24
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:9
std::string m_version
Definition: tag.h:134
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
virtual bool canEncodingBeUsed(TagTextEncoding encoding) const
Returns an indication whether the specified encoding can be used to provide string values for the tag...
Definition: tag.h:154