Tag Parser  9.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/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  Year,
49  Comment,
50  Bpm,
51  Bps,
52  Lyricist,
54  DiskPosition,
55  PartNumber,
56  TotalParts,
57  Encoder,
58  RecordDate,
59  Performers,
60  Length,
63  Lyrics,
65  Grouping,
66  RecordLabel,
67  Cover,
68  Composer,
69  Rating,
70  Description,
71  Vendor,
72  AlbumArtist,
73  ReleaseDate,
74 };
75 
80 
85 
89 constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
90 
94 constexpr bool isKnownFieldDeprecated(KnownField field)
95 {
96  return field == KnownField::Year;
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 const char *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::uint32_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  const char *targetLevelName() const;
130  bool isTargetingLevel(TagTargetLevel tagTargetLevel) const;
131  std::string targetString() const;
132  virtual unsigned int 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 unsigned int insertValues(const Tag &from, bool overwrite);
140 
141 protected:
142  Tag();
143 
144  std::string m_version;
145  std::uint32_t m_size;
147 };
148 
149 inline TagType Tag::type() const
150 {
151  return TagType::Unspecified;
152 }
153 
154 inline const char *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::uint32_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 const char *Tag::targetLevelName() const
200 {
201  return supportsTarget() ? tagTargetLevelName(targetLevel()) : nullptr;
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
TagParser::KnownField::DiskPosition
@ DiskPosition
TagParser::TagDataType::TimeSpan
@ TimeSpan
TagParser::Tag::targetLevelName
const char * targetLevelName() const
Returns the name of the current target level.
Definition: tag.h:199
TagParser::KnownField::Vendor
@ Vendor
TagParser::KnownField::Description
@ Description
TagParser::VorbisCommentIds::version
constexpr TAG_PARSER_EXPORT const char * version()
Definition: vorbiscommentids.h:34
TagParser::KnownField::Comment
@ Comment
TagParser::KnownField::Bps
@ Bps
TagParser::KnownField::Performers
@ Performers
TagParser::KnownField::Lyricist
@ Lyricist
TagParser::KnownField::Genre
@ Genre
TagParser::nextKnownField
constexpr KnownField nextKnownField(KnownField field)
Returns the next known field skipping any deprecated fields.
Definition: tag.h:102
TagParser::Tag::targetLevel
virtual TagTargetLevel targetLevel() const
Returns the name of the current tag target level.
Definition: tag.h:194
TagParser::TagTextEncoding
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:25
TagParser::KnownField::Bpm
@ Bpm
TagParser::KnownField::Rating
@ Rating
TagParser::Tag::setTarget
void setTarget(const TagTarget &target)
Sets the target of tag.
Definition: tag.h:189
TagParser::Tag::version
const std::string & version() const
Returns the version of the tag as std::string. The version denotation depends on the tag type.
Definition: tag.h:169
TagParser::Tag::proposedDataType
virtual TagDataType proposedDataType(KnownField field) const
Returns the proposed data type for the specified field as TagDataType.
Definition: tag.h:214
tagvalue.h
TagParser::Tag::supportsDescription
virtual bool supportsDescription(KnownField field) const
Returns an indications whether the specified field supports descriptions.
Definition: tag.h:239
TagParser::Tag::ensureTextValuesAreProperlyEncoded
virtual void ensureTextValuesAreProperlyEncoded()=0
Ensures the encoding of all assigned text values is supported by the tag by converting the character ...
TagParser::Tag::m_target
TagTarget m_target
Definition: tag.h:146
TagParser::Tag
The Tag class is used to store, read and write tag information.
Definition: tag.h:108
TagParser::KnownField::SynchronizedLyrics
@ SynchronizedLyrics
TagParser::lastKnownField
constexpr KnownField lastKnownField
The last valid entry in the TagParser::KnownField enum.
Definition: tag.h:84
TagParser::KnownField::Length
@ Length
TagParser::Tag::size
std::uint32_t size() const
Returns the size of the tag in bytes. The tag needs to be parsed before.
Definition: tag.h:174
TagParser::Tag::fieldCount
virtual unsigned int fieldCount() const =0
Returns the number of present fields.
TagParser::TagTarget::toString
std::string toString(const std::function< TagTargetLevel(std::uint64_t)> &tagTargetMapping) const
Returns the string representation of the current instance.
Definition: tagtarget.h:201
TagParser::Tag::hasField
virtual bool hasField(KnownField field) const =0
Returns an indication whether the specified field is present.
TagParser::TagDataType::PositionInSet
@ PositionInSet
TagParser::TagDataType::StandardGenreIndex
@ StandardGenreIndex
TagParser::TagTargetLevel
TagTargetLevel
The TagTargetLevel enum specifies tag target levels.
Definition: tagtarget.h:16
TagParser::KnownField::Lyrics
@ Lyrics
TagParser
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TagParser::KnownField::RecordDate
@ RecordDate
TagParser::Tag::supportsField
virtual bool supportsField(KnownField field) const =0
Returns an indication whether the specified field is supported by the tag.
TagParser::OggVorbisComment
Specialization of TagParser::VorbisComment for Vorbis comments inside an OGG stream.
Definition: oggcontainer.h:67
TagParser::TagDataType
TagDataType
Specifies the data type.
Definition: tagvalue.h:54
TagParser::KnownField::Grouping
@ Grouping
TagParser::KnownField::Title
@ Title
TagParser::KnownField::Language
@ Language
TagParser::Tag::m_size
std::uint32_t m_size
Definition: tag.h:145
TagParser::Tag::target
const TagTarget & target() const
Returns the target of tag.
Definition: tag.h:184
TagParser::KnownField::Invalid
@ Invalid
TagParser::KnownField::Cover
@ Cover
TagParser::Tag::supportsMultipleValues
virtual bool supportsMultipleValues(KnownField field) const
Returns an indications whether the specified field supports multiple values.
Definition: tag.h:249
TagParser::Tag::removeAllFields
virtual void removeAllFields()=0
Removes all fields from the tag.
TagParser::TagTextEncoding::Latin1
@ Latin1
TagParser::TagDataType::Undefined
@ Undefined
TagParser::Tag::proposedTextEncoding
virtual TagTextEncoding proposedTextEncoding() const
Returns the proposed text encoding.
Definition: tag.h:159
TagParser::KnownField::Composer
@ Composer
TagParser::Tag::value
virtual const TagValue & value(KnownField field) const =0
Returns the value of the specified field.
TagParser::knownFieldArraySize
constexpr unsigned int knownFieldArraySize
The number of valid entries in the TagParser::KnownField enum.
Definition: tag.h:89
TagParser::TagDataType::Text
@ Text
TagParser::tagTargetLevelName
TAG_PARSER_EXPORT const char * tagTargetLevelName(TagTargetLevel tagTargetLevel)
Returns a string representation for the specified tagTargetLevel.
Definition: tagtarget.cpp:17
TagParser::Tag::m_version
std::string m_version
Definition: tag.h:144
TagParser::Tag::canEncodingBeUsed
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
TagParser::Tag::isTargetingLevel
bool isTargetingLevel(TagTargetLevel tagTargetLevel) const
Returns whether the tag is targeting the specified tagTargetLevel.
Definition: tag.h:204
TagParser::KnownField::EncoderSettings
@ EncoderSettings
TagParser::KnownField::RecordLabel
@ RecordLabel
TagParser::TagDataType::Picture
@ Picture
TagParser::Id3v2Tag
Implementation of TagParser::Tag for ID3v2 tags.
Definition: id3v2tag.h:61
TagParser::TagTargetLevel::Unspecified
@ Unspecified
TagParser::KnownField
KnownField
Specifies the field.
Definition: tag.h:42
TagParser::KnownField::ReleaseDate
@ ReleaseDate
TagParser::Id3v1Tag
Implementation of TagParser::Tag for ID3v1 tags.
Definition: id3v1tag.h:10
TagParser::Tag::supportsMimeType
virtual bool supportsMimeType(KnownField field) const
Returns an indications whether the specified field supports mime types.
Definition: tag.h:244
TagParser::Tag::typeName
virtual const char * typeName() const
Returns the type name of the tag as C-style string.
Definition: tag.h:154
TagParser::Tag::supportsTarget
virtual bool supportsTarget() const
Returns an indication whether a target is supported by the tag.
Definition: tag.h:179
TagParser::TagTarget
The TagTarget class specifies the target of a tag.
Definition: tagtarget.h:20
TagParser::Tag::targetString
std::string targetString() const
Returns the string representation for the assigned tag target.
Definition: tag.h:209
TagParser::TagValue
The TagValue class wraps values of different types. It is meant to be assigned to a tag field.
Definition: tagvalue.h:75
TagParser::MatroskaTag
Implementation of TagParser::Tag for the Matroska container.
Definition: matroskatag.h:58
TagParser::Mp4Tag
Implementation of TagParser::Tag for the MP4 container.
Definition: mp4tag.h:97
TagParser::Tag::type
virtual TagType type() const
Returns the type of the tag as TagParser::TagType.
Definition: tag.h:149
TagParser::MatroskaIds::Tag
@ Tag
Definition: matroskaid.h:204
TagParser::KnownField::Album
@ Album
TagParser::KnownField::Encoder
@ Encoder
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TagParser::KnownField::AlbumArtist
@ AlbumArtist
TagParser::TagType::Unspecified
@ Unspecified
TagParser::KnownField::PartNumber
@ PartNumber
tagtarget.h
TagParser::KnownField::Artist
@ Artist
TagParser::KnownField::TrackPosition
@ TrackPosition
TagParser::VorbisComment
Implementation of TagParser::Tag for Vorbis comments.
Definition: vorbiscomment.h:25
TagParser::firstKnownField
constexpr KnownField firstKnownField
The first valid entry in the TagParser::KnownField enum.
Definition: tag.h:79
TagParser::isKnownFieldDeprecated
constexpr bool isKnownFieldDeprecated(KnownField field)
Returns whether the specified field is deprecated and should not be used anymore.
Definition: tag.h:94
TagParser::Tag::setValue
virtual bool setValue(KnownField field, const TagValue &value)=0
Assigns the given value to the specified field.
TagParser::KnownField::Year
@ Year
TagParser::KnownField::TotalParts
@ TotalParts
TagParser::TagDataType::Integer
@ Integer
TagParser::TagType
TagType
Specifies the tag type.
Definition: tag.h:20