MPEG-4 Tools by ENST


Document updated on October 10th, 2003

Sorry, as of January 1st, 2004, the MPEG-4 Systems licence is not free anymore, so we cannot make mp4tool available for free download any more.

For developers, you can use Mp4Box at gpac.sourceforge.net instead.

NHNT Mux Hint File Format

For every media file named x.y, it is assumed that x.info contains the headers a.k.a. decoder specific info, and x.nhnt contains the description of all access units. Multiple byte values are stored in MOST SIGNIFICANT BYTE FIRST.

File header:

char(4) 'NHnt' or 'NHnl'
int(8) version
int(8) streamType (needs to be < 64)
int(8) objectTypeIndication
int(16) reserved
int(24) bufferSizeDB
int(32) maxBitrate
int(32) avgBitrate
int(32) timeScale (number of ticks per second)

Signature 'NHnt':

int(24) accessUnitLength
bit(1) isRandomAccessPointFlag
bit(1) accessUnitStartFlag
bit(1) accessUnitEndFlag
bit(1) reserved
bit(1) reserved
bit(1) reserved
bit(2) accessUnitType (for video I=0, P=1, B=2)
int(32) startOffset
int(32) CTS (in ticks, not in milliseconds)
int(32) DTS (in ticks, not in milliseconds)

Signature 'NHnl': for large files

int(24) accessUnitLength
bit(1) isRandomAccessPointFlag
bit(1) accessUnitStartFlag
bit(1) accessUnitEndFlag
bit(1) reserved
bit(1) reserved
bit(1) reserved
bit(2) accessUnitType (for video I=0, P=1, B=2)
int(64) startOffset
int(64) CTS (in ticks, not in milliseconds)
int(64) DTS (in ticks, not in milliseconds)

Quick usage guide for MP4TOOL:

Scene Encoding

To encode a scene, it is necessary to gather:

The first three elements should come as a .bt file. The actual command to encode a scene de-scribed in file scene.bt is:

mp4tool -mp4 scene

The result of this execution is a file scene.mp4.
The various options are described in the Options section below.

Scene Decoding

To decode a scene packaged in an MP4 file, the -d option can be used.
The actual command for scene.mp4 is:

mp4tool -d scene -o scene


This produces a file scene.bt which contains a decoded version of the BIFS stream enclosed in the file scene.mp4.

MP4 File Validation

To validate an MP4 file called scene.mp4, the command is:

mp4tool -d scene

This produces a set of log files:

Here is a short example of both formats:
Log:

BIFS ( 2, 138) scene replace command 3 // End of OD decoding
BIFS ( 8, 146) reserved 0
BIFS ( 1, 147) isReusable 0 //////////new node
BIFS ( 3, 150) Group 1
BIFS ( 1, 151) isUpdatable 0
BIFS ( 1, 152) maskDescription 0 //Group {
BIFS ( 1, 153) end 0
BIFS ( 0, 153) children 0
BIFS ( 1, 154) reserved 0 // Group.children
BIFS ( 1, 155) list 1
BIFS ( 1, 156) end 0
BIFS ( 1, 157) isReusable 0 //////////new node
BIFS ( 6, 163) Anchor 1
BIFS ( 1, 164) isUpdatable 0
BIFS ( 1, 165) maskDescription 0 // Anchor {
BIFS ( 1, 166) end 0
BIFS ( 2, 168) children 0
BIFS ( 1, 169) reserved 0 // Anchor.children
BIFS ( 1, 170) list 1
BIFS ( 1, 171) end 0
BIFS ( 1, 172) isReusable 0 //////////new node
BIFS ( 6, 178) Transform2D 30
BIFS ( 1, 179) isUpdatable 0
BIFS ( 1, 180) maskDescription 0 // Transform2D {
BIFS ( 1, 181) end 0
BIFS ( 3, 184) translation 5
BIFS ( 32, 216) float value 42980000 // Transform2D.translation
BIFS ( 32, 248) float value 0
BIFS ( 1, 249) end 0
BIFS ( 3, 252) children 0
BIFS ( 1, 253) reserved 0 // Transform2D.children
BIFS ( 1, 254) list 1
BIFS ( 1, 255) end 0

Trace_MP4:

MovieDataAtom 82
MovieAtom 571
MovieHeaderAtom 108
ObjectDescriptorAtom 29
TrackAtom 426
TrackHeaderAtom 92
MediaAtom 326
MediaHeaderAtom 32
HandlerAtom 33
MediaInformationAtom 253
DataInformationAtom 36
DataReferenceAtom 28
DataEntryAtom 12
Mpeg4MediaHeaderAtom 12
SampleTableAtom 197
CompositionTimeToSampleAtom 24
SampleDescriptionAtom 77
MpegSampleEntryAtom 61
ESDAtom 45
SampleSizeAtom 20
SampleToChunkAtom 28
SyncSampleAtom 20
ChunkOffsetAtom 20

Supported Media Types

By default, mp4tool uses the former V2 policy, which can theoretically process any kind of stream, if the relevant files are provided with the raw media files.
For each raw elementary stream called stream.type, two files are expected:

This new way of proceeding has many benefits:

The syntax of the .nhnt is above.

For V1 function (command line option -old), the actual processing requires that the elementary streams have been processed by "parsers", following a usual but undocumented practice within IM1. The "parsers" are tools written and maintained by CSELT, which insert easy-to-find access unit information into the raw elementary streams in order to ease the muxing job.
Mp4tool is capable of processing the following media types with the V1 policy:

Specification of the .BT Format

Here comes a commented example of the .bt format. We thought that this form of presentation is the best to help understand the format quickly.

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

BIFS Text Section

This section is BIFS text as defined by the IM1 group in the document describing the BIFSENC tool (part of the CORE release).

Group {

children [
Transform2D {

translation -352.0 288.0
children [

DEF I0 Group { # Root
children [

DEF I4 Transform2D {
translation 348.0 -286.0
children [

DEF I3 Shape { geometry Bitmap { }
appearance Appearance {
texture ImageTexture { url 3} } } # 06centre.jpg

]
}

]
} # Root

]}]}


The above describes a simple scene with just one image close to the center of the screen.
If routes are present, their description follows the above text.

Initial Object Descriptor Section

This section describes the initial object descriptor. This contains a reference to the main streams, OD and BIFS. The format is the same as described in the document describing the MUX (part of the CORE release)

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

InitialObjectDescriptor {

objectDescriptorID 1
ODProfileLevelIndication 1
sceneProfileLevelIndication 1
audioProfileLevelIndication 2
visualProfileLevelIndication 1
graphicsProfileLevelIndication 1
esdescr [

ES_Descriptor {

es_id 1
muxInfo muxInfo {

fileName "exe.od"
maxAhead 1
streamFormat BIFS

}
decConfigDescr DecoderConfigDescriptor {

objectTypeIndication 0xFF

avgBitrate 0

}
slConfigDescr SLConfigDescriptor {

predefined 0

packetSeqNumLength 0

}

}
ES_Descriptor {

es_id 2
muxInfo muxInfo { }
decConfigDescr DecoderConfigDescriptor {

objectTypeIndication 0xFF

}
decSpecificInfo BIFSConfig {

nodeIDbits 10
pixelMetric TRUE
pixelWidth 704
pixelHeight 576

}
slConfigDescr SLConfigDescriptor {

predefined 0

packetSeqNumLength 0

}

}

]

}

Object Descriptors Section

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

UPDATE OD [
{

objectDescriptorID 3
esdescr [

ES_Descriptor {

es_id 3
muxInfo muxInfo {

fileName "..\streams\06centre.jpg"
streamFormat JPEG
maxAhead 10

}
decConfigDescr DecoderConfigDescriptor {

objectTypeIndication 0x6C
streamType 4
upStream FALSE
bufferSizeDB 50000
maxBitrate 0
avgBitrate 0
bufferSizeDB 16678

}
slConfigDescr SlConfigDescriptor {

predefined 0

packetSeqNumLength 0

}

}

]

}
]

Updates Section

If there are any updates (if the scene changes over time), there should follow here a sequence of BIFS updates followed by OD updates. BIFS updates follow the structure of the BIFS section. OD updates follow the structure of the OD section.

Options

Basically, the "options" are the same as with the IM1 mux or bifsenc. However, there is one specific functionality: media files can be left out of the main MP4 file, or included in it. If all media are inserted into the main MP4 file, a self-contained MP4 file is created. This functionality is some sort of equivalent to the muxing of streams in separate files.
Another functionality derives from the limitations of mp4tool. Mp4tool does not implement Scripts, Quantisation or Protos. In order to be able to create MP4 files with one or more of these features, mp4tool has the option to use the encoded BIFS as produced by BIFSENC.

Stream Inclusion/Exclusion

Stream in/exclusion is managed within the beginning of the ES Descriptor. Here is an example of a ES that resides within the main MP4 file:

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

ES_Descriptor {

es_id 3
muxInfo muxInfo {

fileName "..\streams\06centre.jpg"

}

In the above description, mp4tool is instructed to take the raw stream from ..\streams\06centre.jpg and insert it in the main MP4 file by the absence of a URLstring field in the ES Descriptor.
Here is an example of a ES that resides outside of the main MP4 file:

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

ES_Descriptor {

es_id 3
URLstring "scene_06centre.media"
muxInfo muxInfo {

fileName "..\streams\06centre.jpg"

}

In the above description, mp4tool is instructed to place the stream taken from ..\streams\06centre.jpg into a separate file called scene_06centre.media, beside the main MP4 file.
Here is an example of a ES that resides outside of the main MP4 file, on a web site:

NOTE: keywords in bold are required by mp4tool but optional in bifsenc.

ES_Descriptor {

es_id 3
URLstring "http://web.site.org/dir/scene_06centre.media"
muxInfo muxInfo {

fileName "..\streams\06centre.jpg"
externalMediaName "scene_06centre.media"

}

In the above description, mp4tool is instructed to place the stream taken from ..\streams\06centre.jpg TEMPORARILY into a separate file called scene_06centre.media, beside the main MP4 file but to store into the MP4 file the information that this stream will be found at the address given in URLstring in the final usage phase. This is necessary since mp4tool will not be able to write directly to the address given in URLstring and the user will need to do the trans-fer by other means.
NOTE: Some keywords in bold in the above samples are required by mp4tool but optional in bifsenc.

Cooperation with BIFSENC

BIFSENC produces scene.bif and scene.od from scene.txt. With the following command:

mp4tool -bifsenc scene

mp4tool will read scene.bt but ignore its BIFS text section. The OD section is only read for the muxInfos. The content of the file scene.bif will be used instead. The rest of the function of mp4tool is unchanged. This means that IOD and OD sections of the scene.bt file need to be compatible with what is in scene.txt and scene.scr.

License agreement:

THIS  IS  A  CONTRACT. IF YOU PROCEED TO DOWNLOAD AND/OR  INSTALL
AND/OR  USE THE FILES IN THIS SOFTWARE, YOU ACCEPT ALL THE TERMS,
CONDITIONS AND OBLIGATIONS IMPOSED UPON YOU BY THIS CONTRACT.

This  Software product is a copyright (c) 2001 of Ecole Nationale
Supérieure des Télécommunications (ENST). All title and copyright
in  and to the Software (including but not limited to any images,
animations, and text incorporated into the Software) are owned by
ENST.

You are granted a free license to the use of any number of copies
of the latest freely distributed  version of the Software for the
development of the MPEG-4 standard provided that you agree to the
following:

. You  shall  use  the  software for commercial or non-commercial
purposes  only  for the development of MPEG-4 compliant  products
or for the promotion of the MPEG-4 standard.
.  The Software is owned by ENST, and its structure, organization
and  code are the valuable trade secrets of ENST.  You agree  not
to   modify,   adapt,  translate,  reverse  engineer,  decompile,
disassemble or otherwise attempt to discover the source  code  of
the  Software, or to give, rent, lend, sell or lease the Software
to anyone.
. THE SOFTWARE IS MADE AVAILABLE FOR YOUR USE "AS IS" AND WITHOUT
ANY  WARRANTIES,  INCLUDING  ANY WARRANTY OF MERCHANTABILITY, ANY
WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE, ANY WARRANTY AS  TO
NON-INFRINGEMENT  OF THE RIGHTS OF THIRD PARTIES,  OR  ANY  OTHER
WARRANTY WHETHER EXPRESSED OR IMPLIED.
.  You assume the entire risk of using the Software. ENST ACCEPTS
NO  LIABILITY WHATSOEVER. IN NO EVENT WILL ENST BE LIABLE TO  YOU
OR   THIRD  PARTIES  FOR  CONSEQUENTIAL,  INCIDENTAL  OR  SPECIAL
DAMAGES, EVEN IF ENST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
.  This Agreement will be governed by the laws of France. If  any
part  of  this Agreement is found void or unenforceable, it  will
not affect the validity of the balance of the Agreement.

You acknowledge that you have read this Agreement, understand it,
and  that by downloading or using the Software, you agree  to  be
bound by all of the terms and conditions of this Agreement.

MP4TOOL also includes Xerces, which is subject to the following licence:

/*
* The Apache Software License, Version 1.1
*
*
* Copyright (c) 1999-2000 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "Xerces" and "Apache Software Foundation" must
* not be used to endorse or promote products derived from this
* software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache",
* nor may "Apache" appear in their name, without prior written
* permission of the Apache Software Foundation.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation and was
* originally based on software copyright (c) 1999, International
* Business Machines, Inc., http://www.ibm.com. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*/