Tag Parser  6.5.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Protected Member Functions | List of all members
Media::MediaFileInfo Class Reference

The MediaFileInfo class allows to read and write tag information providing a container/tag format independent interface. More...

#include <mediafileinfo.h>

Inheritance diagram for Media::MediaFileInfo:
[legend]
Collaboration diagram for Media::MediaFileInfo:
[legend]

Public Member Functions

 MediaFileInfo ()
 Constructs a new MediaFileInfo. More...
 
 MediaFileInfo (const std::string &path)
 Constructs a new MediaFileInfo for the specified file. More...
 
 MediaFileInfo (const MediaFileInfo &)=delete
 
MediaFileInfooperator= (const MediaFileInfo &)=delete
 
 ~MediaFileInfo ()
 Destroys the MediaFileInfo. More...
 
void parseContainerFormat ()
 Parses the container format of the current file. More...
 
void parseTracks ()
 Parses the tracks of the current file. More...
 
void parseTags ()
 Parses the tag(s) of the current file. More...
 
void parseChapters ()
 Parses the chapters of the current file. More...
 
void parseAttachments ()
 Parses the attachments of the current file. More...
 
void parseEverything ()
 Parses the container format, the tracks and the tag information of the current file. More...
 
void applyChanges ()
 Applies assigned/changed tag information to the current file. More...
 
ContainerFormat containerFormat () const
 Returns the container format of the current file. More...
 
const char * containerFormatName () const
 Returns the name of the container format as C-style string. More...
 
const char * containerFormatAbbreviation () const
 Returns the abbreviation of the container format as C-style string. More...
 
const char * containerFormatSubversion () const
 Returns the subversion of the container format as C-style string. More...
 
const char * mimeType () const
 Returns the MIME-type of the container format as C-style string. More...
 
uint64 containerOffset () const
 Returns the actual container start offset. More...
 
uint64 paddingSize () const
 Returns the padding size. More...
 
AbstractContainercontainer () const
 Returns the container for the current file. More...
 
ParsingStatus containerParsingStatus () const
 Returns an indication whether the container format has been parsed yet. More...
 
ParsingStatus chaptersParsingStatus () const
 Returns whether the chapters have been parsed yet. More...
 
std::vector< AbstractChapter * > chapters () const
 Returns all chapters assigned to the current file. More...
 
bool areChaptersSupported () const
 Returns an indication whether this library supports parsing the chapters of the current file. More...
 
ParsingStatus attachmentsParsingStatus () const
 Returns whether the attachments have been parsed yet. More...
 
std::vector< AbstractAttachment * > attachments () const
 Returns all attachments assigned to the current file. More...
 
bool areAttachmentsSupported () const
 Returns an indication whether this library supports attachment format of the current file. More...
 
ParsingStatus tracksParsingStatus () const
 Returns an indication whether tracks have been parsed yet. More...
 
std::size_t trackCount () const
 Returns the number of tracks that could be parsed. More...
 
std::vector< AbstractTrack * > tracks () const
 Returns the tracks for the current file. More...
 
bool hasTracksOfType (Media::MediaType type) const
 Returns an indication whether the current file has tracks of the specified type. More...
 
ChronoUtilities::TimeSpan duration () const
 Returns the overall duration of the file is known; otherwise returns a TimeSpan with zero ticks. More...
 
std::unordered_set< std::string > availableLanguages (Media::MediaType type=Media::MediaType::Audio) const
 Determines the available languages for specified media type (by default MediaType::Audio). More...
 
std::string technicalSummary () const
 Generates a short technical summary about the file's tracks. More...
 
bool areTracksSupported () const
 Returns an indication whether this library supports parsing the tracks information of the current file. More...
 
ParsingStatus tagsParsingStatus () const
 Returns an indication whether tag information has been parsed yet. More...
 
bool hasId3v1Tag () const
 Returns an indication whether an ID3v1 tag is assigned. More...
 
bool hasId3v2Tag () const
 Returns an indication whether an ID3v2 tag is assigned. More...
 
bool hasAnyTag () const
 Returns an indication whether a tag of any format is assigned. More...
 
Id3v1Tagid3v1Tag () const
 Returns a pointer to the assigned ID3v1 tag or nullptr if none is assigned. More...
 
const std::vector< std::unique_ptr< Id3v2Tag > > & id3v2Tags () const
 Returns pointers to the assigned ID3v2 tags. More...
 
void tags (std::vector< Tag *> &tags) const
 Stores all tags assigned to the current file in the specified vector. More...
 
std::vector< Tag * > tags () const
 Returns all tags assigned to the current file. More...
 
Mp4Tagmp4Tag () const
 Returns a pointer to the assigned MP4 tag or nullptr if none is assigned. More...
 
const std::vector< std::unique_ptr< MatroskaTag > > & matroskaTags () const
 Returns pointers to the assigned Matroska tags. More...
 
VorbisCommentvorbisComment () const
 Returns a pointer to the first assigned Vorbis comment or nullptr if none is assigned. More...
 
bool areTagsSupported () const
 Returns an indication whether this library supports the tag format of the current file. More...
 
bool createAppropriateTags (bool treatUnknownFilesAsMp3Files=false, TagUsage id3v1usage=TagUsage::KeepExisting, TagUsage id3v2usage=TagUsage::Always, bool id3InitOnCreate=false, bool id3TransferValuesOnRemoval=true, bool mergeMultipleSuccessiveId3v2Tags=true, bool keepExistingId3v2version=true, byte id3v2MajorVersion=3, const std::vector< TagTarget > &requiredTargets=std::vector< TagTarget >())
 Ensures appropriate tags are created according the given specifications. More...
 
bool removeId3v1Tag ()
 Removes a possibly assigned ID3v1 tag from the current file. More...
 
Id3v1TagcreateId3v1Tag ()
 Creates an ID3v1 tag for the current file. More...
 
bool removeId3v2Tag (Id3v2Tag *tag)
 Removes an assigned ID3v2 tag from the current file. More...
 
bool removeAllId3v2Tags ()
 Removes all assigned ID3v2 tags from the current file. More...
 
Id3v2TagcreateId3v2Tag ()
 Creates an ID3v2 tag for the current file. More...
 
void removeTag (Tag *tag)
 Removes a possibly assigned tag from the current file. More...
 
void removeAllTags ()
 Removes all assigned tags from the file. More...
 
void mergeId3v2Tags ()
 Merges the assigned ID3v2 tags into a single ID3v2 tag. More...
 
bool id3v1ToId3v2 ()
 Converts an existing ID3v1 tag into an ID3v2 tag. More...
 
bool id3v2ToId3v1 ()
 Converts the existing ID3v2 tags into an ID3v1 tag. More...
 
VorbisCommentcreateVorbisComment ()
 Creates a Vorbis comment for the current file. More...
 
bool removeVorbisComment ()
 Removes all assigned Vorbis comment from the current file. More...
 
bool haveRelatedObjectsNotifications () const
 Returns an indication whether at least one related object (track, tag, container) has notifications. More...
 
NotificationType worstNotificationTypeIncludingRelatedObjects () const
 Returns the worst notification type including related objects such as track, tag and container. More...
 
void gatherRelatedNotifications (NotificationList &notifications) const
 Returns the notifications of the current instance and all related objects (tracks, tags, container, ...). More...
 
NotificationList gatherRelatedNotifications () const
 Returns the notifications of the current instance and all related objects (tracks, tags, container, ...). More...
 
void clearParsingResults ()
 Clears all parsing results and assigned/created/changed information such as detected container format, tracks, tags, ... More...
 
const std::string & saveFilePath () const
 Returns the "save file path" which has been set using setSaveFilePath(). More...
 
void setSaveFilePath (const std::string &saveFilePath)
 Sets the "save file path". More...
 
bool isForcingFullParse () const
 Returns an indication whether forcing a full parse is enabled. More...
 
void setForceFullParse (bool forceFullParse)
 Sets whether forcing a full parse is enabled. More...
 
bool isForcingRewrite () const
 Returns whether forcing rewriting (when applying changes) is enabled. More...
 
void setForceRewrite (bool forceRewrite)
 Sets whether forcing rewriting (when applying changes) is enabled. More...
 
size_t minPadding () const
 Returns the minimum padding to be written before the data blocks when applying changes. More...
 
void setMinPadding (size_t minPadding)
 Sets the minimum padding to be written before the data blocks when applying changes. More...
 
size_t maxPadding () const
 Returns the maximum padding to be written before the data blocks when applying changes. More...
 
void setMaxPadding (size_t maxPadding)
 Sets the maximum padding to be written before the data blocks when applying changes. More...
 
size_t preferredPadding () const
 Returns the padding to be written before the data block when applying changes and the file needs to be rewritten anyways. More...
 
void setPreferredPadding (size_t preferredPadding)
 Sets the padding to be written before the data block when applying changes and the file needs to be rewritten anyways. More...
 
ElementPosition tagPosition () const
 Returns the position (in the output file) where the tag information is written when applying changes. More...
 
void setTagPosition (ElementPosition tagPosition)
 Sets the position (in the output file) where the tag information is written when applying changes. More...
 
bool forceTagPosition () const
 Returns whether tagPosition() is forced. More...
 
void setForceTagPosition (bool forceTagPosition)
 Sets whether tagPosition() is forced. More...
 
ElementPosition indexPosition () const
 Returns the position (in the output file) where the index is written when applying changes. More...
 
void setIndexPosition (ElementPosition indexPosition)
 Sets the position (in the output file) where the index is written when applying changes. More...
 
bool forceIndexPosition () const
 Returns whether indexPosition() is forced. More...
 
void setForceIndexPosition (bool forceTagPosition)
 Sets whether indexPosition() is forced. More...
 
- Public Member Functions inherited from Media::BasicFileInfo
 BasicFileInfo (const std::string &path=std::string())
 Constructs a new BasicFileInfo for the specified file. More...
 
 BasicFileInfo (const BasicFileInfo &)=delete
 
BasicFileInfooperator= (const BasicFileInfo &)=delete
 
virtual ~BasicFileInfo ()
 Destroys the BasicFileInfo. More...
 
void open (bool readOnly=false)
 Opens a std::fstream for the current file. More...
 
void reopen (bool readonly=false)
 Opens a std::fstream for the current file. More...
 
bool isOpen () const
 Indicates whether a std::fstream is open for the current file. More...
 
bool isReadOnly () const
 Indicates whether the last open()/reopen() call was read-only. More...
 
void close ()
 A possibly opened std::fstream will be closed. More...
 
void invalidate ()
 Invalidates the file info manually. More...
 
IoUtilities::NativeFileStream & stream ()
 Returns the std::fstream for the current instance. More...
 
const IoUtilities::NativeFileStream & stream () const
 Returns the std::fstream for the current instance. More...
 
const std::string & path () const
 Returns the path of the current file. More...
 
void setPath (const std::string &path)
 Sets the current file. More...
 
std::string fileName (bool cutExtension=false) const
 Returns the file name of the current file. More...
 
std::string extension () const
 Returns the extension of the current file. More...
 
std::string pathWithoutExtension () const
 Returns the path of the current file without the extension/suffix. More...
 
std::string containingDirectory () const
 Returns the path of the directory containing the current file. More...
 
uint64 size () const
 Returns size of the current file in bytes. More...
 
void reportSizeChanged (uint64 newSize)
 Call this function to report that the size changed. More...
 
void reportPathChanged (const std::string &newPath)
 Call this function to report that the path changed. More...
 
- Public Member Functions inherited from Media::StatusProvider
const NotificationListnotifications () const
 Returns notifications for the current object. More...
 
bool hasNotifications () const
 Returns an indication whether there are notifications for the current object. More...
 
bool hasCriticalNotifications () const
 Returns an indication whether there are critical notifications for the current object. More...
 
NotificationType worstNotificationType () const
 Returns the worst notification type. More...
 
const std::string & currentStatus () const
 Returns a status information for the current object. More...
 
double currentPercentage () const
 Returns the progress percentage of the current object. More...
 
size_t registerCallback (CallbackFunction callback)
 Registers a callback function. More...
 
void unregisterCallback (size_t id)
 Unregisters a previously registered callback function whith the specified id. More...
 
void unregisterAllCallbacks ()
 Unregisters all callback functions. More...
 
void forwardStatusUpdateCalls (StatusProvider *other=nullptr)
 Forwards all status updates calls to the specified statusProvider. More...
 
StatusProviderusedProvider ()
 Returns the provider which callback functions will be called when the status or the percentage is updated. More...
 
void tryToAbort ()
 Commands the object to abort the current operation. More...
 
bool isAborted () const
 Returns an indication whether the current operation should be aborted. More...
 
void invalidateStatus ()
 Invalidates the current status. More...
 
void invalidateNotifications ()
 Invalidates the object's notifications. More...
 
void updateStatus (const std::string &status)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updateStatus (const std::string &status, double percentage)
 This method is meant to be called by the derived class to report updated status information. More...
 
void updatePercentage (double percentage)
 This method is meant to be called by the derived class to report updated progress percentage only. More...
 
void addNotification (const Notification &notification)
 This method is meant to be called by the derived class to add a notification. More...
 
void addNotification (NotificationType type, const std::string &message, const std::string &context)
 This method is meant to be called by the derived class to add a notification of the specified type, message and context. More...
 
void addNotifications (const StatusProvider &from)
 This method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const std::string &higherContext, const StatusProvider &from)
 This method is meant to be called by the derived class to add all notifications from another StatusProvider instance. More...
 
void addNotifications (const NotificationList &notifications)
 This method is meant to be called by the derived class to add the specified notifications. More...
 

Protected Member Functions

virtual void invalidated ()
 Reimplemented from BasicFileInfo::invalidated(). More...
 
- Protected Member Functions inherited from Media::StatusProvider
 StatusProvider ()
 Constructs a new StatusProvider. More...
 

Additional Inherited Members

- Public Types inherited from Media::StatusProvider
typedef std::function< void(StatusProvider &sender)> CallbackFunction
 
typedef std::vector< CallbackFunctionCallbackVector
 
typedef std::pair< int, CallbackFunctionCallbackPair
 
- Static Public Member Functions inherited from Media::BasicFileInfo
static std::string fileName (const std::string &path, bool cutExtension=false)
 Returns the file name of the given file. More...
 
static std::string extension (const std::string &path)
 Returns the extension of the given file. More...
 
static std::string pathWithoutExtension (const std::string &fullPath)
 Returns a copy of the given path without the extension/suffix. More...
 
static std::string containingDirectory (const std::string &path)
 Returns the path of the directory containing the given file. More...
 

Detailed Description

The MediaFileInfo class allows to read and write tag information providing a container/tag format independent interface.

It also provides some technical information such as contained streams.

For examples see "cli/mainfeatures.cpp" of the tageditor repository.

Definition at line 53 of file mediafileinfo.h.

Constructor & Destructor Documentation

◆ MediaFileInfo() [1/3]

Media::MediaFileInfo::MediaFileInfo ( )

Constructs a new MediaFileInfo.

Definition at line 79 of file mediafileinfo.cpp.

◆ MediaFileInfo() [2/3]

Media::MediaFileInfo::MediaFileInfo ( const std::string &  path)

Constructs a new MediaFileInfo for the specified file.

Parameters
pathSpecifies the absolute or relative path of the file.

Definition at line 104 of file mediafileinfo.cpp.

◆ MediaFileInfo() [3/3]

Media::MediaFileInfo::MediaFileInfo ( const MediaFileInfo )
delete

◆ ~MediaFileInfo()

Media::MediaFileInfo::~MediaFileInfo ( )

Destroys the MediaFileInfo.

Definition at line 128 of file mediafileinfo.cpp.

Member Function Documentation

◆ applyChanges()

void Media::MediaFileInfo::applyChanges ( )

Applies assigned/changed tag information to the current file.

This method applies previously assigned tag information to the current file.

Depending on the changes to be applied the file will be rewritten.

When the file needs to be rewritten it will be renamed. A new file with the old name will be created to replace the old file.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a making error occurs.
Remarks
Tags and tracks need to be parsed without errors before this method can be called. All previous parsing results are cleared (using clearParsingResults()). Hence the file must be reparsed. All related objects (tags, tracks, ...) might get invalidated. This includes notifications of these objects as well.
See also
clearParsingResults()

Definition at line 644 of file mediafileinfo.cpp.

◆ areAttachmentsSupported()

bool Media::MediaFileInfo::areAttachmentsSupported ( ) const

Returns an indication whether this library supports attachment format of the current file.

Definition at line 1096 of file mediafileinfo.cpp.

◆ areChaptersSupported()

bool Media::MediaFileInfo::areChaptersSupported ( ) const

Returns an indication whether this library supports parsing the chapters of the current file.

Definition at line 1079 of file mediafileinfo.cpp.

◆ areTagsSupported()

bool Media::MediaFileInfo::areTagsSupported ( ) const

Returns an indication whether this library supports the tag format of the current file.

Definition at line 1134 of file mediafileinfo.cpp.

◆ areTracksSupported()

bool Media::MediaFileInfo::areTracksSupported ( ) const

Returns an indication whether this library supports parsing the tracks information of the current file.

Definition at line 1113 of file mediafileinfo.cpp.

◆ attachments()

vector< AbstractAttachment * > Media::MediaFileInfo::attachments ( ) const

Returns all attachments assigned to the current file.

Remarks
The MediaFileInfo keeps the ownership over the object which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1219 of file mediafileinfo.cpp.

◆ attachmentsParsingStatus()

ParsingStatus Media::MediaFileInfo::attachmentsParsingStatus ( ) const
inline

Returns whether the attachments have been parsed yet.

Definition at line 311 of file mediafileinfo.h.

◆ availableLanguages()

unordered_set< string > Media::MediaFileInfo::availableLanguages ( Media::MediaType  type = Media::MediaType::Audio) const

Determines the available languages for specified media type (by default MediaType::Audio).

If type is MediaType::Unknown, all media types are considered.

parseTracks() needs to be called before. Otherwise this method always returns an empty set.

See also
parseTracks()

Definition at line 868 of file mediafileinfo.cpp.

◆ chapters()

vector< AbstractChapter * > Media::MediaFileInfo::chapters ( ) const

Returns all chapters assigned to the current file.

Remarks
The MediaFileInfo keeps the ownership over the object which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1201 of file mediafileinfo.cpp.

◆ chaptersParsingStatus()

ParsingStatus Media::MediaFileInfo::chaptersParsingStatus ( ) const
inline

Returns whether the chapters have been parsed yet.

Definition at line 303 of file mediafileinfo.h.

◆ clearParsingResults()

void Media::MediaFileInfo::clearParsingResults ( )

Clears all parsing results and assigned/created/changed information such as detected container format, tracks, tags, ...

This allows a rescan of the file using parsing methods like parseContainerFormat(). Otherwise, these methods do nothing if the information to be parsed has already been gathered.

Remarks
Any pointers previously returned by tags(), tracks(), ... object should be considered invalidated. Notifications of those objects are transfered to the media file info.

Definition at line 1365 of file mediafileinfo.cpp.

◆ container()

AbstractContainer * Media::MediaFileInfo::container ( ) const
inline

Returns the container for the current file.

If there is not corresponding subclass of AbstractContainer for the container format or the container has not been parsed yet using the parseContainerFormat() method nullptr will be returned.

See also
parseContainerFormat()
AbstractContainer

Definition at line 394 of file mediafileinfo.h.

◆ containerFormat()

ContainerFormat Media::MediaFileInfo::containerFormat ( ) const
inline

Returns the container format of the current file.

parseContainerFormat() needs to be called before. Otherwise always ContainerFormat::Unknown will be returned.

Definition at line 220 of file mediafileinfo.h.

◆ containerFormatAbbreviation()

const char * Media::MediaFileInfo::containerFormatAbbreviation ( ) const

Returns the abbreviation of the container format as C-style string.

This abbreviation might be used as file extension.

parseContainerFormat() needs to be called before. Otherwise always an empty string will be returned.

See also
containerFormat()
containerFormatName()
parseContainerFormat()

Definition at line 711 of file mediafileinfo.cpp.

◆ containerFormatName()

const char * Media::MediaFileInfo::containerFormatName ( ) const
inline

Returns the name of the container format as C-style string.

parseContainerFormat() needs to be called before. Otherwise always the name "Unknown" will be returned.

See also
containerFormat()
containerFormatAbbreviation()
parseContainerFormat()

Definition at line 235 of file mediafileinfo.h.

◆ containerFormatSubversion()

const char * Media::MediaFileInfo::containerFormatSubversion ( ) const
inline

Returns the subversion of the container format as C-style string.

parseContainerFormat() needs to be called before. Otherwise always an empty string will be returned.

See also
containerFormat()
containerFormatName()
parseContainerFormat()

Definition at line 250 of file mediafileinfo.h.

◆ containerOffset()

uint64 Media::MediaFileInfo::containerOffset ( ) const
inline

Returns the actual container start offset.

Definition at line 258 of file mediafileinfo.h.

◆ containerParsingStatus()

ParsingStatus Media::MediaFileInfo::containerParsingStatus ( ) const
inline

Returns an indication whether the container format has been parsed yet.

Definition at line 209 of file mediafileinfo.h.

◆ createAppropriateTags()

bool Media::MediaFileInfo::createAppropriateTags ( bool  treatUnknownFilesAsMp3Files = false,
TagUsage  id3v1usage = TagUsage::KeepExisting,
TagUsage  id3v2usage = TagUsage::Always,
bool  id3InitOnCreate = false,
bool  id3TransferValuesOnRemoval = true,
bool  mergeMultipleSuccessiveId3v2Tags = true,
bool  keepExistingId3v2version = true,
byte  id3v2MajorVersion = 3,
const std::vector< TagTarget > &  requiredTargets = std::vector<TagTarget>() 
)

Ensures appropriate tags are created according the given specifications.

Parameters
treatUnknownFilesAsMp3FilesSpecifies whether unknown file formats should be treated as MP3 (might break the file).
id3v1usageSpecifies the usage of ID3v1 when creating tags for MP3 files (has no effect when the file is no MP3 file or not treated as one).
id3v2usageSpecifies the usage of ID3v2 when creating tags for MP3 files (has no effect when the file is no MP3 file or not treated as one).
id3InitOnCreateIndicates whether to initialize newly created ID3 tags (according to id3v1usage and id3v2usage) with the values of the already present ID3 tags.
id3TransferValuesOnRemovalIndicates whether values of removed ID3 tags (according to id3v1usage and id3v2usage) should be transfered to remaining ID3 tags (no values will be overwritten).
mergeMultipleSuccessiveId3v2TagsSpecifies whether multiple successive ID3v2 tags should be merged (see mergeId3v2Tags()).
keepExistingId3v2versionSpecifies whether the version of existing ID3v2 tags should be adjusted to id3v2version (otherwise id3v2version is only used when creating a new ID3v2 tag).
id3v2MajorVersionSpecifies the ID3v2 version to be used. Valid values are 2, 3 and 4.
requiredTargetsSpecifies the required targets. If targets are not supported by the container an informal notification is added.
Returns
Returns whether appropriate tags could be created for the file.
Remarks
  • Tags must have been parsed before invoking this method (otherwise it will just return false).
  • The ID3 related arguments are only practiced when the file format is MP3 or when the file format is unknown and treatUnknownFilesAsMp3Files is true.
  • Tags might be removed as well. For example the existing ID3v1 tag of an MP3 file will be removed if id3v1Usage is set to TagUsage::Never.
  • The method might do nothing if present tag(s) already match the given specifications.
  • This is only a convenience method. The task could be done by manually using the methods createId3v1Tag(), createId3v2Tag(), removeId3v1Tag() ... as well.
  • Some tag information might be discarded. For example when an ID3v2 tag needs to be removed (id3v2usage is set to TagUsage::Never) and an ID3v1 tag will be created instead not all fields can be transfered.
Todo:
Refactoring required, there are too much params (not sure how to refactor though, since not all of the params are simple flags).

Definition at line 511 of file mediafileinfo.cpp.

◆ createId3v1Tag()

Id3v1Tag * Media::MediaFileInfo::createId3v1Tag ( )

Creates an ID3v1 tag for the current file.

This method does nothing the tags of the current file haven't been parsed using the parseTags() method.

If the file has already an ID3v1 tag no new tag will be created.

To apply the created tag and other changings call the applyChanges() method.

Returns
Returns the ID3v1 tag of the current file or nullptr if the tag haven't been parsed yet.
See also
applyChanges()

Definition at line 950 of file mediafileinfo.cpp.

◆ createId3v2Tag()

Id3v2Tag * Media::MediaFileInfo::createId3v2Tag ( )

Creates an ID3v2 tag for the current file.

This method does nothing the tags of the current file haven't been parsed using the parseTags() method.

If the file has already an ID3v2 tag no new tag will be created.

To apply the created tag and other changings call the applyChanges() method.

Returns
Returns the first ID3v2 tag of the current file.
Remarks
The MediaFileInfo keeps the ownership over the created tag. It will be destroyed when the MediaFileInfo is invalidated.
See also
applyChanges()

Definition at line 1020 of file mediafileinfo.cpp.

◆ createVorbisComment()

VorbisComment * Media::MediaFileInfo::createVorbisComment ( )

Creates a Vorbis comment for the current file.

This method does nothing if the tags/tracks of the current file haven't been parsed using the parseTags() and parseTracks() methods.

If the file has already a Vorbis comment no new tag will be created.

To apply the created tag and other changings call the applyChanges() method.

Returns
Returns the Vorbis comment or nullptr if creation is not possible.
See also
applyChanges()

Definition at line 1492 of file mediafileinfo.cpp.

◆ duration()

ChronoUtilities::TimeSpan Media::MediaFileInfo::duration ( ) const

Returns the overall duration of the file is known; otherwise returns a TimeSpan with zero ticks.

parseTracks() needs to be called before. Otherwise this method always returns false.

See also
parseTracks()

Definition at line 848 of file mediafileinfo.cpp.

◆ forceIndexPosition()

bool Media::MediaFileInfo::forceIndexPosition ( ) const
inline

Returns whether indexPosition() is forced.

See also
setForceIndexPosition()
indexPosition(), setIndexPosition()

Definition at line 584 of file mediafileinfo.h.

◆ forceTagPosition()

bool Media::MediaFileInfo::forceTagPosition ( ) const
inline

Returns whether tagPosition() is forced.

See also
setForceTagPosition()
tagPosition(), setTagPosition()

Definition at line 544 of file mediafileinfo.h.

◆ gatherRelatedNotifications() [1/2]

void Media::MediaFileInfo::gatherRelatedNotifications ( NotificationList notifications) const

Returns the notifications of the current instance and all related objects (tracks, tags, container, ...).

Remarks
The specified list is not cleared before notifications are added.

Definition at line 1301 of file mediafileinfo.cpp.

◆ gatherRelatedNotifications() [2/2]

NotificationList Media::MediaFileInfo::gatherRelatedNotifications ( ) const

Returns the notifications of the current instance and all related objects (tracks, tags, container, ...).

Definition at line 1346 of file mediafileinfo.cpp.

◆ hasAnyTag()

bool Media::MediaFileInfo::hasAnyTag ( ) const

Returns an indication whether a tag of any format is assigned.

Definition at line 1572 of file mediafileinfo.cpp.

◆ hasId3v1Tag()

bool Media::MediaFileInfo::hasId3v1Tag ( ) const
inline

Returns an indication whether an ID3v1 tag is assigned.

Definition at line 319 of file mediafileinfo.h.

◆ hasId3v2Tag()

bool Media::MediaFileInfo::hasId3v2Tag ( ) const
inline

Returns an indication whether an ID3v2 tag is assigned.

Definition at line 327 of file mediafileinfo.h.

◆ hasTracksOfType()

bool Media::MediaFileInfo::hasTracksOfType ( Media::MediaType  type) const

Returns an indication whether the current file has tracks of the specified type.

parseTracks() needs to be called before. Otherwise this method always returns false.

See also
parseTracks()

Definition at line 822 of file mediafileinfo.cpp.

◆ haveRelatedObjectsNotifications()

bool Media::MediaFileInfo::haveRelatedObjectsNotifications ( ) const

Returns an indication whether at least one related object (track, tag, container) has notifications.

Definition at line 1236 of file mediafileinfo.cpp.

◆ id3v1Tag()

Id3v1Tag * Media::MediaFileInfo::id3v1Tag ( ) const
inline

Returns a pointer to the assigned ID3v1 tag or nullptr if none is assigned.

Remarks
The MediaFileInfo keeps the ownership over the returned pointer. The returned ID3v1 tag will be destroyed when the MediaFileInfo gets invalidated.

Definition at line 339 of file mediafileinfo.h.

◆ id3v1ToId3v2()

bool Media::MediaFileInfo::id3v1ToId3v2 ( )

Converts an existing ID3v1 tag into an ID3v2 tag.

Effectively merges all ID3 tags into a single ID3v2 tag.

Remarks
Does nothing if
  • there is no ID3v1 tag assigned.
  • the file format isn't known to support ID3 tags (unless there is an ID3 tag present).
  • the tags of the current file haven't been parsed using the parseTags() method.

Definition at line 1450 of file mediafileinfo.cpp.

◆ id3v2Tags()

const std::vector< std::unique_ptr< Id3v2Tag > > & Media::MediaFileInfo::id3v2Tags ( ) const
inline

Returns pointers to the assigned ID3v2 tags.

Remarks
The MediaFileInfo keeps the ownership over the returned pointers. The returned ID3v2 tags will be destroyed when the MediaFileInfo gets invalidated.

Definition at line 351 of file mediafileinfo.h.

◆ id3v2ToId3v1()

bool Media::MediaFileInfo::id3v2ToId3v1 ( )

Converts the existing ID3v2 tags into an ID3v1 tag.

Effectively merges all ID3 tags into a single ID3v1 tag.

Remarks
Does nothing if
  • there is not at least one ID3v2 tag assigned.
  • the file format isn't known to support ID3 tags (unless there is an ID3 tag present).
  • the tags of the current file haven't been parsed using the parseTags() method.

Definition at line 1469 of file mediafileinfo.cpp.

◆ indexPosition()

ElementPosition Media::MediaFileInfo::indexPosition ( ) const
inline

Returns the position (in the output file) where the index is written when applying changes.

See also
setIndexPosition()
Remarks
To determine the current index position, use AbstractContainer::determineIndexPosition().

Definition at line 564 of file mediafileinfo.h.

◆ invalidated()

void Media::MediaFileInfo::invalidated ( )
protectedvirtual

Reimplemented from BasicFileInfo::invalidated().

Reimplemented from Media::BasicFileInfo.

Definition at line 1596 of file mediafileinfo.cpp.

◆ isForcingFullParse()

bool Media::MediaFileInfo::isForcingFullParse ( ) const
inline

Returns an indication whether forcing a full parse is enabled.

If enabled the parser will analyse the file structure as deep as possible. This might cause long parsing times for big files.

See also
setForceFullParse()

Definition at line 407 of file mediafileinfo.h.

◆ isForcingRewrite()

bool Media::MediaFileInfo::isForcingRewrite ( ) const
inline

Returns whether forcing rewriting (when applying changes) is enabled.

Definition at line 425 of file mediafileinfo.h.

◆ matroskaTags()

const vector< unique_ptr< MatroskaTag > > & Media::MediaFileInfo::matroskaTags ( ) const

Returns pointers to the assigned Matroska tags.

Remarks
The MediaFileInfo keeps the ownership over the returned pointers. The returned Matroska tags will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1171 of file mediafileinfo.cpp.

◆ maxPadding()

size_t Media::MediaFileInfo::maxPadding ( ) const
inline

Returns the maximum padding to be written before the data blocks when applying changes.

Maximum padding in front of the file allows adding additional fields afterwards whithout needing to rewrite the entire file or to put tag information at the end of the file.

The default value is 0 which will force the library to rewrite the entire file almost always when applying changes. Increate the value using setMaxPadding() to prevent this.

See also
minPadding()
tagPosition()
setMaxPadding()

Definition at line 478 of file mediafileinfo.h.

◆ mergeId3v2Tags()

void Media::MediaFileInfo::mergeId3v2Tags ( )

Merges the assigned ID3v2 tags into a single ID3v2 tag.

Some files I've got contain multiple successive ID3v2 tags. If the tags of such an file is parsed by this class, these tags will be kept seperate. This method merges all assigned ID3v2 tags. All fields from the additional ID3v2 tags will be inserted to the first tag. All assigned ID3v2 tag instances except thefirst will be destroyed.

A possibly assigned ID3v1 tag remains unaffected.

This method does nothing the tags of the current file haven't been parsed using the parseTags() method.

See also
id3v2Tags()

Definition at line 1423 of file mediafileinfo.cpp.

◆ mimeType()

const char * Media::MediaFileInfo::mimeType ( ) const

Returns the MIME-type of the container format as C-style string.

parseContainerFormat() needs to be called before. Otherwise always an empty string will be returned.

See also
containerFormat()
containerFormatName()
parseContainerFormat()

Definition at line 765 of file mediafileinfo.cpp.

◆ minPadding()

size_t Media::MediaFileInfo::minPadding ( ) const
inline

Returns the minimum padding to be written before the data blocks when applying changes.

Minimum padding in front of the file allows adding additional fields afterwards whithout needing to rewrite the entire file or to put tag information at the end of the file.

The default value is 0.

See also
maxPadding()
tagPosition()
setMinPadding()

Definition at line 450 of file mediafileinfo.h.

◆ mp4Tag()

Mp4Tag * Media::MediaFileInfo::mp4Tag ( ) const

Returns a pointer to the assigned MP4 tag or nullptr if none is assigned.

Remarks
The MediaFileInfo keeps the ownership over the object which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1159 of file mediafileinfo.cpp.

◆ operator=()

MediaFileInfo& Media::MediaFileInfo::operator= ( const MediaFileInfo )
delete

◆ paddingSize()

uint64 Media::MediaFileInfo::paddingSize ( ) const
inline

Returns the padding size.

Container format and tags should have been parsed yet.

Definition at line 266 of file mediafileinfo.h.

◆ parseAttachments()

void Media::MediaFileInfo::parseAttachments ( )

Parses the attachments of the current file.

This method parses the attachments of the current file if not been parsed yet.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.
Remarks
parseContainerFormat() must be called before.
See also
areChaptersParsed(), parseContainerFormat(), parseTracks(), parseTags(), parseEverything()

Definition at line 453 of file mediafileinfo.cpp.

◆ parseChapters()

void Media::MediaFileInfo::parseChapters ( )

Parses the chapters of the current file.

This method parses the chapters of the current file if not been parsed yet.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.
Remarks
parseContainerFormat() must be called before.
See also
areChaptersParsed(), parseContainerFormat(), parseTracks(), parseTags(), parseEverything()

Definition at line 420 of file mediafileinfo.cpp.

◆ parseContainerFormat()

void Media::MediaFileInfo::parseContainerFormat ( )

Parses the container format of the current file.

This method parses the container of the current file format if it has not been parsed yet.

After calling this method the methods containerFormat(), containerFormatName(), containerFormatAbbreviation(), containerFormatSubversion(), containerMimeType(), container(), mp4Container() and matroskaContainer() will return the parsed information.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.
See also
isContainerParsed(), parseTracks(), parseTag(), parseChapters(), parseEverything()

Definition at line 146 of file mediafileinfo.cpp.

◆ parseEverything()

void Media::MediaFileInfo::parseEverything ( )

Parses the container format, the tracks and the tag information of the current file.

See the individual methods to for more details and exceptions which might be thrown.

See also
parseContainerFormat(), parseTracks(), parseTags()

Definition at line 481 of file mediafileinfo.cpp.

◆ parseTags()

void Media::MediaFileInfo::parseTags ( )

Parses the tag(s) of the current file.

This method parses the tag(s) of the current file if not been parsed yet. After calling this method the methods id3v1Tag(), id3v2Tags(), mp4Tag() and allTags() will return the parsed information.

Previously assigned but not applied tag information will be discarted.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.
Remarks
parseContainerFormat() must be called before.
See also
isTagParsed(), parseContainerFormat(), parseTracks(), parseChapters(), parseEverything()

Definition at line 354 of file mediafileinfo.cpp.

◆ parseTracks()

void Media::MediaFileInfo::parseTracks ( )

Parses the tracks of the current file.

This method parses the tracks of the current file if not been parsed yet. After calling this method the methods trackCount(), tracks(), and hasTracksOfType() will return the parsed information.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsMedia::Failure or a derived exception when a parsing error occurs.
Remarks
parseContainerFormat() must be called before.
See also
areTracksParsed(), parseContainerFormat(), parseTags(), parseChapters(), parseEverything()

Definition at line 293 of file mediafileinfo.cpp.

◆ preferredPadding()

size_t Media::MediaFileInfo::preferredPadding ( ) const
inline

Returns the padding to be written before the data block when applying changes and the file needs to be rewritten anyways.

Padding in front of the file allows adding additional fields afterwards whithout needing to rewrite the entire file or to put tag information at the end of the file.

Definition at line 499 of file mediafileinfo.h.

◆ removeAllId3v2Tags()

bool Media::MediaFileInfo::removeAllId3v2Tags ( )

Removes all assigned ID3v2 tags from the current file.

To apply the removal and other changings call the applyChanges() method.

Returns
Returns whether there where ID3v2 tags assigned which could be removed.
See also
applyChanges()

Definition at line 996 of file mediafileinfo.cpp.

◆ removeAllTags()

void Media::MediaFileInfo::removeAllTags ( )

Removes all assigned tags from the file.

To apply the removal and other changings call the applyChanges() method.

Definition at line 1064 of file mediafileinfo.cpp.

◆ removeId3v1Tag()

bool Media::MediaFileInfo::removeId3v1Tag ( )

Removes a possibly assigned ID3v1 tag from the current file.

To apply the removal and other changings call the applyChanges() method.

Returns
Returns whether there was an ID3v1 tag assigned which could be removed.
See also
applyChanges()

Definition at line 923 of file mediafileinfo.cpp.

◆ removeId3v2Tag()

bool Media::MediaFileInfo::removeId3v2Tag ( Id3v2Tag tag)

Removes an assigned ID3v2 tag from the current file.

To apply the removal and other changings call the applyChanges() method.

Parameters
tagSpecifies the ID3v2 tag to be removed.
Returns
Returns whether there the an ID3v2 tag could be removed.
Remarks
The tag will be destroyed by the MediaFileInfo if it could be removed.
See also
applyChanges()

Definition at line 974 of file mediafileinfo.cpp.

◆ removeTag()

void Media::MediaFileInfo::removeTag ( Tag tag)

Removes a possibly assigned tag from the current file.

Parameters
tagSpecifies the tag to be removed. The tag will not only be detached from the file, it will be destroyed as well. Might be nullptr (for convenience; eg. you might want to call file.removeTag(file.mp4Tag()) to ensure no MP4 tag is present without checking before).

To apply the removal and other changings call the applyChanges() method.

See also
applyChanges()

Definition at line 1040 of file mediafileinfo.cpp.

◆ removeVorbisComment()

bool Media::MediaFileInfo::removeVorbisComment ( )

Removes all assigned Vorbis comment from the current file.

To apply the removal and other changings call the applyChanges() method.

Returns
Returns whether there was an Vorbis comment assigned which could be removed.
See also
applyChanges()

Definition at line 1520 of file mediafileinfo.cpp.

◆ saveFilePath()

const std::string & Media::MediaFileInfo::saveFilePath ( ) const
inline

Returns the "save file path" which has been set using setSaveFilePath().

See also
setSaveFilePath()

Definition at line 360 of file mediafileinfo.h.

◆ setForceFullParse()

void Media::MediaFileInfo::setForceFullParse ( bool  forceFullParse)
inline

Sets whether forcing a full parse is enabled.

Remarks
The setting is applied next time parsing. The current parsing results are not mutated.
See also
isForcingFullParse()

Definition at line 417 of file mediafileinfo.h.

◆ setForceIndexPosition()

void Media::MediaFileInfo::setForceIndexPosition ( bool  forceIndexPosition)
inline

Sets whether indexPosition() is forced.

See also
forceIndexPosition()
indexPosition(), setIndexPosition()

Definition at line 594 of file mediafileinfo.h.

◆ setForceRewrite()

void Media::MediaFileInfo::setForceRewrite ( bool  forceRewrite)
inline

Sets whether forcing rewriting (when applying changes) is enabled.

Definition at line 433 of file mediafileinfo.h.

◆ setForceTagPosition()

void Media::MediaFileInfo::setForceTagPosition ( bool  forceTagPosition)
inline

Sets whether tagPosition() is forced.

See also
forceTagPosition()
tagPosition(), setTagPosition()

Definition at line 554 of file mediafileinfo.h.

◆ setIndexPosition()

void Media::MediaFileInfo::setIndexPosition ( ElementPosition  indexPosition)
inline

Sets the position (in the output file) where the index is written when applying changes.

Remarks
Same rules as for tagPosition() apply. If conflicting with tagPosition(), tagPosition() has priority.

Definition at line 574 of file mediafileinfo.h.

◆ setMaxPadding()

void Media::MediaFileInfo::setMaxPadding ( size_t  maxPadding)
inline

Sets the maximum padding to be written before the data blocks when applying changes.

Remarks
This value might be ignored if not supported by the container/tag format or the corresponding implementation.
See also
maxPadding()

Definition at line 488 of file mediafileinfo.h.

◆ setMinPadding()

void Media::MediaFileInfo::setMinPadding ( size_t  minPadding)
inline

Sets the minimum padding to be written before the data blocks when applying changes.

Remarks
This value might be ignored if not supported by the container/tag format or the corresponding implementation.
See also
minPadding()

Definition at line 460 of file mediafileinfo.h.

◆ setPreferredPadding()

void Media::MediaFileInfo::setPreferredPadding ( size_t  preferredPadding)
inline

Sets the padding to be written before the data block when applying changes and the file needs to be rewritten anyways.

Remarks
This value might be ignored if not supported by the container/tag format or the corresponding implementation.
See also
preferredPadding()

Definition at line 509 of file mediafileinfo.h.

◆ setSaveFilePath()

void Media::MediaFileInfo::setSaveFilePath ( const std::string &  saveFilePath)
inline

Sets the "save file path".

If saveFilePath is not empty, this path will be used to save the output file when applying changes using applyChanges(). Thus the current file is not modified by applyChanges() in this case and the variable isForcingRewrite() does not affect the behaviour of applyChanges(). If the changes have been applied without fatal errors the "save file path" is cleared and used as the new regular path().

By default, this path is empty.

Remarks
saveFilePath mustn't be the current path().

Definition at line 379 of file mediafileinfo.h.

◆ setTagPosition()

void Media::MediaFileInfo::setTagPosition ( ElementPosition  tagPosition)
inline

Sets the position (in the output file) where the tag information is written when applying changes.

Remarks
  • If putting the tags at another position would prevent rewriting the entire file the specified position might not be used if forceTagPosition() is false.
  • However if the specified position is not supported by the container/tag format or by the implementation for the format it is ignored (even if forceTagPosition() is true).
  • Default value is ElementPosition::BeforeData

Definition at line 534 of file mediafileinfo.h.

◆ tagPosition()

ElementPosition Media::MediaFileInfo::tagPosition ( ) const
inline

Returns the position (in the output file) where the tag information is written when applying changes.

See also
setTagPosition()
Remarks
To determine the current tag position, use AbstractContainer::determineTagPosition().

Definition at line 519 of file mediafileinfo.h.

◆ tags() [1/2]

void Media::MediaFileInfo::tags ( std::vector< Tag *> &  tags) const

Stores all tags assigned to the current file in the specified vector.

Previous elements of the vector will not be cleared.

Remarks
The MediaFileInfo keeps the ownership over the tags which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1549 of file mediafileinfo.cpp.

◆ tags() [2/2]

vector< Tag * > Media::MediaFileInfo::tags ( ) const

Returns all tags assigned to the current file.

Remarks
The MediaFileInfo keeps the ownership over the tags which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1586 of file mediafileinfo.cpp.

◆ tagsParsingStatus()

ParsingStatus Media::MediaFileInfo::tagsParsingStatus ( ) const
inline

Returns an indication whether tag information has been parsed yet.

Definition at line 274 of file mediafileinfo.h.

◆ technicalSummary()

string Media::MediaFileInfo::technicalSummary ( ) const

Generates a short technical summary about the file's tracks.

parseTracks() needs to be called before. Otherwise this method always returns an empty string.

Example (exact format might change in the future!): "H.264-720p / HE-AAC-6ch-eng / HE-AAC-2ch-ger / SRT-eng / SRT-ger"

See also
parseTracks()

Definition at line 895 of file mediafileinfo.cpp.

◆ trackCount()

size_t Media::MediaFileInfo::trackCount ( ) const
inline

Returns the number of tracks that could be parsed.

parseTracks() needs to be called before. Otherwise this method always returns zero.

See also
parseTracks()

Definition at line 295 of file mediafileinfo.h.

◆ tracks()

vector< AbstractTrack * > Media::MediaFileInfo::tracks ( ) const

Returns the tracks for the current file.

parseTracks() needs to be called before. Otherwise this method always returns an empty vector.

Remarks
The MediaFileInfo keeps the ownership over the returned pointers. The returned Tracks will be destroyed when the MediaFileInfo is invalidated.
See also
parseTracks()

Definition at line 792 of file mediafileinfo.cpp.

◆ tracksParsingStatus()

ParsingStatus Media::MediaFileInfo::tracksParsingStatus ( ) const
inline

Returns an indication whether tracks have been parsed yet.

Definition at line 282 of file mediafileinfo.h.

◆ vorbisComment()

VorbisComment * Media::MediaFileInfo::vorbisComment ( ) const

Returns a pointer to the first assigned Vorbis comment or nullptr if none is assigned.

Remarks
The MediaFileInfo keeps the ownership over the object which will be destroyed when the MediaFileInfo is invalidated.

Definition at line 1187 of file mediafileinfo.cpp.

◆ worstNotificationTypeIncludingRelatedObjects()

NotificationType Media::MediaFileInfo::worstNotificationTypeIncludingRelatedObjects ( ) const

Returns the worst notification type including related objects such as track, tag and container.

Definition at line 1263 of file mediafileinfo.cpp.


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