MP4DMX Detailed Library Operation

Table of Contents

Overview

A function's return value normally determines which function should be called next.

After reading the MP4 data file according to the offset and size specified in the output parameters, the next API function specified by the return value should be called.

Flowcharts of both the ordinary process and special process with a description of reading the MP4 data file are given in this section.

Ordinary Process

The following diagrams show a detailed flowchart, a sequence diagram for the ordinary process, illustrate the ordinary process used when the MP4 data file contains a MovieFragmentBox, and illustrate the demultiplexing process when boxes are split based on a specified read size.

These flowcharts cover only situations in which functions do not return errors. When a function returns an error or the end of an MP4 data file is reached, processing moves to the shutdown process.


Figure 1: Ordinary Process Flowchart


Figure 2: Ordinary Process Sequence


Figure 3: Ordinary Process Flowchart (MP4 Data File Includes a MovieFragmentBox)

If there are MovieFragmentRandomAccessBox segments in the MP4 data file, these can be used for random access in the file, without needing to parse the intervening fragments.


Figure 4: Advantages of Using a MovieFragmentRandomAccessBox

Randomly access the data using a MovieFragmentRandomAccessBox. To do so, use the MP4DMXFindHeader and MP4DMXReadHeader functions to parse a MovieBox and then immediately parse the MovieFragmentRandomAccessBox.


Figure 5: Ordinary Process Flowchart (With a MovieFragmentRandomAccessBox)


Figure 6: Ordinary Process Flowchart (With Boxes Split Based on Specified Read Size)


Figure 7: Shutdown Process

Special Process

For the special process, in addition to performing the steps used in the ordinary process, the offset of the seek point reached in current execution (get current position, MP4DMXExecute) must be obtained first. Then execution (or sample extraction) must be resumed using the offset value obtained.

To obtain the seek point and offset, the sample maintained within the library must be output, and the header data maintained by the library updated with the seek target header data. To do this, processing should be stopped (MP4DMXEnd) and restarted (MP4DMXBegin) every time, directly before beginning demultiplexing (get current position, MP4DMXExecute).

This flowchart covers only situations in which functions do not return errors. See the shutdown flowchart for information on the flow when a function returns an error or the end of the MP4 data file is reached.


Figure 8: Special Process Flowchart


Figure 9: Special Process

Reading a File

An application must read the MP4 data file before calling each API function.

When reading an MP4 data file, the user application specifies 8 bytes from the beginning of the MP4 data file when finding the first header (MP4DMXFindHeader), and 16 bytes from the end of the file when using MovieFragmentRandomAccessBox fragments.

In all other cases, the user application reads the MP4 data file using the offset and data size returned in the output arguments of the API functions (MP4DMXFindHeader, MP4DMXReadHeader, MP4DMXExecute) when they return.

The following list shows which units of data are requested by each function and in what order.

[ 1 ] FileTypeBox
[ 2 ] MovieBox
[ 3 ] MovieFragmentBox #1
[ 4 ] MovieFragmentBox #2
[ 1' ] MovieFragmentRandomAccessOffsetBox
[ 2' ] MovieFragmentRandomAccessBox
NOTE:
Handle [ 1' ] and [ 2' ] before [ 3 ].

MP4 Data File Range and Reading Order

1 2 3 4 5 6 7 Order
ftyp [ 1 ]
moov [ 2 ]
mvhd
trak  
tkhd
tref
edts  
elst
mdia  
mdhd
hdlr
minf  
vmhd
smhd
hmhd
nmhd
dinf  
dref
stbl  
stsd  
mp4a
mp4v
stts
ctts
stsc
stsz
stz2
stco
stss
uuid
mvex  
 
trex
udta
cprt
mdat (1)  
AudioChunk (1)  
AudioSample (1)
AudioSample (2)
AudioSample (3)
...
VideoChunk (1)  
VideoSample (1)
VideoSample (2)
VideoSample (3)
...
AudioChunk (2)  
AudioSample (4)
AudioSample (5)
AudioSample (6)
...
VideoChunk (2)  
VideoSample (4)
VideoSample (5)
VideoSample (6)
...
AudioChunk (3)  
AudioSample (7)
AudioSample (8)
...
moof (1) [ 3 ]
Mfhd
Traf  
tfhd
trun
mdat (2)  
AudioChunk (4)  
AudioSample (9)
AudioSample (10)
AudioSample (11)
...
VideoChunk (3)  
VideoSample (7)
VideoSample (8)
VideoSample (9)
...
moof (2)   [ 4 ]
Mfhd
Traf  
tfhd
trun
mfra [ 2' ]
Tfra
Mfro [ 1' ]

Each function normally needs to be passed certain data from the MP4 data file, as shown below.

MP4DMXFindHeader

[1] 8 bytes from the beginning of an MP4 data file.
[2] 8 bytes from the offset returned after parsing (MP4DMXReadHeader) of an FtypBox, until a MovieBox is found.
[1'] 16 bytes of data from the end of an MP4 data file (MovieFragmentRandomAccessOffsetBox).
[2'] Data from the offset read into a MovieFragmentRandomAccessOffsetBox until a MovieFragmentRandomAccessBox is found.
[3] 8 bytes from the offset returned after parsing (MP4DMXReadHeader) of a MovieBox, until a MovieFragmentBox is found.
[4] 8 bytes from the offset returned after parsing (MP4DMXReadHeader) of a MovieFragmentBox, until a MovieFragmentBox is found.

MP4DMXReadHeader

  1. FileTypeBox data
  2. MovieBox data
  3. MovieFragmentRandomAccessOffsetBox data
  4. MovieFragmentRandomAccessBox data
  5. MovieFragmentBox data

A data offset value and size are returned as output arguments to each function, as shown below.

Data Offset and Size Returned as Output Arguments to MP4DMXFindHeader

Return Value Offset and Size Next Function to be Called
MP4DMX_RET_FOUND_MOOV_BOX The size of the MovieBox and the offset from the beginning of the MP4 data file. MP4DMXReadHeader
MP4DMX_RET_FOUND_MOOF_BOX The size of the MovieFragmentBox and the offset from the beginning of the MP4 data file. MP4DMXReadHeader
MP4DMX_RET_FOUND_MFRA_BOX The size of the MovieFragmentRandomAccessBox and the offset from the beginning of the MP4 data file. MP4DMXReadHeader
MP4DMX_RET_FOUND_MFRO_BOX The size of the MovieFragmentRandomAccessOffsetBox and the offset from the beginning of the MP4 data file. MP4DMXReadHeader
MP4DMX_RET_FOUND_FTYP_BOX The size of the FileTypeBox and the offset from the beginning of the MP4 data file. MP4DMXReadHeader
MP4DMX_RET_NOT_FOUND_BOX The size (8 bytes) of the data after what has already been read and the starting offset.
NOTE:
If a MediaDataBox or other Box was found, the offset to the data following that Box is returned.
MP4DMXFindHeader

Data Offset and Size Returned as Output Arguments to MP4DMXReadHeader

Return Value Offset and Size Next Function to be Called
MP4DMX_RET_FIND_HEADER The default size and offset to the data following the MovieBox, MovieFragmentBox, or MovieFragmentRandomAccessBox that was just read. Alternately, the offset and size for a MovieFragmentRandomAccessBox after a MovieFragmentRandomAccessOffsetBox is read. MP4DMXFindHeader
MP4DMX_RET_READ_HEADER The MovieBox related to the MediaDataBox containing the data for the specified timestamp, or the size and offset of the MovieFragmentBox. MP4DMXFindHeader
MP4DMX_RET_EXECUTE_NORMAL N/A MP4DMXExecute
MP4DMX_RET_INPUT_CONTINUE The required size and offset for the data remaining in the Box currently being parsed. MP4DMXReadHeader

Return Value and Output Arguments (offset, size) of MP4DMXExecute When Getting Samples

Return Value Offset and Size Next Function to be Called
MP4DMX_RET_SUCCESS A size of 0 and an offset to the chunk specified as an input parameter. User-dependent
MP4DMX_RET_FIND_HEADER A size of 8 bytes and the offset 1 byte beyond the end of the MediaDataBox that was just read. MP4DMXFindHeader
MP4DMX_RET_READ_HEADER The size of and offset to the next existing MovieFragmentBox after the one that just processed. MP4DMXReadHeader
MP4DMX_RET_EXECUTE_WARNING A size of 0 and an offset to the chunk specified as an input parameter. MP4DMXExecute

Return Value and Output Arguments (Offset, Size) of MP4DMXExecute When Getting Current Position

Return Value Offset and Size Next Function to be Called
MP4DMX_RET_FIND_HEADER A size of 8 bytes and the offset to the data following the MovieFragmentBox or the MovieBox that was just read before now. MP4DMXFindHeader
MP4DMX_RET_READ_HEADER The size of and offset into the MP4 data file for the MovieBox or MovieFragmentBox related to the MediaDataBox with data for the specified timestamp. MP4DMXReadHeader
MP4DMX_RET_EXECUTE_NORMAL N/A MP4DMXExecute
(demultiplexing specified)

Utility Processing

For more information, see the Ordinary Process Sequence diagram for an example of using the utility functions.

Revision History

2014/08/05 Initial version.


CONFIDENTIAL