Tag Parser 12.1.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
TagParser::Mp4Track Class Referencefinal

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

#include <mp4track.h>

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

Public Member Functions

 Mp4Track (Mp4Atom &trakAtom)
 Constructs a new track for the specified trakAtom.
 
 ~Mp4Track () override
 Destroys the track.
 
TrackType type () const override
 Returns the type of the track if known; otherwise returns TrackType::Unspecified.
 
Mp4AtomtrakAtom ()
 Returns the trak atom for the current instance.
 
const std::vector< std::uint32_t > & sampleSizes () const
 Returns the sample size table for the track.
 
unsigned int chunkOffsetSize () const
 Returns the size of a single chunk offset denotation within the stco atom.
 
std::uint32_t chunkCount () const
 Returns the number of chunks denoted by the stco atom.
 
std::uint32_t sampleToChunkEntryCount () const
 Returns the number of "sample to chunk" entries within the stsc atom.
 
const Mpeg4ElementaryStreamInfompeg4ElementaryStreamInfo () const
 Returns information about the MPEG-4 elementary stream.
 
const AvcConfigurationavcConfiguration () const
 Returns the AVC configuration.
 
const Av1Configurationav1Configuration () const
 Returns the AV1 configuration.
 
std::vector< std::uint64_t > readChunkOffsets (bool parseFragments, Diagnostics &diag)
 Reads the chunk offsets from the stco atom and fragments if parseFragments is true.
 
std::vector< std::tuple< std::uint32_t, std::uint32_t, std::uint32_t > > readSampleToChunkTable (Diagnostics &diag)
 Reads the sample to chunk table.
 
std::vector< std::uint64_t > readChunkSizes (TagParser::Diagnostics &diag)
 Reads the chunk sizes from the stsz (sample sizes) and stsc (samples per chunk) atom.
 
void bufferTrackAtoms (Diagnostics &diag)
 Buffers all atoms required by the makeTrack() method.
 
std::uint64_t requiredSize (Diagnostics &diag) const
 Returns the number of bytes written when calling makeTrack().
 
void makeTrack (Diagnostics &diag)
 Makes the track entry ("trak"-atom) for the track.
 
void makeTrackHeader (Diagnostics &diag)
 Makes the track header (tkhd atom) for the track.
 
void makeMedia (Diagnostics &diag)
 Makes the media information (mdia atom) for the track.
 
void makeMediaInfo (Diagnostics &diag)
 Makes a media information (minf atom) for the track.
 
void makeSampleTable (Diagnostics &diag)
 Makes the sample table (stbl atom) for the track.
 
void updateChunkOffsets (const std::vector< std::int64_t > &oldMdatOffsets, const std::vector< std::int64_t > &newMdatOffsets)
 Updates the chunk offsets of the track.
 
void updateChunkOffsets (const std::vector< std::uint64_t > &chunkOffsets)
 Updates the chunk offsets of the track.
 
void updateChunkOffset (std::uint32_t chunkIndex, std::uint64_t offset)
 Updates a particular chunk offset.
 
- Public Member Functions inherited from TagParser::AbstractTrack
virtual ~AbstractTrack ()
 Destroys the track.
 
std::istream & inputStream ()
 Returns the associated input stream.
 
void setInputStream (std::istream &stream)
 Assigns another input stream.
 
std::ostream & outputStream ()
 Returns the associated output stream.
 
void setOutputStream (std::ostream &stream)
 Assigns another output stream.
 
CppUtilities::BinaryReader & reader ()
 Returns a binary reader for the associated stream.
 
CppUtilities::BinaryWriter & writer ()
 Returns a binary writer for the associated stream.
 
std::uint64_t startOffset () const
 Returns the start offset of the track in the associated stream.
 
TrackFlags flags () const
 Returns flags (various boolean properties) of this track.
 
MediaFormat format () const
 Returns the format of the track if known; otherwise returns MediaFormat::Unknown.
 
double version () const
 Returns the version/level of the track if known; otherwise returns 0.
 
std::string_view formatName () const
 Returns the format of the track as C-style string if known; otherwise returns the format abbreviation or an empty string.
 
std::string_view formatAbbreviation () const
 Returns the a more or less common abbreviation for the format of the track if known; otherwise returns an empty string.
 
const std::string & formatId () const
 Returns the format/codec ID.
 
MediaType mediaType () const
 Returns the media type if known; otherwise returns MediaType::Other.
 
std::string_view mediaTypeName () const
 Returns the string representation of the media type of the track.
 
std::uint64_t size () const
 Returns the size in bytes if known; otherwise returns 0.
 
void setSize (std::uint64_t size)
 Sets the size in bytes.
 
std::uint32_t trackNumber () const
 Returns the track number if known; otherwise returns 0.
 
void setTrackNumber (std::uint32_t trackNumber)
 Sets the track number.
 
std::uint64_t id () const
 Returns the track ID if known; otherwise returns 0.
 
void setId (std::uint64_t id)
 Sets the track ID.
 
const std::string name () const
 Returns the track name if known; otherwise returns an empty string.
 
void setName (std::string_view name)
 Sets the name.
 
const CppUtilities::TimeSpan & duration () const
 Returns the duration if known; otherwise returns a TimeSpan of zero ticks.
 
double bitrate () const
 Returns the average bitrate in kbit/s if known; otherwise returns zero.
 
double maxBitrate () const
 Returns the maximum bitrate in kbit/s if known; otherwise returns zero.
 
const CppUtilities::DateTime & creationTime () const
 Returns the creation time if known; otherwise returns a DateTime of zero ticks.
 
const CppUtilities::DateTime & modificationTime () const
 Returns the time of the last modification if known; otherwise returns a DateTime of zero ticks.
 
const Localelocale () const
 Returns the locale of the track if known; otherwise returns an empty locale.
 
void setLocale (const Locale &locale)
 Sets the locale of the track.
 
std::uint32_t samplingFrequency () const
 Returns the number of samples per second if known; otherwise returns 0.
 
std::uint32_t extensionSamplingFrequency () const
 Returns the number of samples per second if known; otherwise returns 0.
 
std::uint16_t bitsPerSample () const
 Returns the number of bits per sample; otherwise returns 0.
 
std::uint16_t channelCount () const
 Returns the number of channels if known; otherwise returns 0.
 
std::uint8_t channelConfig () const
 Returns the channel configuration.
 
std::string_view channelConfigString () const
 Returns a string with the channel configuration if available; otherwise returns nullptr.
 
std::uint8_t extensionChannelConfig () const
 Returns the extension channel configuration if available; otherwise returns nullptr.
 
std::string_view extensionChannelConfigString () const
 Returns a string with the extension channel configuration if available; otherwise returns nullptr.
 
std::uint64_t sampleCount () const
 Returns the number of samples/frames if known; otherwise returns 0.
 
int quality () const
 Returns the quality if known; otherwise returns 0.
 
const SizepixelSize () const
 Returns the size of the encoded video frames if known; otherwise returns a zero size.
 
const SizedisplaySize () const
 Returns the size of the video frames to display if known; otherwise returns a zero size.
 
const Sizeresolution () const
 Returns the resolution if known; otherwise returns a zero size.
 
const std::string & compressorName () const
 Returns the compressor name if known; otherwise returns an empty string.
 
void setCompressorName (std::string_view compressorName)
 Returns the compressor name if known; otherwise returns an empty string.
 
std::uint16_t depth () const
 Returns the bit depth if known; otherwise returns 0.
 
std::uint32_t fps () const
 Returns the number of frames per second if known; otherwise returns 0.
 
std::string_view chromaFormat () const
 Returns the chroma subsampling format if known; otherwise returns nullptr.
 
const AspectRatiopixelAspectRatio () const
 Returns the pixel aspect ratio (PAR).
 
bool isInterlaced () const
 Returns true if the video is interlaced; otherwise returns false.
 
std::uint32_t timeScale () const
 Returns the time scale if known; otherwise returns 0.
 
bool isEnabled () const
 Returns true if the track is marked as enabled; otherwise returns false.
 
void setEnabled (bool enabled)
 Sets whether the track is enabled.
 
bool isDefault () const
 Returns true if the track is marked as default; otherwise returns false.
 
void setDefault (bool isDefault)
 Sets whether the track is a default track.
 
bool isForced () const
 Returns true if the track is marked as forced; otherwise returns false.
 
void setForced (bool forced)
 Sets whether the track is forced.
 
bool hasLacing () const
 Returns true if the track has lacing; otherwise returns false.
 
bool isEncrypted () const
 Returns true if the track is marked as encrypted; otherwise returns false.
 
std::uint32_t colorSpace () const
 Returns the color space if known; otherwise returns 0.
 
const Margincropping () const
 Returns the cropping if known; otherwise returns zero margins.
 
std::string label () const
 Returns a label for the track.
 
std::string description () const
 Returns a description about the track.
 
std::string shortDescription () const
 Returns a short description about the track.
 
void parseHeader (Diagnostics &diag, AbortableProgressFeedback &progress)
 Parses technical information about the track from the header.
 
bool isHeaderValid () const
 Returns an indication whether the track header is valid.
 

Static Public Member Functions

static std::unique_ptr< Mpeg4ElementaryStreamInfoparseMpeg4ElementaryStreamInfo (CppUtilities::BinaryReader &reader, Mp4Atom *esDescAtom, Diagnostics &diag)
 Reads the MPEG-4 elementary stream descriptor for the track.
 
static std::unique_ptr< Mpeg4AudioSpecificConfigparseAudioSpecificConfig (std::istream &stream, std::uint64_t startOffset, std::uint64_t size, Diagnostics &diag)
 Parses the audio specific configuration for the track.
 
static std::unique_ptr< Mpeg4VideoSpecificConfigparseVideoSpecificConfig (CppUtilities::BinaryReader &reader, std::uint64_t startOffset, std::uint64_t size, Diagnostics &diag)
 Parses the video specific configuration for the track.
 
static void addInfo (const AvcConfiguration &avcConfig, AbstractTrack &track)
 Adds the information from the specified avcConfig to the specified track.
 
static void addInfo (const Av1Configuration &av1Config, AbstractTrack &track)
 Adds the information from the specified av1Config to the specified track.
 

Protected Member Functions

void internalParseHeader (Diagnostics &diag, AbortableProgressFeedback &progress) override
 This method is internally called to parse header information.
 
- Protected Member Functions inherited from TagParser::AbstractTrack
 AbstractTrack (std::istream &inputStream, std::ostream &outputStream, std::uint64_t startOffset)
 Constructs a new track.
 
 AbstractTrack (std::iostream &stream, std::uint64_t startOffset)
 Constructs a new track.
 

Additional Inherited Members

- Protected Attributes inherited from TagParser::AbstractTrack
std::istream * m_istream
 
std::ostream * m_ostream
 
CppUtilities::BinaryReader m_reader
 
CppUtilities::BinaryWriter m_writer
 
std::uint64_t m_startOffset
 
TrackFlags m_flags
 
MediaFormat m_format
 
std::string m_formatId
 
std::string m_formatName
 
MediaType m_mediaType
 
double m_version
 
std::uint64_t m_size
 
std::uint32_t m_trackNumber
 
std::uint64_t m_id
 
std::string m_name
 
CppUtilities::TimeSpan m_duration
 
double m_bitrate
 
double m_maxBitrate
 
CppUtilities::DateTime m_creationTime
 
CppUtilities::DateTime m_modificationTime
 
Locale m_locale
 
std::uint32_t m_samplingFrequency
 
std::uint32_t m_extensionSamplingFrequency
 
std::uint16_t m_bitsPerSample
 
std::uint32_t m_bytesPerSecond
 
std::uint16_t m_channelCount
 
std::uint8_t m_channelConfig
 
std::uint8_t m_extensionChannelConfig
 
std::uint16_t m_chunkSize
 
std::uint64_t m_sampleCount
 
int m_quality
 
Size m_pixelSize
 
Size m_displaySize
 
Size m_resolution
 
std::string m_compressorName
 
std::uint16_t m_depth
 
std::uint32_t m_fps
 
std::string_view m_chromaFormat
 
AspectRatio m_pixelAspectRatio
 
std::uint32_t m_timeScale
 
std::uint32_t m_colorSpace
 
Margin m_cropping
 
FieldOrder m_fieldOrder
 
StereoMode m_stereoMode
 
AlphaMode m_alphaMode
 
DisplayUnit m_displayUnit
 
AspectRatioType m_aspectRatioType
 
std::unique_ptr< AbstractTrackPrivatem_p
 

Detailed Description

Implementation of TagParser::AbstractTrack for the MP4 container.

Definition at line 119 of file mp4track.h.

Constructor & Destructor Documentation

◆ Mp4Track()

TagParser::Mp4Track::Mp4Track ( Mp4Atom trakAtom)

Constructs a new track for the specified trakAtom.

"trak"-atoms are stored in the top-level atom "move". Each "trak"-atom holds header information for one track in the MP4 file.

Definition at line 150 of file mp4track.cpp.

◆ ~Mp4Track()

TagParser::Mp4Track::~Mp4Track ( )
override

Destroys the track.

Definition at line 180 of file mp4track.cpp.

Member Function Documentation

◆ addInfo() [1/2]

void TagParser::Mp4Track::addInfo ( const Av1Configuration av1Config,
AbstractTrack track 
)
static

Adds the information from the specified av1Config to the specified track.

Todo:
Provide implementation

Definition at line 1106 of file mp4track.cpp.

◆ addInfo() [2/2]

void TagParser::Mp4Track::addInfo ( const AvcConfiguration avcConfig,
AbstractTrack track 
)
static

Adds the information from the specified avcConfig to the specified track.

Definition at line 1072 of file mp4track.cpp.

◆ av1Configuration()

const Av1Configuration * TagParser::Mp4Track::av1Configuration ( ) const
inline

Returns the AV1 configuration.

Remarks
  • The track must be parsed before this information becomes available.
  • The track keeps ownership over the returned object.

Definition at line 280 of file mp4track.h.

◆ avcConfiguration()

const AvcConfiguration * TagParser::Mp4Track::avcConfiguration ( ) const
inline

Returns the AVC configuration.

Remarks
  • The track must be parsed before this information becomes available.
  • The track keeps ownership over the returned object.

Definition at line 269 of file mp4track.h.

◆ bufferTrackAtoms()

void TagParser::Mp4Track::bufferTrackAtoms ( Diagnostics diag)

Buffers all atoms required by the makeTrack() method.

This allows to invoke makeTrack() also when the input stream is going to be modified (eg. to apply changed tags without rewriting the file).

Definition at line 1119 of file mp4track.cpp.

◆ chunkCount()

std::uint32_t TagParser::Mp4Track::chunkCount ( ) const
inline

Returns the number of chunks denoted by the stco atom.

Definition at line 238 of file mp4track.h.

◆ chunkOffsetSize()

unsigned int TagParser::Mp4Track::chunkOffsetSize ( ) const
inline

Returns the size of a single chunk offset denotation within the stco atom.

Valid values are 4 and 8 bytes.

Definition at line 230 of file mp4track.h.

◆ internalParseHeader()

void TagParser::Mp4Track::internalParseHeader ( Diagnostics diag,
AbortableProgressFeedback progress 
)
overrideprotectedvirtual

This method is internally called to parse header information.

It needs to be implemented when subclassing this class.

Exceptions
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsTagParser::Failure or a derived exception when a parsing error occurs.

Implements TagParser::AbstractTrack.

Definition at line 1526 of file mp4track.cpp.

◆ makeMedia()

void TagParser::Mp4Track::makeMedia ( Diagnostics diag)

Makes the media information (mdia atom) for the track.

The data is written to the assigned output stream at the current position.

Definition at line 1311 of file mp4track.cpp.

◆ makeMediaInfo()

void TagParser::Mp4Track::makeMediaInfo ( Diagnostics diag)

Makes a media information (minf atom) for the track.

The data is written to the assigned output stream at the current position.

Definition at line 1411 of file mp4track.cpp.

◆ makeSampleTable()

void TagParser::Mp4Track::makeSampleTable ( Diagnostics diag)

Makes the sample table (stbl atom) for the track.

The data is written to the assigned output stream at the current position.

Remarks
Not fully implemented yet.

Definition at line 1466 of file mp4track.cpp.

◆ makeTrack()

void TagParser::Mp4Track::makeTrack ( Diagnostics diag)

Makes the track entry ("trak"-atom) for the track.

The data is written to the assigned output stream at the current position. Note that this method uses the assigned input stream to copy some parts from the source file. Hence the input stream must still be valid when calling this method. To avoid this limitation call bufferTrackAtoms() before invalidating the input stream.

Definition at line 1194 of file mp4track.cpp.

◆ makeTrackHeader()

void TagParser::Mp4Track::makeTrackHeader ( Diagnostics diag)

Makes the track header (tkhd atom) for the track.

The data is written to the assigned output stream at the current position.

Definition at line 1223 of file mp4track.cpp.

◆ mpeg4ElementaryStreamInfo()

const Mpeg4ElementaryStreamInfo * TagParser::Mp4Track::mpeg4ElementaryStreamInfo ( ) const
inline

Returns information about the MPEG-4 elementary stream.

Remarks
  • The track must be parsed before this information becomes available.
  • The information is only available, if the track has an MPEG-4 elementary stream descriptor atom.
  • The track keeps ownership over the returned object.

Definition at line 258 of file mp4track.h.

◆ parseAudioSpecificConfig()

unique_ptr< Mpeg4AudioSpecificConfig > TagParser::Mp4Track::parseAudioSpecificConfig ( std::istream &  stream,
std::uint64_t  startOffset,
std::uint64_t  size,
Diagnostics diag 
)
static

Parses the audio specific configuration for the track.

See also
mpeg4ElementaryStreamInfo()

Definition at line 705 of file mp4track.cpp.

◆ parseMpeg4ElementaryStreamInfo()

std::unique_ptr< Mpeg4ElementaryStreamInfo > TagParser::Mp4Track::parseMpeg4ElementaryStreamInfo ( CppUtilities::BinaryReader &  reader,
Mp4Atom esDescAtom,
Diagnostics diag 
)
static

Reads the MPEG-4 elementary stream descriptor for the track.

See also
mpeg4ElementaryStreamInfo()

Definition at line 613 of file mp4track.cpp.

◆ parseVideoSpecificConfig()

std::unique_ptr< Mpeg4VideoSpecificConfig > TagParser::Mp4Track::parseVideoSpecificConfig ( CppUtilities::BinaryReader &  reader,
std::uint64_t  startOffset,
std::uint64_t  size,
Diagnostics diag 
)
static

Parses the video specific configuration for the track.

See also
mpeg4ElementaryStreamInfo()

Definition at line 870 of file mp4track.cpp.

◆ readChunkOffsets()

std::vector< std::uint64_t > TagParser::Mp4Track::readChunkOffsets ( bool  parseFragments,
Diagnostics diag 
)

Reads the chunk offsets from the stco atom and fragments if parseFragments is true.

Returns
Returns the chunk offset table for the track.
Exceptions
ThrowsInvalidDataException when
  • there is no stream assigned.
  • the header has been considered as invalid when parsing the header information.
  • the determined chunk offset size is invalid.
Throwsstd::ios_base::failure when an IO error occurs.
See also
readChunkSizes();

Definition at line 199 of file mp4track.cpp.

◆ readChunkSizes()

vector< std::uint64_t > TagParser::Mp4Track::readChunkSizes ( TagParser::Diagnostics diag)

Reads the chunk sizes from the stsz (sample sizes) and stsc (samples per chunk) atom.

Returns
Returns the chunk sizes for the track.
Exceptions
ThrowsInvalidDataException when
  • there is no stream assigned.
  • the header has been considered as invalid when parsing the header information.
  • the determined chunk offset size is invalid.
Throwsstd::ios_base::failure when an IO error occurs.
See also
readChunkOffsets();

Definition at line 563 of file mp4track.cpp.

◆ readSampleToChunkTable()

vector< tuple< std::uint32_t, std::uint32_t, std::uint32_t > > TagParser::Mp4Track::readSampleToChunkTable ( Diagnostics diag)

Reads the sample to chunk table.

Returns
Returns a vector with the table entries wrapped using the tuple container. The first value is an integer that gives the first chunk that share the same samples count and sample description index. The second value is sample count and the third value is the sample description index.
Remarks
The table is not validated.

Definition at line 514 of file mp4track.cpp.

◆ requiredSize()

std::uint64_t TagParser::Mp4Track::requiredSize ( Diagnostics diag) const

Returns the number of bytes written when calling makeTrack().

Definition at line 1142 of file mp4track.cpp.

◆ sampleSizes()

const std::vector< std::uint32_t > & TagParser::Mp4Track::sampleSizes ( ) const
inline

Returns the sample size table for the track.

Remarks
If the table contains only one size this is the constant sample size.
The table is empty if the track denotes 64-bit sample sizes.
See also
sampleSizes64()

Definition at line 220 of file mp4track.h.

◆ sampleToChunkEntryCount()

std::uint32_t TagParser::Mp4Track::sampleToChunkEntryCount ( ) const
inline

Returns the number of "sample to chunk" entries within the stsc atom.

Definition at line 246 of file mp4track.h.

◆ trakAtom()

Mp4Atom & TagParser::Mp4Track::trakAtom ( )
inline

Returns the trak atom for the current instance.

Definition at line 208 of file mp4track.h.

◆ type()

TrackType TagParser::Mp4Track::type ( ) const
overridevirtual

Returns the type of the track if known; otherwise returns TrackType::Unspecified.

Reimplemented from TagParser::AbstractTrack.

Definition at line 184 of file mp4track.cpp.

◆ updateChunkOffset()

void TagParser::Mp4Track::updateChunkOffset ( std::uint32_t  chunkIndex,
std::uint64_t  offset 
)

Updates a particular chunk offset.

Parameters
chunkIndexSpecifies the index of the chunk offset to be updated.
offsetSpecifies the new chunk offset. If the "stco" atom is used the value must fit into a 32-bit unsigned int.
Remarks
This method seems to be obsolete.
Exceptions
ThrowsInvalidDataException when
  • there is no stream assigned.
  • the header has been considered as invalid when parsing the header information.
  • chunkIndex is not less than chunkCount().
  • there is no atom holding these offsets.
  • the ID of the atom holding these offsets is not "stco" or "co64".

Definition at line 1051 of file mp4track.cpp.

◆ updateChunkOffsets() [1/2]

void TagParser::Mp4Track::updateChunkOffsets ( const std::vector< std::int64_t > &  oldMdatOffsets,
const std::vector< std::int64_t > &  newMdatOffsets 
)

Updates the chunk offsets of the track.

This is necessary when the "mdat"-atom (which contains the actual chunk data) is moved.

Parameters
oldMdatOffsetsSpecifies a vector holding the old offsets of the "mdat"-atoms.
newMdatOffsetsSpecifies a vector holding the new offsets of the "mdat"-atoms.
Exceptions
ThrowsInvalidDataException when
  • there is no stream assigned.
  • the header has been considered as invalid when parsing the header information.
  • oldMdatOffsets holds not the same number of offsets as newMdatOffsets.
  • there is no atom holding these offsets.
  • the ID of the atom holding these offsets is not "stco" or "co64"
Throwsstd::ios_base::failure when an IO error occurs.
Remarks
This method needs to be fixed.

Definition at line 946 of file mp4track.cpp.

◆ updateChunkOffsets() [2/2]

void TagParser::Mp4Track::updateChunkOffsets ( const std::vector< std::uint64_t > &  chunkOffsets)

Updates the chunk offsets of the track.

This is necessary when the "mdat"-atom (which contains the actual chunk data) is moved.

Parameters
chunkOffsetsSpecifies the new chunk offset table. If the "stco" atom is used the values must fit into an 32-bit unsigned int.
Exceptions
ThrowsInvalidDataException when
  • there is no stream assigned.
  • the header has been considered as invalid when parsing the header information.
  • the size of chunkOffsets does not match chunkCount().
  • there is no atom holding these offsets.
  • the ID of the atom holding these offsets is not "stco" or "co64".

Definition at line 1013 of file mp4track.cpp.


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