Tag Parser: TagParser::Mp4Tag Class Reference

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

Loading...
Searching...
No Matches
Public Member Functions | Static Public Attributes | Protected Member Functions | Friends | List of all members
TagParser::Mp4Tag Class Referencefinal

Implementation of TagParser::Tag for the MP4 container. More...

`#include <mp4tag.h>`

Inheritance diagram for TagParser::Mp4Tag:
[legend]
Collaboration diagram for TagParser::Mp4Tag:
[legend]

## Public Member Functions
| Mp4Tag ()
| Constructs a new tag.
bool | canEncodingBeUsed (TagTextEncoding encoding) const override
| Returns an indication whether the specified encoding can be used to provide string values for the tag.
bool | supportsField (KnownField field) const override
| Returns an indication whether the specified field is supported by the tag.
const TagValue & | value (KnownField value) const override
| Returns the value of the specified field.
std::vector< const TagValue * > | values (KnownField field) const override
| Returns the values of the specified field.
const TagValue & | value (std::string_view mean, std::string_view name) const
| Returns the value of the field with the specified mean and name attributes.
bool | setValue (KnownField field, const TagValue &value) override
| Assigns the given value to the specified field.
bool | setValues (KnownField field, const std::vector< TagValue > &values) override
| Assigns the given values to the specified field.
bool | setValue (std::string_view mean, std::string_view name, const TagValue &value)
| Assigns the given value to the field with the specified mean and name attributes.
bool | hasField (KnownField value) const override
| Returns an indication whether the specified field is present.
bool | supportsMultipleValues (KnownField) const override
| Returns false for all fields (for now).
void | parse (Mp4Atom &metaAtom, Diagnostics &diag)
| Parses tag information from the specified metaAtom.
Mp4TagMaker | prepareMaking (Diagnostics &diag)
| Prepares making.
void | make (std::ostream &stream, Diagnostics &diag)
| Writes tag information to the specified stream.
Public Member Functions inherited from TagParser::FieldMapBasedTag< Mp4Tag >
virtual TagDataType | proposedDataType (KnownField field) const
| Returns the proposed data type for the specified field as TagDataType.
| FieldMapBasedTag ()
| Constructs a new FieldMapBasedTag.
TagType | type () const
| Returns the type of the tag as TagParser::TagType.
std::string_view | typeName () const
| Returns the type name of the tag.
TagTextEncoding | proposedTextEncoding () const
| Returns the proposed text encoding.
const TagValue & | value (const IdentifierType &id) const
| Returns the value of the field with the specified id.
std::vector< const TagValue * > | values (const IdentifierType &id) const
| Returns the values of the field with the specified id.
bool | setValue (const IdentifierType &id, const TagValue &value)
| Assigns the given value to the field with the specified id.
bool | setValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Assigns the given values to the field with the specified id.
void | removeAllFields ()
| Removes all fields from the tag.
const std::multimap< IdentifierType, FieldType, Compare > & | fields () const
| Returns the fields of the tag by providing direct access to the field map of the tag.
std::size_t | fieldCount () const
| Returns the number of present fields.
IdentifierType | fieldId (KnownField value) const
| Returns the ID for the specified field.
KnownField | knownField (const IdentifierType &id) const
| Returns the field for the specified ID.
std::size_t | insertFields (const FieldMapBasedTag< Mp4Tag > &from, bool overwrite)
| Inserts all fields from another tag of the same field type and compare function.
std::size_t | insertValues (const Tag &from, bool overwrite)
| Inserts all compatible values from another Tag.
void | ensureTextValuesAreProperlyEncoded ()
| Ensures the encoding of all assigned text values is supported by the tag by converting the character set if necessary.
Public Member Functions inherited from TagParser::Tag
virtual | ~Tag ()
| Destroys the Tag.
std::string | toString () const
| Returns a string representation of the tag.
const std::string & | version () const
| Returns the version of the tag.
std::uint64_t | size () const
| Returns the size the tag within the file it is parsed from in bytes.
virtual bool | supportsTarget () const
| Returns an indication whether a target is supported by the tag.
const TagTarget & | target () const
TagTarget & | target ()
| Returns the target of tag.
void | setTarget (const TagTarget &target)
| Sets the target of tag.
virtual TagTargetLevel | targetLevel () const
| Returns the name of the current tag target level.
std::string_view | targetLevelName () const
| Returns the name of the current target level.
bool | isTargetingLevel (TagTargetLevel tagTargetLevel) const
| Returns whether the tag is targeting the specified tagTargetLevel.
std::string | targetString () const
| Returns the string representation for the assigned tag target.
virtual bool | supportsDescription (KnownField field) const
| Returns an indications whether the specified field supports descriptions.
virtual bool | supportsMimeType (KnownField field) const
| Returns an indications whether the specified field supports mime types.

## Static Public Attributes
static constexpr TagType | tagType = TagType::Mp4Tag
static constexpr std::string_view | tagName = "MP4/iTunes tag"
static constexpr TagTextEncoding | defaultTextEncoding = TagTextEncoding::Utf8

## Protected Member Functions
IdentifierType | internallyGetFieldId (KnownField field) const
KnownField | internallyGetKnownField (const IdentifierType &id) const
void | internallyGetValuesFromField (const FieldType &field, std::vector< const TagValue * > &values) const
| Adds values from additional data atoms as well.
Protected Member Functions inherited from TagParser::FieldMapBasedTag< Mp4Tag >
const TagValue & | internallyGetValue (const IdentifierType &id) const
| Default implementation for value().
void | internallyGetValuesFromField (const FieldType &field, std::vector< const TagValue * > &values) const
| Default way to gather values from a field in internallyGetValues().
std::vector< const TagValue * > | internallyGetValues (const IdentifierType &id) const
| Default implementation for values().
bool | internallySetValue (const IdentifierType &id, const TagValue &value)
| Default implementation for setValue().
bool | internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Default implementation for setValues().
bool | internallyHasField (const IdentifierType &id) const
| Default implementation for hasField().
TagDataType | internallyGetProposedDataType (const IdentifierType &id) const
| Default implementation for proposedDataType().
Protected Member Functions inherited from TagParser::Tag
| Tag ()
| Constructs a new Tag.

## Friends
class | FieldMapBasedTag< Mp4Tag >

## Additional Inherited Members
Public Types inherited from TagParser::FieldMapBasedTag< Mp4Tag >
using | FieldType
using | IdentifierType
using | Compare
Protected Types inherited from TagParser::FieldMapBasedTag< Mp4Tag >
using | CRTPBase
Protected Attributes inherited from TagParser::Tag
std::string | m_version
std::uint64_t | m_size
std::unique_ptr< TagPrivate > | m_p
TagTarget | m_target

## Detailed Description

Implementation of TagParser::Tag for the MP4 container.

Definition at line 97 of file mp4tag.h.

## Constructor & Destructor Documentation

## ◆ Mp4Tag()

TagParser::Mp4Tag::Mp4Tag | ( |  | ) |
| inline

Constructs a new tag.

Definition at line 136 of file mp4tag.h.

## Member Function Documentation

## ◆ canEncodingBeUsed()

bool TagParser::Mp4Tag::canEncodingBeUsed | ( | TagTextEncoding | encoding | ) | const
| overridevirtual

Returns an indication whether the specified encoding can be used to provide string values for the tag.

Only the proposedTextEncoding() is accepted by default. This might be overwritten when subclassing.

The tag class and its subclasses do not perform any conversions. You have to provide all string values using an encoding which is appropriate for the specific tag type. This method is meant to determine if a particular encoding can be used.

See also
  canEncodingBeUsed()

Reimplemented from TagParser::Tag.

Definition at line 47 of file mp4tag.cpp.

## ◆ hasField()

bool TagParser::Mp4Tag::hasField | ( | KnownField | field | ) | const
| overridevirtual

Returns an indication whether the specified field is present.

See also
  value(), setValue()

Reimplemented from TagParser::FieldMapBasedTag< Mp4Tag >.

Definition at line 365 of file mp4tag.cpp.

## ◆ internallyGetFieldId()

Mp4Tag::IdentifierType TagParser::Mp4Tag::internallyGetFieldId | ( | KnownField | field | ) | const
| protected

Definition at line 119 of file mp4tag.cpp.

## ◆ internallyGetKnownField()

KnownField TagParser::Mp4Tag::internallyGetKnownField | ( | const IdentifierType & | id | ) | const
| protected

Definition at line 195 of file mp4tag.cpp.

## ◆ internallyGetValuesFromField()

void TagParser::Mp4Tag::internallyGetValuesFromField | ( | const FieldType & | field,
|  | std::vector< const TagValue * > & | values ) const
| protected

Adds values from additional data atoms as well.

Definition at line 275 of file mp4tag.cpp.

## ◆ make()

void TagParser::Mp4Tag::make | ( | std::ostream & | stream,
|  | Diagnostics & | diag )

Writes tag information to the specified stream.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | TagParser::Failure or a derived exception when a making error occurs.

Definition at line 459 of file mp4tag.cpp.

## ◆ parse()

void TagParser::Mp4Tag::parse | ( | Mp4Atom & | metaAtom,
|  | Diagnostics & | diag )

Parses tag information from the specified metaAtom.

Exceptions

  Throws | std::ios_base::failure when an IO error occurs.
  Throws | TagParser::Failure or a derived exception when a parsing error occurs.

Definition at line 382 of file mp4tag.cpp.

## ◆ prepareMaking()

Mp4TagMaker TagParser::Mp4Tag::prepareMaking | ( | Diagnostics & | diag | ) |

Prepares making.

Returns
  Returns a Mp4TagMaker object which can be used to actually make the tag.

Remarks
  The tag must NOT be mutated after making is prepared when it is intended to actually make the tag using the make method of the returned object.

Exceptions

  Throws | TagParser::Failure or a derived exception when a making error occurs.

This method might be useful when it is necessary to know the size of the tag before making it.

See also
  make()

Definition at line 448 of file mp4tag.cpp.

## ◆ setValue() [1/2]

bool TagParser::Mp4Tag::setValue | ( | KnownField | field,
|  | const TagValue & | value )
| overridevirtual

Assigns the given value to the specified field.

Remarks
  - If an empty value is given, the field will be be removed.
  - Some tags support more than just one value per field. This method will only alter the first value.

See also
  value(), hasField()

Implements TagParser::Tag.

Definition at line 287 of file mp4tag.cpp.

## ◆ setValue() [2/2]

bool TagParser::Mp4Tag::setValue | ( | std::string_view | mean,
|  | std::string_view | name,
|  | const TagValue & | value )

Assigns the given value to the field with the specified mean and name attributes.

Remarks
  - If there are multiple fields with specified mean and name only the first will be altered.
  - If no field is present, a new one will be created.
  - If value is empty, the field will be removed.

Definition at line 352 of file mp4tag.cpp.

## ◆ setValues()

bool TagParser::Mp4Tag::setValues | ( | KnownField | field,
|  | const std::vector< TagValue > & | values )
| overridevirtual

Assigns the given values to the specified field.

Remarks
  - There might me more than one value assigned to a field. Whereas setValue() only alters the first value, this method will replace all currently assigned values with the specified values.
  - However, the default implementation just sets the first value and discards additional values assuming multiple values per field are not supported by the tag.

Reimplemented from TagParser::Tag.

Definition at line 311 of file mp4tag.cpp.

## ◆ supportsField()

bool TagParser::Mp4Tag::supportsField | ( | KnownField | field | ) | const
| inlineoverridevirtual

Returns an indication whether the specified field is supported by the tag.

Reimplemented from TagParser::FieldMapBasedTag< Mp4Tag >.

Definition at line 140 of file mp4tag.h.

## ◆ supportsMultipleValues()

bool TagParser::Mp4Tag::supportsMultipleValues | ( | KnownField |  | ) | const
| inlineoverridevirtual

Returns false for all fields (for now).

Remarks
  Not sure whether iTunes-style MP4 tags allow this. Let's return false for now.

Todo
  Do some research whether it is supported or not.

Reimplemented from TagParser::Tag.

Definition at line 155 of file mp4tag.h.

## ◆ value() [1/2]

const TagValue & TagParser::Mp4Tag::value | ( | KnownField | field | ) | const
| overridevirtual

Returns the value of the specified field.

Remarks
  - If the specified field is not present an empty TagValue will be returned.
  - Some tags support more than just one value per field. If there are multiple values this method just returns the first one.

See also
  setValue(), hasField()

Implements TagParser::Tag.

Definition at line 59 of file mp4tag.cpp.

## ◆ value() [2/2]

const TagValue & TagParser::Mp4Tag::value | ( | std::string_view | mean,
|  | std::string_view | name ) const

Returns the value of the field with the specified mean and name attributes.

Remarks
  - If there are multiple fields with specified mean and name only the first value will be returned.

Definition at line 108 of file mp4tag.cpp.

## ◆ values()

std::vector< const TagValue * > TagParser::Mp4Tag::values | ( | KnownField | field | ) | const
| overridevirtual

Returns the values of the specified field.

Remarks
  - There might me more than one value assigned to a field. Whereas value() returns only the first value, this method returns all values.
  - However, the default implementation just returns the first value assuming multiple values per field are not supported by the tag.

Reimplemented from TagParser::Tag.

Definition at line 85 of file mp4tag.cpp.

## Friends And Related Symbol Documentation

## ◆ FieldMapBasedTag< Mp4Tag >

friend class FieldMapBasedTag< Mp4Tag >
| friend

Definition at line 69 of file mp4tag.h.

## Member Data Documentation

## ◆ defaultTextEncoding

TagTextEncoding TagParser::Mp4Tag::defaultTextEncoding = TagTextEncoding::Utf8
| staticconstexpr

Definition at line 105 of file mp4tag.h.

## ◆ tagName

std::string_view TagParser::Mp4Tag::tagName = "MP4/iTunes tag"
| staticconstexpr

Definition at line 104 of file mp4tag.h.

## ◆ tagType

TagType TagParser::Mp4Tag::tagType = TagType::Mp4Tag
| staticconstexpr

Definition at line 103 of file mp4tag.h.

The documentation for this class was generated from the following files:

- mp4/mp4tag.h
- mp4/mp4tag.cpp