Tag Parser 11.0.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
13namespace TagParser {
14
20enum 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
42enum 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,
52 TrackPosition,
53 DiskPosition,
56 Encoder,
58 Performers,
59 Length,
60 Language,
62 Lyrics,
64 Grouping,
65 RecordLabel,
66 Cover,
67 Composer,
68 Rating,
69 Description,
70 Vendor,
71 AlbumArtist,
73};
74
79
84
88constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
89
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
109public:
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
141protected:
142 Tag();
143
144 std::string m_version;
145 std::uint64_t m_size;
147};
148
149inline TagType Tag::type() const
150{
152}
153
154inline std::string_view Tag::typeName() const
155{
156 return "unspecified";
157}
158
160{
162}
163
164inline bool Tag::canEncodingBeUsed(TagTextEncoding encoding) const
165{
166 return encoding == proposedTextEncoding();
167}
168
169inline const std::string &Tag::version() const
170{
171 return m_version;
172}
173
174inline std::uint64_t Tag::size() const
175{
176 return m_size;
177}
178
179inline bool Tag::supportsTarget() const
180{
181 return false;
182}
183
184inline const TagTarget &Tag::target() const
185{
186 return m_target;
187}
188
189inline void Tag::setTarget(const TagTarget &target)
190{
192}
193
195{
197}
198
199inline std::string_view Tag::targetLevelName() const
200{
201 return supportsTarget() ? tagTargetLevelName(targetLevel()) : std::string_view();
202}
203
204inline bool Tag::isTargetingLevel(TagTargetLevel tagTargetLevel) const
205{
206 return !supportsTarget() || static_cast<std::uint8_t>(targetLevel()) >= static_cast<std::uint8_t>(tagTargetLevel);
207}
208
209inline 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:
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:72
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:217
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 the tag within the file it is parsed from 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