mirror/taglib
1
0
Fork 0
mirror of https://github.com/taglib/taglib.git synced 2026-07-24 04:10:54 -04:00
Code Issues Packages Projects Releases Wiki Activity

Correct the API documentation

Browse Source
This commit is contained in:
Urs Fleisch
2024-01-01 17:46:45 +01:00
parent ef013b76db
commit c5d798a50d
89 changed files with 728 additions and 541 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
taglib/mpeg/id3v1/id3v1tag.h
View File

@@ -38,7 +38,7 @@ namespace TagLib {
namespace ID3v1 {
//! A abstraction for the string to data encoding in ID3v1 tags.
//! An abstraction for the string to data encoding in ID3v1 tags.
/*!
* ID3v1 should in theory always contain ISO-8859-1 (Latin1) data. In

6
taglib/mpeg/id3v2/frames/attachedpictureframe.h
View File

@@ -50,7 +50,7 @@ namespace TagLib {
public:
/*!
/*
* This describes the function or content of the picture.
*/
DECLARE_PICTURE_TYPE_ENUM(Type)
@@ -67,7 +67,7 @@ namespace TagLib {
explicit AttachedPictureFrame(const ByteVector &data);
/*!
* Destroys the AttahcedPictureFrame instance.
* Destroys the AttachedPictureFrame instance.
*/
~AttachedPictureFrame() override;
@@ -150,7 +150,7 @@ namespace TagLib {
/*!
* Returns the image data as a ByteVector.
*
* \note ByteVector has a data() method that returns a const char * which
* \note ByteVector has a data() method that returns a <tt>const char *</tt> which
* should make it easy to export this data to external programs.
*
* \see setPicture()

12
taglib/mpeg/id3v2/frames/chapterframe.h
View File

@@ -57,7 +57,7 @@ namespace TagLib {
* \a startTime, end time \a endTime, start offset \a startOffset,
* end offset \a endOffset and optionally a list of embedded frames,
* whose ownership will then be taken over by this Frame, in
* \a embeddedFrames;
* \a embeddedFrames.
*
* All times are in milliseconds.
*/
@@ -153,7 +153,7 @@ namespace TagLib {
void setEndOffset(const unsigned int &eO);
/*!
* Returns a reference to the frame list map. This is an FrameListMap of
* Returns a reference to the frame list map. This is a FrameListMap of
* all of the frames embedded in the CHAP frame.
*
* This is the most convenient structure for accessing the CHAP frame's
@@ -169,11 +169,11 @@ namespace TagLib {
const FrameListMap &embeddedFrameListMap() const;
/*!
* Returns a reference to the embedded frame list. This is an FrameList
* Returns a reference to the embedded frame list. This is a FrameList
* of all of the frames embedded in the CHAP frame in the order that they
* were parsed.
*
* This can be useful if for example you want iterate over the CHAP frame's
* This can be useful if for example you want to iterate over the CHAP frame's
* embedded frames in the order that they occur in the CHAP frame.
*
* \warning You should not modify this data structure directly, instead
@@ -204,8 +204,8 @@ namespace TagLib {
void addEmbeddedFrame(Frame *frame);
/*!
* Remove an embedded frame from the CHAP frame. If \a del is true the frame's
* memory will be freed; if it is false, it must be deleted by the user.
* Remove an embedded frame from the CHAP frame. If \a del is \c true the frame's
* memory will be freed; if it is \c false, it must be deleted by the user.
*
* \note Using this method will invalidate any pointers on the list
* returned by embeddedFrameList()

2
taglib/mpeg/id3v2/frames/eventtimingcodesframe.h
View File

@@ -137,7 +137,7 @@ namespace TagLib {
EventTimingCodesFrame &operator=(const EventTimingCodesFrame &) = delete;
/*!
* Returns a null string.
* Returns an empty string.
*/
String toString() const override;

2
taglib/mpeg/id3v2/frames/generalencapsulatedobjectframe.h
View File

@@ -151,7 +151,7 @@ namespace TagLib {
/*!
* Returns the object data as a ByteVector.
*
* \note ByteVector has a data() method that returns a const char * which
* \note ByteVector has a data() method that returns a <tt>const char *</tt> which
* should make it easy to export this data to external programs.
*
* \see setObject()

2
taglib/mpeg/id3v2/frames/ownershipframe.cpp
View File

@@ -127,7 +127,7 @@ void OwnershipFrame::parseFields(const ByteVector &data)
d->textEncoding = static_cast<String::Type>(data[0]);
pos += 1;
// Read the price paid this is a null terminate string
// Read the price paid, this is a null terminated string
d->pricePaid = readStringField(data, String::Latin1, &pos);
// If we don't have at least 8 bytes left then don't parse the rest of the

2
taglib/mpeg/id3v2/frames/ownershipframe.h
View File

@@ -51,7 +51,7 @@ namespace TagLib {
explicit OwnershipFrame(String::Type encoding = String::Latin1);
/*!
* Construct a ownership based on the data in \a data.
* Construct an ownership frame based on the data in \a data.
*/
explicit OwnershipFrame(const ByteVector &data);

2
taglib/mpeg/id3v2/frames/podcastframe.h
View File

@@ -56,7 +56,7 @@ namespace TagLib {
PodcastFrame &operator=(const PodcastFrame &) = delete;
/*!
* Returns a null string.
* Returns an empty string.
*/
String toString() const override;

2
taglib/mpeg/id3v2/frames/privateframe.h
View File

@@ -34,7 +34,7 @@ namespace TagLib {
namespace ID3v2 {
//! An implementation of ID3v2 privateframe
//! An implementation of ID3v2 private frame
class TAGLIB_EXPORT PrivateFrame : public Frame
{

14
taglib/mpeg/id3v2/frames/tableofcontentsframe.h
View File

@@ -78,7 +78,7 @@ namespace TagLib {
ByteVector elementID() const;
/*!
* Returns true, if the frame is top-level (doesn't have
* Returns \c true, if the frame is top-level (doesn't have
* any parent CTOC frame).
*
* \see setIsTopLevel()
@@ -86,7 +86,7 @@ namespace TagLib {
bool isTopLevel() const;
/*!
* Returns true, if the child elements list entries
* Returns \c true, if the child elements list entries
* are ordered.
*
* \see setIsOrdered()
@@ -153,7 +153,7 @@ namespace TagLib {
void removeChildElement(const ByteVector &cE);
/*!
* Returns a reference to the frame list map. This is an FrameListMap of
* Returns a reference to the frame list map. This is a FrameListMap of
* all of the frames embedded in the CTOC frame.
*
* This is the most convenient structure for accessing the CTOC frame's
@@ -169,11 +169,11 @@ namespace TagLib {
const FrameListMap &embeddedFrameListMap() const;
/*!
* Returns a reference to the embedded frame list. This is an FrameList
* Returns a reference to the embedded frame list. This is a FrameList
* of all of the frames embedded in the CTOC frame in the order that they
* were parsed.
*
* This can be useful if for example you want iterate over the CTOC frame's
* This can be useful if for example you want to iterate over the CTOC frame's
* embedded frames in the order that they occur in the CTOC frame.
*
* \warning You should not modify this data structure directly, instead
@@ -204,8 +204,8 @@ namespace TagLib {
void addEmbeddedFrame(Frame *frame);
/*!
* Remove an embedded frame from the CTOC frame. If \a del is true the frame's
* memory will be freed; if it is false, it must be deleted by the user.
* Remove an embedded frame from the CTOC frame. If \a del is \c true the frame's
* memory will be freed; if it is \c false, it must be deleted by the user.
*
* \note Using this method will invalidate any pointers on the list
* returned by embeddedFrameList()

4
taglib/mpeg/id3v2/frames/textidentificationframe.h
View File

@@ -59,7 +59,7 @@ namespace TagLib {
* <li><b>TDTG</b> Tagging time</li>
* <li><b>TENC</b> Encoded by</li>
* <li><b>TEXT</b> Lyricist/Text writer</li>
* <li><b>TFLT</b> File type</li>
* <li><b>TFLT</b> %File type</li>
* <li><b>TIPL</b> Involved people list</li>
* <li><b>TIT1</b> Content group description</li>
* <li><b>TIT2</b> Title/songname/content description</li>
@@ -74,7 +74,7 @@ namespace TagLib {
* <li><b>TOFN</b> Original filename</li>
* <li><b>TOLY</b> Original lyricist(s)/text writer(s)</li>
* <li><b>TOPE</b> Original artist(s)/performer(s)</li>
* <li><b>TOWN</b> File owner/licensee</li>
* <li><b>TOWN</b> %File owner/licensee</li>
* <li><b>TPE1</b> Lead performer(s)/Soloist(s)</li>
* <li><b>TPE2</b> Band/orchestra/accompaniment</li>
* <li><b>TPE3</b> Conductor/performer refinement</li>

2
taglib/mpeg/id3v2/frames/unknownframe.h
View File

@@ -37,7 +37,7 @@ namespace TagLib {
/*!
* This class represents a frame type not known (or more often simply
* unimplemented) in TagLib. This is here provide a basic API for
* unimplemented) in TagLib. This is here to provide a basic API for
* manipulating the binary data of unknown frames and to provide a means
* of rendering such \e unknown frames.
*

10
taglib/mpeg/id3v2/id3v2.h
View File

@@ -8,6 +8,16 @@ namespace TagLib {
* This is a relatively complete and flexible framework for working with ID3v2
* tags.
*
* More information about ID3v2 tags can be found at
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.2.0.txt">
* id3v2.2.0.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.3.0.txt">
* id3v2.3.0.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>
* - <a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>
*
* \see ID3v2::Tag
*/
namespace ID3v2 {

3
taglib/mpeg/id3v2/id3v2extendedheader.h
View File

@@ -42,7 +42,8 @@ namespace TagLib {
* the ID3v2 standard. The API is based on the properties of ID3v2 extended
* headers specified there. If any of the terms used in this documentation
* are unclear please check the specification in the linked section.
* (Structure, <a href="id3v2-structure.html#3.2">3.2</a>)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 3.2)
*/
class TAGLIB_EXPORT ExtendedHeader

50
taglib/mpeg/id3v2/id3v2frame.h
View File

@@ -45,10 +45,12 @@ namespace TagLib {
/*!
* This class is the main ID3v2 frame implementation. In ID3v2, a tag is
* split between a collection of frames (which are in turn split into fields
* (Structure, <a href="id3v2-structure.html#4">4</a>)
* (<a href="id3v2-frames.html">Frames</a>). This class provides an API for
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>). This class provides an API for
* gathering information about and modifying ID3v2 frames. Functionality
* specific to a given frame type is handed in one of the many subclasses.
* specific to a given frame type is handled in one of the many subclasses.
*/
class TAGLIB_EXPORT Frame
@@ -67,8 +69,11 @@ namespace TagLib {
Frame &operator=(const Frame &) = delete;
/*!
* Returns the Frame ID (Structure, <a href="id3v2-structure.html#4">4</a>)
* (Frames, <a href="id3v2-frames.html#4">4</a>)
* Returns the Frame ID
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>, 4)
*/
ByteVector frameID() const;
@@ -177,7 +182,7 @@ namespace TagLib {
explicit Frame(const ByteVector &data);
/*!
* This creates an Frame using the header \a h.
* This creates a Frame using the header \a h.
*
* The ownership of this header will be assigned to the frame and the
* header will be deleted when the frame is destroyed.
@@ -185,7 +190,7 @@ namespace TagLib {
Frame(Header *h);
/*!
* Sets the header to \a h. If \a deleteCurrent is true, this will free
* Sets the header to \a h. If \a deleteCurrent is \c true, this will free
* the memory of the current header.
*
* The ownership of this header will be assigned to the frame and the
@@ -229,7 +234,7 @@ namespace TagLib {
int *position = nullptr);
/*!
* Checks a the list of string values to see if they can be used with the
* Checks the list of string values to see if they can be used with the
* specified encoding and returns the recommended encoding. This method
* also checks the ID3v2 version and makes sure the encoding can be used
* in the version specified by the frame's header.
@@ -271,7 +276,9 @@ namespace TagLib {
//! ID3v2 frame header implementation
/*!
* The ID3v2 Frame Header (Structure, <a href="id3v2-structure.html#4">4</a>)
* The ID3v2 Frame Header
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
*
* Every ID3v2::Frame has an associated header that gives some general
* properties of the frame and also makes it possible to identify the frame
@@ -309,8 +316,11 @@ namespace TagLib {
void setData(const ByteVector &data, unsigned int version = 4);
/*!
* Returns the Frame ID (Structure, <a href="id3v2-structure.html#4">4</a>)
* (Frames, <a href="id3v2-frames.html#4">4</a>)
* Returns the Frame ID
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 4)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-frames.txt">
* id3v2.4.0-frames.txt</a>, 4)
*/
ByteVector frameID() const;
@@ -353,7 +363,7 @@ namespace TagLib {
unsigned int size();
/*!
* Returns true if the flag for tag alter preservation is set.
* Returns \c true if the flag for tag alter preservation is set.
*
* The semantics are a little backwards from what would seem natural
* (setting the preservation flag to throw away the frame), but this
@@ -365,7 +375,7 @@ namespace TagLib {
/*!
* Sets the flag for preservation of this frame if the tag is set. If
* this is set to true the frame will not be written when the tag is
* this is set to \c true the frame will not be written when the tag is
* saved.
*
* The semantics are a little backwards from what would seem natural
@@ -377,47 +387,47 @@ namespace TagLib {
void setTagAlterPreservation(bool preserve);
/*!
* Returns true if the flag for file alter preservation is set.
* Returns \c true if the flag for file alter preservation is set.
*
* \note This flag is currently ignored internally in TagLib.
*/
bool fileAlterPreservation() const;
/*!
* Returns true if the frame is meant to be read only.
* Returns \c true if the frame is meant to be read only.
*
* \note This flag is currently ignored internally in TagLib.
*/
bool readOnly() const;
/*!
* Returns true if the flag for the grouping identity is set.
* Returns \c true if the flag for the grouping identity is set.
*
* \note This flag is currently ignored internally in TagLib.
*/
bool groupingIdentity() const;
/*!
* Returns true if compression is enabled for this frame.
* Returns \c true if compression is enabled for this frame.
*
* \note This flag is currently ignored internally in TagLib.
*/
bool compression() const;
/*!
* Returns true if encryption is enabled for this frame.
* Returns \c true if encryption is enabled for this frame.
*
* \note This flag is currently ignored internally in TagLib.
*/
bool encryption() const;
/*!
* Returns true if unsynchronisation is enabled for this frame.
* Returns \c true if unsynchronisation is enabled for this frame.
*/
bool unsynchronisation() const;
/*!
* Returns true if the flag for a data length indicator is set.
* Returns \c true if the flag for a data length indicator is set.
*/
bool dataLengthIndicator() const;

15
taglib/mpeg/id3v2/id3v2framefactory.h
View File

@@ -50,14 +50,15 @@ namespace TagLib {
* factory to be the default factory in ID3v2::Tag constructor you can
* implement behavior that will allow for new ID3v2::Frame subclasses (also
* provided by you) to be used.
* See \c testFrameFactory() in \e tests/test_mpeg.cpp for an example.
* See <a href="https://github.com/taglib/taglib/blob/master/tests/test_id3v2framefactory.cpp">
* tests/test_id3v2framefactory.cpp</a> for an example.
*
* This implements both <i>abstract factory</i> and <i>singleton</i> patterns
* of which more information is available on the web and in software design
* textbooks (Notably <i>Design Patterns</i>).
* textbooks (notably <i>Design Patterns</i>).
*
* \note You do not need to use this factory to create new frames to add to
* an ID3v2::Tag. You can instantiate frame subclasses directly (with new)
* an ID3v2::Tag. You can instantiate frame subclasses directly (with \c new)
* and add them to a tag using ID3v2::Tag::addFrame()
*
* \see ID3v2::Tag::addFrame()
@@ -115,7 +116,7 @@ namespace TagLib {
void setDefaultTextEncoding(String::Type encoding);
/*!
* Returns true if defaultTextEncoding() is used.
* Returns \c true if defaultTextEncoding() is used.
* The default text encoding is used when setDefaultTextEncoding() has
* been called. In this case, reimplementations of FrameFactory should
* use defaultTextEncoding() on the frames (having a text encoding field)
@@ -144,8 +145,8 @@ namespace TagLib {
* is not compatible with the current standard, this method either updates
* the frame or indicates that it should be discarded.
*
* This method with return true (with or without changes to the frame) if
* this frame should be kept or false if it should be discarded.
* This method with return \c true (with or without changes to the frame) if
* this frame should be kept or \c false if it should be discarded.
*
* See the id3v2.4.0-changes.txt document for further information.
*/
@@ -157,7 +158,7 @@ namespace TagLib {
* \param data data of the frame (might be modified)
* \param tagHeader the tag header
* \return {header, ok}: header is a created frame header or nullptr
* if the frame is invalid; ok is true if the frame is supported.
* if the frame is invalid; ok is \c true if the frame is supported.
*/
std::pair<Frame::Header *, bool> prepareFrameHeader(
ByteVector &data, const Header *tagHeader) const;

11
taglib/mpeg/id3v2/id3v2header.h
View File

@@ -42,7 +42,8 @@ namespace TagLib {
* the ID3v2 standard. The API is based on the properties of ID3v2 headers
* specified there. If any of the terms used in this documentation are
* unclear please check the specification in the linked section.
* (Structure, <a href="id3v2-structure.html#3.1">3.1</a>)
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 3.1)
*/
class TAGLIB_EXPORT Header
@@ -91,22 +92,22 @@ namespace TagLib {
unsigned int revisionNumber() const;
/*!
* Returns true if unsynchronisation has been applied to all frames.
* Returns \c true if unsynchronisation has been applied to all frames.
*/
bool unsynchronisation() const;
/*!
* Returns true if an extended header is present in the tag.
* Returns \c true if an extended header is present in the tag.
*/
bool extendedHeader() const;
/*!
* Returns true if the experimental indicator flag is set.
* Returns \c true if the experimental indicator flag is set.
*/
bool experimentalIndicator() const;
/*!
* Returns true if a footer is present in the tag.
* Returns \c true if a footer is present in the tag.
*/
bool footerPresent() const;
/*!

5
taglib/mpeg/id3v2/id3v2synchdata.h
View File

@@ -47,8 +47,9 @@ namespace TagLib {
{
/*!
* This returns the unsigned integer value of \a data where \a data is a
* ByteVector that contains a \e synchsafe integer (Structure,
* <a href="id3v2-structure.html#6.2">6.2</a>). The default \a length of
* ByteVector that contains a \e synchsafe integer
* (<a href="https://github.com/taglib/taglib/blob/master/taglib/mpeg/id3v2/id3v2.4.0-structure.txt">
* id3v2.4.0-structure.txt</a>, 6.2). The default \a length of
* 4 is used if another value is not specified.
*/
TAGLIB_EXPORT unsigned int toUInt(const ByteVector &data);

18
taglib/mpeg/id3v2/id3v2tag.h
View File

@@ -88,18 +88,18 @@ namespace TagLib {
/*!
* This is the main class in the ID3v2 implementation. It serves two
* functions. This first, as is obvious from the public API, is to provide a
* functions. The first, as is obvious from the public API, is to provide a
* container for the other ID3v2 related classes. In addition, through the
* read() and parse() protected methods, it provides the most basic level of
* parsing. In these methods the ID3v2 tag is extracted from the file and
* split into data components.
*
* ID3v2 tags have several parts, TagLib attempts to provide an interface
* for them all. header(), footer() and extendedHeader() correspond to those
* for them all. header() and extendedHeader() correspond to those
* data structures in the ID3v2 standard and the APIs for the classes that
* they return attempt to reflect this.
*
* Also ID3v2 tags are built up from a list of frames, which are in turn
* Also ID3v2 tags are built up from a list of frames, which
* have a header and a list of fields. TagLib provides two ways of accessing
* the list of frames that are in a given ID3v2 tag. The first is simply
* via the frameList() method. This is just a list of pointers to the frames.
@@ -126,7 +126,7 @@ namespace TagLib {
* with said spec (which is distributed with the TagLib sources). TagLib
* tries to do most of the work, but with a little luck, you can still
* convince it to generate invalid ID3v2 tags. The APIs for ID3v2 assume a
* working knowledge of ID3v2 structure. You're been warned.
* working knowledge of ID3v2 structure. You've been warned.
*/
class TAGLIB_EXPORT Tag : public TagLib::Tag
@@ -194,7 +194,7 @@ namespace TagLib {
ExtendedHeader *extendedHeader() const;
/*!
* Returns a reference to the frame list map. This is an FrameListMap of
* Returns a reference to the frame list map. This is a FrameListMap of
* all of the frames in the tag.
*
* This is the most convenient structure for accessing the tag's frames.
@@ -230,10 +230,10 @@ namespace TagLib {
const FrameListMap &frameListMap() const;
/*!
* Returns a reference to the frame list. This is an FrameList of all of
* Returns a reference to the frame list. This is a FrameList of all of
* the frames in the tag in the order that they were parsed.
*
* This can be useful if for example you want iterate over the tag's frames
* This can be useful if for example you want to iterate over the tag's frames
* in the order that they occur in the tag.
*
* \warning You should not modify this data structure directly, instead
@@ -264,8 +264,8 @@ namespace TagLib {
void addFrame(Frame *frame);
/*!
* Remove a frame from the tag. If \a del is true the frame's memory
* will be freed; if it is false, it must be deleted by the user.
* Remove a frame from the tag. If \a del is \c true the frame's memory
* will be freed; if it is \c false, it must be deleted by the user.
*
* \note Using this method will invalidate any pointers on the list
* returned by frameList()

36
taglib/mpeg/mpegfile.h
View File

@@ -71,7 +71,7 @@ namespace TagLib {
};
/*!
* Constructs an MPEG file from \a file. If \a readProperties is true the
* Constructs an MPEG file from \a file. If \a readProperties is \c true the
* file's audio properties will also be read.
*
* If \a propertiesStyle is not Fast, the file will be scanned
@@ -85,7 +85,7 @@ namespace TagLib {
ID3v2::FrameFactory *frameFactory = nullptr);
/*!
* Constructs an MPEG file from \a file. If \a readProperties is true the
* Constructs an MPEG file from \a file. If \a readProperties is \c true the
* file's audio properties will also be read.
*
* If this file contains an ID3v2 tag, the frames will be created using
@@ -93,6 +93,8 @@ namespace TagLib {
*
* If \a propertiesStyle is not Fast, the file will be scanned
* completely if no ID3v2 tag or MPEG sync code is found at the start.
*
* \deprecated Use the constructor above.
*/
TAGLIB_DEPRECATED
File(FileName file, ID3v2::FrameFactory *frameFactory,
@@ -100,7 +102,7 @@ namespace TagLib {
Properties::ReadStyle propertiesStyle = Properties::Average);
/*!
* Constructs an MPEG file from \a stream. If \a readProperties is true the
* Constructs an MPEG file from \a stream. If \a readProperties is \c true the
* file's audio properties will also be read.
*
* \note TagLib will *not* take ownership of the stream, the caller is
@@ -120,7 +122,7 @@ namespace TagLib {
ID3v2::FrameFactory *frameFactory = nullptr);
/*!
* Constructs an MPEG file from \a stream. If \a readProperties is true the
* Constructs an MPEG file from \a stream. If \a readProperties is \c true the
* file's audio properties will also be read.
*
* \note TagLib will *not* take ownership of the stream, the caller is
@@ -131,6 +133,8 @@ namespace TagLib {
*
* If \a propertiesStyle is not Fast, the file will be scanned
* completely if no ID3v2 tag or MPEG sync code is found at the start.
*
* \deprecated Use the constructor above.
*/
TAGLIB_DEPRECATED
File(IOStream *stream, ID3v2::FrameFactory *frameFactory,
@@ -192,7 +196,7 @@ namespace TagLib {
/*!
* Save the file. If at least one tag -- ID3v1 or ID3v2 -- exists this
* will duplicate its content into the other tag. This returns true
* will duplicate its content into the other tag. This returns \c true
* if saving was successful.
*
* If neither exists or if both tags are empty, this will strip the tags
@@ -217,7 +221,7 @@ namespace TagLib {
* \a version specifies the ID3v2 version to be used for writing tags. By
* default, the latest standard, ID3v2.4 is used.
*
* If \a duplicate is set to DuplicateTags and at least one tag -- ID3v1
* If \a duplicate is set to Duplicate and at least one tag -- ID3v1
* or ID3v2 -- exists this will duplicate its content into the other tag.
*/
bool save(int tags, StripTags strip = StripOthers,
@@ -227,8 +231,8 @@ namespace TagLib {
/*!
* Returns a pointer to the ID3v2 tag of the file.
*
* If \a create is false (the default) this may return a null pointer
* if there is no valid ID3v2 tag. If \a create is true it will create
* If \a create is \c false (the default) this may return a null pointer
* if there is no valid ID3v2 tag. If \a create is \c true it will create
* an ID3v2 tag if one does not exist and returns a valid pointer.
*
* \note This may return a valid pointer regardless of whether or not the
@@ -246,8 +250,8 @@ namespace TagLib {
/*!
* Returns a pointer to the ID3v1 tag of the file.
*
* If \a create is false (the default) this may return a null pointer
* if there is no valid ID3v1 tag. If \a create is true it will create
* If \a create is \c false (the default) this may return a null pointer
* if there is no valid ID3v1 tag. If \a create is \c true it will create
* an ID3v1 tag if one does not exist and returns a valid pointer.
*
* \note This may return a valid pointer regardless of whether or not the
@@ -265,8 +269,8 @@ namespace TagLib {
/*!
* Returns a pointer to the APE tag of the file.
*
* If \a create is false (the default) this may return a null pointer
* if there is no valid APE tag. If \a create is true it will create
* If \a create is \c false (the default) this may return a null pointer
* if there is no valid APE tag. If \a create is \c true it will create
* an APE tag if one does not exist and returns a valid pointer.
*
* \note This may return a valid pointer regardless of whether or not the
@@ -283,10 +287,10 @@ namespace TagLib {
/*!
* This will strip the tags that match the OR-ed together TagTypes from the
* file. By default it strips all tags. It returns true if the tags are
* file. By default it strips all tags. It returns \c true if the tags are
* successfully stripped.
*
* If \a freeMemory is true the ID3 and APE tags will be deleted and
* If \a freeMemory is \c true the ID3 and APE tags will be deleted and
* pointers to them will be invalidated.
*
* \note This will update the file immediately.
@@ -300,13 +304,13 @@ namespace TagLib {
/*!
* Returns the position in the file of the next MPEG frame,
* using the current position as start
* using the current position as start.
*/
offset_t nextFrameOffset(offset_t position);
/*!
* Returns the position in the file of the previous MPEG frame,
* using the current position as start
* using the current position as start.
*/
offset_t previousFrameOffset(offset_t position);

34
taglib/mpeg/mpegheader.h
View File

@@ -42,9 +42,12 @@ namespace TagLib {
/*!
* This is an implementation of MPEG Layer III headers. The API follows more
* or less the binary format of these headers. I've used
* <a href="http://www.mp3-tech.org/programmer/frame_header.html">this</a>
* document as a reference.
* or less the binary format of these headers.
*
* See these documents as a reference
* - <a href="http://www.mp3-tech.org/programmer/frame_header.html">
* MPEG Audio Layer I/II/III frame header</a>
* - <a href="https://wiki.multimedia.cx/index.php/ADTS">ADTS</a>
*/
class TAGLIB_EXPORT Header
@@ -53,7 +56,7 @@ namespace TagLib {
/*!
* Parses an MPEG header based on \a file and \a offset.
*
* \note If \a checkLength is true, this requires the next MPEG frame to
* \note If \a checkLength is \c true, this requires the next MPEG frame to
* check if the frame length is parsed and calculated correctly. So it's
* suitable for seeking for the first valid frame.
*/
@@ -70,7 +73,7 @@ namespace TagLib {
virtual ~Header();
/*!
* Returns true if the frame is at least an appropriate size and has
* Returns \c true if the frame is at least an appropriate size and has
* legal values.
*/
bool isValid() const;
@@ -100,7 +103,7 @@ namespace TagLib {
int layer() const;
/*!
* Returns true if the MPEG protection bit is enabled.
* Returns \c true if the MPEG protection bit is enabled.
*/
bool protectionEnabled() const;
@@ -115,7 +118,7 @@ namespace TagLib {
int sampleRate() const;
/*!
* Returns true if the frame is padded.
* Returns \c true if the frame is padded.
*/
bool isPadded() const;
@@ -143,13 +146,24 @@ namespace TagLib {
* MPEG-4 channel configuration.
*/
enum ChannelConfiguration {
//! Defined in audio object type (AOT) specific configuration
Custom = 0,
//! 1 channel: front-center
FrontCenter = 1,
//! 2 channels: front-left, front-right
FrontLeftRight = 2,
//! 3 channels: front-center, front-left, front-right
FrontCenterLeftRight = 3,
//! 4 channels: front-center, front-left, front-right, back-center
FrontCenterLeftRightBackCenter = 4,
//! 5 channels: front-center, front-left, front-right, back-left,
//! back-right
FrontCenterLeftRightBackLeftRight = 5,
//! 6 channels: front-center, front-left, front-right, back-left,
//! back-right, LFE-channel
FrontCenterLeftRightBackLeftRightLFE = 6,
//! 8 channels: front-center, front-left, front-right, side-left,
//! side-right, back-left, back-right, LFE-channel
FrontCenterLeftRightSideLeftRightBackLeftRightLFE = 7
};
@@ -159,18 +173,18 @@ namespace TagLib {
ChannelConfiguration channelConfiguration() const;
/*!
* Returns true if this is the header of an Audio Data Transport Stream
* Returns \c true if this is the header of an Audio Data Transport Stream
* (ADTS), usually AAC.
*/
bool isADTS() const;
/*!
* Returns true if the copyrighted bit is set.
* Returns \c true if the copyrighted bit is set.
*/
bool isCopyrighted() const;
/*!
* Returns true if the "original" bit is set.
* Returns \c true if the "original" bit is set.
*/
bool isOriginal() const;

8
taglib/mpeg/mpegproperties.h
View File

@@ -100,7 +100,7 @@ namespace TagLib {
int layer() const;
/*!
* Returns true if the MPEG protection bit is enabled.
* Returns \c true if the MPEG protection bit is enabled.
*/
bool protectionEnabled() const;
@@ -115,17 +115,17 @@ namespace TagLib {
Header::ChannelConfiguration channelConfiguration() const;
/*!
* Returns true for an Audio Data Transport Stream (ADTS), usually AAC.
* Returns \c true for an Audio Data Transport Stream (ADTS), usually AAC.
*/
bool isADTS() const;
/*!
* Returns true if the copyrighted bit is set.
* Returns \c true if the copyrighted bit is set.
*/
bool isCopyrighted() const;
/*!
* Returns true if the "original" bit is set.
* Returns \c true if the "original" bit is set.
*/
bool isOriginal() const;

6
taglib/mpeg/xingheader.h
View File

@@ -45,8 +45,8 @@ namespace TagLib {
* to make it easy to compute the length and quality of a VBR stream. Our
* implementation is only concerned with the total size of the stream (so
* that we can calculate the total playing time and the average bitrate).
* It uses <a href="http://home.pcisys.net/~melanson/codecs/mp3extensions.txt">
* this text</a> and the XMMS sources as references.
* It uses <a href="https://multimedia.cx/mp3extensions.txt">
* mp3extensions.txt</a> and the XMMS sources as references.
*/
class TAGLIB_EXPORT XingHeader
@@ -88,7 +88,7 @@ namespace TagLib {
XingHeader &operator=(const XingHeader &) = delete;
/*!
* Returns true if the data was parsed properly and if there is a valid
* Returns \c true if the data was parsed properly and if there is a valid
* Xing/VBRI header present.
*/
bool isValid() const;