MP4Parser Class Reference

MP4Parser is a class that parses MP4 container files and extracts boxes (atoms). It provides a callback mechanism to process each box as it is parsed. You can define specific callbacks for individual box types or use a generic callback for the undefined boxes: By default it just prints the box information to Serial. If a container box contains data, it will be processed recursively and if it contains data itself, it might be reported in a second callback call. More...

#include <MP4Parser.h>

Classes
struct	Box
	Represents an individual box in the MP4 file. More...
struct	CallbackEntry
	Structure for type-specific callbacks. More...
struct	ContainerInfo
	Structure for container box information. More...

Public Types
using	BoxCallback = std::function< void(Box &, void *ref)>

Public Member Functions
void	addContainer (const char *name, int start=0)
	Adds a box name that will be interpreted as a container.
int	availableForWrite ()
	Returns the available space for writing.
bool	begin (uint64_t startFileOffset=0)
	Initializes the parser.
bool	findBox (const char *name, const uint8_t *data, size_t len, Box &result)
	find box in box
int	parseString (const uint8_t *str, int len, int fileOffset=0, int level=0)
	Trigger separate parsing (and callbacks) on the indicated string.
bool	resize (size_t size)
	Defines a specific buffer size.
void	setCallback (BoxCallback cb)
	Defines the generic callback for all boxes.
void	setCallback (const char *type, BoxCallback cb, bool callGeneric=true)
	Defines a specific callback for a box type.
void	setReference (void *ref)
	Defines an optional reference. By default it is the parser itself.
void	setRequireMoovBeforeMdat (bool flag)
	Defines whether an mdat box found before any moov box is treated as an error (LOGE, the default) or downgraded to a warning (LOGW). Set to false to opt out of the moov-before-mdat requirement, e.g. for files from encoders that are known to violate it but still work.
size_t	write (const char *data, size_t len)
	Provide the data to the parser (in chunks if needed).
size_t	write (const uint8_t *data, size_t len)
	Provide the data to the parser (in chunks if needed).

Static Public Member Functions
static void	defaultCallback (const Box &box, void *ref)
	Default callback that prints box information to Serial.

Protected Member Functions
size_t	checkParseOffset ()
	Checks and adjusts the parse offset for valid box types.
bool	continueIncrementalBox ()
	Continue filling an incremental box. Returns false if not enough data.
uint64_t	currentFileOffset ()
	Returns the current file offset (absolute position in file).
void	finalizeParse ()
	Finalizes parsing, updating file offset and clearing buffer.
int	getContainerDataLength (const char *type)
	Gets the start offset for a subcontainer.
void	handleCompleteBox (const char *type, const uint8_t *p, size_t headerSize, size_t payload_size, int level)
	Handles a complete (non-incremental) box.
void	handleContainerBox (const char *type, uint64_t boxSize, size_t headerSize, int level)
	Handles a container box (box with children).
bool	isContainerBox (const char *type)
	Checks if a box type is a container box.
bool	isValidType (const char *type, int offset=0) const
	Checks if a type string is a valid 4-character box type.
void	parse ()
	Main parsing loop. Handles incremental and complete boxes.
void	popLevels ()
	Pops levels from the stack if we've passed their bounds.
void	processCallback (Box &box)
	Processes the callback for a box. Calls the type-specific callback if present, and the generic callback if allowed.
void	startIncrementalBox (const char *type, const uint8_t *p, size_t headerSize, size_t payload_size, int level, size_t bufferSize)
	Starts parsing a box incrementally.
bool	tryStartNewBox (size_t bufferSize)
	Try to start parsing a new box. Returns false if not enough data.

Static Protected Member Functions
static uint32_t	readU32 (const uint8_t *p)
	Reads a 32-bit big-endian unsigned integer from a buffer.
static uint64_t	readU64 (const uint8_t *p)
	Reads a 64-bit big-endian unsigned integer from a buffer.

Protected Attributes
Box	box
	Current box being processed.
size_t	box_bytes_expected = 0
	Total expected bytes for the current box.
size_t	box_bytes_received = 0
	Bytes received so far for the current box.
bool	box_in_progress
	True if currently parsing a box incrementally.
int	box_level = 0
	Current box level (nesting)
int	box_seq = 0
char	box_type [5] = {0}
	Current box type.
SingleBuffer< uint8_t >	buffer
	Buffer for incoming data.
BoxCallback	callback = defaultCallback
	Generic callback for all boxes.
Vector< CallbackEntry >	callbacks
	List of type-specific callbacks.
Vector< ContainerInfo >	containers
	List of container box info.
uint64_t	fileOffset = 0
	Current file offset.
size_t	incremental_offset = 0
bool	is_error = false
	True if an error occurred.
Vector< size_t >	levelStack
	Stack for container box levels.
bool	moov_found = false
	True once a top-level moov box has been seen.
size_t	parseOffset = 0
	Current parse offset in buffer.
void *	ref = this
	Reference pointer for callbacks.
bool	require_moov_before_mdat = true
	false: warn instead of error

Detailed Description

MP4Parser is a class that parses MP4 container files and extracts boxes (atoms). It provides a callback mechanism to process each box as it is parsed. You can define specific callbacks for individual box types or use a generic callback for the undefined boxes: By default it just prints the box information to Serial. If a container box contains data, it will be processed recursively and if it contains data itself, it might be reported in a second callback call.

Note

This parser expects the mdat box to be the last box in the file, and the moov box (which carries the sample/format info needed to decode mdat) to come before it. This layout can be achieved with the following ffmpeg commands:

• ffmpeg -i ../sine.wav -c:a alac -movflags +faststart alac.m4a
• ffmpeg -i ../sine.wav -c:a aac -movflags +faststart aac.m4a

If an mdat box is encountered at the top level before any moov box has been parsed, an error is logged (via LOGE) since the file will not be decodable in that state. Call setRequireMoovBeforeMdat(false) to opt out of this requirement, in which case only a warning (LOGW) is logged and parsing continues.

The parser also supports the ISO/IEC 14496-12 special box-size values that a plain 32-bit size field can't express: a size of 1 indicates a 64-bit "largesize" follows the type field, and a size of 0 means the box extends to the end of the file/stream - both are common for an mdat box written by an encoder that streams the payload without seeking back to patch in the final size. A size-0 mdat is treated as unbounded: it is read incrementally until the input stream ends, since its true length is not known upfront.

Author

Phil Schatzmann

Member Typedef Documentation

BoxCallback

using BoxCallback = std::function<void(Box&, void* ref)>

Member Function Documentation

addContainer()

void addContainer ( const char *  name, int  start = 0  )

inline

Adds a box name that will be interpreted as a container.

Parameters

name	Name of the container box.
start	Offset of child boxes (default 0).

availableForWrite()

int availableForWrite ( )

inline

Returns the available space for writing.

Returns

Number of bytes available for writing.

begin()

bool begin ( uint64_t  startFileOffset = 0 )

inline

Initializes the parser.

Parameters

startFileOffset

Absolute file offset the next written byte corresponds to - 0 for a normal parse from the start of the file, or an arbitrary offset to resume parsing elsewhere (e.g. DemuxerMP4's moov-at-end quick start, which begin()s twice for two disjoint byte ranges) so Box::file_offset stays correct.

Returns

true on success.

checkParseOffset()

size_t checkParseOffset ( )

inlineprotected

Checks and adjusts the parse offset for valid box types.

Returns

Adjusted parse offset.

continueIncrementalBox()

bool continueIncrementalBox ( )

inlineprotected

Continue filling an incremental box. Returns false if not enough data.

Returns

False if more data was processed, true otherwise.

currentFileOffset()

uint64_t currentFileOffset ( )

inlineprotected

Returns the current file offset (absolute position in file).

Returns

Current file offset.

defaultCallback()

static void defaultCallback ( const Box &  box, void *  ref  )

inlinestatic

Default callback that prints box information to Serial.

Parameters

box	The box being processed.
ref	Optional reference pointer.

finalizeParse()

void finalizeParse ( )

inlineprotected

Finalizes parsing, updating file offset and clearing buffer.

findBox()

bool findBox ( const char *  name, const uint8_t *  data, size_t  len, Box &  result  )

inline

find box in box

getContainerDataLength()

int getContainerDataLength ( const char *  type )

inlineprotected

Gets the start offset for a subcontainer.

Parameters

type	Box type string.

Returns

Offset of the subcontainer.

handleCompleteBox()

void handleCompleteBox ( const char *  type, const uint8_t *  p, size_t  headerSize, size_t  payload_size, int  level  )

inlineprotected

Handles a complete (non-incremental) box.

Parameters

type	Box type string.
p	Pointer to the start of the box in the buffer.
headerSize	Size of the box header.
payload_size	Size of the box payload.
level	Nesting level of the box.

handleContainerBox()

void handleContainerBox ( const char *  type, uint64_t  boxSize, size_t  headerSize, int  level  )

inlineprotected

Handles a container box (box with children).

Parameters

type	Box type string.
boxSize	Size of the box.
level	Nesting level of the box.

isContainerBox()

bool isContainerBox ( const char *  type )

inlineprotected

Checks if a box type is a container box.

Parameters

type	Box type string.

Returns

true if container box, false otherwise.

isValidType()

bool isValidType ( const char *  type, int  offset = 0  ) const

inlineprotected

Checks if a type string is a valid 4-character box type.

Parameters

type	Pointer to type string.
offset	Offset in the string.

Returns

true if valid, false otherwise.

parse()

void parse ( )

inlineprotected

Main parsing loop. Handles incremental and complete boxes.

parseString()

int parseString ( const uint8_t *  str, int  len, int  fileOffset = 0, int  level = 0  )

inline

Trigger separate parsing (and callbacks) on the indicated string.

Parameters

str	Pointer to the string data.
len	Length of the string data.

Returns

Number of bytes parsed.

popLevels()

void popLevels ( )

inlineprotected

Pops levels from the stack if we've passed their bounds.

processCallback()

void processCallback ( Box &  box )

inlineprotected

Processes the callback for a box. Calls the type-specific callback if present, and the generic callback if allowed.

Parameters

box	The box being processed.

call generic callback if allowed

readU32()

static uint32_t readU32 ( const uint8_t *  p )

inlinestaticprotected

Reads a 32-bit big-endian unsigned integer from a buffer.

Parameters

p	Pointer to buffer.

Returns

32-bit unsigned integer.

readU64()

static uint64_t readU64 ( const uint8_t *  p )

inlinestaticprotected

Reads a 64-bit big-endian unsigned integer from a buffer.

Parameters

p	Pointer to buffer.

Returns

64-bit unsigned integer.

resize()

bool resize ( size_t  size )

inline

Defines a specific buffer size.

Parameters

size	Buffer size in bytes.

Returns

true if the buffer was resized successfully.

setCallback() [1/2]

void setCallback ( BoxCallback  cb )

inline

Defines the generic callback for all boxes.

Parameters

cb	Callback function for all boxes.

setCallback() [2/2]

void setCallback ( const char *  type, BoxCallback  cb, bool  callGeneric = true  )

inline

Defines a specific callback for a box type.

Parameters

type	4-character box type (e.g. "moov", "mdat").
cb	Callback function for this box type.
callGeneric	If true, the generic callback will also be called after the type-specific callback.

setReference()

void setReference ( void *  ref )

inline

Defines an optional reference. By default it is the parser itself.

Parameters

ref	Pointer to reference object.

setRequireMoovBeforeMdat()

void setRequireMoovBeforeMdat ( bool  flag )

inline

Defines whether an mdat box found before any moov box is treated as an error (LOGE, the default) or downgraded to a warning (LOGW). Set to false to opt out of the moov-before-mdat requirement, e.g. for files from encoders that are known to violate it but still work.

Parameters

flag	true to require moov before mdat (default), false to opt out.

startIncrementalBox()

void startIncrementalBox ( const char *  type, const uint8_t *  p, size_t  headerSize, size_t  payload_size, int  level, size_t  bufferSize  )

inlineprotected

Starts parsing a box incrementally.

Parameters

type	Box type string.
p	Pointer to the start of the box in the buffer.
headerSize	Size of the box header.
payload_size	Size of the box payload.
level	Nesting level of the box.
bufferSize	Number of bytes available in the buffer.

tryStartNewBox()

bool tryStartNewBox ( size_t  bufferSize )

inlineprotected

Try to start parsing a new box. Returns false if not enough data.

Parameters

bufferSize

Number of bytes available in the buffer.

Returns

True if a box was started, false otherwise.

write() [1/2]

size_t write ( const char *  data, size_t  len  )

inline

Provide the data to the parser (in chunks if needed).

Parameters

data	Pointer to input data (char*).
len	Length of input data.

Returns

Number of bytes written to the buffer.

write() [2/2]

size_t write ( const uint8_t *  data, size_t  len  )

inline

Provide the data to the parser (in chunks if needed).

Parameters

data	Pointer to input data.
len	Length of input data.

Returns

Number of bytes written to the buffer.

Member Data Documentation

box

Box box

protected

Current box being processed.

box_bytes_expected

size_t box_bytes_expected = 0

protected

Total expected bytes for the current box.

box_bytes_received

size_t box_bytes_received = 0

protected

Bytes received so far for the current box.

box_in_progress

bool box_in_progress

protected

Initial value:

=
      false

True if currently parsing a box incrementally.

box_level

int box_level = 0

protected

Current box level (nesting)

box_seq

int box_seq = 0

protected

box_type

char box_type[5] = {0}

protected

Current box type.

buffer

SingleBuffer<uint8_t> buffer

protected

Buffer for incoming data.

callback

BoxCallback callback = defaultCallback

protected

Generic callback for all boxes.

callbacks

Vector<CallbackEntry> callbacks

protected

List of type-specific callbacks.

containers

Vector<ContainerInfo> containers

protected

List of container box info.

fileOffset

uint64_t fileOffset = 0

protected

Current file offset.

incremental_offset

size_t incremental_offset = 0

protected

is_error

bool is_error = false

protected

True if an error occurred.

levelStack

Vector<size_t> levelStack

protected

Stack for container box levels.

moov_found

bool moov_found = false

protected

True once a top-level moov box has been seen.

parseOffset

size_t parseOffset = 0

protected

Current parse offset in buffer.

ref

void* ref = this

protected

Reference pointer for callbacks.

require_moov_before_mdat

bool require_moov_before_mdat = true

protected

false: warn instead of error

---

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

• src/AudioTools/AudioCodecs/MP4Parser.h