Tag Parser: id3/id3v2tag.h Source File

Tag Parser 12.5.2 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
id3v2tag.h
Go to the documentation of this file.
1#ifndef TAG_PARSER_ID3V2TAG_H
2#define TAG_PARSER_ID3V2TAG_H
3
4#include "./id3v2frame.h"
5
6#include "../fieldbasedtag.h"
7
8#include <c++utilities/misc/flagenumclass.h>
9
10#include <map>
11
12namespace TagParser {
13
17 enum class Id3v2HandlingFlags : std::uint64_t {
18 None = 0,
19 ConvertRecordDateFields = (1 << 1),
20 Defaults = ConvertRecordDateFields,
21};
22
23} // namespace TagParser
24
25 CPP_UTILITIES_MARK_FLAG_ENUM_CLASS(TagParser, TagParser::Id3v2HandlingFlags)
26
27namespace TagParser {
28
29class Id3v2Tag;
30
31 struct TAG_PARSER_EXPORT FrameComparer {
32 bool operator()(std::uint32_t lhs, std::uint32_t rhs) const;
33};
34
35 class TAG_PARSER_EXPORT Id3v2TagMaker {
36 friend class Id3v2Tag;
37
38public:
39 void make(std::ostream &stream, std::uint32_t padding, Diagnostics &diag);
40 const Id3v2Tag &tag() const;
41 std::uint64_t requiredSize() const;
42
43private:
44 Id3v2TagMaker(Id3v2Tag &tag, Diagnostics &diag);
45
46 Id3v2Tag &m_tag;
47 std::uint32_t m_framesSize;
48 std::uint32_t m_requiredSize;
49 std::vector<Id3v2FrameMaker> m_maker;
50};
51
55 inline const Id3v2Tag &Id3v2TagMaker::tag() const
56{
57 return m_tag;
58}
59
64 inline std::uint64_t Id3v2TagMaker::requiredSize() const
65{
66 return m_requiredSize;
67}
68
72 template <> class TAG_PARSER_EXPORT FieldMapBasedTagTraits<Id3v2Tag> {
73public:
74 using FieldType = Id3v2Frame;
75 using Compare = FrameComparer;
76};
77
78 class TAG_PARSER_EXPORT Id3v2Tag final : public FieldMapBasedTag<Id3v2Tag> {
79 friend class FieldMapBasedTag<Id3v2Tag>;
80 friend class Id3v2TagMaker;
81
82public:
83 Id3v2Tag();
84
85 static constexpr TagType tagType = TagType::Id3v2Tag;
86 static constexpr std::string_view tagName = "ID3v2 tag";
87 static constexpr TagTextEncoding defaultTextEncoding = TagTextEncoding::Utf16LittleEndian;
88 TagTextEncoding proposedTextEncoding() const override;
89 bool canEncodingBeUsed(TagTextEncoding encoding) const override;
90 bool supportsDescription(KnownField field) const override;
91 bool supportsMimeType(KnownField field) const override;
92 bool supportsMultipleValues(KnownField field) const override;
93 bool supportsMultipleValues(IdentifierType id) const;
94 void ensureTextValuesAreProperlyEncoded() override;
95
96 void parse(std::istream &sourceStream, const std::uint64_t maximalSize, Diagnostics &diag);
97 Id3v2TagMaker prepareMaking(Diagnostics &diag);
98 void make(std::ostream &targetStream, std::uint32_t padding, Diagnostics &diag);
99 Id3v2HandlingFlags handlingFlags() const;
100 void setHandlingFlags(Id3v2HandlingFlags flags);
101
102 std::uint8_t majorVersion() const;
103 std::uint8_t revisionVersion() const;
104 void setVersion(std::uint8_t majorVersion, std::uint8_t revisionVersion);
105 bool isVersionSupported() const;
106 std::uint8_t flags() const;
107 bool isUnsynchronisationUsed() const;
108 bool hasExtendedHeader() const;
109 bool isExperimental() const;
110 bool hasFooter() const;
111 std::uint32_t extendedHeaderSize() const;
112 std::uint64_t paddingSize() const;
113
114protected:
115 IdentifierType internallyGetFieldId(KnownField field) const;
116 KnownField internallyGetKnownField(const IdentifierType &id) const;
117 TagDataType internallyGetProposedDataType(const std::uint32_t &id) const;
118 void internallyGetValuesFromField(const FieldType &field, std::vector<const TagValue *> &values) const;
119 bool internallySetValues(const IdentifierType &id, const std::vector<TagValue> &values);
120
121private:
122 void convertOldRecordDateFields(const std::string &diagContext, Diagnostics &diag);
123 void removeOldRecordDateRelatedFields();
124 void prepareRecordDataForMaking(const std::string &diagContext, Diagnostics &diag);
125
126private:
127 std::uint8_t m_majorVersion;
128 std::uint8_t m_revisionVersion;
129 std::uint8_t m_flags;
130 std::uint32_t m_sizeExcludingHeader;
131 std::uint32_t m_extendedHeaderSize;
132 std::uint64_t m_paddingSize;
133 Id3v2HandlingFlags m_handlingFlags;
134};
135
139 inline Id3v2Tag::Id3v2Tag()
140 : m_majorVersion(4)
141 , m_revisionVersion(0)
142 , m_flags(0)
143 , m_sizeExcludingHeader(0)
144 , m_extendedHeaderSize(0)
145 , m_paddingSize(0)
146 , m_handlingFlags(Id3v2HandlingFlags::Defaults)
147{
148}
149
150 inline TagTextEncoding Id3v2Tag::proposedTextEncoding() const
151{
152 return m_majorVersion > 3 ? TagTextEncoding::Utf8 : TagTextEncoding::Utf16LittleEndian;
153}
154
155 inline bool Id3v2Tag::canEncodingBeUsed(TagTextEncoding encoding) const
156{
157 return encoding == TagTextEncoding::Latin1 || (encoding == TagTextEncoding::Utf8 && m_majorVersion > 3)
158 || encoding == TagTextEncoding::Utf16BigEndian || encoding == TagTextEncoding::Utf16LittleEndian;
159}
160
161 inline bool Id3v2Tag::supportsDescription(KnownField field) const
162{
163 switch (field) {
164 case KnownField::Cover:
165 case KnownField::Lyrics:
166 case KnownField::SynchronizedLyrics:
167 return true;
168 default:
169 return false;
170 }
171}
172
173 inline bool Id3v2Tag::supportsMimeType(KnownField field) const
174{
175 return field == KnownField::Cover;
176}
177
181 inline Id3v2HandlingFlags Id3v2Tag::handlingFlags() const
182{
183 return m_handlingFlags;
184}
185
189 inline void Id3v2Tag::setHandlingFlags(Id3v2HandlingFlags flags)
190{
191 m_handlingFlags = flags;
192}
193
197 inline std::uint8_t Id3v2Tag::majorVersion() const
198{
199 return m_majorVersion;
200}
201
205 inline std::uint8_t Id3v2Tag::revisionVersion() const
206{
207 return m_revisionVersion;
208}
209
216 inline bool Id3v2Tag::isVersionSupported() const
217{
218 return m_majorVersion == 2 || m_majorVersion == 3 || m_majorVersion == 4;
219}
220
224 inline std::uint8_t Id3v2Tag::flags() const
225{
226 return m_flags;
227}
228
232 inline bool Id3v2Tag::isUnsynchronisationUsed() const
233{
234 return m_flags & 0x80;
235}
236
240 inline bool Id3v2Tag::hasExtendedHeader() const
241{
242 return (m_majorVersion >= 3) && (m_flags & 0x40);
243}
244
248 inline bool Id3v2Tag::isExperimental() const
249{
250 return (m_majorVersion >= 3) && (m_flags & 0x20);
251}
252
256 inline bool Id3v2Tag::hasFooter() const
257{
258 return (m_majorVersion >= 3) && (m_flags & 0x10);
259}
260
264 inline std::uint32_t Id3v2Tag::extendedHeaderSize() const
265{
266 return m_extendedHeaderSize;
267}
268
273 inline std::uint64_t Id3v2Tag::paddingSize() const
274{
275 return m_paddingSize;
276}
277
278} // namespace TagParser
279
280#endif // TAG_PARSER_ID3V2TAG_H
TagParser::Diagnostics
The Diagnostics class is a container for DiagMessage.
Definition diagnostics.h:156
TagParser::FieldMapBasedTagTraits< Id3v2Tag >::Compare
FrameComparer Compare
Definition id3v2tag.h:75
TagParser::FieldMapBasedTagTraits< Id3v2Tag >::FieldType
Id3v2Frame FieldType
Definition id3v2tag.h:74
TagParser::FieldMapBasedTagTraits
Defines traits for the specified ImplementationType.
Definition fieldbasedtag.h:17
TagParser::FieldMapBasedTag< Id3v2Tag >::IdentifierType
typename FieldMapBasedTagTraits< Id3v2Tag >::FieldType::IdentifierType IdentifierType
Definition fieldbasedtag.h:35
TagParser::FieldMapBasedTag< Id3v2Tag >::FieldMapBasedTag
FieldMapBasedTag()
Definition fieldbasedtag.h:100
TagParser::FieldMapBasedTag< Id3v2Tag >::FieldType
typename FieldMapBasedTagTraits< Id3v2Tag >::FieldType FieldType
Definition fieldbasedtag.h:34
TagParser::FieldMapBasedTag< Id3v2Tag >::values
std::vector< const TagValue * > values(const IdentifierType &id) const
Definition fieldbasedtag.h:175
TagParser::Id3v2Frame
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition id3v2frame.h:86
TagParser::Id3v2TagMaker::requiredSize
std::uint64_t requiredSize() const
Returns the number of bytes which will be written when making the tag.
Definition id3v2tag.h:64
TagParser::Id3v2TagMaker::make
void make(std::ostream &stream, std::uint32_t padding, Diagnostics &diag)
Saves the tag (specified when constructing the object) to the specified stream.
Definition id3v2tag.cpp:891
TagParser::Id3v2TagMaker::tag
const Id3v2Tag & tag() const
Returns the associated tag.
Definition id3v2tag.h:55
TagParser::Id3v2TagMaker::Id3v2Tag
friend class Id3v2Tag
Definition id3v2tag.h:36
TagParser::Id3v2Tag
Implementation of TagParser::Tag for ID3v2 tags.
Definition id3v2tag.h:78
TagParser::Id3v2Tag::revisionVersion
std::uint8_t revisionVersion() const
Returns the revision version if known; otherwise returns 0.
Definition id3v2tag.h:205
TagParser::Id3v2Tag::make
void make(std::ostream &targetStream, std::uint32_t padding, Diagnostics &diag)
Writes tag information to the specified stream.
Definition id3v2tag.cpp:682
TagParser::Id3v2Tag::tagType
static constexpr TagType tagType
Definition id3v2tag.h:85
TagParser::Id3v2Tag::hasExtendedHeader
bool hasExtendedHeader() const
Returns an indication whether an extended header is used.
Definition id3v2tag.h:240
TagParser::Id3v2Tag::isVersionSupported
bool isVersionSupported() const
Returns an indication whether the version is supported by the Id3v2Tag class.
Definition id3v2tag.h:216
TagParser::Id3v2Tag::supportsMultipleValues
bool supportsMultipleValues(KnownField field) const override
Allows multiple values for some fields.
Definition id3v2tag.cpp:26
TagParser::Id3v2Tag::setHandlingFlags
void setHandlingFlags(Id3v2HandlingFlags flags)
Sets flags influencing the behavior when parsing/making the ID3v2 tag.
Definition id3v2tag.h:189
TagParser::Id3v2Tag::handlingFlags
Id3v2HandlingFlags handlingFlags() const
Returns flags influencing the behavior when parsing/making the ID3v2 tag.
Definition id3v2tag.h:181
TagParser::Id3v2Tag::setVersion
void setVersion(std::uint8_t majorVersion, std::uint8_t revisionVersion)
Sets the version to the specified majorVersion and the specified revisionVersion.
Definition id3v2tag.cpp:691
TagParser::Id3v2Tag::internallyGetKnownField
KnownField internallyGetKnownField(const IdentifierType &id) const
Definition id3v2tag.cpp:287
TagParser::Id3v2Tag::canEncodingBeUsed
bool canEncodingBeUsed(TagTextEncoding encoding) const override
Returns an indication whether the specified encoding can be used to provide string values for the tag...
Definition id3v2tag.h:155
TagParser::Id3v2Tag::flags
std::uint8_t flags() const
Returns the flags read from the ID3v2 header.
Definition id3v2tag.h:224
TagParser::Id3v2Tag::isUnsynchronisationUsed
bool isUnsynchronisationUsed() const
Returns an indication whether unsynchronisation is used.
Definition id3v2tag.h:232
TagParser::Id3v2Tag::extendedHeaderSize
std::uint32_t extendedHeaderSize() const
Returns the size of the extended header if one is present; otherwise returns 0.
Definition id3v2tag.h:264
TagParser::Id3v2Tag::majorVersion
std::uint8_t majorVersion() const
Returns the major version if known; otherwise returns 0.
Definition id3v2tag.h:197
TagParser::Id3v2Tag::hasFooter
bool hasFooter() const
Returns an indication whether a footer is present.
Definition id3v2tag.h:256
TagParser::Id3v2Tag::internallyGetValuesFromField
void internallyGetValuesFromField(const FieldType &field, std::vector< const TagValue * > &values) const
Adds additional values as well.
Definition id3v2tag.cpp:78
TagParser::Id3v2Tag::internallySetValues
bool internallySetValues(const IdentifierType &id, const std::vector< TagValue > &values)
Uses default implementation for non-text frames and applies special handling to text frames.
Definition id3v2tag.cpp:96
TagParser::Id3v2Tag::supportsMimeType
bool supportsMimeType(KnownField field) const override
Returns an indications whether the specified field supports mime types.
Definition id3v2tag.h:173
TagParser::Id3v2Tag::Id3v2Tag
Id3v2Tag()
Constructs a new tag.
Definition id3v2tag.h:139
TagParser::Id3v2Tag::proposedTextEncoding
TagTextEncoding proposedTextEncoding() const override
Returns the proposed text encoding.
Definition id3v2tag.h:150
TagParser::Id3v2Tag::internallyGetProposedDataType
TagDataType internallyGetProposedDataType(const std::uint32_t &id) const
Definition id3v2tag.cpp:435
TagParser::Id3v2Tag::paddingSize
std::uint64_t paddingSize() const
Returns the size of the padding between the tag and the first MPEG frame if one is present; otherwise...
Definition id3v2tag.h:273
TagParser::Id3v2Tag::prepareMaking
Id3v2TagMaker prepareMaking(Diagnostics &diag)
Prepares making.
Definition id3v2tag.cpp:670
TagParser::Id3v2Tag::ensureTextValuesAreProperlyEncoded
void ensureTextValuesAreProperlyEncoded() override
Ensures the encoding of all assigned text values is supported by the tag by converting the character ...
Definition id3v2tag.cpp:65
TagParser::Id3v2Tag::tagName
static constexpr std::string_view tagName
Definition id3v2tag.h:86
TagParser::Id3v2Tag::defaultTextEncoding
static constexpr TagTextEncoding defaultTextEncoding
Definition id3v2tag.h:87
TagParser::Id3v2Tag::supportsDescription
bool supportsDescription(KnownField field) const override
Returns an indications whether the specified field supports descriptions.
Definition id3v2tag.h:161
TagParser::Id3v2Tag::internallyGetFieldId
IdentifierType internallyGetFieldId(KnownField field) const
Definition id3v2tag.cpp:138
TagParser::Id3v2Tag::isExperimental
bool isExperimental() const
Returns an indication whether the tag is labeled as experimental.
Definition id3v2tag.h:248
TagParser::Id3v2Tag::Id3v2TagMaker
friend class Id3v2TagMaker
Definition id3v2tag.h:80
TagParser::Id3v2Tag::parse
void parse(std::istream &sourceStream, const std::uint64_t maximalSize, Diagnostics &diag)
Parses tag information from the specified stream.
Definition id3v2tag.cpp:550
fieldbasedtag.h
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
Definition global.h:14
id3v2frame.h
TagParser::SubFormats::None
@ None
Definition mediaformat.h:112
TagParser
Contains all classes and functions of the TagInfo library.
Definition aaccodebook.h:10
TagParser::KnownField
KnownField
Specifies the field.
Definition tag.h:37
TagParser::KnownField::SynchronizedLyrics
@ SynchronizedLyrics
Definition tag.h:58
TagParser::KnownField::Lyrics
@ Lyrics
Definition tag.h:57
TagParser::KnownField::Cover
@ Cover
Definition tag.h:61
TagParser::TagTextEncoding
TagTextEncoding
Specifies the text encoding.
Definition tagvalue.h:29
TagParser::TagTextEncoding::Latin1
@ Latin1
Definition tagvalue.h:30
TagParser::TagTextEncoding::Utf16BigEndian
@ Utf16BigEndian
Definition tagvalue.h:33
TagParser::TagTextEncoding::Utf8
@ Utf8
Definition tagvalue.h:31
TagParser::TagTextEncoding::Utf16LittleEndian
@ Utf16LittleEndian
Definition tagvalue.h:32
TagParser::TagType
TagType
Specifies the tag type.
Definition tagtype.h:11
TagParser::TagType::Id3v2Tag
@ Id3v2Tag
Definition tagtype.h:14
TagParser::Id3v2HandlingFlags
Id3v2HandlingFlags
The Id3v2Flags enum specifies flags which controls parsing and making of ID3v2 tags.
Definition id3v2tag.h:17
TagParser::Id3v2HandlingFlags::Defaults
@ Defaults
Definition id3v2tag.h:20
TagParser::Id3v2HandlingFlags::ConvertRecordDateFields
@ ConvertRecordDateFields
Definition id3v2tag.h:19
TagParser::TagDataType
TagDataType
Specifies the data type.
Definition tagvalue.h:119
CPP_UTILITIES_MARK_FLAG_ENUM_CLASS
CPP_UTILITIES_MARK_FLAG_ENUM_CLASS(TagParser, TagParser::TagCreationFlags)
TagParser::FrameComparer
Defines the order which is used to store ID3v2 frames.
Definition id3v2tag.h:31
TagParser::FrameComparer::operator()
bool operator()(std::uint32_t lhs, std::uint32_t rhs) const
Returns true if lhs goes before rhs; otherwise returns false.
Definition id3v2tag.cpp:710