Tag Parser  10.0.1
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/io/binaryreader.h>
8 
9 #include <cstdint>
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  Comment,
49  Bpm,
50  Bps,
51  Lyricist,
53  DiskPosition,
54  PartNumber,
55  TotalParts,
56  Encoder,
57  RecordDate,
58  Performers,
59  Length,
60  Language,
62  Lyrics,
64  Grouping,
65  RecordLabel,
66  Cover,
67  Composer,
68  Rating,
69  Description,
70  Vendor,
71  AlbumArtist,
72  ReleaseDate,
73 };
74 
79 
84 
88 constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
89 
93 constexpr bool isKnownFieldDeprecated(KnownField field)
94 {
95  CPP_UTILITIES_UNUSED(field)
96  return false;
97 }
98 
103 {
104  const auto next = field == lastKnownField ? KnownField::Invalid : static_cast<KnownField>(static_cast<int>(field) + 1);
105  return isKnownFieldDeprecated(next) ? nextKnownField(next) : next;
106 }
107 
109 public:
110  virtual ~Tag();
111 
112  virtual TagType type() const;
113  virtual std::string_view typeName() const;
114  std::string toString() const;
115  virtual TagTextEncoding proposedTextEncoding() const;
116  virtual bool canEncodingBeUsed(TagTextEncoding encoding) const;
117  virtual const TagValue &value(KnownField field) const = 0;
118  virtual std::vector<const TagValue *> values(KnownField field) const;
119  virtual bool setValue(KnownField field, const TagValue &value) = 0;
120  virtual bool setValues(KnownField field, const std::vector<TagValue> &values);
121  virtual bool hasField(KnownField field) const = 0;
122  virtual void removeAllFields() = 0;
123  const std::string &version() const;
124  std::uint64_t size() const;
125  virtual bool supportsTarget() const;
126  const TagTarget &target() const;
127  void setTarget(const TagTarget &target);
128  virtual TagTargetLevel targetLevel() const;
129  std::string_view targetLevelName() const;
130  bool isTargetingLevel(TagTargetLevel tagTargetLevel) const;
131  std::string targetString() const;
132  virtual std::size_t fieldCount() const = 0;
133  virtual bool supportsField(KnownField field) const = 0;
134  virtual TagDataType proposedDataType(KnownField field) const;
135  virtual bool supportsDescription(KnownField field) const;
136  virtual bool supportsMimeType(KnownField field) const;
137  virtual bool supportsMultipleValues(KnownField field) const;
138  virtual std::size_t insertValues(const Tag &from, bool overwrite);
140 
141 protected:
142  Tag();
143 
144  std::string m_version;
145  std::uint64_t m_size;
147 };
148 
149 inline TagType Tag::type() const
150 {
151  return TagType::Unspecified;
152 }
153 
154 inline std::string_view Tag::typeName() const
155 {
156  return "unspecified";
157 }
158 
160 {
162 }
163 
164 inline bool Tag::canEncodingBeUsed(TagTextEncoding encoding) const
165 {
166  return encoding == proposedTextEncoding();
167 }
168 
169 inline const std::string &Tag::version() const
170 {
171  return m_version;
172 }
173 
174 inline std::uint64_t Tag::size() const
175 {
176  return m_size;
177 }
178 
179 inline bool Tag::supportsTarget() const
180 {
181  return false;
182 }
183 
184 inline const TagTarget &Tag::target() const
185 {
186  return m_target;
187 }
188 
189 inline void Tag::setTarget(const TagTarget &target)
190 {
191  m_target = target;
192 }
193 
195 {
197 }
198 
199 inline std::string_view Tag::targetLevelName() const
200 {
201  return supportsTarget() ? tagTargetLevelName(targetLevel()) : std::string_view();
202 }
203 
204 inline bool Tag::isTargetingLevel(TagTargetLevel tagTargetLevel) const
205 {
206  return !supportsTarget() || static_cast<std::uint8_t>(targetLevel()) >= static_cast<std::uint8_t>(tagTargetLevel);
207 }
208 
209 inline std::string Tag::targetString() const
210 {
211  return target().toString(targetLevel());
212 }
213 
215 {
216  switch (field) {
217  case KnownField::Bpm:
218  case KnownField::Bps:
219  case KnownField::Rating:
222  return TagDataType::Integer;
223  case KnownField::Cover:
224  return TagDataType::Picture;
225  case KnownField::Length:
226  return TagDataType::TimeSpan;
230  case KnownField::Genre:
233  return TagDataType::Undefined; // not supported so far
234  default:
235  return TagDataType::Text;
236  }
237 }
238 
240 {
241  return false;
242 }
243 
245 {
246  return false;
247 }
248 
250 {
251  return false;
252 }
253 
254 } // namespace TagParser
255 
256 #endif // TAG_PARSER_TAG_H
Implementation of TagParser::Tag for ID3v1 tags.
Definition: id3v1tag.h:10
Implementation of TagParser::Tag for ID3v2 tags.
Definition: id3v2tag.h:78
Implementation of TagParser::Tag for the Matroska container.
Definition: matroskatag.h:58
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
The TagTarget class specifies the target of a tag.
Definition: tagtarget.h:20
std::string toString(const std::function< TagTargetLevel(std::uint64_t)> &tagTargetMapping) const
Returns the string representation of the current instance.
Definition: tagtarget.h:201
The TagValue class wraps values of different types.
Definition: tagvalue.h:95
The Tag class is used to store, read and write tag information.
Definition: tag.h:108
std::uint64_t size() const
Returns the size of the tag in bytes.
Definition: tag.h:174
std::string_view targetLevelName() const
Returns the name of the current target level.
Definition: tag.h:199
void setTarget(const TagTarget &target)
Sets the target of tag.
Definition: tag.h:189
bool isTargetingLevel(TagTargetLevel tagTargetLevel) const
Returns whether the tag is targeting the specified tagTargetLevel.
Definition: tag.h:204
std::string m_version
Definition: tag.h:144
std::uint64_t m_size
Definition: tag.h:145
virtual std::size_t fieldCount() const =0
Returns the number of present fields.
const std::string & version() const
Returns the version of the tag as std::string.
Definition: tag.h:169
virtual bool supportsDescription(KnownField field) const
Returns an indications whether the specified field supports descriptions.
Definition: tag.h:239
std::string targetString() const
Returns the string representation for the assigned tag target.
Definition: tag.h:209
virtual TagTextEncoding proposedTextEncoding() const
Returns the proposed text encoding.
Definition: tag.h:159
virtual TagType type() const
Returns the type of the tag as TagParser::TagType.
Definition: tag.h:149
virtual std::string_view typeName() const
Returns the type name of the tag as C-style string.
Definition: tag.h:154
virtual bool hasField(KnownField field) const =0
Returns an indication whether the specified field is present.
virtual void removeAllFields()=0
Removes all fields from the tag.
TagTarget m_target
Definition: tag.h:146
const TagTarget & target() const
Returns the target of tag.
Definition: tag.h:184
virtual TagTargetLevel targetLevel() const
Returns the name of the current tag target level.
Definition: tag.h:194
virtual bool setValue(KnownField field, const TagValue &value)=0
Assigns the given value to the specified field.
virtual TagDataType proposedDataType(KnownField field) const
Returns the proposed data type for the specified field as TagDataType.
Definition: tag.h:214
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:164
virtual bool supportsMultipleValues(KnownField field) const
Returns an indications whether the specified field supports multiple values.
Definition: tag.h:249
virtual void ensureTextValuesAreProperlyEncoded()=0
Ensures the encoding of all assigned text values is supported by the tag by converting the character ...
virtual bool supportsMimeType(KnownField field) const
Returns an indications whether the specified field supports mime types.
Definition: tag.h:244
virtual bool supportsField(KnownField field) const =0
Returns an indication whether the specified field is supported by the tag.
virtual const TagValue & value(KnownField field) const =0
Returns the value of the specified field.
virtual bool supportsTarget() const
Returns an indication whether a target is supported by the tag.
Definition: tag.h:179
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 version()
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
KnownField
Specifies the field.
Definition: tag.h:42
TAG_PARSER_EXPORT std::string_view tagTargetLevelName(TagTargetLevel tagTargetLevel)
Returns a string representation for the specified tagTargetLevel.
Definition: tagtarget.cpp:17
constexpr unsigned int knownFieldArraySize
The number of valid entries in the TagParser::KnownField enum.
Definition: tag.h:88
TagTargetLevel
The TagTargetLevel enum specifies tag target levels.
Definition: tagtarget.h:16
constexpr KnownField nextKnownField(KnownField field)
Returns the next known field skipping any deprecated fields.
Definition: tag.h:102
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:28
constexpr KnownField lastKnownField
The last valid entry in the TagParser::KnownField enum.
Definition: tag.h:83
TagType
Specifies the tag type.
Definition: tag.h:20
constexpr KnownField firstKnownField
The first valid entry in the TagParser::KnownField enum.
Definition: tag.h:78
constexpr bool isKnownFieldDeprecated(KnownField field)
Returns whether the specified field is deprecated and should not be used anymore.
Definition: tag.h:93
TagDataType
Specifies the data type.
Definition: tagvalue.h:74