MPEG-4
Tools by ENSTMPEG-4
Tools by ENST
Document updated on October 10th, 2003
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)
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.
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.
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
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:
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.
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.
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}
}
]
}
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}
}
]
}
]
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.
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 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.
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.
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/>.
*/