Tag Parser 11.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
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 Subtitle,
75 Arranger,
76 Conductor,
77 Director,
80 SoundEngineer,
81 ArtDirector,
85 Actor,
86 Character,
87 WrittenBy,
89 EditedBy,
90 Producer,
92 ExecutiveProducer,
95 EncodedBy,
96 MixedBy,
97 RemixedBy,
99 ThanksTo,
100 Publisher,
101 Mood,
104 Subject,
105 Keywords,
106 Summary,
107 Synopsis,
108 InitialKey,
109 Period,
110 LawRating,
121 Measure,
122 Tuning,
123 ISRC,
124 MCDI,
125 ISBN,
126 Barcode,
128 LabelCode,
129 LCCN,
130 IMDB,
131 TMDB,
132 TVDB,
138 Copyright,
140 License,
141 TermsOfUse,
142};
143
148
153
157constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
158
163{
164 CPP_UTILITIES_UNUSED(field)
165 return false;
166}
167
172{
173 const auto next = field == lastKnownField ? KnownField::Invalid : static_cast<KnownField>(static_cast<int>(field) + 1);
174 return isKnownFieldDeprecated(next) ? nextKnownField(next) : next;
175}
176
178public:
179 virtual ~Tag();
180
181 virtual TagType type() const;
182 virtual std::string_view typeName() const;
183 std::string toString() const;
184 virtual TagTextEncoding proposedTextEncoding() const;
185 virtual bool canEncodingBeUsed(TagTextEncoding encoding) const;
186 virtual const TagValue &value(KnownField field) const = 0;
187 virtual std::vector<const TagValue *> values(KnownField field) const;
188 virtual bool setValue(KnownField field, const TagValue &value) = 0;
189 virtual bool setValues(KnownField field, const std::vector<TagValue> &values);
190 virtual bool hasField(KnownField field) const = 0;
191 virtual void removeAllFields() = 0;
192 const std::string &version() const;
193 std::uint64_t size() const;
194 virtual bool supportsTarget() const;
195 const TagTarget &target() const;
196 TagTarget &target();
197 void setTarget(const TagTarget &target);
198 virtual TagTargetLevel targetLevel() const;
199 std::string_view targetLevelName() const;
200 bool isTargetingLevel(TagTargetLevel tagTargetLevel) const;
201 std::string targetString() const;
202 virtual std::size_t fieldCount() const = 0;
203 virtual bool supportsField(KnownField field) const = 0;
204 virtual TagDataType proposedDataType(KnownField field) const;
205 virtual bool supportsDescription(KnownField field) const;
206 virtual bool supportsMimeType(KnownField field) const;
207 virtual bool supportsMultipleValues(KnownField field) const;
208 virtual std::size_t insertValues(const Tag &from, bool overwrite);
210
211protected:
212 Tag();
213
214 std::string m_version;
215 std::uint64_t m_size;
217};
218
219inline TagType Tag::type() const
220{
222}
223
224inline std::string_view Tag::typeName() const
225{
226 return "unspecified";
227}
228
230{
232}
233
234inline bool Tag::canEncodingBeUsed(TagTextEncoding encoding) const
235{
236 return encoding == proposedTextEncoding();
237}
238
239inline const std::string &Tag::version() const
240{
241 return m_version;
242}
243
244inline std::uint64_t Tag::size() const
245{
246 return m_size;
247}
248
249inline bool Tag::supportsTarget() const
250{
251 return false;
252}
253
254inline const TagTarget &Tag::target() const
255{
256 return m_target;
257}
258
260{
261 return m_target;
262}
263
264inline void Tag::setTarget(const TagTarget &target)
265{
267}
268
270{
272}
273
274inline std::string_view Tag::targetLevelName() const
275{
276 return supportsTarget() ? tagTargetLevelName(targetLevel()) : std::string_view();
277}
278
279inline bool Tag::isTargetingLevel(TagTargetLevel tagTargetLevel) const
280{
281 return !supportsTarget() || static_cast<std::uint8_t>(targetLevel()) >= static_cast<std::uint8_t>(tagTargetLevel);
282}
283
284inline std::string Tag::targetString() const
285{
286 return target().toString(targetLevel());
287}
288
290{
291 switch (field) {
292 case KnownField::Bpm:
293 case KnownField::Bps:
307 case KnownField::MCDI:
308 return TagDataType::Binary;
310 return TagDataType::Undefined; // not supported so far
311 default:
312 return TagDataType::Text;
313 }
314}
315
317{
318 return false;
319}
320
322{
323 return false;
324}
325
327{
328 return false;
329}
330
331} // namespace TagParser
332
333#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:177
std::uint64_t size() const
Returns the size the tag within the file it is parsed from in bytes.
Definition: tag.h:244
std::string_view targetLevelName() const
Returns the name of the current target level.
Definition: tag.h:274
void setTarget(const TagTarget &target)
Sets the target of tag.
Definition: tag.h:264
bool isTargetingLevel(TagTargetLevel tagTargetLevel) const
Returns whether the tag is targeting the specified tagTargetLevel.
Definition: tag.h:279
std::string m_version
Definition: tag.h:214
std::uint64_t m_size
Definition: tag.h:215
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:239
virtual bool supportsDescription(KnownField field) const
Returns an indications whether the specified field supports descriptions.
Definition: tag.h:316
std::string targetString() const
Returns the string representation for the assigned tag target.
Definition: tag.h:284
virtual TagTextEncoding proposedTextEncoding() const
Returns the proposed text encoding.
Definition: tag.h:229
virtual TagType type() const
Returns the type of the tag as TagParser::TagType.
Definition: tag.h:219
virtual std::string_view typeName() const
Returns the type name of the tag as C-style string.
Definition: tag.h:224
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:216
virtual TagTargetLevel targetLevel() const
Returns the name of the current tag target level.
Definition: tag.h:269
const TagTarget & target() const
Definition: tag.h:254
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:289
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:234
virtual bool supportsMultipleValues(KnownField field) const
Returns an indications whether the specified field supports multiple values.
Definition: tag.h:326
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:321
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:249
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:157
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:171
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:28
constexpr KnownField lastKnownField
The last valid entry in the TagParser::KnownField enum.
Definition: tag.h:152
TagType
Specifies the tag type.
Definition: tag.h:20
constexpr KnownField firstKnownField
The first valid entry in the TagParser::KnownField enum.
Definition: tag.h:147
constexpr bool isKnownFieldDeprecated(KnownField field)
Returns whether the specified field is deprecated and should not be used anymore.
Definition: tag.h:162
TagDataType
Specifies the data type.
Definition: tagvalue.h:74